agent-method 1.5.3 → 1.5.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-method",
-  "version": "1.5.3",
+  "version": "1.5.6",
   "description": "CLI tools for the wwa methodology — registry-driven routing, validation, and project setup for AI-agent-assisted development",
   "keywords": [
     "ai-agents",
@@ -8,19 +8,27 @@
     "context-engineering",
     "methodology",
     "developer-tools",
-    "cli"
+    "cli",
+    "claude-code",
+    "cursor",
+    "gemini",
+    "codex",
+    "mcp",
+    "agent-framework"
   ],
   "type": "module",
   "license": "MIT",
   "author": "wwa contributors",
   "bin": {
-    "wwa": "bin/wwa.js"
+    "wwa": "bin/wwa.js",
+    "agent-method": "bin/wwa.js"
   },
   "files": [
     "bin/",
     "lib/",
     "templates/",
-    "docs/internal/feature-registry.yaml"
+    "docs/internal/feature-registry.yaml",
+    "docs/internal/doc-tokens.yaml"
   ],
   "main": "lib/registry.js",
   "engines": {

package/templates/README.md

@@ -4,7 +4,7 @@ Copyable project templates. Pick one, copy it into your project root, fill in PR
 
 ## Starter template (minimum viable)
 
-For most projects. Seven files that give you cross-session memory, scoped context loading, persistent codebase understanding, lifecycle tracking, and structured execution.
+For most projects. Gives you cross-session memory, scoped context loading, persistent codebase understanding, lifecycle tracking, structured execution, and management reporting.
 
 ```
 starter/
@@ -16,15 +16,31 @@ starter/
   STATE.md            # Decisions, blockers, current position
   ROADMAP.md          # Phase breakdown with gate criteria
   PLAN.md             # Current task with verification criteria
+  SUMMARY.md          # Session audit trail
+  SESSION-LOG.md      # Session metrics for case study data
   .context/
     BASE.md           # Core context -- always loaded with entry point
+    METHODOLOGY.md    # Methodology overflow for lite/standard profiles
+    feature-registry.yaml  # Feature registry (copied from package at init)
+    doc-tokens.yaml        # Project metrics (created at init, updated by wwa close)
+  Management/
+    DIGEST.md         # High-effort task digest for managers
+    STATUS.md         # Project health snapshot
+  Reviews/
+    INDEX.md          # Synthesized project intelligence dashboard
+  agentWorkflows/
+    INDEX.md          # Agent workflow performance overview
+  intro/
+    README.md         # Methodology overview + link to full docs
 ```
 
 **Setup**: Delete the two entry point files you don't use. Keep the one that matches your agent runtime.
 
-**What you get**: Persistent decisions, scoped file reading, phase-gated execution, atomic task tracking, configurable interaction level, persistent codebase context.
+**What you get**: Persistent decisions, scoped file reading, phase-gated execution, atomic task tracking, configurable interaction level, persistent codebase context, management digest, project reviews, workflow analysis, docs dependency mapping.
 
-**What you don't get**: Specialist context pairing, human-facing docs scaffold, execution history, full communication point structure.
+**docs/ is for your project**: The `docs/` folder is not pre-created — the agent creates `.context/DOCS-MAP.md` during first-session onboarding and proposes docs/ files as your project grows based on its scaffolding rules.
+
+**What you don't get**: Specialist context pairing, full review drill-downs, full workflow analysis files.
 
 ## Full template (complete methodology)
 
@@ -32,27 +48,49 @@ For complex or multi-phase projects where context management and dual-audience s
 
 ```
 full/
-  CLAUDE.md         # Claude Code entry point (auto-loaded)
-  .cursorrules      # Cursor entry point (auto-loaded)
-  AGENT.md          # Generic entry point (manual loading)
+  CLAUDE.md           # Claude Code entry point (auto-loaded)
+  .cursorrules        # Cursor entry point (auto-loaded)
+  AGENT.md            # Generic entry point (manual loading)
   PROJECT.md          # Vision, audiences, structure
   PROJECT-PROFILE.md  # Project type, lifecycle, extensions (agent-maintained)
   STATE.md            # Decisions, blockers, position, open questions
   REQUIREMENTS.md     # Scoped features with phase traceability
-  ROADMAP.md        # Phase breakdown with gate criteria
-  PLAN.md           # Current atomic task
-  SUMMARY.md        # Execution history (session audit trail)
+  ROADMAP.md          # Phase breakdown with gate criteria
+  PLAN.md             # Current atomic task
+  SUMMARY.md          # Session audit trail
+  SESSION-LOG.md      # Session metrics for case study data
   .context/
-    BASE.md         # Core context -- always loaded with entry point
-  docs/
-    index.md        # Human-facing project dashboard (checkpoint records land here)
+    BASE.md           # Core context -- always loaded with entry point
+    METHODOLOGY.md    # Methodology overflow for lite/standard profiles
+    REGISTRY.md       # Navigation registry for split file trees
+    COMPOSITION.md    # Specialist template for analytical projects
+    feature-registry.yaml  # Feature registry (copied from package at init)
+    doc-tokens.yaml        # Project metrics (created at init, updated by wwa close)
+  Management/
+    DIGEST.md         # High-effort task digest for managers
+    STATUS.md         # Project health snapshot
+  Reviews/
+    INDEX.md          # Synthesized project intelligence dashboard
+    roadmap.md        # Phase progress synthesis
+    plan.md           # Plan execution history
+    project.md        # Project scope evolution
+    requirements.md   # Requirements traceability matrix
+    state.md          # Decision trends and blocker analysis
+    backlog.md        # Backlog health and aging
+  agentWorkflows/
+    INDEX.md          # Agent workflow performance overview
+    sessions.md       # Session analysis from SESSION-LOG.md
+    patterns.md       # Extracted behavioral patterns
+    observations.md   # Case study observations
+  intro/
+    README.md         # Methodology overview + link to full docs
   todos/
-    backlog.md      # Captured ideas for future work
+    backlog.md        # Captured ideas for future work
 ```
 
 **Setup**: Delete the two entry point files you don't use. Keep the one that matches your agent runtime.
 
-**What you get**: Everything in starter, plus specialist context pairing, dependency cascade, execution history, human dashboard scaffold, backlog capture, full communication point structure (direction, checkpoint, record).
+**What you get**: Everything in starter, plus specialist context pairing, dependency cascade, execution history, human dashboard scaffold, backlog capture, full review drill-downs, full workflow analysis, full communication point structure (direction, checkpoint, record).
 
 ## Template content: guided, not empty
 
@@ -229,7 +267,7 @@ See `docs/architecture/context-pairing.md` for the full context maintenance life
 ### Recommended: npx
 
 ```bash
-npx wwa init code ~/my-project
+npx agent-method init code ~/my-project
 ```
 
 Replace `code` with: `context`, `data`, `mix`, or `general`.
@@ -249,8 +287,8 @@ See `docs/guides/quick-start.md` for a detailed walkthrough.
 The methodology works without any tooling. For teams that want additional validation and automation:
 
 ```bash
-npx wwa                        # zero-install (Node.js 18+)
-npm install -g wwa             # permanent install
+npx agent-method                        # zero-install (Node.js 18+)
+npm install -g agent-method             # permanent install
 pip install wwa-tools          # Python alternative
 ```
 
@@ -258,13 +296,23 @@ pip install wwa-tools          # Python alternative
 
 | Command | Use case |
 |---------|----------|
-| `npx wwa check` | Validate entry point (auto-finds CLAUDE.md/.cursorrules/AGENT.md) |
-| `npx wwa scan` | Detect project type from directory contents |
-| `npx wwa route "<query>"` | Test how a query routes through the pipeline |
-| `npx wwa refine` | Extract refinement report (auto-finds SESSION-LOG.md) |
-| `npx wwa status` | Check if methodology version is current |
-| `npx wwa upgrade` | Brownfield-safe update (adds missing files, updates version) |
-| `npx wwa init <type>` | Describe entry point contents for a project type |
+| `wwa check` | Validate entry point (auto-finds CLAUDE.md/.cursorrules/AGENT.md) |
+| `wwa scan` | Detect project type from directory contents |
+| `wwa route "<query>"` | Test how a query routes through the pipeline |
+| `wwa plan` | Display current plan status from PLAN.md |
+| `wwa implement` | Show implementation guidance for current step |
+| `wwa review` | Display project review dashboard |
+| `wwa digest` | Show management digest |
+| `wwa close` | Session close checklist, project snapshot, updates .context/doc-tokens.yaml |
+| `wwa refine` | Extract refinement report (auto-finds SESSION-LOG.md) |
+| `wwa casestudy` | Extract case study with project tokens + methodology reference data |
+| `wwa docs` | Show docs coverage report from DOCS-MAP.md |
+| `wwa status` | Check if methodology version is current |
+| `wwa upgrade` | Brownfield-safe update (adds missing files, updates version) |
+| `wwa init <type>` | Set up a new project |
+| `wwa completion` | Generate shell tab-completion (bash/zsh/fish/PowerShell) |
+
+**Safety invariant**: The CLI tool never modifies user source code. Only `.md` and `.yaml`/`.yml` files are writable.
 
 ### Project types
 
@@ -279,7 +327,7 @@ wwa init mix       # multi-type project
 
 ### Advanced: pipeline subcommands
 
-For debugging routing logic: `npx wwa pipeline classify|select|resolve|cascade|test`.
+For debugging routing logic: `wwa pipeline classify|select|resolve|cascade|test`.
 
 ### Dependencies
 

package/templates/entry-points/.cursorrules

@@ -7,7 +7,8 @@
 
 1. This file is auto-loaded — read it first
 2. Read `STATE.md` for current position, decisions, blockers
-3. Scope based on query type (see table below)
+3. Check `PROJECT-PROFILE.md` for lifecycle stage and active extensions
+4. Scope based on query type (see table below)
 
 ## Scoping rules
 
@@ -15,10 +16,16 @@
 |------------|-------------------|-------------------|
 | **Planning / roadmap** | REQUIREMENTS.md, ROADMAP.md | STATE.md, PLAN.md |
 | **Context refresh** | .context/ (all), project structure | .context/, this file (if scoping rules affected) |
+| **Project discovery** | Project structure, package files, key source files | .context/BASE.md, .context/ specialists, STATE.md |
 | **{your-domain-type}** | .context/BASE.md + .context/{SPECIALIST}.md | {affected working files} |
+| **Structural navigation** | .context/REGISTRY.md | .context/REGISTRY.md (if structure changed) |
 | **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. -->
@@ -35,18 +42,129 @@ When a file changes, check this table and update dependent files in the same res
 | Open question resolved | STATE.md (mark resolved with resolution text, don't delete) |
 | Project structure | .context/BASE.md (codebase map), this file (if new query types needed) |
 | Intelligence layer file exceeds 300 lines | Restructure into index + components subdirectory (keep active content, archive completed sections) |
+| 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) |
-| Session close or high-effort task completion | SESSION-LOG.md (append metrics entry — effort, ambiguity, context level, tokens, time, workflow, features, cascades, friction, findings) |
+| 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). 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.
+     For full component-to-docs mapping, see .context/DOCS-MAP.md. -->
+
+| Trigger | Update these 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
 
 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
+- **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
 
@@ -56,7 +174,7 @@ mode: checkpoint
 
 ## Model tier
 
-tier: standard
+tier: full
 <!-- lite | standard | full -->
 <!-- lite: minimal rules, STATE.md only, 2 cascade rules — for Haiku or simple projects -->
 <!-- standard: core rules + context pairing, overflow to .context/METHODOLOGY.md — for Sonnet (default) -->
@@ -66,21 +184,28 @@ tier: standard
 
 method_version: 1.5
 <!-- Tracks which methodology version generated this entry point -->
-<!-- Use `npx wwa status` to compare against latest -->
+<!-- Use `wwa status` to compare against latest -->
 
 ## CLI tools (optional)
 
-Available via `npx wwa` (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 wwa check` |
-| See what type of project this is | `npx wwa scan` |
-| Test how a query routes | `npx wwa route "your question"` |
-| Extract a refinement report | `npx wwa refine` |
-| Check methodology version | `npx wwa status` |
-| Update methodology files | `npx wwa upgrade` |
-| See what an entry point should contain | `npx wwa 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
@@ -95,7 +220,9 @@ Available via `npx wwa` (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
-- 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, and time. Never skip, never read previous entries during normal work
+- 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
 
@@ -105,5 +232,7 @@ Available via `npx wwa` (zero-install) or `pip install wwa-tools`:
 - Defer STATE.md decision recording to end of session
 - 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/entry-points/AGENT.md

@@ -7,7 +7,8 @@
 
 1. This file is auto-loaded — read it first
 2. Read `STATE.md` for current position, decisions, blockers
-3. Scope based on query type (see table below)
+3. Check `PROJECT-PROFILE.md` for lifecycle stage and active extensions
+4. Scope based on query type (see table below)
 
 ## Scoping rules
 
@@ -15,10 +16,16 @@
 |------------|-------------------|-------------------|
 | **Planning / roadmap** | REQUIREMENTS.md, ROADMAP.md | STATE.md, PLAN.md |
 | **Context refresh** | .context/ (all), project structure | .context/, this file (if scoping rules affected) |
+| **Project discovery** | Project structure, package files, key source files | .context/BASE.md, .context/ specialists, STATE.md |
 | **{your-domain-type}** | .context/BASE.md + .context/{SPECIALIST}.md | {affected working files} |
+| **Structural navigation** | .context/REGISTRY.md | .context/REGISTRY.md (if structure changed) |
 | **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. -->
@@ -35,18 +42,129 @@ When a file changes, check this table and update dependent files in the same res
 | Open question resolved | STATE.md (mark resolved with resolution text, don't delete) |
 | Project structure | .context/BASE.md (codebase map), this file (if new query types needed) |
 | Intelligence layer file exceeds 300 lines | Restructure into index + components subdirectory (keep active content, archive completed sections) |
+| 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) |
-| Session close or high-effort task completion | SESSION-LOG.md (append metrics entry — effort, ambiguity, context level, tokens, time, workflow, features, cascades, friction, findings) |
+| 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). 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.
+     For full component-to-docs mapping, see .context/DOCS-MAP.md. -->
+
+| Trigger | Update these 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
 
 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
+- **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
 
@@ -56,7 +174,7 @@ mode: checkpoint
 
 ## Model tier
 
-tier: standard
+tier: full
 <!-- lite | standard | full -->
 <!-- lite: minimal rules, STATE.md only, 2 cascade rules — for Haiku or simple projects -->
 <!-- standard: core rules + context pairing, overflow to .context/METHODOLOGY.md — for Sonnet (default) -->
@@ -66,21 +184,28 @@ tier: standard
 
 method_version: 1.5
 <!-- Tracks which methodology version generated this entry point -->
-<!-- Use `npx wwa status` to compare against latest -->
+<!-- Use `wwa status` to compare against latest -->
 
 ## CLI tools (optional)
 
-Available via `npx wwa` (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 wwa check` |
-| See what type of project this is | `npx wwa scan` |
-| Test how a query routes | `npx wwa route "your question"` |
-| Extract a refinement report | `npx wwa refine` |
-| Check methodology version | `npx wwa status` |
-| Update methodology files | `npx wwa upgrade` |
-| See what an entry point should contain | `npx wwa 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
@@ -95,7 +220,9 @@ Available via `npx wwa` (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
-- 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, and time. Never skip, never read previous entries during normal work
+- 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
 
@@ -105,5 +232,7 @@ Available via `npx wwa` (zero-install) or `pip install wwa-tools`:
 - Defer STATE.md decision recording to end of session
 - 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 -->