How it works

How it works

The roles in one picture

flowchart LR
    you((You))
    router["router<br/>pa-session"]
    planners["planners"]
    critic["critic"]
    review["review"]
    discuss["discuss"]
    expert["expert<br/>one per task"]
    coder["coder"]
    retrievers["retrievers"]
    ledger[("hooks and<br/>usage ledger")]

    you <--> router
    you -. "/discuss" .-> discuss
    router --> planners
    router --> expert
    router --> critic
    router --> review
    expert --> coder
    expert --> retrievers
    coder --> retrievers
    planners --> retrievers
    ledger -. statusline .-> you

Loading

You talk to one session, the router. The router asks a planner for each plan and shows it to you; after you approve it, it runs one expert per task, each in a fresh context. The expert briefs coders, who edit, build, test and commit, and retrievers, who look things up and return only the answer. Every change an expert wants to make to the plan goes to the critic. A task that needs your eyes pauses, and the review agent turns its results into numbered decisions for you. /discuss opens a thinking partner beside all of this. Hooks record every request in a local usage ledger, and the statusline shows it.

A phase, from plan to close

flowchart LR
    gen["generation plan<br/>phases and milestones"] --> plan["phase plan<br/>drafted by the planner"]
    plan -->|you approve| tasks["tasks<br/>one expert each"]
    tasks --> check{"milestone<br/>check"}
    check -->|green| close["PhaseEnd<br/>recap, decisions, audit"]
    check -->|red| tasks
    close --> plan

Loading

A phase has two gates: your approval of its plan, and a milestone check a machine can run. Between them nobody stops to ask; a task that hits a wall comes back blocked with its evidence and a recommendation.

The agents

Role	Agent	Model, effort	What it does
Router	pa-session	Sonnet 5.5, medium	The one session you open. Reads the seed, relays plans and questions, spawns one expert per task, runs the closing scripts. Never does task work.
Planners	planner-gen, planner-phase	Opus 5.5, medium	Draft the generation plan (phases and milestones) and each phase plan (tasks with their files, done-when and verify command).
Experts	expert-opus55; expert-fable	Opus 5.5, medium; Fable 5.1, medium	Run one task each in a fresh context: read the plan, decide, brief coders and retrievers, write the task's log and summary. expert-fable takes the tasks whose result rests on a judgment no test can settle.
Coder	coder-opus55	Opus 5.5, medium	The edit, build and test loop for one briefed change; commits when the tests pass.
Retrievers	retriever-code, retriever-digest, retriever-web	Sonnet 5.5, medium	Answer one question about the code, a long document or the web, and return only the answer.
Critic	critic	Fable 5.1, medium	Judges every plan change an expert proposes, and brings you only what it cannot settle.
Review	review	Fable 5.1, medium	Turns a review pause into numbered decisions, each with a recommendation.
Discuss	discuss, discuss-high, discuss-max	Opus 5.5, medium, high or max	Your thinking partner for one discussion; writes the record and the plan edits when you say proceed.
Auditor	auditor	Fable 5.1, medium	Reads a closed phase's audit of what agents carried in their context and proposes tools that would cut it.
Memory curator	memory-curator	Fable 5.1, medium	At the start of each generation, retires memories, techniques and rules that no longer apply.
Plain	plain	Fable 5.1, high	A design session with you that bypasses the router (claude --agent plain).

The expert-fable, judge and plain rows follow your plan's preset (Install).

What lives in your repository

• phase-ends/: the current phase's plan, task summaries and logs, and one PhaseEnd per closed phase.
• GENERATION_PLAN.md: the phases of the current generation with their milestones.
• HOW_WE_WORK.md: the card of standing facts each role reads a slice of.
• rules/ and cookbook/: the rules the project keeps and the techniques it learned, one file each, with an index.
• .claude/: the agents, the skill, the commands and pa.json; tools/: the scripts the agents call.