Home

Building Prototypes with AI.

A simple, repeatable way for our team to go from "I have an idea" to "here's a working prototype" using AI coding agents.

---

The problem

The first hour with an AI coding tool feels like magic. You describe what you want, and code appears.

Then it drifts.

By the fourth hour the model has quietly forgotten a decision it made earlier. You explain the same thing for the third time. A couple of days later you're staring at a few thousand lines.

---

The idea

Nothing gets built until we've written down what we're building and how. The work happens in small phases, each one small enough to finish in a single focused sitting. And one file, PROGRESS.md, keeps the running notes, so the AI never has to "remember." It reads where things stand and carries on.

The idea is to do better then "Vibe coding"

---

The team: a few specialists, not one know-it-all

One AI trying to do everything does all of it a little badly. So we use a small crew, each with one clear job.

Who	What they do
analyst	Makes sure we actually agree on what we're building, before a line of code
architect	Picks the tech and decides how the pieces fit
planner	Chops the work into small, safe chunks
doc-fetcher	Looks up the real docs for any library we'll use, so nobody guesses
implementer	Writes the code and the tests, one chunk at a time
reviewer	Pokes holes in the plan, then checks each chunk against what we asked for
/visual-check	For UI work: does it actually look like our product?
/harden	Once we decide to keep it: tidy up and leave a map for the next person

---

The whole flow, in one picture

flowchart TD
    A(["Start: run  bash init.sh  to copy the kit into a fresh repo"]) --> B["Edit constitution.md<br/>your stack and standards"]
    B --> G1{{"Gate 1: approve the rules"}}

    subgraph shape ["1 · Shape the idea"]
        G1 --> C["Write spec.md<br/>what & why"]
        C --> D["analyst<br/>asks the questions that catch misunderstandings early"]
        D --> G2{{"Gate 2: sign off the spec"}}
        G2 --> E["architect<br/>picks the tech & structure"]
        E --> F["planner<br/>slices it into small phases"]
        F --> R["reviewer<br/>pokes holes in the plan"]
        R --> G3{{"Gate 3: approve the plan"}}
    end

    subgraph build ["2 · Build it, one phase at a time"]
        G3 --> H["doc-fetcher<br/>grabs library docs, if a phase needs them"]
        H --> I["implementer<br/>writes the code + tests"]
        I --> J["reviewer + /visual-check<br/>check this phase"]
        J --> G4{{"Gate 4: approve the phase"}}
        G4 -->|"more phases left"| H
    end

    G4 -->|"all phases done"| K["Demo it"]

    subgraph ship ["3 · Ship or shelve"]
        K --> L{"Keep it?"}
        L -->|"yes"| M["/harden<br/>tidy up + write the map"]
        L -->|"no"| N(["Done. The lesson is logged."])
    end

    M --> O(["A working prototype"])

Loading

Read it top to bottom: set up once, shape the idea, build it phase by phase, then ship or shelve. The four six-sided stops are you the moments the work pauses and waits for a human.

---

The four moments you're in charge

The agents do the work, but they stop and wait for you at four points. These are the whole reason this doesn't slide back into vibe coding.

1. The rules — you approve constitution.md.
2. The spec — you agree on what we're building.
3. The plan — you agree on how, before any code is written.
4. Each phase — you see it actually work before moving to the next one.

---

How you actually start (your first hour)

# 1. Copy the kit into a fresh repo
bash init.sh ../my-prototype

# 2. Edit constitution.md to match your stack        →  you approve   (Gate 1)

# 3. Start a feature
cp -r specs/_template specs/my-feature               #  then write spec.md

Then, in your AI tool:

Use the analyst subagent to validate the spec        →  you sign off   (Gate 2)
Use the architect subagent to design the plan
Use the planner subagent to break it into phases
Use the reviewer subagent to challenge the plan      →  you approve    (Gate 3)

Use the implementer subagent to build Phase 1
Use the reviewer subagent to check Phase 1           →  you approve    (Gate 4)
   ↳  repeat for each phase

# demo it, then decide: keep or shelve
/harden                                              #  only if you're keeping it

On Cursor or Copilot the steps are identical. You just point the chat at the role file ("read .claude/agents/analyst.md and act as that agent") instead of typing "Use the … subagent."

---

See it before you try it

There's a complete worked example in the repo: specs/example-link-checker/. It's a tiny feature taken all the way through — a real spec, plan, phase tasks, and a filled-in PROGRESS.md. Read it to see what "good" looks like before you write your own.