Artifact Shapes — V1

Artifacts are the audit trail of AI work. They live in the project repo at .claude/artifacts/<feature-id>/, versioned with the code, and are indexed in the control plane's Postgres for fast admin queries. Source file: spec/v1/artifacts/README.md.

Artifact layout

project-repo/
└── .claude/
    └── artifacts/
        └── FEAT-42-recurring-payments/
            ├── 01-spec.md          # Feature spec
            ├── 02-design.md        # High-level design + Mermaid diagram
            ├── 03-stories.md       # Decomposed user stories list
            ├── stories/
            │   ├── STORY-101.md    # Per-story: description, AC, solution
            │   └── STORY-102.md
            ├── tasks/
            │   ├── DEV-201-transcript.md  # Full executor transcript
            │   ├── DEV-201-diff.patch     # Final diff
            │   ├── QA-202-report.md       # QA findings + screenshots
            │   └── ...
            ├── retrospective.md    # Auto-generated at feature Done (P3+)
            └── cost.json           # Tokens/minutes/iterations per task

Artifact files

File	Description	Phase
01-spec.md	Feature spec: objectives, in/out of scope, acceptance criteria	P1
02-design.md	High-level design + impacts + Mermaid diagram	P1
03-stories.md	Decomposed user stories list	P1
stories/STORY-*.md	Per-story description, acceptance criteria, solution notes	P1
tasks/DEV-*-transcript.md	Full executor transcript for the dev task run	P0
tasks/DEV-*-diff.patch	Final diff produced by the executor	P0
tasks/QA-*-report.md	QA findings, test plan, screenshots	P1
retrospective.md	Auto-generated retrospective at feature Done	P3
cost.json	Tokens, minutes, and iterations per task	P2

Raw source (spec/v1/artifacts/README.md)

# Per-feature output artifacts (spec)

Artifacts are the audit trail of AI work. They live in the **project repo** at `.claude/artifacts/<feature-id>/`, versioned with the code, and are indexed in the control plane's Postgres for fast admin queries.

## Layout

```
project-repo/
└── .claude/
    └── artifacts/
        └── FEAT-42-recurring-payments/
            ├── 01-spec.md                 # Feature spec (objectives, in/out of scope, AC)
            ├── 02-design.md               # High-level design + impacts + Mermaid diagram
            ├── 03-stories.md              # Decomposed user stories list
            ├── stories/
            │   ├── STORY-101.md           # Per-story: description, AC, solution
            │   └── STORY-102.md
            ├── tasks/
            │   ├── DEV-201-transcript.md  # Full transcript from Dev Task run
            │   ├── DEV-201-diff.patch     # Final diff
            │   ├── QA-202-report.md       # QA findings + screenshots
            │   └── ...
            ├── retrospective.md           # Auto-generated at feature Done (P3+)
            └── cost.json                  # Tokens/minutes/iterations per task
```

## Shape

Schema for each file lives in this directory (`*.schema.json`) and is generated from Zod in `packages/schema/`. The shapes are part of the versioned spec so future tooling (dashboards, search) can rely on them.

Files added in later phases:
- `retrospective.md` — P3 (with `core:retrospective` skill)
- `cost.json` — P2 (with multi-agent cost tracking)