What PA3 does

What PA3 is and does

Project Architect (PA3) is two things at once. It is a way to run a long project with Claude Code: a written plan you approve, work done task by task against it, and a record of everything the project learns. And it is a way to spend less of your plan's allowance doing it: each piece of work runs in its own small context, and the statusline shows what that saved. This page explains the working parts in plain words. How it works shows the roles in a picture, and A day in the life shows them at work.

The constitution

Every project starts from PROJECT_CONTEXT.md, its constitution: what you are building and why, for whom, the key decisions, the constraints, and what success looks like. You write it once, on your own or by working it out with Claude in a plain session (claude --agent plain). PA3 plans from it and never edits it. Everything else in the project can change; the constitution is the fixed point.

Generations

A generation is one big stretch of the roadmap: a handful of phases that together reach a larger goal. Its plan, GENERATION_PLAN.md, lists the phases in order, each with its scope and a milestone, and says why they run in that order. The generation planner drafts it from the constitution, you approve it, and only that planner ever writes it. Most projects need two or three generations: a new one starts only when something fundamentally new needs the previous one stable and proven.

When the last phase of a generation closes, PA3 assembles a GenerationEnd, the generation's record, built from its phase records with a recap in plain words. The next session opens the new generation with a short ceremony before any planning: a curator retires the memories, techniques and rules that only mattered to the old generation, an auditor reviews what the agents carried in their context, and every deferred idea is sorted into a phase, a later generation or the bin.

Phases

A phase is a piece of work that ends in something you can check: a test suite that passes, a program that runs, output that matches. Its plan, phase-ends/current/PHASE_PLAN.md, is drafted by the phase planner and holds the milestone, the context every task needs, and the tasks. Each task names the files it touches, what done means, the command that proves it, and the earlier task summaries its expert should read.

A phase has two gates:

• The plan. The router shows you the planner's summary, and nothing starts until you approve it. From then on the plan changes only through a script that logs every change, and every change an expert wants goes to the critic first. What the critic cannot settle comes to you as a question, and an answer that changes the milestone or the scope sends the phase back to the planner.
• The milestone. When the last task is done, a closing expert runs the milestone's check. Only a green check closes the phase: the check decides, not anyone's say-so.

Between the gates the router runs the tasks in order, one expert per task, each in a fresh context, and nobody stops to ask. A task marked for review waits for your decision on its results. You can leave a note in INBOX.md at any time; the router reads it between tasks.

When the phase closes, PA3 writes its record, PhaseEnd_Phase<N>.md: a plain-English recap, the decisions that still bind, what was deferred and to where, every agent run with what it saved, and an audit of what the agents carried in their context. The phase's working files move to phase-ends/phase-<N>/, and the next session plans the next phase.

The roles

You talk to one session, the router, which relays and routes and never does task work itself. Planners draft the plans. An expert takes one task in a fresh context, decides how to do it, and briefs coders, who edit, build, test and commit, and retrievers, who read the code, long documents or the web and return only the answer. The critic judges changes to the plan, the review agent turns a task's results into decisions for you, and /discuss opens a thinking partner beside all of it. How it works lists every agent with its model.

Memory across sessions

No session relies on the one before it. Everything the next session needs is in files in your repository:

• The seed. At every start PA3 writes a short summary of where the project stands: the phase, the next task, your inbox, and the deferred items that belong to the phase ahead. The router reads that instead of the history.
• The card. HOW_WE_WORK.md holds the standing facts: the tools, paths, conventions and decisions that bind. It is kept under a size cap, and each role reads only its own slice.
• Task summaries and logs. Every task ends with a full log and a short summary. The next task reads the summaries it is pointed to, never the logs, so an expert starts from a few pages instead of a transcript.
• Phase and generation records. The PhaseEnds and GenerationEnds are the project's history, and history is append-only: nothing is deleted, and a retired file moves to docs/retired/. phase-ends/TASK_INDEX.md, RESEARCH_INDEX.md and DISCUSSION_INDEX.md index what every phase did, learned and discussed.
• Claude Code's own memory. Claude Code keeps a memory folder for each project; PA3 moves it into the repository (.claude-state/memory/), so it is versioned and a fresh machine gets it back. PA3's agents don't write to it, because their facts go to the card, the rules and the cookbook, and the curator trims it at each generation start.

So a session can start on another machine, after weeks away, or after a crash, and pick up where the work stopped.

What the project learns

Four stores keep what the project learns. Each holds one file per entry and an index that agents search rather than read whole.

• Rules (rules/): how work is done on this project. PA3 ships 32. A task that finds a new one proposes it, the next phase planner weighs it, and you ratify it with one question when you approve that plan. A replaced rule keeps its file with a note; nothing is deleted.
• The cookbook (cookbook/): techniques that worked, from a build trick to a debugging recipe. An expert marks a finding worth keeping in its task summary, and the closing expert adds it at the phase end. Agents check the cookbook before recurring work.
• Research reports (research/): what the retrievers found in the code, in documents or on the web, with their sources. An expert cites a report by its id instead of pasting it.
• Discussions (discussions/): the record of each /discuss session, with its decisions and the plan edits they led to, and a line for every note you left in the inbox saying where it went.