Module agent_artifact 

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-agent outcome of an install. The orchestrator returns one of these per input agent in selection order.

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

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.

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.

SUMMARY

One-line description used in every per-agent frontmatter block (Claude SKILL.md, Cursor .mdc) and in the # repograph heading body for the frontmatter-less writers.

Functions

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.

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.

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 writer-side summary. Mirrors SUMMARY; this exists so writers don’t reach into module-level constants directly.