agent-method 1.5.12

package/README.md

@@ -0,0 +1,343 @@
+# 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, 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
+
+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 project takes a different position: it treats files and documentation as the primary interface between you and your agent, so work stays understandable, auditable, and easy to review.
+
+If you want to build with an agent but also want clear visibility into the work being done and the decisions being made, this methodology is designed 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) / Composer, [Gemini](https://gemini.google.com), [Codex](https://openai.com/index/codex/), or any agent that reads markdown
+
+---
+
+## Installation
+
+### Quick start (recommended)
+
+Install once, use everywhere:
+
+```bash
+npm install -g agent-method
+wwa 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 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.
+
+To update an existing project later:
+
+```bash
+wwa upgrade    # adds new methodology sections, never overwrites
+wwa status     # check your current version
+```
+
+<details>
+<summary><strong>Zero-install</strong> — no global install needed</summary>
+
+```bash
+npx agent-method init
+```
+
+Runs directly via npx without installing anything. Useful for one-time setup or CI.
+
+</details>
+
+<details>
+<summary><strong>Non-interactive install</strong> — CI, scripts, Docker</summary>
+
+Specify everything on the command line (no prompts):
+
+```bash
+# Full options
+wwa init code ~/my-project --runtime claude --tier starter --profile standard
+
+# Just type and directory (defaults for the rest)
+wwa init code ~/my-project
+
+# Data project for Cursor
+wwa init data ~/my-data --runtime cursor
+
+# Analytical project with full methodology
+wwa init context ~/my-analysis --tier full --profile full
+```
+
+**Options:**
+
+| Flag | Values | Default |
+|------|--------|---------|
+| `--runtime` | `claude`, `cursor`, `all` | `all` |
+| `--tier` | `starter`, `full` | `starter` |
+| `--profile` | `lite`, `standard`, `full` | `standard` |
+| `--onboarding` | `greenfield`, `brownfield`, `auto` | `auto` — when set to `brownfield`, `wwa init` always runs the brownfield onboarding questionnaire (even if other flags are provided) unless `--auto-configure` is also set |
+
+</details>
+
+<details>
+<summary><strong>Python alternative</strong> — same commands, same templates</summary>
+
+Requires Python >= 3.9:
+
+```bash
+pip install wwa-tools
+```
+
+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>
+
+<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
+```
+
+Or use the bash setup script directly:
+
+```bash
+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 — copies templates, feature registry, creates doc-tokens) |
+| `wwa check` | Validate your entry point |
+| `wwa scan` | Detect project type from directory contents and show a high-level methodology overview (doc structure, key files, dependency summary) |
+| `wwa project-discovery` / `wwa context-refresh` / `wwa plan-create` | Show how common workflows route 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 registry/doc-tokens.yaml |
+| `wwa refine` | Extract refinement report from SESSION-LOG.md |
+| `wwa casestudy` | Extract case study with project tokens + methodology reference data (aligned with SESSION-LOG fields) |
+| `wwa record` | Append the last CLI run’s human-readable summary to SESSION-LOG.md |
+| `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. When you run read-only developer commands without `--json` (for example `wwa scan`, `wwa plan`), the CLI prints a short **Input** block (command + main argument) and a concise **Summary** before the detailed sections so chat/terminal output is easier to read. You can then use `wwa record` to capture the latest run’s summary in `SESSION-LOG.md`.
+
+<details>
+<summary><strong>MCP Server</strong> — expose tools directly to your AI agent</summary>
+
+The `wwa serve` command runs an MCP server that IDEs and agents can call to get routing and docs advice without touching your files directly. For full setup instructions and a complete list of tools, see the [MCP Integration Guide](docs/public/guides/mcp-integration.md).
+
+</details>
+
+---
+
+## 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
+  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
+```
+
+<details>
+<summary><strong>Full tier</strong> — adds these files for complex projects</summary>
+
+```
+  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.
+
+---
+
+## About
+
+<details>
+<summary><strong>The problem</strong></summary>
+
+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.
+
+</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.
+
+**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.
+
+</details>
+
+<details>
+<summary><strong>Integration profiles</strong></summary>
+
+| Profile | Best for | What's included |
+|---------|----------|-----------------|
+| **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.
+
+</details>
+
+<details>
+<summary><strong>Project types</strong></summary>
+
+| 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 |
+
+</details>
+
+<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
+
+</details>
+
+<details>
+<summary><strong>Supported runtimes</strong></summary>
+
+| File | Runtime | Auto-loaded? |
+|------|---------|:------------:|
+| `CLAUDE.md` | Claude Code | Yes |
+| `.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
+
+| Document | Audience |
+|----------|----------|
+| [Quick start guide](docs/public/guides/quick-start.md) | Setup and first session |
+| [For developers](docs/public/guides/for-developers.md) | Workflows, context, troubleshooting |
+| [CLI tools reference](docs/public/guides/for-developers/cli-tools.md) | All 22 commands with examples |
+| [Command reference](docs/public/guides/for-developers/command-reference.md) | Tabular quick-lookup by project type |
+| [MCP Integration](docs/public/guides/mcp-integration.md) | IDE integration (VS Code, Cursor, Claude Code, Cline) |
+| [For managers](docs/public/guides/for-managers.md) | Reading project status from methodology files |
+| [Template kit](templates/README.md) | Template tiers, extensions, bootstrapping |
+| [Docs hub](docs/public/index.md) | Full public documentation hub (guides and pointers into internal specs) |
+
+## 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 |
+

package/bin/wwa.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+/**
+ * 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, 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)
+ */
+
+import { Command } from "commander";
+import { pkg } from "../lib/cli/helpers.js";
+
+import { register as check } from "../lib/cli/check.js";
+import { register as scan } from "../lib/cli/scan.js";
+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";
+import { register as docReviewCmd } from "../lib/cli/doc-review.js";
+import { register as depsCmd } from "../lib/cli/deps.js";
+import { register as updateDocsCmd } from "../lib/cli/update-docs.js";
+import { register as routable } from "../lib/cli/routable.js";
+import { register as addCmd } from "../lib/cli/add.js";
+import { register as recordCmd } from "../lib/cli/record.js";
+
+const program = new Command();
+
+program
+  .name("wwa")
+  .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" +
+      "  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" +
+      "  doc-review  Generate docs/internal/ document registry\n" +
+      "  deps        Show document dependency graph\n" +
+      "  update-docs Build/query term-to-file index for docs updates\n" +
+      "  project-discovery  Run project discovery workflow (routable)\n" +
+      "  context-refresh    Run context refresh workflow (routable)\n" +
+      "  phase-complete     Run phase completion workflow (routable)\n" +
+      "  backlog            Show routing for backlog (routable)\n" +
+      "  plan-create        Run planning workflow (routable)\n" +
+      "  dependency-analysis Run dependency analysis workflow (routable)\n" +
+      "  debt-assessment    Run debt assessment workflow (routable)\n" +
+      "  docs-update        Run docs update workflow (routable)\n" +
+      "  cross-reference    Run cross-reference workflow (routable)\n" +
+      "  add                Append to backlog, decision, finding, session, summary\n" +
+      "  record             Record last CLI run summary to SESSION-LOG.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" +
+      "  pipeline resolve    Resolve features for a workflow stage\n" +
+      "  pipeline cascade    Compute cascade chain from a trigger\n" +
+      "  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\n\n" +
+      "Shell completion:\n" +
+      "  completion          Generate tab-completion for bash/zsh/fish/powershell"
+  )
+  .version(pkg.version, "-V, --version");
+
+// Register all commands
+check(program);
+scan(program);
+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);
+docReviewCmd(program);
+depsCmd(program);
+updateDocsCmd(program);
+routable(program);
+addCmd(program);
+recordCmd(program);
+
+program.parse();