agent-method 1.5.0 → 1.5.3

package/README.md

@@ -1,256 +1,246 @@
-# agent-method
-
-A file-structure-first methodology for AI-agent-assisted development. Files are the interface — with optional CLI tools for validation, routing, and project management.
-
-`ai-agents` `prompt-engineering` `developer-tools` `context-engineering` `agent-framework` `markdown` `llm-tools` `ai-workflow` `cursor` `claude-code`
-
----
-
-## The problem
-
-AI-agent-assisted development breaks down in three ways:
-
-- **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
-
-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.
-
-## Quick start
-
-### Option A: npx (recommended, zero-install)
-
-```bash
-npx agent-method init code ~/my-project
-```
-
-Replace `code` with your project type: `code`, `context`, `data`, `mix`, or `general`.
-
-Done. Templates are copied, extensions merged, placeholders filled. Open `PROJECT.md` and start working.
-
-### Option B: Setup script
-
-```bash
-git clone https://github.com/anthropics/agent-method.git
-cd agent-method
-bash setup.sh ~/my-project
-```
-
-Interactive installer — asks project name, type, runtime, tier, lifecycle, and profile.
-
-### Option C: Manual copy
-
-```
-cp -r templates/starter/ ~/my-project/
-```
-
-Delete the two entry point files you don't use and fill in `PROJECT.md`.
-
-## CLI Tools (optional)
-
-The methodology works entirely through files, but CLI tools are available for validation, routing, and project management.
-
-### Installation
-
-```bash
-npx agent-method            # zero-install, runs directly
-```
-
-Or install permanently:
-
-```bash
-npm install -g agent-method           # Node.js (global)
-pip install agent-method-tools        # Python (alternative)
-```
-
-Both distributions have identical commands, same registry, same templates.
-
-### Developer commands
-
-| Command | What it does |
-|---------|-------------|
-| `agent-method check` | Validate your entry point (auto-finds file, auto-detects type) |
-| `agent-method scan` | Detect project type from directory contents |
-| `agent-method route "<query>"` | Show how a query routes through the pipeline |
-| `agent-method refine` | Extract refinement report from SESSION-LOG.md |
-| `agent-method status` | Check if your methodology version is current |
-| `agent-method upgrade` | Brownfield-safe methodology update |
-| `agent-method init <type>` | Describe entry point contents for a project type |
-
-### Project type aliases
-
-Use friendly names with any command: `code`, `context`, `data`, `mix`, `general`.
-
-```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
-```
-
-### Advanced: pipeline subcommands
-
-For debugging individual pipeline stages: `agent-method pipeline classify|select|resolve|cascade|test`.
-
-### Key features
-
-- **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
-
-Run `agent-method --help` for full command reference.
-
-## What you get
-
-```
-your-project/
-  CLAUDE.md / .cursorrules / AGENT.md   # Agent entry point (pick one)
-  PROJECT.md            # Project vision — fill this in first
-  PROJECT-PROFILE.md    # Project type, lifecycle stage, extensions
-  STATE.md              # Decisions, blockers, current position
-  ROADMAP.md            # Phase breakdown with gate criteria
-  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)
-```
-
-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
-
-### Scoping rules
-
-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.
-
-```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         |
-```
-
-### Dependency cascade
-
-"When X changes, also update Y." The agent checks this table after every file change, preventing files from drifting out of sync.
-
-```markdown
-| When this changes    | Also update                                    |
-|----------------------|------------------------------------------------|
-| Database schema      | Migrations, type imports, .context/DATABASE.md |
-| Phase completion     | SUMMARY.md, STATE.md, ROADMAP.md               |
-```
-
-### Context pairing
-
-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.
-
-### Cross-session memory
-
-`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.
-
-## Integration profiles
-
-Control how much methodology surface area gets installed. Match the profile to your model's capability.
-
-| 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 |
-
-Three rules followed consistently beat ten rules followed inconsistently.
-
-## Project types
-
-| 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.) |
-
-Extensions are additive — they add rows to existing tables, never override universal content.
-
-## Brownfield projects (existing codebases)
-
-For projects with existing code, `setup.sh` detects project indicators and activates brownfield mode:
-
-- **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:
-
-> Ask your agent: "Scan the codebase and populate the context files"
-
-The agent inventories your project, maps dependencies, extracts patterns, and bootstraps `.context/` files — all without modifying your source code.
-
-## Lifecycle stages
-
-Projects evolve. The methodology adapts.
-
-| 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 |
-
-Transitions happen naturally — update `PROJECT-PROFILE.md` when you're ready to move on.
-
-## Supported runtimes
-
-| File | Runtime | Auto-loaded? |
-|------|---------|:------------:|
-| `CLAUDE.md` | Claude Code | Yes |
-| `.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
-
-**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 |
-| [Template kit](templates/README.md) | Template tiers, extensions, bootstrapping |
-| [CLI tools](https://github.com/anthropics/agent-method#cli-tools-optional) | Command reference (or run `agent-method --help`) |
-| [Docs hub](docs/index.md) | Full architecture, workflow, and methodology docs |
-
-## 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 |
-
-## License
-
-MIT (pending)
+# 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.
+
+`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.
+
+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
+
+## Getting Started
+
+```bash
+npx wwa init
+```
+
+The installer guides 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.
+
+### Verify
+
+```bash
+npx wwa check
+```
+
+Validates your entry point, auto-detects project type, and reports any issues.
+
+## Staying Updated
+
+```bash
+npx wwa upgrade
+```
+
+Brownfield-safe — appends new methodology sections without overwriting your customizations. Check your current version with `npx wwa status`.
+
+## Non-interactive Install (CI, Scripts, Docker)
+
+```bash
+# Specify everything on the command line
+npx 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
+
+# Data project for Cursor
+npx wwa init data ~/my-data --runtime cursor
+
+# Analytical project with full methodology
+npx wwa init context ~/my-analysis --tier full --profile full
+```
+
+### Install globally
+
+Instead of `npx` each time:
+
+```bash
+npm install -g wwa
+```
+
+### Python alternative
+
+Same commands, same registry, same templates:
+
+```bash
+pip install wwa-tools        # requires Python >= 3.9
+```
+
+## Development Installation
+
+Clone and run locally for testing or contributing:
+
+```bash
+git clone https://github.com/anthropics/wwa.git
+cd wwa
+npm link
+wwa init code ./test-project --runtime claude
+```
+
+Or use the bash setup script directly:
+
+```bash
+bash setup.sh ~/my-project
+```
+
+Interactive — asks project name, type, runtime, tier, lifecycle, and profile.
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `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.
+
+### MCP Server (AI tool integration)
+
+Expose methodology tools directly to your AI agent via the [Model Context Protocol](https://modelcontextprotocol.io):
+
+```json
+{
+  "mcpServers": {
+    "wwa": {
+      "command": "npx",
+      "args": ["wwa", "serve"]
+    }
+  }
+}
+```
+
+8 tools available. Works with VS Code, Cursor, Claude Code, Cline. See [MCP Integration Guide](docs/guides/mcp-integration.md).
+
+### Pipeline commands (advanced)
+
+For debugging individual pipeline stages:
+
+```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/
+```
+
+## What You Get
+
+```
+your-project/
+  CLAUDE.md / .cursorrules / AGENT.md   # Agent entry point (pick one)
+  PROJECT.md            # Project vision — fill this in first
+  PROJECT-PROFILE.md    # Project type, lifecycle stage, extensions
+  STATE.md              # Decisions, blockers, current position
+  ROADMAP.md            # Phase breakdown with gate criteria
+  PLAN.md               # Current task with verification criteria
+  .context/
+    BASE.md             # Core context — always loaded with entry point
+    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.
+
+---
+
+## About
+
+### The problem
+
+AI-agent-assisted development breaks down in three ways:
+
+- **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
+
+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
+
+**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.
+
+**Dependency cascade** — "When X changes, also update Y." The agent checks this table after every file change, preventing files from drifting out of sync.
+
+**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.
+
+**Cross-session memory** — `STATE.md` persists decisions, blockers, and current position across sessions. No re-explaining what happened yesterday.
+
+### Integration profiles
+
+| 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 |
+
+Three rules followed consistently beat ten rules followed inconsistently.
+
+### Project types
+
+| 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 |
+
+### Brownfield projects
+
+Works with existing codebases:
+
+- **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
+
+| File | Runtime | Auto-loaded? |
+|------|---------|:------------:|
+| `CLAUDE.md` | Claude Code | Yes |
+| `.cursorrules` | Cursor | Yes |
+| `AGENT.md` | Any agent | No (paste or reference manually) |
+
+## Documentation
+
+| Document | Audience |
+|----------|----------|
+| [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 |
+| [Docs hub](docs/index.md) | Full architecture, workflow, and methodology docs |
+
+## Prior art
+
+| System | Relationship |
+|--------|-------------|
+| [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
+
+MIT (pending)

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();

package/lib/cli/check.js

@@ -1,4 +1,4 @@
-/** agent-method check — validate entry point and project setup. */
+/** wwa check — validate entry point and project setup. */
 
 import { dirname, resolve } from "node:path";
 import {
@@ -28,7 +28,7 @@ export function register(program) {
           console.error(
             "No entry point found in current directory " +
               "(looked for CLAUDE.md, .cursorrules, AGENT.md).\n" +
-              "Specify a path: agent-method check path/to/CLAUDE.md"
+              "Specify a path: npx wwa check path/to/CLAUDE.md"
           );
           process.exit(1);
         }