The artifact chain

The artifact chain turns an idea into six reviewable handoffs: intent.md, spec.md, plan.md, the diff with test evidence, review findings, and an incident record or next intent. One named source of truth keeps every human and agent on the same accepted state while preserving an auditable history.

The chain

Every stage ends by writing one artifact to version control. The next stage begins by reading it.

Stage	Artifact	Who accepts it
Plan	intent.md	Product owner
Design	spec.md	Product owner, with a technical lead on higher-risk work
Build	plan.md, then the diff and its tests	Engineer (routine); tech lead or architect (higher risk)
Test	Test output, build log, or screenshot diff attached to the session or PR	Code owner reviewing the PR
Deploy	Pull request with review findings	Code owner; release manager at the production gate
Maintain	Incident record, then a new intent.md	Service owner or on-call, then the product owner for product-facing findings

For the early stages, markdown is the predominant artifact because a product owner and an agent can both read and act on the same file. From build onward the artifact is code and its records.

Where to put the files

For a single product, the simplest home is an intent/ folder in the product repo (and spec.md / plan.md beside the change, or in the same folder). A dedicated intent repo is worth the overhead only when intent spans many repositories. In a monorepo it is a directory.

Name one source of truth

Existing SDLC processes already track artifacts, just not as markdown files. Work items may live in Jira, requirements in a tool with regulatory traceability, designs in Figma, and change approvals with a change board. Those systems are hard to displace because auditors already accept them.

For every artifact the process produces, name one system as the source of truth. Everything else holds a copy or a link.

The following configurations all work. Pick one per artifact:

The repo as the source of truth. The markdown files are the authoritative record. The legacy system references files within commits. This is the cleanest setup for engineering-led organizations: one tool, one timestamp authority.

The legacy system as the source of truth. Jira, ServiceNow, or the requirements tool holds the authoritative record. The markdown files are working copies. The agent reads the record at the start of the session and writes the outcome back through an MCP connector in the same session that produced the spec or the plan.

Linkage as the minimum bar. Every markdown file notes the record ID. Every legacy record contains the commit SHA of the markdown file. Start here when you cannot pick a single source of truth yet.

Templates

Use the following shapes. Replace the placeholders with values for your change.

Template: intent.md

# Intent: INTENT_TITLE
Author: AUTHOR_NAME (TEAM). Status: draft.

## Problem
WHAT_IS_BROKEN_OR_MISSING

## Proposed outcome
WHAT_BETTER_LOOKS_LIKE

## Affected users and systems
USERS_AND_SYSTEMS

## Constraints
CONSTRAINTS

## Open questions
OPEN_QUESTIONS

Template: spec.md

# Spec: SPEC_TITLE (from intent.md DATE)
Status: ready-for-plan

## Requirements
REQUIREMENTS_LIST

## Architecture and design
DESIGN_DETAILS

## Skills and policies applied
- Security: POLICIES_APPLIED
- Brand and UX: GUIDELINES_APPLIED

## Flagged concerns
CONCERNS_FOR_POLICY_OWNERS

Template: plan.md

# Plan: PLAN_TITLE (from spec.md DATE)

## Files that change
FILE_LIST

## Order of work
1. FIRST_STEP
2. SECOND_STEP

## Risks
RISKS

## Proof
HOW_YOU_WILL_KNOW_IT_WORKED

Template: REVIEW.md

# Review instructions

## Passes
Run three passes and tag each finding with its pass:
- Bugs: logic errors, broken edge cases, subtle regressions
- Security: injection risks, authentication gaps, PII in logs
- Compliance: the change matches spec.md, plan.md, and design principles

## Severity criteria
- Important: broken behavior, leaked data, security vulnerability, policy breach
- Nit: formatting, naming, cosmetic refactors (cap at 5 nits total)

## Exclusions
Exclude generated code under src/gen/, dist/, and checks already enforced by CI.

When implementation departs from the plan, update plan.md in the same commit.

Harness-specific artifact tips

Store artifacts where all harnesses can access them:

• Cursor: Cursor Plan mode saves plan drafts under .cursor/plans/. Copy or save the final approved plan as plan.md in your repository root or docs/plans/ so external reviews, CI, and other tools can read it.
• Codex: Use /plan in the CLI and save the accepted plan in the repo. Use app worktrees or explicit Git worktrees for separate artifact states; Codex CLI 0.146.0 has no --worktree flag.
• Claude Code: Shift+Tab or --permission-mode plan enters Plan mode. Commit the accepted output as plan.md. Run claude -w BRANCH_NAME for an isolated session.

Verify

Confirm all of the following:

• You can point to one home for intent.md (a folder in the product repo, or a dedicated repo).
• Each artifact type has a named source of truth.
• A new contributor can find the last accepted intent.md and the spec.md / plan.md derived from it without asking Slack.

Put the chain into use

1. Capture the first idea as intent.md — see Plan.
2. Map the same files onto Cursor, Claude Code, and Codex — see the tool map.