The artifact chain

The artifact chain is a sequence of committed files that carries a change from idea to production: intent.md, spec.md, plan.md with its task list, the diff with test evidence, review findings, and an incident record that becomes the next intent. Each stage reads the previous artifact, and a named person accepts it before the next stage starts.

You have a ticket that says “Add user notifications”, and it is due Friday. You paste it into the agent, and it writes 400 lines that look plausible, miss half the requirements, invent a notifications table that clashes with your events table, and ignore your API conventions. The agent did not fail. It made architectural decisions nobody asked it to make, and nothing written down told it otherwise.

This page is for developers who run agents on real features and for tech leads who want every change to leave the same trail. It replaces the older “PRD → plan → todo” method on this site: the PRD became intent.md and spec.md, the plan became plan.md, and the todo list became the task section of plan.md.

What the artifact chain gives you on your next feature

• Six artifacts, each with a template, an owner who accepts it, and the proof that goes with it.
• Six copy-paste prompts: interview you into an intent, read a spec for gaps, draft a plan, execute one task, check the diff for drift, and audit a codebase into plans.
• The plan-mode commands for Claude Code, Codex, and Cursor, and where each one’s output has to end up.
• A way to check each hand-off with tests, acceptance criteria, and a drift review, so you do not have to read every line the agent writes.

Which files make up the artifact chain?

Every stage ends by committing one artifact. The next stage begins by reading it.

Stage	Artifact	Who accepts it	What proves it is done
Plan	intent.md	Product owner	Problem, outcome, and constraints are stated; open questions are listed, not guessed
Design	spec.md	Product owner, plus a tech lead on higher-risk work	Every requirement has an acceptance criterion that a test can check
Build	plan.md with its task list, then the diff	Engineer (routine); tech lead or architect (higher risk)	Each task names its files and the command that proves it
Test	Test output, build log, or screenshot diff attached to the PR	Code owner reviewing the PR	The commands in the plan’s Proof section pass in CI
Deploy	Pull request with review findings	Code owner; release manager at the production gate	No open finding tagged Important
Maintain	Incident record, then a new intent.md	Service owner or on-call, then the product owner	The next intent links the incident

Up to the plan, the artifact is markdown, 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. The stage pages hold the full procedure for each file: Plan for intent.md, Design for spec.md, and Build for plan.md.

Where to put the files

Keep one folder per feature in the product repository: intent/<feature>/intent.md, intent/<feature>/spec.md, and intent/<feature>/plan.md. Every prompt on this page uses that layout. If your team already keeps plans in docs/plans/, point the prompts there instead, but pick one layout. A separate intent repository is worth the overhead only when one intent spans many repositories.

Name one source of truth for each artifact

Your process already tracks these artifacts, just not as markdown. Work items live in Jira, requirements in a tool with regulatory traceability, designs in Figma, and change approvals with a change board. Auditors accept those systems, so they are hard to displace.

For every artifact, name one system as the source of truth. Everything else holds a copy or a link. Pick one of the following configurations per artifact:

Configuration	The authoritative record	How the agent works with it	Choose it when
Repository	The markdown file	Reads and edits the file; the ticket links the commit	Engineering owns the process, and you want one timestamp authority
Legacy system	The Jira, ServiceNow, or requirements-tool record	Reads the record at session start and writes the outcome back through an MCP server in the same session	Auditors or regulators already accept that system
Linkage only	Both, cross-referenced	Every file notes the record ID; every record holds the commit SHA of the file	You cannot pick a single source yet; start here

The Legacy-system configuration needs an MCP server for that system. For Jira, use the Atlassian Rovo MCP server at https://mcp.atlassian.com/v2/mcp; for GitHub issues, the GitHub MCP server. Add the Atlassian server in your tool:

Claude Code

claude mcp add --transport http atlassian https://mcp.atlassian.com/v2/mcp

Then run /mcp in a session to sign in.

Codex

codex mcp add atlassian --url https://mcp.atlassian.com/v2/mcp

Cursor

Install the Atlassian plugin from Cursor’s marketplace, or add the server to mcp.json:

{ "mcpServers": { "atlassian": { "url": "https://mcp.atlassian.com/v2/mcp" } } }

For authentication options and other trackers, see Atlassian MCP, project-management servers for Linear and others, and version-control servers.

Walk one feature through the chain

The following steps take the notifications ticket from the opening scenario through the whole chain. Each step names its prompt.

1. Capture intent. When all you have is a one-line ticket, make the agent interview you rather than writing the intent alone. Commit the result as intent/notifications/intent.md and have the product owner accept it.

   Copy-paste prompt: interview me into an intent

   I want to add in-app and email notifications when a teammate comments on a
   document. Interview me before writing anything. Ask one question at a time
   about users, triggers, delivery channels, opt-out, volume, edge cases, and
   constraints, and dig into the parts I have not thought about. When we have
   covered everything, write intent/notifications/intent.md with the sections
   Problem, Proposed outcome, Affected users and systems, Constraints, and Open
   questions. Put anything I could not answer under Open questions. Do not
   propose a design and do not write code.

   In Claude Code, the agent can ask through its AskUserQuestion tool, which gives you multiple-choice questions instead of a wall of text (present in v2.1.283).

2. Write the spec, then have the agent read it for gaps. Follow Design to produce spec.md. Before any plan exists, start a fresh session and have the agent read the spec against the code. This step catches the clashing table before it is written.

   Copy-paste prompt: read the spec against the codebase

   Read intent/notifications/spec.md. Do not write or change any files.
   1. Restate each requirement in one sentence.
   2. List every ambiguity or gap, and the question that would close it.
   3. Find the existing code, tables, and API patterns this feature touches,
      with file paths.
   4. Flag every place where the spec conflicts with the current architecture,
      for example a new table where an existing one could be extended.
   5. List each requirement that has no testable acceptance criterion.

   Close each gap in spec.md, not in the chat. A decision that lives only in a conversation is lost when the session ends.

3. Draft the plan in plan mode. Plan mode lets the agent read the code without changing it. Ask for a plan that reuses what exists and ends with a task list.

   Copy-paste prompt: draft plan.md with tasks

   Using intent/notifications/spec.md and what you found in the codebase, write
   intent/notifications/plan.md with these sections:
   - Files that change, with the existing file you use as the pattern for each.
   - Decisions: every choice with a real trade-off, the options, and your pick.
   - Tasks: an ordered checklist (- [ ]). Each task fits one focused session,
     names its files, states its acceptance check, and is followed by the test
     that proves it. Order by dependency: migration, then API, then UI.
   - Risks.
   - Proof: the exact commands that show the whole change works.
   Prefer dependencies already in package.json. Do not implement anything.

   Push back on the plan the way you would in a design review. For example: “The plan adds a notifications table. What are the trade-offs against extending events, and which one matches our existing patterns?” Then have the tech lead or the engineer accept plan.md and commit it.

4. Execute one task per turn. Each task is small enough to verify and to throw away. When the agent goes wrong on task 7, you lose task 7, not the feature.

   Copy-paste prompt: execute the next task

   Read intent/notifications/plan.md. Implement only the first unchecked task.
   Then run the test named in that task and the lint and type checks. If they
   pass, tick the task in plan.md and commit the code and plan.md together with
   a message that names the task. If the implementation has to depart from the
   plan, stop and tell me what and why instead of improvising. Stop after this
   one task.

5. Check the diff against the chain. Before the pull request goes to a human, run a review pass that compares what was built with what was accepted. Put the same pass in a repository-root REVIEW.md (template below); Claude Code’s managed Code Review reads it (research preview, Team and Enterprise). Local /code-review does not read it, so run the drift prompt below as an ordinary prompt instead. With Codex, pass it as the prompt: codex review "Follow REVIEW.md. Compare this branch with main against intent/notifications/spec.md and plan.md.". A custom prompt cannot be combined with --base (checked v0.157.1), so name the branch in the prompt.

   Copy-paste prompt: drift review against spec and plan

   Compare the diff on this branch with main against intent/notifications/spec.md
   and intent/notifications/plan.md. Do not change code. Report:
   1. Files changed that plan.md does not list.
   2. Tasks ticked in plan.md without a test that exercises them.
   3. Spec requirements with no test, or with a test that cannot fail.
   4. Behaviour in the diff that the spec does not ask for.
   Tag each finding Important or Nit, and quote the spec line it relates to.

6. Merge, then close the loop. The pull request carries the review findings and the test evidence. When the feature causes an incident or reveals a missing requirement, the record becomes a new intent.md — see Maintain.

How do you enter plan mode in Claude Code, Codex, and Cursor?

The chain is the same in every tool. What differs is how you keep the agent read-only while it plans, and where the plan lands. In all three, the plan only counts once it is a committed file: that file is what CI, review agents, and the next session read.

Claude Code

• Enter plan mode with Shift+Tab, /plan, or claude --permission-mode plan. From v2.1.283 (the latest channel), interactive terminal and VS Code sessions start in auto mode, so switch to plan mode deliberately; claude -p, the Agent SDK, sessions where settings set disableAutoMode, and sessions on a model that auto mode does not support still start in Manual.
• Press Ctrl+G to open the proposed plan in your external editor and edit it before you accept it.
• Ctrl+T toggles the built-in task list. Set CLAUDE_CODE_TASK_LIST_ID to share one task list across sessions. Treat that list as a working view; plan.md stays the record.
• Run claude -w notifications to work in a new Git worktree, and claude -c to continue the most recent conversation.

Codex

• Enter plan mode with /plan in the CLI.
• The update_plan planning tool is off by default since v0.152.0, so Codex does not keep a live checklist unless you enable tools.update_plan.enabled = true. Keep the tasks in plan.md, where they survive every session.
• Run codex --worktree for a session in a new managed Git worktree (v0.157.1), and codex resume --last to pick up the most recent session.
• For one task at a time without a chat, pass the “execute the next task” prompt to codex exec.

Cursor

• Pick Plan in the agent’s mode selector. Plan Mode “creates detailed implementation plans before writing any code” (Cursor docs, checked 2026-08-28).
• Save the approved plan into the repository as plan.md before you build, so reviewers, CI, and the other tools read the same file.
• Run the drift-review prompt from step 5 in a new Agent chat, so the reviewer does not inherit the context that wrote the code.
• Worktrees “let Agent work in isolated Git checkouts” (Cursor docs, checked 2026-08-28), which keeps a parallel task off your working branch.

For the full per-tool mapping of every stage, see the tool map.

Templates for each artifact

Copy these shapes into your repository. Replace the UPPER_SNAKE_CASE placeholders.

Template: intent.md

# Intent: INTENT_TITLE
Author: AUTHOR_NAME (TEAM). Status: draft | accepted. Ticket: TICKET_ID

## 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, accepted DATE)
Status: ready-for-plan

## Requirements and acceptance criteria
- R1: REQUIREMENT. Accepted when: CHECKABLE_CRITERION

## Architecture and design
DESIGN_DETAILS

## Out of scope
OUT_OF_SCOPE

## 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, accepted DATE)

## Files that change
FILE_LIST_WITH_REFERENCE_PATTERNS

## Decisions
DECISION: OPTIONS, CHOICE, REASON

## Tasks
- [ ] 1. TASK (files: FILES). Accepted when: CHECK. Test: TEST_COMMAND
- [ ] 2. TASK (files: FILES). Accepted when: CHECK. Test: TEST_COMMAND

## Risks
RISKS

## Proof
COMMANDS_THAT_SHOW_THE_CHANGE_WORKS

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

Template: REVIEW.md

# Review instructions

## Passes
Run four 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
- Drift: files changed outside plan.md, ticked tasks without tests

## Severity criteria
- Important: broken behaviour, 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.

If you would rather adopt the chain as a packaged framework, GitHub Spec Kit runs the same sequence through its /speckit-specify, /speckit-plan, /speckit-tasks, and /speckit-implement commands (github/spec-kit, checked 2026-09-26). See Spec Kit and spec-driven development for when plain markdown is enough.

Should you plan with a stronger model than you execute with?

Planning and execution reward different things. The plan needs the model to read widely, weigh trade-offs, and notice edge cases. A well-specified task is comparatively mechanical. Follow the site-wide rule: start on your tool’s default model, raise the effort for planning before you switch models, and switch only when your own evals show a gain.

When you do split the work, Claude Code has a built-in alias for it: opusplan uses Opus in plan mode and Sonnet for execution. In any tool, the committed plan.md is what makes the split possible, because the executing session reads the file rather than the planning conversation. For model choice, see model routing and the models hub.

The same split scales to a backlog. One thorough session audits the codebase and writes plans. Later sessions, or parallel ones in separate worktrees, execute them.

Copy-paste prompt: audit the codebase into plans

Audit this codebase for the highest-impact improvements: correctness bugs,
performance, security, missing tests, and tech debt. Do not fix anything. For
each finding, write a self-contained plan to docs/improvement-plans/NN-slug.md
with the files to change, the approach, the acceptance criteria, and the test
that proves it. Order the files by impact against effort. A separate session
will execute each plan without access to this conversation, so leave nothing
implicit.

How do you verify each hand-off without reading every line?

Each artifact carries the evidence for the next gate, so a reviewer checks the evidence, not every line of the diff.

• Spec to tests. Every requirement in spec.md has an acceptance criterion. Turn each criterion into a failing test before implementation starts — see executable acceptance criteria and test-driven development.
• Plan to proof. Each task names its test, and the Proof section names the commands. CI runs them; a human reads the result, not the code.
• Diff to plan. The drift review in step 5 flags files outside the plan and ticked tasks without tests. An agent runs it, and a human reads only the findings tagged Important.
• Pull request to production. The code owner accepts findings and test evidence; the release manager owns the production gate. See reviewing agent pull requests.
• Chain completeness. Before merge, confirm that the pull request links intent.md, spec.md, and plan.md, and that every task in plan.md is ticked or explicitly deferred.

Who signs off stays fixed: the acceptor column in the table at the top of this page. An agent can draft every artifact and review every diff, but it does not accept its own work.

When the artifact chain breaks and how to recover

The intent is too vague to plan. “Make notifications better” cannot produce a spec. Run the interview prompt, and put everything the requester cannot answer under Open questions. Do not start the spec until the product owner closes them.

The plan is too big. A plan with 40 or more tasks is several features. Split it into milestones that each deliver something a user can see, and ship the first before you plan the second.

The agent drifts from the plan in a long session. The planning conversation falls out of the context window, and the agent starts improvising. Name the plan file in every prompt, clear the context between tasks (/clear in Claude Code, /new in Codex, a new chat in Cursor), and resume from plan.md, not from the chat. See context windows.

The code and the plan diverge. Someone fixed a bug the plan did not foresee and never updated plan.md. The next session then trusts a stale plan. Make “update plan.md in the same commit” a rule in REVIEW.md, and let the drift review catch the misses.

The plan never left the tool. The approved plan exists only in a plan-mode draft or a chat, so review agents and CI cannot read it. Commit it as plan.md before the first task runs.

Two sources of truth disagree. The Jira ticket says one thing and spec.md another. Check which system your configuration names as authoritative, correct the other one, and record the commit SHA or record ID in both.

You skip the chain “just this once”. A one-file change can go straight to a task. Anything that touches a schema, a public API, or more than one layer gets at least spec.md and plan.md, because that is where the clashing-table class of mistake is caught.

Checklist: is the artifact chain working in your repository?

• You can point to one home for intent.md, spec.md, and plan.md.
• Each artifact type has one named source of truth.
• A new contributor can find the last accepted intent.md and the spec.md and plan.md derived from it without asking anyone.
• Every merged pull request in the last month links its plan.md, and its tasks are ticked or deferred.

Where to go next with the artifact chain

Plan: capture intent.md The first link in the chain, step by step.

Executable acceptance criteria Turn each requirement in spec.md into a failing test.

Human in the loop When to intervene during execution and when to let the agent run.

The AI-native SDLC The six stages that the chain connects.