# Project Architect 3.0 The methodology that turns Claude Code into a governed project architect: it takes a rough idea, an existing codebase, or an old-methodology project and produces a scoped, phased, documented build — then runs the build phase by phase with a living document system, pinned models, measured costs and hard stops between phases so any fresh session can reconstruct exactly where the project is and how to work on it. --- ## For humans Two commands install the system. Once per machine, from the package folder: python pa_install.py --root --yes Once per project, from the project's own root: python pa_install.py --project . --yes After that you open a terminal in the project and type `claude`. The session reads a seed, determines where the project is (planning a generation, planning a phase, the work loop, a review pause) and starts. You interact at a few moments: approving a plan, answering a review's decisions, responding when the critic says the developer must decide, answering the close question, allowing a command outside the allow rules, and opening `/discuss [model] [effort]` when you want to think alongside the system (Opus 5.5 at medium unless you opt into Fable or Sonnet, or high or max effort; `/thoughts` stays an alias for one release). Everything else — spawning experts, briefing coders, running tests, committing, closing phases — happens without a keypress. The roles in one paragraph: a planner drafts the plan you approve; a router spawns one expert per task and never does task work itself; the expert thinks, decides and briefs coders (which run the edit-build-test loops) and retrievers (which look things up); a critic judges every plan change an expert proposes; a review agent turns a review pause into numbered decisions for you. A day in the life: you launch with `claude`, the router reads the seed and picks the next task, spawns the expert in the background and waits. The expert reads the plan, spawns a coder, waits idle in the background until the coder's hand-back wakes it (a per-session warmer daemon pings idle agents with `.` before the cache TTL, at 285 s or 3,300 s, relayed by the router's Monitor; the agent answers `.`), writes the task log and summary, and returns done. The router marks the task done and moves to the next. When every task is done the closer verifies the milestone, writes the phase-end record and archives the phase. You relaunch for the next one. Where to look: `HOW_WE_WORK.md` for standing decisions, tools and environment; `phase-ends/current/PHASE_PLAN.md` for the live plan; `phase-ends/TASK_INDEX.md` for what was done; the cookbook (`cookbook/INDEX.md`, grep by tag) for techniques; `rules/INDEX.md` for every rule in force. --- ## Philosophy The creed, carried from 1.3.0 and amended by three generations of experience: - The constitution is permanent. The rules, the cookbook, the standing decisions and the phase records are the living system. Never conflate the layers. - History is append-only. A rule is never deleted; it is superseded with a note. A phase record is never rewritten; a correction is a new record. A file is never removed from the repository; it moves to `docs/retired/`. - Rules are living. They are proposed at phase ends, adjudicated by the planner, and added to `rules/` as individual files. The expert writes `Rule candidate:` in the task summary; the phase planner adjudicates. - Every phase milestone is an observable, machine-checkable outcome. The gate, not anyone's say-so, is the arbiter. - Generations are evolutionary leaps, not version bumps. A new generation only when a fundamentally new capability requires the prior generation stable and proven. Most projects need two or three. - Knowledge compounds only if captured: consult the cookbook before, feed it after, and write context-dependent findings during the session that produced them. New in 3.0: one task per fresh context (the expert knows its task, not the whole phase). The plan is the contract between the developer and the system; `plan_edit.py` is the only writer. Nothing enters a context that a pointer could replace: a summary id instead of a pasted body, a `file:line` instead of a code block, a report id instead of a retriever's raw output. The plan's `reads:` line names what the expert loads; everything else is a retriever dispatch. --- ## The document system The five layers of 2.0 are replaced by a deeper structure. Precedence runs top to bottom; where wording differs, the higher layer governs. 1. `CLAUDE.md` (about 190 tokens): the roles line, pointers to the project-architect skill, `HOW_WE_WORK.md`, the live plan and the constitution. It is not the rules; it points at them. The rules themselves live in `.claude/skills/project-architect/SKILL.md` and each agent file names that skill under `skills:`. Leaf agents (retrievers, the critic) carry `omitClaudeMd: true`, which drops `CLAUDE.md` and the auto-memory index from their context; the critic keeps the skill because it must quote the rules. 2. The project-architect skill: eleven numbered sections (precedence, roles, output, proportionality, git, verification, hygiene, knowledge, the developer, long compute, house style) plus a project-rules section that holds project-specific additions. This is what governs every expert and coder. 3. `HOW_WE_WORK.md`: standing decisions, environment, tools, the docs map. The living reference for how this project runs on this machine. Target size about 3,500 tokens. 4. `PROJECT_CONTEXT.md`: the constitution. Permanent and static; never edited after generation. 5. `GENERATION_PLAN.md`: the generation-level roadmap (phases, milestones, scope, ordering rationale). Changed only at generation boundaries. 6. `phase-ends/current/PHASE_PLAN.md` and its `tasks/`, `logs/`, `research/`, `discussions/` directories: the live work of the current phase. The plan is frozen at approval and changed only through `plan_edit.py`. Task summaries, logs and research reports are written by the agents that do the work. At phase close, `phaseend_index.py archive` moves `current/` to `phase-ends/phase-/`. 7. `PhaseEnd_Phase.md` and `GenerationEnd_.md`: the append-only build history. Assembled by scripts from the phase's task logs and summaries, the milestone verification, and the closer's recap. 8. `rules/` (one file per rule), `cookbook/` (one file per technique), `docs/ops/` (environment and build references). Auto memory stays on. Claude Code's auto memory keeps one directory per repository under `~/.claude/projects//memory/`. The first 200 lines or 25 KB of the index load at session start for every agent that reads `CLAUDE.md`. PA3 keeps it enabled and curates it at every generation start: standing facts belong in `HOW_WE_WORK.md`, rules in `rules/`, techniques in the cookbook. The memory index is kept small and current by a curator agent rather than switched off. The memory directory lives in the repository (`.claude-state/memory/`) behind a junction so a fresh machine restores it with `pa_install --project`. --- ## Roles | Role | Agent | Model | Effort | Spawns | Tools | |---|---|---|---|---|---| | Planner (generation) | planner-gen | Opus 5.5 | medium | retrievers | — | | Planner (phase) | planner-phase | Opus 5.5 | medium | retrievers | — | | Router | pa-session | Sonnet 5.5 | medium | experts, planners, critic, review, discuss, curator | — | | Expert (default) | expert-opus55 | Opus 5.5 | medium | coders, retrievers | — | | Expert (hard, `effort: high`) | expert-fable | Fable 5.1 | medium | coders, retrievers | — | | Coder (default) | coder-opus55 | Opus 5.5 | medium | retriever-code | — | | Retriever (code) | retriever-code | Sonnet 5.5 | medium | — | Read, Grep, Glob, Write | | Retriever (digest) | retriever-digest | Sonnet 5.5 | medium | — | Read, Grep, Glob, Write | | Retriever (web) | retriever-web | Sonnet 5.5 | medium | — | WebSearch, WebFetch, Write | | Critic | critic | Fable 5.1 | medium | — | — | | Review | review | Fable 5.1 | medium | retriever-code, retriever-digest | — | | Discussion | discuss, discuss-high, discuss-max | Opus 5.5 | medium, high, max | — | — | | Memory curator | memory-curator | Fable 5.1 | medium | — | — | Models and efforts are pinned per agent file; the developer never touches `/effort` or `/model`. The cost structure follows from the pinning: Opus 5.5 is the default builder and expert (coders, the planners since 3.9.5 and the medium-effort expert), Fable 5.1 the thinker for hard tasks ( the critic, the hard-tier expert), and Sonnet the middle ground (the router, all three retrievers). The router runs on Sonnet because it is purely mechanical: it reads a seed, picks the next task, spawns an expert and waits. Judgment lives in the subagents. The phase planner marks `effort: high` only when a task's done-when rests on a judgment no test can arbitrate (a design decision, a harness probe, a proof read from evidence), never for size or importance; at most one task in five per phase plan, each high mark's judgment named in the plan's Rationale. The maximum spawn depth is three: router (0), expert (1), coder (2), retriever-code (3). The depth is set explicitly in the environment (`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=3`) so a harness default change cannot silently break it. A coder's retriever is a leaf by construction (no `Agent` tool) so the chain cannot grow further. The expert delegation rule: a coder for any build or test loop, more than about twenty lines, or more than one file. The expert may make one edit of twenty lines or fewer itself with one verification run. Two coder failures with different causes return `blocked`. Every role reads a file over `guard.whole_read_chars` (20,000 chars by default) by range only: a Read without `offset`/`limit` on such a file is denied, and the denial carries the file's outline inline (what `tools/outline.py ` prints: header block, symbols with their intent lines, section comments; capped at 60 lines, Markdown at depth 2) and ends "Read the ranges you need with offset and limit". Retrievers get the same map without a shell; the served outline writes the same `outline` credit note as the script. The audit's `whole_reads` row mirrors the same threshold. A retriever's report, when written, lands first at `research/pending/-.md`; the retriever returns `REPORT: pending/`, and the file is adopted into `R-.md` by `tools/research_add.py adopt`, run at the expert's hand, at `task_log.py finish`, and at `phaseend_index.py assemble`. --- ## Lifecycle The launcher (`tools/launch.py`) checks the project's state and determines the mode: - No `GENERATION_PLAN.md`, or all its phases closed: planner-gen mode. - Generation open, no approved phase plan: planner-phase mode. - `REPLAN.md` present: planner-phase in replan mode. - `REVIEW.md` present: review mode. - Otherwise: the router loop. In planner mode the router spawns a planner (generation or phase) which explores only through retrievers, drafts into `.run/`, and returns a summary. The router puts the summary in front of the developer through the question picker: approve, show the full plan first, or send changes back. On approval the router writes the plan with `plan_edit.py from-draft`, stamps it with `plan_edit.py approve`, records ratified rules, and commits. From that point `plan_edit.py` is the only writer of the plan file; a `PreToolUse` hook denies any other write to it. In the router loop, at every task boundary the router consumes `INBOX.md` if the developer left notes, asks `plan_edit.py next` for the next runnable task, stamps the statusline and spawns the expert in the background. Then it ends its turn; the harness wakes it when the expert returns. While an expert runs, the statusline shows the task, the agent, the context and the time elapsed. The expert reads the plan's Context, Interfaces and Cookbook sections, its own task entry, and only the summaries the entry names. It works, spawns coders and retrievers as needed, and returns its contract. When an expert returns `done`, the router marks the task done and goes to the next task. When it returns `question` or `blocked`, the router sends the question to the critic. A `handoff` (context crossed the 350,000-token threshold) triggers a respawn: the expert writes `TASK_PROGRESS.md`, commits and returns; the router respawns the same agent with the progress file in its brief. The respawn archives the file to `logs/T.progress.md` when done. When `plan_edit.py next` prints `NONE`, the router asks the developer once whether anything else should come first, then spawns the phase closer (`expert-opus55`). The closer runs `phaseend_index.py verify`, which executes every `verified by:` clause of the milestone and prints GREEN or RED per clause. It writes `RECAP.md`, promotes techniques from `generalizable:` lines to the cookbook, commits, and returns `MILESTONE: green` or `red`. On green the router assembles, lints and archives the phase, commits, and gives the developer the recap with the agent-runs table. The session ends with `Relaunch: /clear then go`. The carry audit rides on the close. `phaseend_index.py assemble` runs `pa_ledger.py audit --phase`, which walks the phase's transcripts once (zero tokens, repeatable) and writes its tables into the PhaseEnd's Audit section: reads by file and role, writes by file, results by kind, whole-plan and tool-source reads, spilled results read whole, noise, carry per request against the previous phase, and candidates promised beside measured. Rows past the thresholds become `- flag:` lines; the seed then carries `Audit flag:` and the router spawns the auditor (Fable, medium effort) before the next planner. The auditor judges tables, never transcripts: one verdict per flagged row (tool, split, guard, script-fix, leave), project-level fixes applied through coders, harness-level ones written as `Tool candidate:` lines in `phase-ends/current/AUDIT.md` with what the tool does, what the model did instead, the occurrences, the saving on the credit formula and the build size. The planner copies them into its return; the developer ratifies each with one picker question at plan approval; a built tool earns the savings credit automatically and the next audit prints measured beside promised. At a generation boundary, `genend_index.py assemble` builds the `GenerationEnd` from the phase-end files. The next `claude` opens in planner-gen mode and the generation-start ceremony (the memory curator, then the auditor over the closing generation's last PhaseEnd) runs before the new planner drafts. Every `/discuss [model] [effort]` session that proceeds writes a discussion record with a `Status:` tag (`open`, `executed`, `planned: T`, `deferred:`, `dropped`, `failed`) and an index line; the phase's discussion lines fold into the PhaseEnd on archive, and cumulative history lives in `phase-ends/DISCUSSION_INDEX.md`. A record's `## Deferred` lines and an inbox's `later:` lines both flow into the PhaseEnd's `## Deferred` block, so a later planner either plans the item as a task or leaves it deferred with one line of reason. Every configured MCP server adds its instruction block to every session, whether or not the task at hand needs it; `doctor` lists the servers found in `~/.claude.json` and the project's `.mcp.json`, and the standing advice is to disable the ones a project does not use. --- ## Contracts Every role returns a fixed-format contract of at most 300 tokens. Nothing else. The contracts are the system's only inter-agent communication; they carry status, pointers and one-line recommendations, never pasted content. Expert brief (router to expert): ``` TASK: T3 — PLAN: phase-ends/current/PHASE_PLAN.md HOW: HOW_WE_WORK.md LOGS TO READ: phase-ends/current/tasks/T1.md, tasks/T2.md CODER: opus55 | none EFFORT: high | medium PROGRESS: <path> (respawn only) NOTE: <developer text or critic's WHY> (only when present) DONE WHEN: <from the task entry> RETURN: the expert contract, ≤300 tokens, nothing else. ``` Expert return: ``` STATUS: done | blocked | question | handoff | review LOG: phase-ends/current/tasks/T3.md CTX: 142k COMMIT: abc123 | none MILESTONE: green | red | n/a (phase-end only) RECOMMENDED: <one line> QUESTION: <one paragraph; only if question> ``` Coder brief (expert to coder): ``` CODER TASK: T3.c1 — <one line> CHANGE: <what to implement; files and functions; ≤8 lines> INTERFACES: <named entries from the plan's ## Interfaces> CONSTRAINTS: <2–4 lines> BUILD/TEST: <exact commands; what green means> DONE WHEN: <machine-checkable> LOG: phase-ends/current/logs/T3.c1.md RETURN: the coder contract, ≤300 tokens. ``` Coder return: ``` STATUS: done | partial | blocked CHANGED: path:lines, … (≤6 entries) VERIFIED: <command -- result> LOG: phase-ends/current/logs/T3.c1.md CTX: 96k COMMIT: def456 | none DEVIATIONS: <one line | none> BLOCKER: <one paragraph; only if partial/blocked> ``` Retriever brief: `QUESTION · FOR · SCOPE · CAP · REPORT yes|auto · KNOWN`. Return: the answer only, first line `REPORT: R24-007` when a report was written. Code retrievers return signatures with `file:line`, call sites one per line, shared state and nearby gotchas, up to 40 lines. Critic brief: the plan sections, task index, named summaries, the question, the recommendation, and a tier guess. Return: `DECISION (continue | edit | needs-developer) · TIER · EDITS (plan_edit.py lines) · WHY (3 lines) · BRIEF (needs-developer only, ends "Recommended: ...")`. --- ## Replan tiers and the critic Changes are graded by scope and routed to the agent with the right authority: - Approach within the task: the expert decides and notes it under Deviations. - A developer's inbox item that only adds within the milestone: the router applies the edit and adds a Changes entry. - Any plan change an expert proposes, additive or not: the critic decides. It returns `continue` (carry on), `edit` (exact `plan_edit.py` commands the router runs and commits) or `needs-developer` (a one-paragraph brief with a recommendation the router puts to the developer in the question picker). - Structural (milestone or scope change): the developer, through `REPLAN.md`. The next `launch.py --seed-only` starts a planner-phase pass that archives the old plan and writes a new one for approval. The critic exists because the expert's context is deliberately narrow. An expert knows its own task, not that another task tests the same thing from the other side. When an expert hits a wall it will sometimes recommend removing the wall. The critic sees the full task index, the milestone, and the plan's rationale, and can judge whether the recommendation protects the milestone or undermines it. Cost: about $0.50 per invocation. --- ## Discussion, questions, notifications The developer is never interrogated. Agents give recommendations, not questions; when a decision is genuinely the developer's (risk appetite, product intent, money, scope), the recommendation states consequences and ends with a recommended answer. Three channels reach the developer: 1. The question picker (plan approval, review decisions, the critic's `needs-developer`, a planner's Developer-decides items): interactive, in the terminal. 2. Plain text at the end of a turn (the close question, and anything the router must ask outside the picker). 3. `/discuss [model] [effort]` (the discuss agent): the developer opens a read-only thinking session with Opus 5.5 at medium (opt-in: fable or sonnet, high or max; `/thoughts` an alias for one release) in its own terminal view. `Edit` and `Write` are denied while the discussion flag is set. When the developer says `proceed`, the agent writes the record under `discussions/` and returns the decisions as exact plan edits for the router to apply. A note for a running expert is typed into the expert's own view (its context stays); the router relays nothing and relaunches only on `stop:` or `relaunch:`. `INBOX.md` takes anything for the next task boundary. Notifications: at the default `toast: waiting` level (`.claude/pa.json`; the others are `all` and `off`) a Windows toast fires only when something waits on the developer: a `Stop` that ends on a question (the toast carries its text), a permission prompt or a picker question (Claude Code reports both as `permission_prompt`), a new `REVIEW.md` or `REPLAN.md`, a finished discussion, and a turn stopped by an error. Phone pushes come from Claude Code itself: with Remote Control on and its `/config` push switches set (the machine install turns them on unless you set them yourself), permission prompts and picker questions reach the Claude app. The toast child gets a console without a window (`CREATE_NO_WINDOW`) so there is no flash and no focus theft. --- ## Mode 1 intake 3.0 change: Gate 2 no longer prompts for `/effort max`. Generation happens in `planner-gen` at medium effort; the model and effort are pinned by the agent file. In 3.0 the intake and the constitution happen in a plain session (`claude --agent plain`) or in Claude Chat with the chat kit; that session writes the outputs of the next chapter itself. The governed loop starts at the first bare `claude` after `pa_install.py --project`; an intake agent is a later item. Conversational, not an interrogation. Weave questions into the discussion; track silently against the intake checklist. Do not generate the constitution during brainstorming, no matter how much detail accrues. Intake checklist (all 12, silently tracked): 1. The elevator pitch — what is this, in two sentences? 2. Motivation — why build it; is it a rewrite/successor of something? 3. Who is the developer — background, skill level, solo or team? (feeds `who-is-dev`) 4. Tech stack — chosen or open; existing constraints? 5. Hard constraints — platform, deadlines, budget, licenses, privacy/closed-source posture? 6. Core features — the non-negotiable heart. 7. Stretch features — wanted, not required. 8. Dream features — someday/maybe (Parking Lot material). 9. Known risks and pain points — what worries them; what failed before? 10. Definition of success — what does "it works" observably look like? (feeds milestones) 11. Multi-user/deployment reality — who else touches it, where does it run? 12. Resource management — data, compute, storage, external services, costs. Gate 1, the structured review (when the developer says "ready"): do not generate yet. Present recommended phase ordering with reasoning, standard features they missed, nice-to-haves worth considering, scope-creep warnings, methodology concerns, architecture suggestions with reasoning, and risk flags. Then ask what to adjust. Gate 2, the generation confirmation (after they confirm the review): generation is Tier-1 work. In 3.0 the planner-gen agent runs at medium effort by its agent file; the developer is not asked to toggle anything. The intake session writes everything listed in the next chapter; the first bare `claude` afterwards enters planner-gen mode. --- ## Generating the constitution 3.0 change: the outputs list is updated. The registry is replaced by individual files under `rules/`; effort and model are pinned per agent file, nothing is mapped per phase; the cookbook is generated as `cookbook/` entries and the ops reference as `docs/ops/` topics. `CLAUDE.md` is about 190 tokens of pointers with two default fail-safes, written by the installer (item 3 below). Phase design principles (you design the phases, not the developer): - Core before periphery. Data before processing. Foundation before features. Safety before action. Observation before optimization. - Every phase produces something runnable and testable. No planning-only or models-only phases. - Every phase ends with an explicit Milestone line: an observable, machine-checkable outcome ("`make check` green", "the level loads and the character walks", "round-trips 100 files byte-identical") — the gate that the closer will hold the phase to. - Validation is a dedicated phase, not an afterthought. - Enhancement layers are toggleable, feature-flagged modules added one at a time and measured before the next. - Size phases to the developer (see Skill-level handling): beginners get fewer, chunkier phases; advanced developers get fine-grained ones. Domain phase-ladder starting points (adapt, do not copy): - Game/game-tool: foundation and skeleton, data formats and I/O, core domain model, core mechanic vertical slice, content layers, UI shell, integration, validation, polish, packaging. - Backend/API: skeleton and config, data layer, domain model, first vertical endpoint, auth and safety, remaining endpoints, integration, validation, observability, deployment. - Desktop app: skeleton and DI shell, data/persistence, core engine, minimal UI, feature layers, import/export, validation, polish/packaging. - Automation/pipeline: skeleton and config, source connectors, transform core, dry-run end-to-end, guarded write path, scheduling, observability, validation, hardening. - RE/decompilation/format: environment and oracle setup, deterministic extraction pipeline, ground-truth maps, byte-exact verification gate, first verified unit, scale-out with a knowledge flywheel, the hard tail via an escalation ladder, integration/packaging. Generation design principles: - Generations are evolutionary leaps, not version numbers. A new generation only when a fundamentally new capability requires the prior generation stable and proven, and there is a hard dependency between them. - The constitution's roadmap covers Gen 1 in phase detail; later generations get a Generation Map sketch and a Future Generations section, not premature phase lists. Generation outputs (the complete set): 1. `PROJECT_CONTEXT.md` on the skeleton — every section, with the Quick Reference Card, Key Decisions, Build Roadmap with machine-checkable Milestones, Parking Lot. 2. `rules/G*.md` — the project's domain rules as individual files with an `INDEX.md`, seeded from the project's oracles, definition-of-done gate, data constraints and environment constraints. 3. `CLAUDE.md` is written by the installer (about 190 tokens of pointers and two default fail-safes: never push, the milestone gate is the arbiter); nothing regenerates it, the developer edits the fail-safe lines by hand if the project's `G*` rules justify others. 4. `docs/ops/` — environment, build/run/test commands, version pins as known at generation, one file per topic with an `INDEX.md`. 5. `cookbook/INDEX.md` — the initial techniques, one file per entry, named for the project's recurring craft. 6. `HOW_WE_WORK.md` — the card, generated from environment detection (`pa/install/detect.py environment()`), the developer interview and the constitution's opening and Quick Reference Card. It is one file, sliced per role (`{{PY}} tools/card.py slice <role>` prints only the sections whose heading tags name that role) and capped (`card.max_chars`, checked by `{{PY}} tools/card.py check`); the archive enforces the cap at phase end and nothing is ever appended to it — a standing decision or an environment fact is routed to a rule, a product doc, a Tools-table row or `docs/ops/` instead. 7. `HOW_WE_WORK.md ## Developer` filled from intake item 3 and the skill-level assessment (no memory is written); it is one of the sections the `router` and `planner` slices carry beyond the shared ones. --- ## Rule detection 3.0 change: "propose at PhaseEnd" becomes "the expert writes `Rule candidate:` in the task summary; the phase planner adjudicates." | Signal | Example | Likely rule type | |---|---|---| | The developer corrects a tool/framework behavior you assumed | "maspsx's default is not latest" | Pin/make-explicit rule | | The same mistake happens twice in one phase | Two stale-build false diffs | Verification rule | | The developer says "never do X" / "always do Y" | "never push", "always dry-run first" | Process rule | | A wiring step gets missed | Registration forgotten | Checklist rule | | An assumption proves wrong in practice | "the archive is per-day" was not | Provenance/verification rule | | A strong workflow preference emerges | Per-task commits after the log | Process rule + memory seed | | A costly gotcha with a cheap guard | The enum-zero config trap | Cookbook entry first; rule if it recurs | When proposing: state it specifically ("always Y when Z", not "be careful"), one-line justification, developer approves or modifies or rejects — never add unilaterally. Some things are deviations to record, not rules. Techniques go to the cookbook, norms of conduct to the rules. A rule enters the package's seed only when it has recurred across projects and fits in one sentence of conduct; otherwise it stays a project rule (a `G*` rule or a per-phase `R` rule). A sharper form of an existing seed rule becomes one clause in that rule, never a new id; techniques never enter the seed. --- ## Migration Migration replaces 2.0's Mode 4. The alternate-heading sweep rule is kept: when consolidating rules from an old project, sweep every rule-bearing heading, not just the literal "Rules Added This Phase." Older phases carry rules under alternate headings ("Key Rules Confirmed", "Architecture/Design Decisions", "Key technical decisions"); a consolidator keying only on the canonical heading silently misses them. PA3 migration is one engine (`pa/install/migrate.py`) and three thin layout modules. The engine handles git mv from a mapping table, heading-level splits, retiring, generating and committing. The layouts differ only in their mapping tables and their `HOW_WE_WORK` sources. The installer detects the project shape and selects the layout automatically. The three paths: 1. Stock 2.0 (`pa/install/stock20.py`): a project with `CLAUDE.md`, `RULES_REGISTRY.md` and `phase-ends/` in the standard 2.0 layout. The registry is split by its `###` headings into individual files under `rules/`. The cookbook is split by its `##` headings into `cookbook/` entries. The ops-setup document is split by its `##` headings into `docs/ops/` (giant sections split again at `###` if over 400 lines). The effort map, the old templates and the old `docs/project-architect.md` are retired. `CURRENT_PHASE.md` becomes a partial log. PhaseEnds stay in place; a `LEGACY_INDEX.md` is generated. The PA2 `SessionEnd` backup hook is removed from settings; no copy is kept, the harness holds transcripts for ten years (`cleanupPeriodDays`). The interphase sorts after the last closed phase and before the next. 2. 1.x-shaped (`pa/install/onex.py`): a project whose `Project Context Markdowns` (or similar) folder holds PhaseEnds with underscore separators, plan/verdict/prereg documents mixed in, a large rules registry under a non-standard name, and no `.claude/settings.json` (or an empty one). PhaseEnds are renamed in place (`_` to `.` between version tokens) and `sort -V` checked. Non-phase documents (plans, verdicts, prereg, checkpoints, audits) move to `docs/research-archive/` with a generated index, linked from `RESEARCH_INDEX.md`'s `## Legacy` section. The rules registry is split from its own headings into `rules/`. The project context becomes `PROJECT_CONTEXT.md` (verbatim, static). Settings are written fresh from the project snippet. The interphase label is proposed from the newest phase family; `--interphase` overrides. 3. Overlay kit (`pa/install/overlay.py`): a project with a `DIGEST.md`, R-numbered rules above 100, a kit folder with its own agents and commands, and a large cookbook with a separate index. Rules come from the DIGEST's rule section and from the kit's `registry-E*.md` templates. The DIGEST is frozen in place with a header line. The cookbook is streamed into `cookbook/` entries with index rows taken from the existing `cookbook-index.md` when its rows match the headings. The kit folder and its agents are untouched; name collisions with PA3 agents fail the install and name the collision. Kit agents that do not collide are listed in `HOW_WE_WORK` as extra experts the plan may name. Existing hooks in `.claude/settings.json` are appended to, never replaced. The interpreter is `python3` when the project runs on POSIX. Every path follows the same runbook discipline: - Dry run first. `--dry-run` prints the full mapping table (`git mv` lines, split counts, retire lines, unmapped files) and writes nothing. The developer reviews the table and confirms once. - One confirmation. After the dry run, the install runs with one confirmation prompt per phase of the install. No per-file prompts. - `git mv` only. Every move preserves history. An untracked source is moved as a plain file and noted. `git log --follow` on a moved file shows the pre-move commit. - `docs/retired/` for everything leaving the load order. Nothing is deleted. - Never push. The developer pushes when satisfied. - The migration's first planning step is the curator. When a project already has a memory directory, the memory curator runs before the planner drafts the first phase, demoting generation-specific memories into a linked archive and keeping the index small. The resume pointer (`.run/install-state.json`) records the last completed step. A crash or interrupt is followed by a rerun that resumes after the last good step. A second run with everything done prints SKIP for every step. --- ## Knowledge PA3 captures knowledge through four indexed stores, each managed by a script that enforces the format and keeps the index current. Rules (`rules/INDEX.md`, one file per rule): `tools/rules_add.py add` writes the file and appends the index line. Rules are proposed at phase end (`Rule candidate:` in a task summary), adjudicated by the phase planner, and never added unilaterally. A superseded rule keeps its file with a `superseded-by:` line; the index marks it. Cookbook (`cookbook/INDEX.md`, one file per technique): `tools/cookbook_add.sh --title ... --tags ... --file ...` writes the entry and appends the index. Planners and experts grep the index by tag before recurring work; they never read it whole (the index can grow past 400 lines in a large project). A technique that recurs across projects is stronger evidence that it is general. Research (`research/INDEX.md`, one file per report): `tools/research_add.py new ... | index <id>` writes the report and appends the index. Retriever findings land here; experts cite report ids and never read the bodies. The index carries the title, the date and the scope. Skills (`.claude/skills/`): `tools/skill_add.py` writes a skill file from a workflow gotcha. Skills are named per agent and listed in the agent file's `skills:` frontmatter. They load into the system prompt of every agent that names them. The flywheel: every task ends with a full log (`logs/T<n>.md`) and a summary (`tasks/T<n>.md`, at most 150 lines). The next task reads summaries only. Gotchas are marked `generalizable:` (promoted to the cookbook at phase end) or `workflow:` (promoted to a skill). Decisions are marked `binding:` (promoted to `HOW_WE_WORK.md` at phase end). The proportionality rule applies: no features, abstractions, options or tests beyond the change. A one-time fetch is a fetch, not a downloader. The generation-start ceremony: when a generation closes and the next one opens, a memory-curator agent (Fable 5.1 at medium effort) runs before the planner drafts. It reads every memory file, the cookbook and rules indexes, and `HOW_WE_WORK.md`. It demotes generation-specific state into archive files: memories into `memory/gen<N>.md`, cookbook entries into `cookbook/gen<N>/`, rules into `rules/gen<N>/`, and superseded standing decisions into `docs/retired/HOW_WE_WORK.gen<N>.md`. It commits the result and returns a recap. The demotion pattern is always: append content to an archive under a generation directory, remove the pointer from the main index, and keep one link line in the main index pointing to the archive. Active demoted rules keep their main-index line, marked `demoted:gen<N>`. The four subcommands of `tools/curate.py` (`memory`, `cookbook`, `rules`, `how-we-work`) each support `--dry-run`. The `how-we-work --report` subcommand lists trim candidates by date and token budget; `--retire` moves them into the generation archive. The pa-session detects the ceremony via a `curate:` line in the seed (written by `launch.py` when a `GenerationEnd` exists) and spawns the curator in the foreground before the planner. The curator's pre-flight is `pa_ledger.py doctor --sizes`: the sizes of the governed files (`CLAUDE.md`, each skill, `HOW_WE_WORK.md`, the memory index, the cookbook and rules indexes) and the current expert seed against their targets. Over a target is a WARN the curator acts on; only a memory index past the harness's own cap fails. The closer's `## Audit` section in every PhaseEnd records the expert seed per phase, its growth over the previous phase, and the same sizes. Standing decisions of 3.1 through 3.3 that change how a project is run: - The measured saving is what a vanilla Claude Code session would have paid to carry what the helpers kept out: one 1h cache write per result per session, re-reads at the read price, the carried results rewritten only at a real idle gap over an hour, bounded by the parent model's window, minus every helper run's seed carry. One rule at every scope (run, session, window, project, account). The statusline reads it in the subscriber's units (percent of the 5h and 7d windows, weeks of allowance at the user's own live exchange rate, "N% fewer tokens than vanilla, lasts Mx longer" per scope). Every input is the user's own ledger, nothing is calibrated from anyone else's runs; the modeled replay stays in `report` as a cross-check. - The meter weighs model families differently: a Fable dollar consumed the 5h window about ten times faster than an Opus dollar (as of 2026-09-20). The fit carries per-family weights and the "percentage of window" figures are summed per family. - One ledger per machine, written only by its own hooks. Other roots are read in copy mode, never over the WSL file boundary. The fit, the window samples and the window savings read the union on the sampler's change path and in the CLI; the hooks' rebuild and the render stay local. - A project's memories live in its repository (`.claude-state/memory/`) behind a junction from the harness's memory folder, so `pa_install --project` on a fresh machine restores them. Never delete a memory; demote it to a linked generation archive. Only the index costs context. - The generation-start ceremony (curator, demotions, trim, seed audit, `doctor --sizes`) runs before the planner at every generation boundary. --- ## Skill-level handling 3.0 change: the developer profile lands in `HOW_WE_WORK.md` under `## Developer` rather than only in a memory. No change to the levels. - Beginner: explain more, simpler architectures, fewer and chunkier phases, warn plainly when scope is over-ambitious. Expand the explain-before-coding depth. - Intermediate: explain the non-obvious; standard patterns; normal phase granularity. - Advanced: brief reasoning, respect their calls, fine-grained phases, argue only when the methodology stakes are real. - When in doubt, ask. Record the profile in `HOW_WE_WORK.md` at install or generation so every future session starts calibrated. --- ## Sunset list and changelog ### Sunset list (mechanisms removed from 2.0) Mid-phase rules check and re-read every four tasks. Session-start rule recitation. Printing checkpoint blocks; the blocks themselves. "Checkpoint CURRENT_PHASE every turn" and `CURRENT_PHASE.md` with its template. The effort map, the tier prompts, the "drop back down" reminders, the context buckets and reset bands, and the statusline-injection checkpoint hook. Token-lean SSP block and digest subagent. Duplicated fail-safe rule blocks. TaskCreate after approval, task-list rebuild on resume, and the Tasks-tool setting. Feedback memories as corrections and the memory index. "Explain before coding" (replaced by: one line when deviating). The "no truncating reads / spend freely" clause (keeping "never state a percentage, never hurry"). Long commit messages. Inline one-liners. "Present results in chat" (replaced by the task log and `REVIEW.md`). Verbatim rule printing. ### Changelog 2.0 to 3.0 | Area | 2.0 | 3.0 | |---|---|---| | Entry point | `SETUP.md` path A/B/C | `pa_install.py --root` + `--project` | | Rules store | One `RULES_REGISTRY.md` (recited every session) | `rules/` one file per rule; grep the index | | Session startup | Rule recitation + checkpoint restore | Seed file (`launch.py --seed-only`) | | Effort and models | Developer toggles `/effort`; effort map per phase | Pinned per agent file; the developer never touches `/effort` | | Execution | One task, confirmation, plan-mode + Max | One task per fresh context; two gates per phase, autonomy between | | State recovery | `CURRENT_PHASE.md` (one large file, reloaded every turn) | `TASK_PROGRESS.md` (written at handoff, archived when done) | | Knowledge stores | One cookbook file, one registry, one ops file | `cookbook/`, `rules/`, `docs/ops/` with indexes and flywheel scripts | | Agent state | `.claude-state/` (repo-contained) | Same, plus the memory junction and the curator | | Phase close | PhaseEnd (append-only) + the developer closes | `phaseend_index.py verify` then `assemble`, `lint`, `archive` | | Cost visibility | None | Usage ledger, statusline with savings and pace, `pa_ledger.py report` | | Migration paths | Mode 4 (one protocol) | Three layout modules: stock 2.0, 1.x-shaped, overlay kit | What is measured (the acceptance metrics): average context per expert request at most 150k tokens; expert seed at most 40k; retriever seed at most 6k; router context at phase end at most 40k; zero prefix rewrites not at session start; zero Tasks-tool attachments; cost per request at most $0.10; developer interruptions limited to the critic's `needs-developer` plus the milestone gates. --- ## Appendix: the chat kit The package still works for brainstorming in Claude Chat without Claude Code. Attach three files to a new chat: this document (`project-architect-3.0.md`), the constitution skeleton (`PROJECT_CONTEXT.skeleton.md`) and the rules seed (`rules-seed/INDEX.seed.md`). The AI runs Mode 1 above and generates the constitution as a markdown artifact with the rules and protocols embedded. That output is migration-ready: when the project later moves to Claude Code, the installer's migration path picks it up. The dispatch section from 2.0 shrinks to one rule: if you are Claude Code and a `.claude/pa.json` exists, the installed system governs and this document is the reference specification. If you are Claude Chat with this document attached, run the modes from this document. Never mix the postures.