jamie-bitflight/create-artifact

Create Artifact (MCP-native storage)

Register your deliverable using mcp__plugin_dh_backlog__artifact_register. This is the ONLY correct storage path for plan artifacts. Do NOT use Write to disk and do NOT return content inline.

Why disk writes and inline returns are wrong

• Disk writes produce a file only accessible from the root worktree. Worktree-isolated agents and CI environments cannot reach ~/.dh/... paths via filesystem — they must use artifact_read(issue_number, artifact_type) over MCP.
• Inline returns are truncated by the task-notification summary when the agent runs as a background-dispatched task. The orchestrator receives a partial summary, not the full document.

MCP-native storage uploads content to a GitHub issue comment where any agent — regardless of worktree or environment — can retrieve it via artifact_read.

Correct invocation (verified against backlog_core/server.py:2385)

mcp__plugin_dh_backlog__artifact_register(
    issue_number=<int>,           # GitHub issue number — REQUIRED
    artifact_type=<str>,          # Artifact type string — REQUIRED (see table below)
    artifact_id=<str>,            # Logical identifier — REQUIRED (see path format below)
    status="current",             # Lifecycle status: draft | current | superseded | archived
    agent=<str>,                  # Name of the producing agent (default: "")
    content=<str | None>,         # Full artifact content — include this to store in GitHub
)

Return value: dict with keys registered (bool), artifact_count (int), action ("added" or "updated"), content_stored (bool), messages, warnings. Check action in your STATUS: DONE report — do NOT paste the full content.

Parameters

artifact_type

One of the recognized type strings:

| artifact_type | Producing agent | When to use | |---|---|---| | feature-context | feature-researcher | Discovery document: WHO/WHAT/WHEN/WHY analysis | | codebase-analysis | codebase-analyzer | Codebase pattern/architecture/testing documents | | architect | python-cli-design-spec | Architecture spec with interfaces and contracts | | task-plan | swarm-task-planner | SAM task plan — auto-registered by sam_plan(action='create', issue=N), do NOT register manually | | T0-baseline | t0-baseline-capture | Pre-implementation baseline of acceptance criteria | | TN-verification | tn-verification-gate | Post-implementation verification results | | research | any research agent | Investigation findings, coverage analysis, rationale |

artifact_id

Logical identifier for the artifact. Two valid formats:

• Repo-relative path for file artifacts that exist on disk in the root worktree: plan/feature-context-{slug}.md, plan/architect-{slug}.md
• Logical id for artifacts that do NOT write a repo file: codebase-patterns-{slug}, codebase-architecture-{slug}, T0-baseline-{slug}, TN-verification-{slug}

Use a logical id (not a path) when the agent stores content via content= without writing a file to disk. Using a path that doesn't exist on disk causes a warning when content=None and is misleading to artifact consumers.

Do NOT use ~/.dh/... paths — these are MCP-server internals, not stable agent interfaces.

content

Pass the full markdown string. When content is provided, it is stored as a structured GitHub issue comment retrievable via artifact_read(issue_number, artifact_type) from any environment.

When content is None: the server attempts to read a local file at artifact_id (resolved against the root worktree). If no file exists, a manifest-only entry is registered and a warning is emitted. For background-dispatched agents, always pass content= explicitly.

Examples by artifact type

feature-context

mcp__plugin_dh_backlog__artifact_register(
    issue_number=1770,
    artifact_type="feature-context",
    artifact_id="plan/feature-context-my-feature.md",
    content=feature_context_markdown,
    agent="feature-researcher",
)

codebase-analysis (one call per focus area, logical id — no filesystem path)

mcp__plugin_dh_backlog__artifact_register(
    issue_number=1770,
    artifact_type="codebase-analysis",
    artifact_id="codebase-patterns-my-feature",  # logical id: codebase-{focus}-{slug}
    content=patterns_markdown,
    agent="codebase-analyzer",
)

mcp__plugin_dh_backlog__artifact_register(
    issue_number=1770,
    artifact_type="codebase-analysis",
    artifact_id="codebase-architecture-my-feature",  # logical id: codebase-{focus}-{slug}
    content=architecture_markdown,
    agent="codebase-analyzer",
)

architect

mcp__plugin_dh_backlog__artifact_register(
    issue_number=1770,
    artifact_type="architect",
    artifact_id="plan/architect-my-feature.md",
    content=architect_markdown,
    agent="python-cli-design-spec",
)

task-plan

sam_plan(action='create', issue=N) auto-registers this artifact. Do NOT call artifact_register for task-plan — it creates a duplicate entry.

research (secondary documents, rationale, coverage analysis)

mcp__plugin_dh_backlog__artifact_register(
    issue_number=1770,
    artifact_type="research",
    artifact_id="plan/swarm-rationale-my-feature.md",
    content=rationale_markdown,
    agent="swarm-task-planner",
)

STATUS: DONE report format

Do NOT paste the full document content. Report only:

STATUS: DONE
ARTIFACT: type={artifact_type}, action={action}, content_stored={content_stored}, chars={len(content)}

Include a <concerns> block if quality issues were found during the work.