Module agent_artifact

Expand description

Per-agent native instruction artifacts.

Installs a small file at a well-known path for each selected agent so the agent’s runtime picks it up automatically and learns when to invoke repograph CLI commands.

§Surface

Scope — user-scope vs project-scope target root.
ArtifactResult — per-agent outcome of an install (Written, Unchanged, Skipped, Failed).
BODY — the canonical instructional prose, shared across every per-agent writer so the CLI surface is documented in exactly one place.
install_artifacts — entry point that iterates a selection and returns one result per agent in selection order.

§Delimiter contract

Each artifact wraps the canonical body in DELIMITER_BEGIN / DELIMITER_END HTML comments. This lets a single file mix user-authored content with the repograph-managed block (relevant for AGENTS.md / CONVENTIONS.md, which users may already maintain). Re-runs only touch the delimited region; everything outside is byte-preserved.

§Force-bypass

Passing force = true to the install layer skips the delimiter check and writes the file fresh with only the delimited block. Any prior file contents (including user content outside the delimited region) are discarded. This is the escape hatch for re-asserting the canonical body after local edits drift.

§Skipped agents

Not every selected agent has a writer. AgentId::Copilot is deferred in v1 because its instruction format varies across surfaces (repo-level, editor-level, Copilot Workspace) and no single converged path covers them. Selecting Copilot is fine — it just produces a ArtifactResult::Skipped with no file write.

Enums§

ArtifactResult: Per-artifact outcome of an install. The orchestrator returns one of these per (agent, capability) artifact actually targeted, in selection order.
Capability: Which generated skill a given artifact carries.
Scope: Where on disk an artifact should be installed.
SpliceOutcome: Outcome of splice_managed_section — describes how the install layer should reconcile the new body against the existing file contents.

Constants§

ARTIFACT_BODY_VERSION: Monotonic version of the managed artifact body.
BODY: The single canonical instructional body, shared by every per-agent writer.
DELIMITER_BEGIN: HTML-comment marker opening the repograph-managed region of an artifact, carrying the current ARTIFACT_BODY_VERSION stamp.
DELIMITER_BEGIN_PREFIX: Version-agnostic prefix of the begin marker. Splice detection matches on this so an older-version block is recognized and rewritten in place rather than appended as a duplicate.
DELIMITER_END: HTML-comment marker closing the repograph-managed region of an artifact.
REASON_COPILOT_DEFERRED: Reason strings used in ArtifactResult::Skipped. Stable: agents may observe them in repograph doctor output or log scraping.
SETUP_BODY: The canonical instructional body for the repograph-setup capability — the mutating surface.
SETUP_SUMMARY: Skill description for the repograph-setup capability — the mutating surface.
SUMMARY: Skill description rendered into the YAML frontmatter of the agents that have it (Claude SKILL.md, Cursor .mdc).

Functions§

body_for: The instructional body for capability.
capabilities_for: The capabilities that should be emitted for agent, in install order.
has_artifact_writer: Is there an installed-artifact writer for this agent in v1?
install_artifacts: Render frontmatter (if any) and a managed-section block for agent, then install it under the resolved (scope, home, cwd) path. The result vector has one entry per input agent in selection order.
install_one: Install a single artifact at path for agent.
installed_version: Parse the body-version stamp from an installed file’s managed block.
render_artifact: Compose the full file contents for agent: per-agent frontmatter (if any) followed by the managed-section delimiters wrapping BODY, plus a trailing newline.
resolve_path: Resolve the target install path for (agent, scope).
scope_is_meaningful: Does the choice between Scope::User and Scope::Project change the resolved path for this agent?
splice_managed_section: Pure-string idempotent splice: read the existing file (or None), produce the SpliceOutcome that tells the install layer what to write.
summary_for: The frontmatter description: summary for capability.
wholly_owned_file: Does this agent’s artifact occupy the whole file (frontmatter included), with no expectation of pre-existing user content to preserve?
writer_summary: Convenience accessor for the consumer writer-side summary. Mirrors SUMMARY; this exists so writers don’t reach into module-level constants directly.