agent-method 1.5.5 → 1.5.6

package/templates/full/AGENT.md

@@ -22,6 +22,10 @@
 | **Methodology guidance** | .context/METHODOLOGY.md | -- |
 | **Phase completion** | SUMMARY.md | SUMMARY.md, STATE.md, ROADMAP.md |
 | **Backlog / ideas** | todos/backlog.md | todos/backlog.md |
+| **Management overview** | Management/DIGEST.md, Management/STATUS.md, STATE.md | Management/STATUS.md, Management/DIGEST.md |
+| **Project review** | Reviews/INDEX.md, relevant source files | Reviews/ (affected review file) |
+| **Workflow analysis** | agentWorkflows/INDEX.md, SESSION-LOG.md | agentWorkflows/ (affected analysis file) |
+| **Docs update** | .context/DOCS-MAP.md, relevant docs/ files | docs/ files, .context/DOCS-MAP.md |
 
 <!-- INSTRUCTION: Replace the {your-domain-type} row with project-specific query types.
      Each should pair .context/BASE.md with one specialist. Add as many rows as needed. -->
@@ -41,20 +45,24 @@ When a file changes, check this table and update dependent files in the same res
 | File split, created, deleted, or renamed | .context/REGISTRY.md (file tree, topic index, structural log) |
 | New domain area | .context/BASE.md, consider new .context/ specialist, this file (if new scoping row) |
 | Lifecycle stage change | PROJECT-PROFILE.md (update stage + date), STATE.md (record decision) |
-| Session close or high-effort task completion | SESSION-LOG.md (append metrics entry — effort, ambiguity, context level, tokens, time, user response, refinement delta, workflow, features, cascades, friction, findings) |
+| Session close or high-effort task completion | SESSION-LOG.md (append metrics entry — effort, ambiguity, context level, tokens, time, user response, refinement delta, workflow, features, cascades, friction, findings). For high-effort tasks also: Management/DIGEST.md (append row — date, task, query, outcome, key changes, decisions, effort, time), Management/STATUS.md (if milestone) |
+| Significant milestone or phase completion | Management/STATUS.md (update current state, recent decisions, health indicators) |
+| New project component or module | .context/DOCS-MAP.md (add component mapping, check scaffolding rules for new docs/ proposals) |
+| docs/ file created or deleted | .context/DOCS-MAP.md (update inventory), docs/index.md (update navigation — create if it doesn't exist yet) |
 
 <!-- INSTRUCTION: Add project-specific cascade rules below the universal ones above. -->
 
 ## Docs maintenance
 
 <!-- INSTRUCTION: This table tells the agent when to update human-facing docs.
-     Add rows as your docs/ structure grows. -->
+     For full component-to-docs mapping, see .context/DOCS-MAP.md. -->
 
 | Trigger | Update these docs/ files |
 |---------|------------------------|
-| Phase completed | docs/index.md (progress section) |
-| Architecture decision | docs/index.md (architecture section) |
-| {structural-change} | {specific docs/ files} |
+| Phase completed | docs/index.md (progress section — create from DOCS-MAP.md if it doesn't exist yet) |
+| Architecture decision | docs/index.md (architecture section), .context/DOCS-MAP.md (if new component) |
+| New project component | .context/DOCS-MAP.md (add mapping), docs/ (per DOCS-MAP.md scaffolding rules) |
+| {structural-change} | {specific docs/ files per DOCS-MAP.md component mapping} |
 
 ## Workflow
 
@@ -62,8 +70,101 @@ Select based on query type:
 - **General task** — Review, Plan, Implement, Document, Update
 - **Code change** — Review, Plan, Implement, Context-sync, Update
 - **Context refresh** — Scan, Compare, Update-context, Cascade, Record
-- **First session** — Detect, Initialize, Map, Pair, Ready
-- **Discovery (brownfield)** — Inventory, Map-dependencies, Extract-patterns, Assess, Bootstrap
+- **First session (greenfield)** — Ask, Populate, Confirm (see onboarding protocol below)
+- **First session (brownfield)** — Scan, Ask, Confirm (see onboarding protocol below)
+
+## First session protocol
+
+<!-- AGENT: Follow this protocol on the FIRST session when methodology files contain only template placeholders. -->
+
+When PROJECT.md still contains `{placeholder}` text, this is a first session. Guide the user through onboarding — ask questions, show what you'll write, get confirmation before writing each file.
+
+### Greenfield onboarding (no existing codebase)
+
+**Stage 1 — Project vision** → populates PROJECT.md
+Ask the user:
+1. What is your project about? (1-2 sentences)
+2. Who is it for?
+3. What problem does it solve?
+4. What technologies, languages, or frameworks will you use?
+5. What are 2-3 guiding principles for this project?
+
+CHECKPOINT: Draft PROJECT.md from the answers. Show the user the draft. Wait for approval before writing.
+
+**Stage 2 — Architecture** → populates .context/BASE.md, PROJECT-PROFILE.md, .context/DOCS-MAP.md
+Ask the user:
+1. What are the main components or modules?
+2. How do they connect? (data flow, API calls, event-driven, etc.)
+3. What is the directory structure? (or what will it be?)
+4. What are the key dependencies?
+
+CHECKPOINT: Draft .context/BASE.md, PROJECT-PROFILE.md, and .context/DOCS-MAP.md (initial component-to-docs mapping based on architecture). Show the user. Wait for approval.
+
+**Stage 3 — Goals** → populates ROADMAP.md, PLAN.md
+Ask the user:
+1. What are your immediate goals? (next 1-3 sessions)
+2. What does "done" look like for this project?
+3. Can you break this into 2-4 phases?
+
+CHECKPOINT: Draft ROADMAP.md and PLAN.md (first task). Show the user. Wait for approval.
+
+**Stage 4 — Starting state** → populates STATE.md
+Ask the user:
+1. Any decisions already made? (tech choices, architecture, constraints)
+2. Any known blockers or risks?
+3. Any open questions you want tracked?
+
+CHECKPOINT: Draft STATE.md. Show the user. Wait for approval. Then begin normal work.
+
+### Brownfield onboarding (existing codebase)
+
+**Stage 1 — Scan** → reads existing files, writes nothing
+Read: package.json, README, directory structure, key config files, entry points.
+Present findings: "Here's what I found in your project: [summary]. Is this accurate?"
+
+CHECKPOINT: Wait for user to confirm or correct your understanding.
+
+**Stage 2 — Clarify** → populates PROJECT.md, PROJECT-PROFILE.md
+Ask targeted questions based on what the scan missed:
+1. What's the intent behind [pattern you found]?
+2. Are there conventions not captured in config? (naming, structure, etc.)
+3. What's the current state — active development, maintenance, exploration?
+
+CHECKPOINT: Draft PROJECT.md from scan + answers. Show the user. Wait for approval.
+
+**Stage 3 — Map** → populates .context/BASE.md, .context/DOCS-MAP.md
+Build codebase map from scan. Ask:
+1. Are there areas of the codebase I should understand deeply vs. ignore?
+2. Any architectural decisions I should know about that aren't documented?
+3. What are the most common types of changes you make?
+
+CHECKPOINT: Draft .context/BASE.md and .context/DOCS-MAP.md (component-to-docs mapping from scan results). Show the user. Wait for approval.
+
+**Stage 4 — Organize** → proposes entry point customization
+Based on understanding, propose:
+1. Scoping rules — which query types match this project?
+2. Specialist context files — which domains need their own .context/ file?
+3. Cascade rules — what project-specific dependencies exist?
+
+CHECKPOINT: Show proposed entry point customizations. Wait for approval before modifying this file.
+
+**Stage 5 — Starting state** → populates STATE.md, ROADMAP.md
+Propose initial state based on everything learned:
+1. Decisions already implicit in the codebase (document them)
+2. Current position (where is the project in its lifecycle?)
+3. Immediate goals
+
+CHECKPOINT: Draft STATE.md and ROADMAP.md. Show the user. Wait for approval. Then begin normal work.
+
+### Checkpoint rules
+
+- NEVER write to a methodology file without showing the user what you will write first
+- At each CHECKPOINT, present the draft as a code block the user can review
+- If the user says "looks good" or similar, write the file
+- If the user edits or corrects, incorporate changes and show the updated draft
+- If the user says "skip", leave the file as template placeholder
+- After all stages complete, summarize what was populated and begin normal work
+- For brownfield: `.context/REGISTRY.md` is deferred — do not create it during onboarding. It will be created automatically when the first file split occurs (reduces first-session cognitive load)
 
 ## Interaction level
 
@@ -83,21 +184,28 @@ tier: full
 
 method_version: 1.5
 <!-- Tracks which methodology version generated this entry point -->
-<!-- Use `npx agent-method status` to compare against latest -->
+<!-- Use `wwa status` to compare against latest -->
 
 ## CLI tools (optional)
 
-Available via `npx agent-method` (zero-install) or `pip install wwa-tools`:
+Install: `npm install -g agent-method` (then use `wwa`), or `pip install wwa-tools`.
 
 | When you want to... | Run |
 |---------------------|-----|
-| Validate this entry point | `npx agent-method check` |
-| See what type of project this is | `npx agent-method scan` |
-| Test how a query routes | `npx agent-method route "your question"` |
-| Extract a refinement report | `npx agent-method refine` |
-| Check methodology version | `npx agent-method status` |
-| Update methodology files | `npx agent-method upgrade` |
-| See what an entry point should contain | `npx agent-method init code` / `context` / `data` / `mix` |
+| Validate this entry point | `wwa check` |
+| See what type of project this is | `wwa scan` |
+| Test how a query routes | `wwa route "your question"` |
+| See current plan status | `wwa plan` |
+| Get implementation guidance | `wwa implement` |
+| View project review dashboard | `wwa review` |
+| Show management digest | `wwa digest` |
+| Session close + project snapshot | `wwa close` |
+| Extract a refinement report | `wwa refine` |
+| Extract a case study (with project tokens) | `wwa casestudy` |
+| Check docs coverage | `wwa docs` |
+| Check methodology version | `wwa status` |
+| Update methodology files | `wwa upgrade` |
+| Set up a new project | `wwa init code` / `context` / `data` / `mix` |
 
 <!-- INSTRUCTION: The agent can suggest these commands when the user asks about validation,
      project setup, or methodology updates. All commands auto-detect project type and find
@@ -112,7 +220,8 @@ Available via `npx agent-method` (zero-install) or `pip install wwa-tools`:
 - Surface uncertainty as open questions in STATE.md — never guess silently
 - Keep intelligence layer files under 300 lines — split into index + components subdirectory when exceeded
 - Propose plans and wait for approval — the human controls direction
-- SUMMARY.md entries follow audit trail format: date, plan, outcome, files, decisions, next
+- Document proportionally — low-effort tasks (status checks, lookups, clarifications) need no STATE.md or SESSION-LOG updates; high-effort tasks get full recording
+- SUMMARY.md is the session audit trail (date, plan, outcome, files, decisions, next). Management digest lives in Management/DIGEST.md
 - At session close or after any high-effort task, append a metrics entry to SESSION-LOG.md — include effort level, question ambiguity, context level, estimated tokens, time, user response (accepted/edited/revised/rejected/redirected), and for medium/high effort tasks: revision count, refinement magnitude (none/minor/moderate/major/rework), delta categories, and survival rate. Never skip, never read previous entries during normal work
 
 ## Do not
@@ -124,5 +233,6 @@ Available via `npx agent-method` (zero-install) or `pip install wwa-tools`:
 - Skip cascade checks after file changes
 - Load multiple specialist .context/ files for a single query
 - Update docs/ for typo fixes or internal-only changes
+- Record routine queries in STATE.md or SESSION-LOG.md — only decisions, blockers, and high-effort work warrant documentation
 
 <!-- INSTRUCTION: Add project-specific "do not" rules as you discover common mistakes -->

package/templates/full/CLAUDE.md

@@ -22,6 +22,10 @@
 | **Methodology guidance** | .context/METHODOLOGY.md | -- |
 | **Phase completion** | SUMMARY.md | SUMMARY.md, STATE.md, ROADMAP.md |
 | **Backlog / ideas** | todos/backlog.md | todos/backlog.md |
+| **Management overview** | Management/DIGEST.md, Management/STATUS.md, STATE.md | Management/STATUS.md, Management/DIGEST.md |
+| **Project review** | Reviews/INDEX.md, relevant source files | Reviews/ (affected review file) |
+| **Workflow analysis** | agentWorkflows/INDEX.md, SESSION-LOG.md | agentWorkflows/ (affected analysis file) |
+| **Docs update** | .context/DOCS-MAP.md, relevant docs/ files | docs/ files, .context/DOCS-MAP.md |
 
 <!-- INSTRUCTION: Replace the {your-domain-type} row with project-specific query types.
      Each should pair .context/BASE.md with one specialist. Add as many rows as needed. -->
@@ -41,20 +45,24 @@ When a file changes, check this table and update dependent files in the same res
 | File split, created, deleted, or renamed | .context/REGISTRY.md (file tree, topic index, structural log) |
 | New domain area | .context/BASE.md, consider new .context/ specialist, this file (if new scoping row) |
 | Lifecycle stage change | PROJECT-PROFILE.md (update stage + date), STATE.md (record decision) |
-| Session close or high-effort task completion | SESSION-LOG.md (append metrics entry — effort, ambiguity, context level, tokens, time, user response, refinement delta, workflow, features, cascades, friction, findings) |
+| Session close or high-effort task completion | SESSION-LOG.md (append metrics entry — effort, ambiguity, context level, tokens, time, user response, refinement delta, workflow, features, cascades, friction, findings). For high-effort tasks also: Management/DIGEST.md (append row — date, task, query, outcome, key changes, decisions, effort, time), Management/STATUS.md (if milestone) |
+| Significant milestone or phase completion | Management/STATUS.md (update current state, recent decisions, health indicators) |
+| New project component or module | .context/DOCS-MAP.md (add component mapping, check scaffolding rules for new docs/ proposals) |
+| docs/ file created or deleted | .context/DOCS-MAP.md (update inventory), docs/index.md (update navigation — create if it doesn't exist yet) |
 
 <!-- INSTRUCTION: Add project-specific cascade rules below the universal ones above. -->
 
 ## Docs maintenance
 
 <!-- INSTRUCTION: This table tells the agent when to update human-facing docs.
-     Add rows as your docs/ structure grows. -->
+     For full component-to-docs mapping, see .context/DOCS-MAP.md. -->
 
 | Trigger | Update these docs/ files |
 |---------|------------------------|
-| Phase completed | docs/index.md (progress section) |
-| Architecture decision | docs/index.md (architecture section) |
-| {structural-change} | {specific docs/ files} |
+| Phase completed | docs/index.md (progress section — create from DOCS-MAP.md if it doesn't exist yet) |
+| Architecture decision | docs/index.md (architecture section), .context/DOCS-MAP.md (if new component) |
+| New project component | .context/DOCS-MAP.md (add mapping), docs/ (per DOCS-MAP.md scaffolding rules) |
+| {structural-change} | {specific docs/ files per DOCS-MAP.md component mapping} |
 
 ## Workflow
 
@@ -62,8 +70,101 @@ Select based on query type:
 - **General task** — Review, Plan, Implement, Document, Update
 - **Code change** — Review, Plan, Implement, Context-sync, Update
 - **Context refresh** — Scan, Compare, Update-context, Cascade, Record
-- **First session** — Detect, Initialize, Map, Pair, Ready
-- **Discovery (brownfield)** — Inventory, Map-dependencies, Extract-patterns, Assess, Bootstrap
+- **First session (greenfield)** — Ask, Populate, Confirm (see onboarding protocol below)
+- **First session (brownfield)** — Scan, Ask, Confirm (see onboarding protocol below)
+
+## First session protocol
+
+<!-- AGENT: Follow this protocol on the FIRST session when methodology files contain only template placeholders. -->
+
+When PROJECT.md still contains `{placeholder}` text, this is a first session. Guide the user through onboarding — ask questions, show what you'll write, get confirmation before writing each file.
+
+### Greenfield onboarding (no existing codebase)
+
+**Stage 1 — Project vision** → populates PROJECT.md
+Ask the user:
+1. What is your project about? (1-2 sentences)
+2. Who is it for?
+3. What problem does it solve?
+4. What technologies, languages, or frameworks will you use?
+5. What are 2-3 guiding principles for this project?
+
+CHECKPOINT: Draft PROJECT.md from the answers. Show the user the draft. Wait for approval before writing.
+
+**Stage 2 — Architecture** → populates .context/BASE.md, PROJECT-PROFILE.md, .context/DOCS-MAP.md
+Ask the user:
+1. What are the main components or modules?
+2. How do they connect? (data flow, API calls, event-driven, etc.)
+3. What is the directory structure? (or what will it be?)
+4. What are the key dependencies?
+
+CHECKPOINT: Draft .context/BASE.md, PROJECT-PROFILE.md, and .context/DOCS-MAP.md (initial component-to-docs mapping based on architecture). Show the user. Wait for approval.
+
+**Stage 3 — Goals** → populates ROADMAP.md, PLAN.md
+Ask the user:
+1. What are your immediate goals? (next 1-3 sessions)
+2. What does "done" look like for this project?
+3. Can you break this into 2-4 phases?
+
+CHECKPOINT: Draft ROADMAP.md and PLAN.md (first task). Show the user. Wait for approval.
+
+**Stage 4 — Starting state** → populates STATE.md
+Ask the user:
+1. Any decisions already made? (tech choices, architecture, constraints)
+2. Any known blockers or risks?
+3. Any open questions you want tracked?
+
+CHECKPOINT: Draft STATE.md. Show the user. Wait for approval. Then begin normal work.
+
+### Brownfield onboarding (existing codebase)
+
+**Stage 1 — Scan** → reads existing files, writes nothing
+Read: package.json, README, directory structure, key config files, entry points.
+Present findings: "Here's what I found in your project: [summary]. Is this accurate?"
+
+CHECKPOINT: Wait for user to confirm or correct your understanding.
+
+**Stage 2 — Clarify** → populates PROJECT.md, PROJECT-PROFILE.md
+Ask targeted questions based on what the scan missed:
+1. What's the intent behind [pattern you found]?
+2. Are there conventions not captured in config? (naming, structure, etc.)
+3. What's the current state — active development, maintenance, exploration?
+
+CHECKPOINT: Draft PROJECT.md from scan + answers. Show the user. Wait for approval.
+
+**Stage 3 — Map** → populates .context/BASE.md, .context/DOCS-MAP.md
+Build codebase map from scan. Ask:
+1. Are there areas of the codebase I should understand deeply vs. ignore?
+2. Any architectural decisions I should know about that aren't documented?
+3. What are the most common types of changes you make?
+
+CHECKPOINT: Draft .context/BASE.md and .context/DOCS-MAP.md (component-to-docs mapping from scan results). Show the user. Wait for approval.
+
+**Stage 4 — Organize** → proposes entry point customization
+Based on understanding, propose:
+1. Scoping rules — which query types match this project?
+2. Specialist context files — which domains need their own .context/ file?
+3. Cascade rules — what project-specific dependencies exist?
+
+CHECKPOINT: Show proposed entry point customizations. Wait for approval before modifying this file.
+
+**Stage 5 — Starting state** → populates STATE.md, ROADMAP.md
+Propose initial state based on everything learned:
+1. Decisions already implicit in the codebase (document them)
+2. Current position (where is the project in its lifecycle?)
+3. Immediate goals
+
+CHECKPOINT: Draft STATE.md and ROADMAP.md. Show the user. Wait for approval. Then begin normal work.
+
+### Checkpoint rules
+
+- NEVER write to a methodology file without showing the user what you will write first
+- At each CHECKPOINT, present the draft as a code block the user can review
+- If the user says "looks good" or similar, write the file
+- If the user edits or corrects, incorporate changes and show the updated draft
+- If the user says "skip", leave the file as template placeholder
+- After all stages complete, summarize what was populated and begin normal work
+- For brownfield: `.context/REGISTRY.md` is deferred — do not create it during onboarding. It will be created automatically when the first file split occurs (reduces first-session cognitive load)
 
 ## Interaction level
 
@@ -83,21 +184,28 @@ tier: full
 
 method_version: 1.5
 <!-- Tracks which methodology version generated this entry point -->
-<!-- Use `npx agent-method status` to compare against latest -->
+<!-- Use `wwa status` to compare against latest -->
 
 ## CLI tools (optional)
 
-Available via `npx agent-method` (zero-install) or `pip install wwa-tools`:
+Install: `npm install -g agent-method` (then use `wwa`), or `pip install wwa-tools`.
 
 | When you want to... | Run |
 |---------------------|-----|
-| Validate this entry point | `npx agent-method check` |
-| See what type of project this is | `npx agent-method scan` |
-| Test how a query routes | `npx agent-method route "your question"` |
-| Extract a refinement report | `npx agent-method refine` |
-| Check methodology version | `npx agent-method status` |
-| Update methodology files | `npx agent-method upgrade` |
-| See what an entry point should contain | `npx agent-method init code` / `context` / `data` / `mix` |
+| Validate this entry point | `wwa check` |
+| See what type of project this is | `wwa scan` |
+| Test how a query routes | `wwa route "your question"` |
+| See current plan status | `wwa plan` |
+| Get implementation guidance | `wwa implement` |
+| View project review dashboard | `wwa review` |
+| Show management digest | `wwa digest` |
+| Session close + project snapshot | `wwa close` |
+| Extract a refinement report | `wwa refine` |
+| Extract a case study (with project tokens) | `wwa casestudy` |
+| Check docs coverage | `wwa docs` |
+| Check methodology version | `wwa status` |
+| Update methodology files | `wwa upgrade` |
+| Set up a new project | `wwa init code` / `context` / `data` / `mix` |
 
 <!-- INSTRUCTION: The agent can suggest these commands when the user asks about validation,
      project setup, or methodology updates. All commands auto-detect project type and find
@@ -112,7 +220,8 @@ Available via `npx agent-method` (zero-install) or `pip install wwa-tools`:
 - Surface uncertainty as open questions in STATE.md — never guess silently
 - Keep intelligence layer files under 300 lines — split into index + components subdirectory when exceeded
 - Propose plans and wait for approval — the human controls direction
-- SUMMARY.md entries follow audit trail format: date, plan, outcome, files, decisions, next
+- Document proportionally — low-effort tasks (status checks, lookups, clarifications) need no STATE.md or SESSION-LOG updates; high-effort tasks get full recording
+- SUMMARY.md is the session audit trail (date, plan, outcome, files, decisions, next). Management digest lives in Management/DIGEST.md
 - At session close or after any high-effort task, append a metrics entry to SESSION-LOG.md — include effort level, question ambiguity, context level, estimated tokens, time, user response (accepted/edited/revised/rejected/redirected), and for medium/high effort tasks: revision count, refinement magnitude (none/minor/moderate/major/rework), delta categories, and survival rate. Never skip, never read previous entries during normal work
 
 ## Do not
@@ -124,5 +233,6 @@ Available via `npx agent-method` (zero-install) or `pip install wwa-tools`:
 - Skip cascade checks after file changes
 - Load multiple specialist .context/ files for a single query
 - Update docs/ for typo fixes or internal-only changes
+- Record routine queries in STATE.md or SESSION-LOG.md — only decisions, blockers, and high-effort work warrant documentation
 
 <!-- INSTRUCTION: Add project-specific "do not" rules as you discover common mistakes -->

package/templates/full/Management/DIGEST.md

@@ -0,0 +1,23 @@
+# Management Digest
+
+<!-- AGENT: Append a row for every HIGH-EFFORT task only.
+     This is the primary management-facing project record — managers and leads
+     read this to understand what significant work happened, without parsing
+     detailed session logs or operational files.
+
+     Low-effort tasks (lookups, status checks, clarifications) are NOT recorded here.
+     See SESSION-LOG.md for complete session data. -->
+
+## What qualifies as high-effort
+
+- Multi-file changes (3+ files)
+- Architectural or design decisions
+- Phase completions
+- Complex queries requiring research or multi-step execution
+- New feature implementations
+
+## Digest
+
+| Date | Task | Query | Outcome | Key Changes | Decisions | Effort | Time |
+|------|------|-------|---------|-------------|-----------|--------|------|
+<!-- Rows added automatically by agent for high-effort tasks -->

package/templates/full/Management/STATUS.md

@@ -0,0 +1,46 @@
+# Project Status
+
+<!-- AGENT: Update this file after significant milestones (phase completions,
+     architectural decisions, blocker changes). This is the management-facing
+     health snapshot — read by leads to understand project state at a glance.
+
+     Do NOT update for routine work. Only update when the project's overall
+     status, direction, or risk profile changes. -->
+
+## Current state
+
+| Field | Value |
+|-------|-------|
+| Phase | {current phase} |
+| Status | {active / blocked / complete} |
+| Active work | {brief description of current task} |
+| Last milestone | {most recent completed phase or significant deliverable} |
+| Next milestone | {what's coming next} |
+
+## Recent decisions
+
+<!-- AGENT: Keep the 5 most recent significant decisions here.
+     Full decision history lives in STATE.md. -->
+
+| Date | Decision | Impact |
+|------|----------|--------|
+<!-- Last 5 significant decisions -->
+
+## Blockers & risks
+
+<!-- AGENT: List active blockers and known risks. Remove when resolved. -->
+
+| Type | Description | Since | Severity |
+|------|-------------|-------|----------|
+<!-- {blocker/risk} | {description} | {date} | {high/medium/low} -->
+
+## Health indicators
+
+<!-- AGENT: Update these after each high-effort task or milestone. -->
+
+| Indicator | Status | Notes |
+|-----------|--------|-------|
+| Scope | {stable / expanding / contracting} | {brief note} |
+| Velocity | {steady / accelerating / slowing} | {brief note} |
+| Technical debt | {low / medium / high} | {brief note} |
+| Context freshness | {current / slightly stale / stale} | {last refresh date} |

package/templates/full/PROJECT.md

@@ -44,3 +44,37 @@
 1. {Principle 1}
 2. {Principle 2}
 3. {Principle 3}
+
+## Agent onboarding
+
+<!-- AGENT: Use these questions to populate this file during the first session.
+     Ask the user each question, draft this file from the answers, and show the
+     draft at the Stage 1 checkpoint before writing. Remove this section after
+     the file is populated — it's scaffolding, not permanent content. -->
+
+### Greenfield (no existing codebase)
+
+Ask the user:
+1. What is your project about? (1-2 sentences for the description above)
+2. Who is it for? (populate the Audiences table)
+3. What problem does it solve? (populate the Problem section)
+4. What technologies, languages, or frameworks will you use? (informs Solution + structure)
+5. What are 2-3 guiding principles for this project? (populate Principles)
+6. What is the top-level directory structure? (populate Project structure table)
+
+### Brownfield (existing codebase)
+
+<!-- AGENT: For brownfield projects, you've already scanned the project at Stage 1.
+     Pre-fill as much as possible from scan results. Only ask what you couldn't determine. -->
+
+Pre-fill from scan:
+- **Description**: infer from README, package.json description, or top-level docs
+- **Project structure**: build from directory listing — auto-populate the table
+- **Technologies**: extract from package.json, requirements.txt, config files, imports
+
+Ask the user only what the scan couldn't determine:
+1. Is this description accurate? (confirm or correct the auto-generated description)
+2. Who is the primary audience? (rarely inferable from code alone)
+3. What problem does this solve from the user's perspective? (intent, not implementation)
+4. What guiding principles drive decisions on this project? (conventions, priorities)
+5. Are there directories I should know about that aren't obvious from the structure? (hidden patterns, legacy areas)

package/templates/full/Reviews/INDEX.md

@@ -0,0 +1,41 @@
+# Project Reviews
+
+<!-- AGENT: This is the review dashboard — a synthesized view of project intelligence.
+     Update the summary table when corresponding source files change significantly.
+     Each area links to a dedicated drill-down file for detailed analysis.
+
+     Source files: ROADMAP.md, PLAN.md, PROJECT.md, REQUIREMENTS.md, STATE.md, todos/backlog.md
+     This file stays lean — detail lives in the drill-down files. -->
+
+## At a glance
+
+| Area | Status | Last updated | Drill-down |
+|------|--------|-------------|------------|
+| Roadmap | {on track / behind / ahead} | {date} | [roadmap.md](roadmap.md) |
+| Plan | {active / blocked / between tasks} | {date} | [plan.md](plan.md) |
+| Project | {healthy / needs attention} | {date} | [project.md](project.md) |
+| Requirements | {N/M covered} | {date} | [requirements.md](requirements.md) |
+| State | {N decisions, N blockers, N open Qs} | {date} | [state.md](state.md) |
+| Backlog | {N items, N categories} | {date} | [backlog.md](backlog.md) |
+
+## Key metrics
+
+<!-- AGENT: Populate from source files. Update after milestones. -->
+
+- **Phases completed**: {N of M}
+- **Requirements covered**: {N of M} ({percentage}%)
+- **Active blockers**: {count}
+- **Open questions**: {count}
+- **Backlog items**: {count}
+- **Decisions recorded**: {count}
+
+## Trend indicators
+
+<!-- AGENT: Track how metrics change over time. Update after phase completions. -->
+
+| Metric | Previous | Current | Trend |
+|--------|----------|---------|-------|
+| Phases completed | {N} | {N} | {↑ / → / ↓} |
+| Requirements coverage | {N}% | {N}% | {↑ / → / ↓} |
+| Open blockers | {N} | {N} | {↑ / → / ↓} |
+| Backlog size | {N} | {N} | {↑ / → / ↓} |

package/templates/full/Reviews/backlog.md

@@ -0,0 +1,52 @@
+# Backlog Review
+
+<!-- AGENT: Synthesize from todos/backlog.md. Track backlog health — item counts,
+     categories, aging, completion rates. This helps identify neglected areas
+     and prioritization patterns.
+     Update after significant backlog changes (new categories, large batch completions).
+
+     Source: todos/backlog.md
+     Parent: Reviews/INDEX.md (update "At a glance" row when this changes) -->
+
+## Summary
+
+- **Total items**: {count}
+- **Completed**: {count} ({%})
+- **Pending**: {count} ({%})
+
+## By category
+
+| Category | Total | Done | Pending | Completion |
+|----------|-------|------|---------|------------|
+<!-- Group backlog items by their section headings -->
+
+## Aging analysis
+
+<!-- AGENT: How long have pending items been in the backlog? Any items that should
+     be promoted to the roadmap or removed? -->
+
+| Age bracket | Count |
+|-------------|-------|
+| Added this phase | {N} |
+| 1-2 phases old | {N} |
+| 3+ phases old | {N} |
+
+### Stale items
+
+<!-- Items that have been pending for 3+ phases. Should they be promoted, deferred, or removed? -->
+
+## Prioritization patterns
+
+<!-- AGENT: What gets completed first? Any categories consistently neglected? -->
+
+### Fast-tracked categories
+
+<!-- Categories with high completion rates — what gets done quickly? -->
+
+### Neglected categories
+
+<!-- Categories with low completion rates — what gets deferred repeatedly? -->
+
+## Recommendations
+
+<!-- AGENT: Based on backlog analysis, what should be prioritized next? -->

package/templates/full/Reviews/plan.md

@@ -0,0 +1,43 @@
+# Plan Review
+
+<!-- AGENT: Synthesize from PLAN.md. Track plan execution patterns — how well do plans
+     match actual outcomes? What patterns emerge in task sizing and completion?
+     Update after each plan completes or when plan structure changes.
+
+     Source: PLAN.md (current), SUMMARY.md (historical)
+     Parent: Reviews/INDEX.md (update "At a glance" row when this changes) -->
+
+## Current plan status
+
+| Field | Value |
+|-------|-------|
+| Plan | {current plan name/phase} |
+| Steps | {completed}/{total} |
+| Status | {in progress / blocked / complete} |
+| Started | {date} |
+
+## Execution history
+
+<!-- AGENT: Track completed plans. Populate from SUMMARY.md audit trail. -->
+
+| Plan | Steps | Outcome | Duration | Revisions |
+|------|-------|---------|----------|-----------|
+<!-- {plan name} | {N steps} | {completed / partial / abandoned} | {time} | {count} -->
+
+## Execution patterns
+
+<!-- AGENT: What patterns emerge across plan completions? -->
+
+### Task sizing accuracy
+
+- **Plans completed as designed**: {count} ({%})
+- **Plans that needed scope adjustment**: {count} ({%})
+- **Plans abandoned/rewritten**: {count} ({%})
+
+### Common revision triggers
+
+<!-- What causes plans to be revised? -->
+
+### Step completion patterns
+
+<!-- Do certain types of steps take longer or fail more often? -->