AI-Native Prototyping Workflow

A team workflow for building prototypes with AI coding agents — spec-driven, phase-based, repeatable.

---

What this is

A working starter kit for our team to adopt spec-driven development with AI coding agents. It's Claude Code-first (the agent team lives in .claude/agents/), but everything it produces is plain Markdown — AGENTS.md, constitution.md, spec.md, plan.md, PROGRESS.md — so the artifacts port to Cursor, Copilot, and the rest. The automation — auto-discovered agents and /-skills — is Claude Code-specific; in other tools you run the same workflow by hand (see the quickstart). Fork it per project and you'll ship prototypes faster without sacrificing code quality or team handoff.

The mental model: you decide what and why; the agents do the typing. Nothing gets built until a spec and plan are written and approved. Work happens in small phases that each fit one AI session, and PROGRESS.md carries the memory between them.

---

The three commitments

1. Spec before code, always. No agent writes a line until the human and the AI agree on what's being built.
2. Phases that fit one context window. Long sessions drift; short, well-scoped phases stay sharp.
3. A small team of specialised agents, not one generalist that does everything.

The agents do the typing. The humans do the deciding. That balance is the whole point.

---

The workflow at a glance

┌─────────────────────────────────────────────────────────────────┐
│  Loop 1: SHAPE (one-time per feature)                           │
│                                                                 │
│   1. Constitution → 2. Specify → 3. Clarify → 4. Plan           │
│      (rules)        (what/why)   (edge cases)  (how/phases)     │
│         ↑                                              ↓        │
│         └──────────  human review at each gate  ───────┘        │
└─────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────┐
│  Loop 2: BUILD (repeats per phase)                              │
│                                                                 │
│   5. Tasks → 6. Implement → 7. Verify → PROGRESS.md updated     │
│                                                                 │
│         ↑  human approves phase before next starts  ↓           │
└─────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────┐
│  Loop 3: SHIP (once all phases done)                            │
│                                                                 │
│   Demo it → harden only if you're keeping it                    │
└─────────────────────────────────────────────────────────────────┘

---

What's in this repo

ai-prototyping-workflow/
├── README.md                 ← you are here
├── constitution.md           ← fork this per project; defines the rules
├── AGENTS.md / CLAUDE.md     ← agent contract (AGENTS.md is source; CLAUDE.md points to it)
├── init.sh                   ← one-command fork into a new repo
├── .claude/agents/           ← 6 agents, one job each
│   ├── analyst.md
│   ├── architect.md
│   ├── planner.md
│   ├── doc-fetcher.md
│   ├── implementer.md
│   └── reviewer.md
├── .claude/skills/           ← conditional steps, invoked by hand
│   ├── visual-check/         ← brand alignment for UI work
│   └── harden/               ← refactor passes, if you keep the prototype
├── specs/_template/          ← copy this into specs/<your-feature>/
│   ├── spec.md
│   ├── plan.md
│   └── phases/phase-template.md
├── specs/example-link-checker/  ← a filled-in worked example (lean path)
├── templates/
│   ├── PROGRESS.md           ← living state + final outcome decision
│   └── ARCHITECTURE.md       ← generated at the end (if the prototype continues)
└── docs/
    └── quickstart.md         ← walkthrough of your first prototype

---

The agent team

Six agents, each with one clear job that produces a concrete, reviewable output — a file on disk or a structured report. Two conditional steps — visual checks and hardening — are skills (/visual-check, /harden), invoked by hand when you need them.

Agent	Job	When to invoke	Produces
analyst	Validate the user story; ask clarifying questions	Specify & Clarify	spec.md, clarifications.md
architect	Decide tech stack, types, state shape, folder structure	Plan	plan.md architecture sections
planner	Break the plan into phases that each fit one session	Plan & Tasks	Phase breakdown + phase-N-tasks.md
doc-fetcher	Fetch and summarise external library APIs	Before any phase with a non-trivial dependency	specs/<feature>/refs/<lib>.md
implementer	Build one phase end-to-end with tests	Implement	Code, tests, PROGRESS.md update
reviewer	Challenge the plan; spec-drift check per phase (review-only)	Gate 3, then Verify	Review notes

Why six and not twenty: fewer, sharper agents beat more, fuzzier ones — start simple and add an agent only when a real gap appears.

The two skills:

Skill	Job	When to run
/visual-check	Screenshot + brand alignment for UI work	After any UI-touching phase (frontend only)
/harden	Three refactor passes + ARCHITECTURE.md	After the demo, only if you're keeping the prototype

Both are manual-only so they never fire on their own or bypass a human gate.

---

Human gates — non-negotiable

These are the four moments where the workflow stops and waits for a human. Skip any of them and the workflow degrades into vibe coding with extra steps.

1. Constitution approval — the rules of the road
2. Spec sign-off — what we're building
3. Plan review — how we're building it (expect 2–4 revisions; this is real engineering time)
4. Per-phase approval — proof this phase works before the next one starts

---

Getting started — your first prototype

1. Fork this repo into your project.
2. Edit constitution.md to match your stack (Python? TypeScript? Kedro?).
3. Copy specs/_template/ to specs/<your-feature>/ and fill in spec.md.
4. Open Claude Code in the repo — the agents in .claude/agents/ are auto-discovered. (On Cursor/Copilot, see Running it outside Claude Code.)
5. Run the loop: analyst validates the spec → architect plans → planner phases it → implementer builds each phase (the reviewer checks each) → demo it → run /harden only if you're keeping it.
6. Update PROGRESS.md after every phase. This is the single most important habit.

New to the workflow? Read docs/quickstart.md for the exact commands and the recovery playbook for when something goes wrong. A complete worked example lives in specs/example-link-checker/ — read it to see what each artifact should look like.

Tiny, throwaway prototype? Use the lean path — same four gates, far less ceremony (skip Clarify, one phase, short PROGRESS.md). See docs/quickstart.md.