Artifact Management

Artifact Management

Intro

Artifacts are tangible deliverables — documents, design files, datasets, build outputs, slide decks, videos, or external URLs. Unlike Notes (thoughts in transit), Artifacts are completed deliverables registered in the project catalog. Unlike WorkItems (units of tracked work), Artifacts have no state lifecycle — they exist or they don't.

Two storage patterns are equally valid:

• Self-hosted: the artifact content is the Markdown body of the entity file; spec.location may reference the file's own path or be omitted. Use for documents that belong in the repository (PRDs, runbooks, research reports, work instructions).
• Pointer: the deliverable lives elsewhere (external URL, cloud storage, build artifact); spec.location is the canonical address. processkit stores only the metadata card.

MCP server. This skill ships a self-contained MCP server at mcp/server.py (PEP 723 script — requires uv and Python ≥ 3.10 on PATH). Agent harnesses reach its tools by reading a single MCP config file at startup, so the contents of mcp/mcp-config.json must be merged into the harness's MCP config and placed at the harness-specific path before this skill is usable.

Overview

Artifact kinds

spec.kind classifies the artifact:

When to create an Artifact

Create an Artifact when:

• A deliverable is complete enough to reference and share.
• Something produced by the project should be discoverable later (a report, a shipped binary, an approved design).
• A Note has been promoted to a finished document.
• A work item produced a document or design that should be cataloged.

Do not create Artifacts for in-progress work — use a WorkItem or a Note while the thing is still being made.

Creating

1. Choose kind from the table above.
2. Write a short, descriptive name.
3. Provide slug_summary when available: 4-6 meaningful words that summarize the durable deliverable. The server validates this shape and turns it into the ID slug; if omitted, the name remains the backwards-compatible fallback.
4. Set location for pointer artifacts (URL, path, bucket key). Omit or set to the entity file path for self-hosted artifacts.
5. Set produced_by to the WorkItem or Process ID that produced it.
6. Set owner to the responsible Actor ID.
7. Add tags for retrieval (topic, project, format, etc.).
8. Write the file to context/artifacts/ART-<id>.md.
9. Log artifact.created.

Querying

Common queries via query_artifacts:

• All artifacts of a given kind (e.g., all document artifacts)
• All artifacts owned by an actor
• All artifacts tagged with a given tag
• Full-text search via index-management

Updating

Use update_artifact to revise metadata (new version, updated location, changed owner). Pass touch_updated_at=false for metadata-only updates that should not restamp metadata.updated and invalidate an agent's prior body-read freshness checks. To replace the body content of a self-hosted artifact, update the Markdown body via update_artifact or by editing the file directly followed by reindex.

Gotchas

Agent-specific failure modes:

• Creating an Artifact for in-progress work. An Artifact is a completed deliverable. If the thing isn't done yet, use a WorkItem (for tracked work) or a Note (for an idea still forming). Premature Artifact registration pollutes the catalog with incomplete items.
• Omitting location for pointer artifacts. If the content lives outside the repository (a URL, a cloud bucket path, a release binary), location is the only way to find it. Omitting it makes the catalog entry useless as a pointer.
• Duplicate registration. Before create_artifact, run query_artifacts and check for an existing entry with the same name or location. Duplicates create confusion about which entry is canonical.
• Using Artifact for ephemeral build outputs. Not every build artifact needs a catalog entry. Register the ones that matter for the release, for compliance, or for future reference. Registering every intermediate build output creates noise.
• Forgetting produced_by. Linking the artifact back to the WorkItem or Process that produced it is cheap and makes the catalog navigable. Always set it when the provenance is known.

Full reference

Full field list

See src/context/schemas/artifact.yaml for the authoritative schema.

Note vs Artifact decision rule

Relationship to WorkItems

A WorkItem is the unit of work that produces an Artifact. Link the two via spec.produced_by on the Artifact (pointing to the WorkItem ID). This gives a navigable trail from deliverable back to the work that created it.