agent-method 1.5.1 → 1.5.5

package/README.md

@@ -1,108 +1,229 @@
-# agent-method
+# wwa
 
-A file-structure-first methodology for AI-agent-assisted development. Files are the interface — with optional CLI tools for validation, routing, and project management.
+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.
 
-`ai-agents` `prompt-engineering` `developer-tools` `context-engineering` `agent-framework` `markdown` `llm-tools` `ai-workflow` `cursor` `claude-code`
+`ai-agents` `prompt-engineering` `developer-tools` `context-engineering` `agent-framework` `mcp` `model-context-protocol` `cursor` `claude-code`
 
 ---
 
-## The problem
+## Who This Is For
 
-AI-agent-assisted development breaks down in three ways:
+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.
 
-- **Context rot** — agent quality degrades as context windows fill with irrelevant conversation
-- **Amnesia** — decisions from session N are lost by session N+1
-- **Scope drift** — without structured gates, work sprawls and progress becomes invisible
+This 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 — this is for you.
+
+---
+
+## Requirements
+
+- **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), or any agent that reads markdown files
+
+---
 
-Existing solutions tie you to specific agent runtimes through CLI tools and slash commands. agent-method solves this with **files as the interface** — readable, portable, agent-agnostic.
+## Installation
 
-## Quick start
+### Quick start (recommended)
+
+One command, guided prompts:
+
+```bash
+npx agent-method init
+```
+
+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)
+5. **Integration profile** — Standard (Sonnet, recommended), Lite (Haiku), or Full (Opus)
+
+Done. Open `PROJECT.md` and start working with your AI agent.
+
+To update an existing project later:
+
+```bash
+npx agent-method upgrade    # adds new methodology sections, never overwrites
+npx agent-method status     # check your current version
+```
 
-### Option A: npx (recommended, zero-install)
+<details>
+<summary><strong>Install globally</strong> — skip <code>npx</code> each time</summary>
 
 ```bash
+npm install -g agent-method
+```
+
+After this, use `wwa` directly:
+
+```bash
+wwa init
+wwa check
+wwa status
+```
+
+Both `wwa` and `agent-method` work as command names.
+
+</details>
+
+<details>
+<summary><strong>Non-interactive install</strong> — CI, scripts, Docker</summary>
+
+Specify everything on the command line (no prompts):
+
+```bash
+# Full options
+npx agent-method init code ~/my-project --runtime claude --tier starter --profile standard
+
+# Just type and directory (defaults for the rest)
 npx agent-method init code ~/my-project
+
+# Data project for Cursor
+npx agent-method init data ~/my-data --runtime cursor
+
+# Analytical project with full methodology
+npx agent-method init context ~/my-analysis --tier full --profile full
 ```
 
-Replace `code` with your project type: `code`, `context`, `data`, `mix`, or `general`.
+**Options:**
+
+| Flag | Values | Default |
+|------|--------|---------|
+| `--runtime` | `claude`, `cursor`, `all` | `all` |
+| `--tier` | `starter`, `full` | `starter` |
+| `--profile` | `lite`, `standard`, `full` | `standard` |
+
+</details>
 
-Done. Templates are copied, extensions merged, placeholders filled. Open `PROJECT.md` and start working.
+<details>
+<summary><strong>Python alternative</strong> — same commands, same templates</summary>
 
-### Option B: Setup script
+Requires Python >= 3.9:
 
 ```bash
-git clone https://github.com/anthropics/agent-method.git
-cd agent-method
-bash setup.sh ~/my-project
+pip install wwa-tools
 ```
 
-Interactive installer — asks project name, type, runtime, tier, lifecycle, and profile.
+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>
 
-### Option C: Manual copy
+<details>
+<summary><strong>Development install</strong> — contributing or testing locally</summary>
 
+```bash
+git clone https://github.com/anthropics/wwa.git
+cd wwa
+npm link
+wwa init code ./test-project --runtime claude
 ```
-cp -r templates/starter/ ~/my-project/
+
+Or use the bash setup script directly:
+
+```bash
+bash setup.sh ~/my-project
 ```
 
-Delete the two entry point files you don't use and fill in `PROJECT.md`.
+Interactive — asks project name, type, runtime, tier, lifecycle, and profile.
 
-## CLI Tools (optional)
+</details>
 
-The methodology works entirely through files, but CLI tools are available for validation, routing, and project management.
+---
 
-### Installation
+## Verify
 
 ```bash
-npx agent-method            # zero-install, runs directly
+npx agent-method check
 ```
 
-Or install permanently:
+Validates your entry point, auto-detects project type, and reports any issues.
+
+---
+
+## Staying Updated
 
 ```bash
-npm install -g agent-method           # Node.js (global)
-pip install agent-method-tools        # Python (alternative)
+npx agent-method upgrade
 ```
 
-Both distributions have identical commands, same registry, same templates.
+Brownfield-safe — appends new methodology sections without overwriting your customizations.
+
+```bash
+npx agent-method status    # check your current version
+```
+
+---
 
-### Developer commands
+## Commands
 
 | Command | What it does |
 |---------|-------------|
-| `npx agent-method check` | Validate your entry point (auto-finds file, auto-detects type) |
-| `npx agent-method scan` | Detect project type from directory contents |
-| `npx agent-method route "<query>"` | Show how a query routes through the pipeline |
-| `npx agent-method refine` | Extract refinement report from SESSION-LOG.md |
-| `npx agent-method status` | Check if your methodology version is current |
-| `npx agent-method upgrade` | Brownfield-safe methodology update |
-| `npx agent-method init <type>` | Describe entry point contents for a project type |
+| `wwa init` | Set up a new project (interactive) |
+| `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 refine` | Extract refinement report from SESSION-LOG.md |
+| `wwa status` | Check if your methodology version is current |
+| `wwa upgrade` | Brownfield-safe methodology update |
+| `wwa serve` | Start MCP server for IDE integration |
+| `wwa watch` | Watch files, validate on save |
+
+All commands support `--json` for machine-readable output.
+
+<details>
+<summary><strong>MCP Server</strong> — expose tools directly to your AI agent</summary>
+
+Add to your IDE's MCP config (VS Code, Cursor, Claude Code, Cline):
+
+```json
+{
+  "mcpServers": {
+    "wwa": {
+      "command": "npx",
+      "args": ["agent-method", "serve"]
+    }
+  }
+}
+```
 
-### Project type aliases
+**8 tools available:**
 
-Use friendly names with any command: `code`, `context`, `data`, `mix`, `general`.
+| 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 |
 
-```bash
-agent-method init code                # software project
-agent-method init context             # analytical/prompt project (PromptStudy)
-agent-method init data                # data index/querying project (SysMLv2)
-agent-method init mix                 # multi-type project
-agent-method route "query" -p context # route with project type
-```
+See [MCP Integration Guide](docs/guides/mcp-integration.md) for full setup.
 
-### Advanced: pipeline subcommands
+</details>
 
-For debugging individual pipeline stages: `npx agent-method pipeline classify|select|resolve|cascade|test`.
+<details>
+<summary><strong>Pipeline commands</strong> — debug individual pipeline stages</summary>
+
+```bash
+wwa pipeline classify "<query>" --project-type code
+wwa pipeline select code_change
+wwa pipeline resolve WF-02 --stage execute
+wwa pipeline cascade --trigger phase_completion
+wwa pipeline test fixtures/
+```
 
-### Key features
+These are primarily for debugging and development. Most users won't need them.
 
-- **All commands support `--json`** for machine-readable output
-- **Smart defaults** — auto-finds entry point, session log, and project type
-- **Two distributions** — `npx agent-method` (Node.js, zero-install) or `pip install agent-method-tools` (Python)
-- **CLI is opt-in** — methodology works without it; tools add convenience
+</details>
 
-Run `npx agent-method --help` for full command reference.
+---
 
-## What you get
+## What You Get
 
 ```
 your-project/
@@ -114,96 +235,95 @@ your-project/
   PLAN.md               # Current task with verification criteria
   .context/
     BASE.md             # Core context — always loaded with entry point
-    METHODOLOGY.md      # Workflows, conventions overflow (lite/standard profiles)
+    METHODOLOGY.md      # Workflows, conventions overflow
 ```
 
-Full tier adds: `REQUIREMENTS.md`, `SUMMARY.md`, `.context/REGISTRY.md`, `docs/`, `todos/backlog.md`.
-
-Every file ships with **inline instructions** — the agent reads them and helps you populate each section.
-
-## How it works
+<details>
+<summary><strong>Full tier</strong> — adds these files for complex projects</summary>
 
-### Scoping rules
+```
+  REQUIREMENTS.md       # Formal requirements with traceability
+  SUMMARY.md            # Session audit trail
+  .context/
+    REGISTRY.md         # Navigation registry for large projects
+  docs/
+    index.md            # Documentation hub
+  todos/
+    backlog.md          # Ideas and future work
+```
 
-The entry point contains a table mapping query types to file sets. When you ask a question, the agent loads only the relevant files and constrains its writes. Context windows stay small, responses stay focused.
+</details>
 
-```markdown
-| Query type          | Read before acting           | Update after acting        |
-|---------------------|------------------------------|----------------------------|
-| **Code change**     | .context/BASE.md + specialist | Source files, test files   |
-| **Planning**        | REQUIREMENTS.md, ROADMAP.md  | STATE.md, PLAN.md         |
-```
+Every file ships with **inline instructions** — the agent reads them and helps you populate each section.
 
-### Dependency cascade
+---
 
-"When X changes, also update Y." The agent checks this table after every file change, preventing files from drifting out of sync.
+## About
 
-```markdown
-| When this changes    | Also update                                    |
-|----------------------|------------------------------------------------|
-| Database schema      | Migrations, type imports, .context/DATABASE.md |
-| Phase completion     | SUMMARY.md, STATE.md, ROADMAP.md               |
-```
+<details>
+<summary><strong>The problem</strong></summary>
 
-### Context pairing
+AI-agent-assisted development breaks down in three ways:
 
-Instead of loading all context at once, the agent pairs `.context/BASE.md` with one specialist file per query type. A code change loads `BASE.md + DATABASE.md`. A planning query loads `REQUIREMENTS.md + ROADMAP.md`. Token usage stays low, relevance stays high.
+- **Context rot** — agent quality degrades as context windows fill with irrelevant conversation
+- **Amnesia** — decisions from session N are lost by session N+1
+- **Scope drift** — without structured gates, work sprawls and progress becomes invisible
 
-### Cross-session memory
+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.
 
-`STATE.md` persists decisions, blockers, and current position across sessions. The agent reads it at the start of every conversation — no re-explaining what happened yesterday.
+</details>
 
-## Integration profiles
+<details>
+<summary><strong>How it works</strong></summary>
 
-Control how much methodology surface area gets installed. Match the profile to your model's capability.
+**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.
 
-| Profile | Best for | Entry point size | What's included |
-|---------|----------|:-----------------:|-----------------|
-| **lite** | Haiku, simple projects | ~25 lines | STATE.md, minimal rules, 2 cascade rules |
-| **standard** | Sonnet (recommended) | ~40 lines | + PLAN.md, context pairing, 6 cascade rules, overflow to METHODOLOGY.md |
-| **full** | Opus, complex projects | ~60 lines | All rules inline, all intelligence layer files |
+**Dependency cascade** — "When X changes, also update Y." The agent checks this table after every file change, preventing files from drifting out of sync.
 
-Three rules followed consistently beat ten rules followed inconsistently.
+**Context pairing** — Instead of loading all context at once, the agent pairs `.context/BASE.md` with one specialist file per query type. Token usage stays low, relevance stays high.
 
-## Project types
+**Cross-session memory** — `STATE.md` persists decisions, blockers, and current position across sessions. No re-explaining what happened yesterday.
 
-| Type | CLI name | What's added to the entry point |
-|------|----------|-------------------------------|
-| **General** | `general` | Universal scoping and cascade rules only |
-| **Code** | `code` | Code change, bug fix, dependency, database, API, deployment scoping + cascade |
-| **Data** | `data` | Data ingest, schema, document, entity, relationship, analytical query scoping + cascade |
-| **Analytical** | `context` | Chain work, evaluation, composition, domain research scoping + cascade |
-| **Mixed** | `mix` | Multiple extensions combined (code+data, code+analytical, etc.) |
+</details>
 
-Extensions are additive — they add rows to existing tables, never override universal content.
+<details>
+<summary><strong>Integration profiles</strong></summary>
 
-## Brownfield projects (existing codebases)
+| 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 |
 
-For projects with existing code, `setup.sh` detects project indicators and activates brownfield mode:
+Three rules followed consistently beat ten rules followed inconsistently.
 
-- **Never overwrites** existing files — only copies methodology files that don't already exist
-- **Appends** methodology sections to your existing entry point (`CLAUDE.md`, `.cursorrules`, etc.)
-- **Preserves** all your existing conventions, rules, and project terminology
-- **Suggests** the Discovery workflow (WF-08) for systematic codebase understanding:
+</details>
 
-> Ask your agent: "Scan the codebase and populate the context files"
+<details>
+<summary><strong>Project types</strong></summary>
 
-The agent inventories your project, maps dependencies, extracts patterns, and bootstraps `.context/` files — all without modifying your source code.
+| Type | CLI name | What's added |
+|------|----------|-------------|
+| **Code** | `code` | Code change, bug fix, dependency, database, API, deployment |
+| **Data** | `data` | Data ingest, schema, document, entity, relationship, analytics |
+| **Analytical** | `context` | Chain work, evaluation, composition, domain research |
+| **Mixed** | `mix` | Multiple extensions combined |
+| **General** | `general` | Universal scoping and cascade rules only |
 
-## Lifecycle stages
+</details>
 
-Projects evolve. The methodology adapts.
+<details>
+<summary><strong>Brownfield projects</strong> — works with existing codebases</summary>
 
-| Stage | When | What activates |
-|-------|------|----------------|
-| **Discovery** | Existing project, agent maps it first | SCAN features, WF-08 discovery workflow |
-| **Design** | New project, defining architecture | Planning workflows, decision recording |
-| **Development** | Building and iterating | Code/data/analytical workflows, full cascade |
-| **Evolution** | Maintaining and extending | Context refresh, drift detection |
+- **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
 
-Transitions happen naturally — update `PROJECT-PROFILE.md` when you're ready to move on.
+</details>
 
-## Supported runtimes
+<details>
+<summary><strong>Supported runtimes</strong></summary>
 
 | File | Runtime | Auto-loaded? |
 |------|---------|:------------:|
@@ -211,45 +331,27 @@ Transitions happen naturally — update `PROJECT-PROFILE.md` when you're ready t
 | `.cursorrules` | Cursor | Yes |
 | `AGENT.md` | Any agent | No (paste or reference manually) |
 
-All three contain identical scoping rules, cascade structure, and conventions — only the filename and auto-loading behavior differ.
-
-## Template tiers
+</details>
 
-**Starter** (7 files) — Cross-session memory, scoped context loading, project profiling, structured execution. Good for most projects.
-
-**Full** (11+ files) — Everything in starter, plus requirements tracking, execution history (`SUMMARY.md`), navigation registry, human-facing docs scaffold, and backlog capture. For complex or long-running projects.
-
-## Methodology at a glance
-
-| Concept | What it does |
-|---------|-------------|
-| **Intelligence layer** | PROJECT / STATE / ROADMAP / PLAN / SUMMARY files provide persistent cross-session memory |
-| **Scoping rules** | Table-driven query routing — agent loads only what's relevant |
-| **Dependency cascade** | "When X changes, also update Y" prevents file drift |
-| **Context pairing** | One specialist file per query type, not everything at once |
-| **Workflow stages** | Initialize → Scope → Plan → Execute → Verify → Close |
-| **Integration profiles** | lite / standard / full — match methodology depth to model capability |
-| **Brownfield merge** | Append-only integration — never overwrites, never deletes |
-| **CLI tools (optional)** | 7 developer commands + pipeline subcommands for debugging |
-| **32 agent capabilities** | Organized across 8 domains, activate behind the scenes |
+---
 
 ## Documentation
 
 | Document | Audience |
 |----------|----------|
-| [Quick start guide](docs/guides/quick-start.md) | Developers — setup and first session |
-| [For developers](docs/guides/for-developers.md) | Developers — workflows, context, troubleshooting |
-| [For managers](docs/guides/for-managers.md) | Managers — reading project status from methodology files |
+| [Quick start guide](docs/guides/quick-start.md) | Setup and first session |
+| [For developers](docs/guides/for-developers.md) | Workflows, context, troubleshooting |
+| [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 |
-| [CLI tools](https://github.com/anthropics/agent-method#cli-tools-optional) | Command reference (or run `npx agent-method --help`) |
 | [Docs hub](docs/index.md) | Full architecture, workflow, and methodology docs |
 
-## Prior art
+## Prior Art
 
 | System | Relationship |
 |--------|-------------|
-| [GSD (get-shit-done)](https://github.com/jlowin/get-shit-done) | Inspired the structured agent workflow. agent-method removes CLI dependency, adds scoping rules and context pairing |
-| PromptStudy | Reference implementation. Scoping rules, cascade, and context pairing patterns extracted from real agent-human collaboration |
+| [GSD](https://github.com/gsd-build/get-shit-done) | Inspired the structured agent workflow. wwa adds scoping rules, context pairing, and file-structure-first approach |
+| PromptStudy | Reference implementation. Patterns extracted from real agent-human collaboration |
 
 ## License
 

package/bin/{agent-method.js → wwa.js}

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 
 /**
- * agent-method CLI — methodology tools for AI-agent-assisted development.
+ * wwa CLI — methodology tools for AI-agent-assisted development.
  *
  * 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 2 (pipeline):   agent-method pipeline classify/select/resolve/cascade/test
+ *   Tier 2 (pipeline):   wwa pipeline classify/select/resolve/cascade/test
+ *   Tier 3 (server):     serve (MCP server), watch (file watcher)
  */
 
 import { Command } from "commander";
@@ -21,11 +22,13 @@ 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 pipeline } from "../lib/cli/pipeline.js";
+import { register as serve } from "../lib/cli/serve.js";
+import { register as watchCmd } from "../lib/cli/watch.js";
 
 const program = new Command();
 
 program
-  .name("agent-method")
+  .name("wwa")
   .description(
     "Methodology tools for AI-agent-assisted development.\n\n" +
       "Developer commands:\n" +
@@ -41,7 +44,10 @@ program
       "  pipeline select     Select workflow for a query type\n" +
       "  pipeline resolve    Resolve features for a workflow stage\n" +
       "  pipeline cascade    Compute cascade chain from a trigger\n" +
-      "  pipeline test       Run YAML test fixtures"
+      "  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"
   )
   .version(pkg.version, "-V, --version");
 
@@ -54,5 +60,7 @@ status(program);
 upgrade(program);
 init(program);
 pipeline(program);
+serve(program);
+watchCmd(program);
 
 program.parse();