agent-method 1.5.3 → 1.5.5

package/README.md

@@ -4,24 +4,36 @@ A file-structure-first methodology for AI-agent-assisted development. Files are
 
 `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 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.
 
-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**
+- **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
 
-## Getting Started
+---
+
+## Installation
+
+### Quick start (recommended)
+
+One command, guided prompts:
 
 ```bash
-npx wwa init
+npx agent-method 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)
@@ -31,57 +43,76 @@ The installer guides you through everything:
 
 Done. Open `PROJECT.md` and start working with your AI agent.
 
-### Verify
+To update an existing project later:
 
 ```bash
-npx wwa check
+npx agent-method upgrade    # adds new methodology sections, never overwrites
+npx agent-method status     # check your current version
 ```
 
-Validates your entry point, auto-detects project type, and reports any issues.
+<details>
+<summary><strong>Install globally</strong> — skip <code>npx</code> each time</summary>
 
-## Staying Updated
+```bash
+npm install -g agent-method
+```
+
+After this, use `wwa` directly:
 
 ```bash
-npx wwa upgrade
+wwa init
+wwa check
+wwa status
 ```
 
-Brownfield-safe — appends new methodology sections without overwriting your customizations. Check your current version with `npx wwa status`.
+Both `wwa` and `agent-method` work as command names.
+
+</details>
 
-## Non-interactive Install (CI, Scripts, Docker)
+<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
+npx agent-method 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)
+npx agent-method init code ~/my-project
 
 # Data project for Cursor
-npx wwa init data ~/my-data --runtime cursor
+npx agent-method init data ~/my-data --runtime cursor
 
 # Analytical project with full methodology
-npx wwa init context ~/my-analysis --tier full --profile full
+npx agent-method 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` |
 
-```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,6 +129,34 @@ bash setup.sh ~/my-project
 
 Interactive — asks project name, type, runtime, tier, lifecycle, and profile.
 
+</details>
+
+---
+
+## Verify
+
+```bash
+npx agent-method check
+```
+
+Validates your entry point, auto-detects project type, and reports any issues.
+
+---
+
+## Staying Updated
+
+```bash
+npx agent-method upgrade
+```
+
+Brownfield-safe — appends new methodology sections without overwriting your customizations.
+
+```bash
+npx agent-method status    # check your current version
+```
+
+---
+
 ## Commands
 
 | Command | What it does |
@@ -114,26 +173,41 @@ Interactive — asks project name, type, runtime, tier, lifecycle, and profile.
 
 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"]
+      "args": ["agent-method", "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 |
 
-### Pipeline commands (advanced)
+See [MCP Integration Guide](docs/guides/mcp-integration.md) for full setup.
 
-For debugging individual pipeline stages:
+</details>
+
+<details>
+<summary><strong>Pipeline commands</strong> — debug individual pipeline stages</summary>
 
 ```bash
 wwa pipeline classify "<query>" --project-type code
@@ -143,6 +217,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
 
 ```
@@ -158,7 +238,21 @@ your-project/
     METHODOLOGY.md      # Workflows, conventions overflow
 ```
 
-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>
+
+```
+  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
+```
+
+</details>
 
 Every file ships with **inline instructions** — the agent reads them and helps you populate each section.
 
@@ -166,7 +260,8 @@ Every file ships with **inline instructions** — the agent reads them and helps
 
 ## About
 
-### The problem
+<details>
+<summary><strong>The problem</strong></summary>
 
 AI-agent-assisted development breaks down in three ways:
 
@@ -176,7 +271,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,7 +284,10 @@ 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 |
 |---------|----------|-----------------|
@@ -196,7 +297,10 @@ Existing solutions tie you to specific agent runtimes through CLI tools and slas
 
 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,16 +310,20 @@ 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? |
 |------|---------|:------------:|
@@ -223,6 +331,10 @@ Works with existing codebases:
 | `.cursorrules` | Cursor | Yes |
 | `AGENT.md` | Any agent | No (paste or reference manually) |
 
+</details>
+
+---
+
 ## Documentation
 
 | Document | Audience |
@@ -234,7 +346,7 @@ Works with existing codebases:
 | [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/lib/cli/check.js

@@ -1,71 +1,71 @@
-/** wwa check — validate entry point and project setup. */
-
-import { dirname, resolve } from "node:path";
-import {
-  findEntryPoint,
-  resolveProjectType,
-  getPipeline,
-  loadRegistryData,
-} from "./helpers.js";
-
-export function register(program) {
-  program
-    .command("check [entry-point]")
-    .description("Validate your entry point and project setup")
-    .option(
-      "-p, --project-type <type>",
-      "Project type: code, context, data, mix, general (auto-detected if omitted)"
-    )
-    .option("--registry <path>", "Path to feature-registry.yaml")
-    .option("--json", "Output as JSON")
-    .action(async (entryPoint, opts) => {
-      const { validateEntryPoint, detectProjectType } = await getPipeline();
-      const reg = await loadRegistryData(opts.registry);
-
-      if (!entryPoint) {
-        entryPoint = findEntryPoint(".");
-        if (!entryPoint) {
-          console.error(
-            "No entry point found in current directory " +
-              "(looked for CLAUDE.md, .cursorrules, AGENT.md).\n" +
-              "Specify a path: npx wwa check path/to/CLAUDE.md"
-          );
-          process.exit(1);
-        }
-      }
-
-      let projectType;
-      if (opts.projectType) {
-        projectType = resolveProjectType(opts.projectType);
-      } else {
-        const detected = detectProjectType(dirname(resolve(entryPoint)));
-        projectType = detected.project_type || "general";
-      }
-
-      const result = validateEntryPoint(entryPoint, projectType, reg);
-      console.log(`Checking: ${entryPoint} (type: ${projectType})`);
-
-      if (opts.json) {
-        console.log(JSON.stringify(result, null, 2));
-      } else {
-        const overall = result.valid ? "PASS" : "FAIL";
-        console.log(`  Overall: ${overall}`);
-        for (const [checkId, chk] of Object.entries(result.checks)) {
-          const cStatus = chk.pass ? "PASS" : "FAIL";
-          let extra = "";
-          if (chk.missing && chk.missing.length > 0) {
-            extra = ` (missing: ${chk.missing.join(", ")})`;
-          }
-          console.log(`  ${checkId}: ${cStatus}${extra}`);
-        }
-        if (result.issues && result.issues.length > 0) {
-          console.log("\n  Issues:");
-          for (const issue of result.issues) {
-            console.log(
-              `    [${issue.severity}] ${issue.check}: ${issue.description}`
-            );
-          }
-        }
-      }
-    });
-}
+/** wwa check — validate entry point and project setup. */
+
+import { dirname, resolve } from "node:path";
+import {
+  findEntryPoint,
+  resolveProjectType,
+  getPipeline,
+  loadRegistryData,
+} from "./helpers.js";
+
+export function register(program) {
+  program
+    .command("check [entry-point]")
+    .description("Validate your entry point and project setup")
+    .option(
+      "-p, --project-type <type>",
+      "Project type: code, context, data, mix, general (auto-detected if omitted)"
+    )
+    .option("--registry <path>", "Path to feature-registry.yaml")
+    .option("--json", "Output as JSON")
+    .action(async (entryPoint, opts) => {
+      const { validateEntryPoint, detectProjectType } = await getPipeline();
+      const reg = await loadRegistryData(opts.registry);
+
+      if (!entryPoint) {
+        entryPoint = findEntryPoint(".");
+        if (!entryPoint) {
+          console.error(
+            "No entry point found in current directory " +
+              "(looked for CLAUDE.md, .cursorrules, AGENT.md).\n" +
+              "Specify a path: npx agent-method check path/to/CLAUDE.md"
+          );
+          process.exit(1);
+        }
+      }
+
+      let projectType;
+      if (opts.projectType) {
+        projectType = resolveProjectType(opts.projectType);
+      } else {
+        const detected = detectProjectType(dirname(resolve(entryPoint)));
+        projectType = detected.project_type || "general";
+      }
+
+      const result = validateEntryPoint(entryPoint, projectType, reg);
+      console.log(`Checking: ${entryPoint} (type: ${projectType})`);
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        const overall = result.valid ? "PASS" : "FAIL";
+        console.log(`  Overall: ${overall}`);
+        for (const [checkId, chk] of Object.entries(result.checks)) {
+          const cStatus = chk.pass ? "PASS" : "FAIL";
+          let extra = "";
+          if (chk.missing && chk.missing.length > 0) {
+            extra = ` (missing: ${chk.missing.join(", ")})`;
+          }
+          console.log(`  ${checkId}: ${cStatus}${extra}`);
+        }
+        if (result.issues && result.issues.length > 0) {
+          console.log("\n  Issues:");
+          for (const issue of result.issues) {
+            console.log(
+              `    [${issue.severity}] ${issue.check}: ${issue.description}`
+            );
+          }
+        }
+      }
+    });
+}