agent-method 1.5.3 → 1.5.6

package/README.md

@@ -1,87 +1,112 @@
 # wwa
 
-A file-structure-first methodology for AI-agent-assisted development. Files are the interface — no proprietary tools, no vendor lock-in. Works with Claude Code, Cursor, or any agent that reads markdown.
+A file-structure-first methodology for AI-agent-assisted development. Files are the interface — no proprietary tools, no vendor lock-in. Works with Claude Code, Cursor, Gemini, Codex, or any agent that reads markdown.
 
 `ai-agents` `prompt-engineering` `developer-tools` `context-engineering` `agent-framework` `mcp` `model-context-protocol` `cursor` `claude-code`
 
+---
+
 ## Who This Is For
 
-People who want to describe what they want and have it built correctly — without losing context between sessions, re-explaining decisions, or watching the agent drift off scope.
+There is real stigma around AI-assisted development, and it's warranted. Most "vibe coding" produces work that no one fully understands — not the developer, not the agent, and certainly not the next person who reads the code.
+
+This spec-drive development project takes a different position. Three active case studies are being run to examine how development agents reason, where they lose context, and what structures keep their output connected to human-readable, auditable decisions. The methodology tracks agent behavior session over session — what worked, what was revised, what the human had to correct — and feeds that data back into improving future collaboration.
+
+If you want to build with an agent but also want full visibility into the work being done, the decisions being made, and a path to measurably improving your agent's effectiveness over time.
 
-If you've ever had an AI agent forget what you told it yesterday, make the same mistake twice, or change files it shouldn't have touched — this fixes that.
+---
 
 ## Requirements
 
-- **Node.js >= 18**
-- **A supported AI runtime** — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.sh), or any agent that reads markdown files
+- **Node.js >= 18** — [download](https://nodejs.org/)
+- **A supported AI runtime** — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.sh) / Composer, [Gemini](https://gemini.google.com), [Codex](https://openai.com/index/codex/), or any agent that reads markdown
+
+---
+
+## Installation
 
-## Getting Started
+### Quick start (recommended)
+
+Install once, use everywhere:
 
 ```bash
-npx wwa init
+npm install -g agent-method
+wwa init
 ```
 
-The installer guides you through everything:
+The installer walks you through everything:
 
 1. **Project type** — Code, Data, Analytical, Mixed, or General
 2. **Directory** — where to set up (default: current directory)
-3. **Runtime** — Claude Code, Cursor, or all (creates the right entry point)
-4. **Template tier** — Starter (7 files, most projects) or Full (11+ files, complex projects)
+3. **Runtime** — Claude Code, Cursor, or Other/All (Gemini, Codex, Composer, etc.)
+4. **Template tier** — Starter (17 files, most projects) or Full (30 files, complex projects)
 5. **Integration profile** — Standard (Sonnet, recommended), Lite (Haiku), or Full (Opus)
 
 Done. Open `PROJECT.md` and start working with your AI agent.
 
-### Verify
+To update an existing project later:
 
 ```bash
-npx wwa check
+wwa upgrade    # adds new methodology sections, never overwrites
+wwa status     # check your current version
 ```
 
-Validates your entry point, auto-detects project type, and reports any issues.
-
-## Staying Updated
+<details>
+<summary><strong>Zero-install</strong> — no global install needed</summary>
 
 ```bash
-npx wwa upgrade
+npx agent-method init
 ```
 
-Brownfield-safe — appends new methodology sections without overwriting your customizations. Check your current version with `npx wwa status`.
+Runs directly via npx without installing anything. Useful for one-time setup or CI.
 
-## Non-interactive Install (CI, Scripts, Docker)
+</details>
+
+<details>
+<summary><strong>Non-interactive install</strong> — CI, scripts, Docker</summary>
+
+Specify everything on the command line (no prompts):
 
 ```bash
-# Specify everything on the command line
-npx wwa init code ~/my-project --runtime claude --tier starter --profile standard
+# Full options
+wwa init code ~/my-project --runtime claude --tier starter --profile standard
 
-# Just the type and directory (defaults for the rest)
-npx wwa init code ~/my-project
+# Just type and directory (defaults for the rest)
+wwa init code ~/my-project
 
 # Data project for Cursor
-npx wwa init data ~/my-data --runtime cursor
+wwa init data ~/my-data --runtime cursor
 
 # Analytical project with full methodology
-npx wwa init context ~/my-analysis --tier full --profile full
+wwa init context ~/my-analysis --tier full --profile full
 ```
 
-### Install globally
+**Options:**
 
-Instead of `npx` each time:
+| Flag | Values | Default |
+|------|--------|---------|
+| `--runtime` | `claude`, `cursor`, `all` | `all` |
+| `--tier` | `starter`, `full` | `starter` |
+| `--profile` | `lite`, `standard`, `full` | `standard` |
+| `--onboarding` | `greenfield`, `brownfield`, `auto` | `auto` |
 
-```bash
-npm install -g wwa
-```
+</details>
 
-### Python alternative
+<details>
+<summary><strong>Python alternative</strong> — same commands, same templates</summary>
 
-Same commands, same registry, same templates:
+Requires Python >= 3.9:
 
 ```bash
-pip install wwa-tools        # requires Python >= 3.9
+pip install wwa-tools
 ```
 
-## Development Installation
+The Python CLI is an independent implementation sharing the same registry and templates. It is **not** required for the Node.js CLI — pick whichever fits your environment.
+
+</details>
 
-Clone and run locally for testing or contributing:
+<details>
+<summary><strong>Development install</strong> — contributing or testing locally</summary>
 
 ```bash
 git clone https://github.com/anthropics/wwa.git
@@ -98,42 +123,93 @@ bash setup.sh ~/my-project
 
 Interactive — asks project name, type, runtime, tier, lifecycle, and profile.
 
+</details>
+
+---
+
+## Verify
+
+```bash
+wwa check
+```
+
+Validates your entry point, auto-detects project type, and reports any issues.
+
+---
+
+## Staying Updated
+
+```bash
+wwa upgrade
+```
+
+Brownfield-safe — appends new methodology sections without overwriting your customizations.
+
+```bash
+wwa status    # check your current version
+```
+
+---
+
 ## Commands
 
 | Command | What it does |
 |---------|-------------|
-| `wwa init` | Set up a new project (interactive) |
+| `wwa init` | Set up a new project (interactive — copies templates, feature registry, creates doc-tokens) |
 | `wwa check` | Validate your entry point |
 | `wwa scan` | Detect project type from directory contents |
 | `wwa route "<query>"` | Show 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 from SESSION-LOG.md |
+| `wwa casestudy` | Extract case study with project tokens + methodology reference data |
+| `wwa docs` | Show docs coverage report from .context/DOCS-MAP.md |
 | `wwa status` | Check if your methodology version is current |
 | `wwa upgrade` | Brownfield-safe methodology update |
+| `wwa completion` | Generate shell tab-completion (bash/zsh/fish/PowerShell) |
 | `wwa serve` | Start MCP server for IDE integration |
 | `wwa watch` | Watch files, validate on save |
 
 All commands support `--json` for machine-readable output.
 
-### MCP Server (AI tool integration)
+<details>
+<summary><strong>MCP Server</strong> — expose tools directly to your AI agent</summary>
 
-Expose methodology tools directly to your AI agent via the [Model Context Protocol](https://modelcontextprotocol.io):
+Add to your IDE's MCP config (VS Code, Cursor, Claude Code, Cline):
 
 ```json
 {
   "mcpServers": {
     "wwa": {
-      "command": "npx",
-      "args": ["wwa", "serve"]
+      "command": "wwa",
+      "args": ["serve"]
     }
   }
 }
 ```
 
-8 tools available. Works with VS Code, Cursor, Claude Code, Cline. See [MCP Integration Guide](docs/guides/mcp-integration.md).
+**8 tools available:**
+
+| Tool | What it does |
+|------|-------------|
+| `route_query` | Classify a query and return read/write sets |
+| `validate_entry_point` | Check entry point for issues |
+| `detect_project` | Auto-detect project type from files |
+| `resolve_cascade` | Show what files to update after a change |
+| `check_capability` | Verify model meets task requirements |
+| `lookup_feature` | Look up a methodology feature by ID |
+| `list_workflows` | List available guided workflows |
+| `refactor_markdown` | Analyze files over 300 lines, suggest splits |
+
+See [MCP Integration Guide](docs/guides/mcp-integration.md) for full setup.
 
-### Pipeline commands (advanced)
+</details>
 
-For debugging individual pipeline stages:
+<details>
+<summary><strong>Pipeline commands</strong> — debug individual pipeline stages</summary>
 
 ```bash
 wwa pipeline classify "<query>" --project-type code
@@ -143,6 +219,12 @@ wwa pipeline cascade --trigger phase_completion
 wwa pipeline test fixtures/
 ```
 
+These are primarily for debugging and development. Most users won't need them.
+
+</details>
+
+---
+
 ## What You Get
 
 ```
@@ -153,20 +235,57 @@ your-project/
   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      # Workflows, conventions overflow
+    feature-registry.yaml  # Feature registry (populated from package)
+    doc-tokens.yaml        # Project metrics (updated by wwa close)
+  Management/
+    DIGEST.md           # High-effort task digest for managers
+    STATUS.md           # Project health snapshot
+  Reviews/
+    INDEX.md            # Project intelligence dashboard
+  agentWorkflows/
+    INDEX.md            # Agent workflow performance overview
+  intro/
+    README.md           # Methodology overview + link to full docs
 ```
 
-Full tier adds: `REQUIREMENTS.md`, `SUMMARY.md`, `.context/REGISTRY.md`, `docs/`, `todos/backlog.md`.
+<details>
+<summary><strong>Full tier</strong> — adds these files for complex projects</summary>
 
-Every file ships with **inline instructions** — the agent reads them and helps you populate each section.
+```
+  REQUIREMENTS.md       # Formal requirements with traceability
+  .context/
+    REGISTRY.md         # Navigation registry for large projects
+    COMPOSITION.md      # Specialist template for analytical projects
+  Reviews/
+    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/
+    sessions.md         # Session analysis from SESSION-LOG.md
+    patterns.md         # Extracted behavioral patterns
+    observations.md     # Case study observations
+  todos/
+    backlog.md          # Ideas and future work
+```
+
+</details>
+
+Every file ships with **inline instructions** — the agent reads them and helps you populate each section. The agent also creates `.context/DOCS-MAP.md` during your first session to map project components to documentation files.
 
 ---
 
 ## About
 
-### The problem
+<details>
+<summary><strong>The problem</strong></summary>
 
 AI-agent-assisted development breaks down in three ways:
 
@@ -176,7 +295,10 @@ AI-agent-assisted development breaks down in three ways:
 
 Existing solutions tie you to specific agent runtimes through CLI tools and slash commands. wwa solves this with **files as the interface** — readable, portable, agent-agnostic.
 
-### How it works
+</details>
+
+<details>
+<summary><strong>How it works</strong></summary>
 
 **Scoping rules** — The entry point contains a table mapping query types to file sets. The agent loads only the relevant files and constrains its writes. Context windows stay small, responses stay focused.
 
@@ -186,17 +308,23 @@ Existing solutions tie you to specific agent runtimes through CLI tools and slas
 
 **Cross-session memory** — `STATE.md` persists decisions, blockers, and current position across sessions. No re-explaining what happened yesterday.
 
-### Integration profiles
+</details>
+
+<details>
+<summary><strong>Integration profiles</strong></summary>
 
 | Profile | Best for | What's included |
 |---------|----------|-----------------|
-| **Lite** | Haiku, simple projects | STATE.md, minimal rules, 2 cascade rules |
-| **Standard** | Sonnet (recommended) | + PLAN.md, context pairing, 6 cascade rules |
-| **Full** | Opus, complex projects | All rules inline, all intelligence layer files |
+| **Lite** | Haiku, GPT-3.5, Gemini Flash | STATE.md, minimal rules, 2 cascade rules |
+| **Standard** | Sonnet, GPT-4, Gemini Pro, Codex (recommended) | + PLAN.md, context pairing, 6 cascade rules |
+| **Full** | Opus, o1, Gemini Ultra | All rules inline, all intelligence layer files |
 
 Three rules followed consistently beat ten rules followed inconsistently.
 
-### Project types
+</details>
+
+<details>
+<summary><strong>Project types</strong></summary>
 
 | Type | CLI name | What's added |
 |------|----------|-------------|
@@ -206,22 +334,32 @@ Three rules followed consistently beat ten rules followed inconsistently.
 | **Mixed** | `mix` | Multiple extensions combined |
 | **General** | `general` | Universal scoping and cascade rules only |
 
-### Brownfield projects
+</details>
 
-Works with existing codebases:
+<details>
+<summary><strong>Brownfield projects</strong> — works with existing codebases</summary>
 
 - **Never overwrites** existing files
 - **Appends** methodology sections to your existing entry point
 - **Preserves** all your existing conventions and rules
 - **Suggests** the Discovery workflow for systematic codebase understanding
 
-### Supported runtimes
+</details>
+
+<details>
+<summary><strong>Supported runtimes</strong></summary>
 
 | File | Runtime | Auto-loaded? |
 |------|---------|:------------:|
 | `CLAUDE.md` | Claude Code | Yes |
-| `.cursorrules` | Cursor | Yes |
-| `AGENT.md` | Any agent | No (paste or reference manually) |
+| `.cursorrules` | Cursor / Cursor Composer | Yes |
+| `AGENT.md` | Gemini, Codex, Cline, Aider, or any agent that reads markdown | No (paste or reference manually) |
+
+The methodology is **agent-agnostic**. `AGENT.md` works with any AI assistant — copy its contents into your tool's system prompt or context window. The file format is standard markdown; no runtime-specific features are required.
+
+</details>
+
+---
 
 ## Documentation
 
@@ -229,12 +367,14 @@ Works with existing codebases:
 |----------|----------|
 | [Quick start guide](docs/guides/quick-start.md) | Setup and first session |
 | [For developers](docs/guides/for-developers.md) | Workflows, context, troubleshooting |
+| [CLI tools reference](docs/guides/for-developers/cli-tools.md) | All 22 commands with examples |
+| [Command reference](docs/guides/for-developers/command-reference.md) | Tabular quick-lookup by project type |
 | [MCP Integration](docs/guides/mcp-integration.md) | IDE integration (VS Code, Cursor, Claude Code, Cline) |
 | [For managers](docs/guides/for-managers.md) | Reading project status from methodology files |
 | [Template kit](templates/README.md) | Template tiers, extensions, bootstrapping |
 | [Docs hub](docs/index.md) | Full architecture, workflow, and methodology docs |
 
-## Prior art
+## Prior Art
 
 | System | Relationship |
 |--------|-------------|

package/bin/wwa.js

@@ -6,7 +6,8 @@
  * Thin entry point: each command is registered from lib/cli/*.js modules.
  *
  * Three-tier command structure:
- *   Tier 1 (developer):  check, scan, route, refine, status, upgrade, init
+ *   Tier 1 (developer):  check, scan, route, refine, status, upgrade, init,
+ *                        plan, implement, review, digest, close
  *   Tier 2 (pipeline):   wwa pipeline classify/select/resolve/cascade/test
  *   Tier 3 (server):     serve (MCP server), watch (file watcher)
  */
@@ -21,9 +22,17 @@ import { register as refine } from "../lib/cli/refine.js";
 import { register as status } from "../lib/cli/status.js";
 import { register as upgrade } from "../lib/cli/upgrade.js";
 import { register as init } from "../lib/cli/init.js";
+import { register as planCmd } from "../lib/cli/plan.js";
+import { register as implementCmd } from "../lib/cli/implement.js";
+import { register as reviewCmd } from "../lib/cli/review.js";
+import { register as digestCmd } from "../lib/cli/digest.js";
+import { register as closeCmd } from "../lib/cli/close.js";
 import { register as pipeline } from "../lib/cli/pipeline.js";
 import { register as serve } from "../lib/cli/serve.js";
 import { register as watchCmd } from "../lib/cli/watch.js";
+import { register as completionCmd } from "../lib/cli/completion.js";
+import { register as casestudyCmd } from "../lib/cli/casestudy.js";
+import { register as docsCmd } from "../lib/cli/docs.js";
 
 const program = new Command();
 
@@ -32,13 +41,20 @@ program
   .description(
     "Methodology tools for AI-agent-assisted development.\n\n" +
       "Developer commands:\n" +
-      "  check     Validate your entry point and project setup\n" +
-      "  scan      Detect project type from directory contents\n" +
-      "  route     Show how a query routes through the pipeline\n" +
-      "  refine    Extract a refinement report from session history\n" +
-      "  status    Check if your methodology version is current\n" +
-      "  upgrade   Update your project to the latest methodology\n" +
-      "  init      Set up a new project with methodology templates\n\n" +
+      "  check       Validate your entry point and project setup\n" +
+      "  scan        Detect project type from directory contents\n" +
+      "  route       Show how a query routes through the pipeline\n" +
+      "  refine      Extract a refinement report from session history\n" +
+      "  status      Check if your methodology version is current\n" +
+      "  upgrade     Update your project to the latest methodology\n" +
+      "  init        Set up a new project with methodology templates\n" +
+      "  plan        Display current plan status from PLAN.md\n" +
+      "  implement   Show implementation guidance for current step\n" +
+      "  review      Display project review dashboard\n" +
+      "  digest      Show management digest\n" +
+      "  close       Session close checklist and cascade reminders\n" +
+      "  casestudy   Extract structured case study from project files\n" +
+      "  docs        Show docs coverage report from DOCS-MAP.md\n\n" +
       "Pipeline commands (advanced):\n" +
       "  pipeline classify   Classify a query against registry patterns\n" +
       "  pipeline select     Select workflow for a query type\n" +
@@ -47,7 +63,9 @@ program
       "  pipeline test       Run YAML test fixtures\n\n" +
       "Server commands:\n" +
       "  serve               Start MCP server on stdio transport\n" +
-      "  watch               Watch files and validate on change"
+      "  watch               Watch files and validate on change\n\n" +
+      "Shell completion:\n" +
+      "  completion          Generate tab-completion for bash/zsh/fish/powershell"
   )
   .version(pkg.version, "-V, --version");
 
@@ -59,8 +77,16 @@ refine(program);
 status(program);
 upgrade(program);
 init(program);
+planCmd(program);
+implementCmd(program);
+reviewCmd(program);
+digestCmd(program);
+closeCmd(program);
 pipeline(program);
 serve(program);
 watchCmd(program);
+completionCmd(program);
+casestudyCmd(program);
+docsCmd(program);
 
 program.parse();