agent-method 1.5.0

package/lib/registry.js

@@ -0,0 +1,108 @@
+/**
+ * Registry loader and structured query interface.
+ *
+ * Loads feature-registry.yaml and provides typed access to features,
+ * workflows, patterns, activation maps, and protocol directives.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import yaml from "js-yaml";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Locate feature-registry.yaml by walking upward from start.
+ *
+ * Search order:
+ *   1. docs/internal/feature-registry.yaml relative to package root
+ *   2. Walk parent directories looking for docs/internal/feature-registry.yaml
+ *   3. feature-registry.yaml in start or its parents
+ */
+export function findRegistry(start) {
+  if (!start) {
+    // Default: package root (one level up from lib/)
+    start = resolve(__dirname, "..");
+  }
+
+  // Direct relative paths from the start
+  const candidates = [
+    join(start, "docs", "internal", "feature-registry.yaml"),
+    join(start, "feature-registry.yaml"),
+  ];
+  for (const p of candidates) {
+    if (existsSync(p)) return p;
+  }
+
+  // Walk upward
+  let current = resolve(start);
+  for (let i = 0; i < 10; i++) {
+    const candidate = join(current, "docs", "internal", "feature-registry.yaml");
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  throw new Error(
+    "Cannot find feature-registry.yaml. " +
+      "Provide --registry or run from the agent-method repo."
+  );
+}
+
+/**
+ * Load and return the parsed registry.
+ * Handles {placeholder} patterns in YAML by quoting them before parsing.
+ */
+export function loadRegistry(path) {
+  if (!path) path = findRegistry();
+  let content = readFileSync(path, "utf-8");
+  // The registry uses {placeholder} in flow sequences — replace them.
+  content = content.replace(/\{([^}]+)\}/g, "_$1_");
+  return yaml.load(content);
+}
+
+/** Return a map of feature ID to feature spec. */
+export function getFeatures(registry) {
+  const features = {};
+  for (const f of registry.features || []) {
+    features[f.id] = f;
+  }
+  return features;
+}
+
+/** Return the list of workflow specs. */
+export function getWorkflows(registry) {
+  return registry.workflows || [];
+}
+
+/** Return a single workflow by ID, or null. */
+export function getWorkflow(registry, workflowId) {
+  for (const wf of getWorkflows(registry)) {
+    if (wf.id === workflowId) return wf;
+  }
+  return null;
+}
+
+/** Return the list of query pattern specs. */
+export function getQueryPatterns(registry) {
+  return registry.query_patterns || [];
+}
+
+/** Return the activation map (stage -> feature list). */
+export function getActivation(registry) {
+  return registry.activation || {};
+}
+
+/** Return the list of protocol directives. */
+export function getDirectives(registry) {
+  return (registry.protocol || {}).core_directives || [];
+}
+
+/** Return the registry version string. */
+export function getVersion(registry) {
+  return String(registry.version || "unknown");
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "agent-method",
+  "version": "1.5.0",
+  "description": "CLI tools for the agent-method methodology — registry-driven routing, validation, and project setup for AI-agent-assisted development",
+  "keywords": [
+    "ai-agents",
+    "prompt-engineering",
+    "context-engineering",
+    "methodology",
+    "developer-tools",
+    "cli"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "author": "agent-method contributors",
+  "bin": {
+    "agent-method": "bin/agent-method.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "docs/internal/feature-registry.yaml"
+  ],
+  "main": "lib/registry.js",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.4.0",
+    "commander": "^12.0.0",
+    "inquirer": "^9.0.0",
+    "js-yaml": "^4.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agent-method/agent-method"
+  }
+}

package/templates/README.md

@@ -0,0 +1,293 @@
+# Template Kit
+
+Copyable project templates. Pick one, copy it into your project root, fill in PROJECT.md, and start working with your AI agent.
+
+## Starter template (minimum viable)
+
+For most projects. Seven files that give you cross-session memory, scoped context loading, persistent codebase understanding, lifecycle tracking, and structured execution.
+
+```
+starter/
+  CLAUDE.md           # Claude Code entry point (auto-loaded)
+  .cursorrules        # Cursor entry point (auto-loaded)
+  AGENT.md            # Generic entry point (manual loading)
+  PROJECT.md          # Your project vision -- fill this in first
+  PROJECT-PROFILE.md  # Project type, lifecycle stage, active extensions (agent-maintained)
+  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
+```
+
+**Setup**: Delete the two entry point files you don't use. Keep the one that matches your agent runtime.
+
+**What you get**: Persistent decisions, scoped file reading, phase-gated execution, atomic task tracking, configurable interaction level, persistent codebase context.
+
+**What you don't get**: Specialist context pairing, human-facing docs scaffold, execution history, full communication point structure.
+
+## Full template (complete methodology)
+
+For complex or multi-phase projects where context management and dual-audience separation matter.
+
+```
+full/
+  CLAUDE.md         # Claude Code entry point (auto-loaded)
+  .cursorrules      # Cursor entry point (auto-loaded)
+  AGENT.md          # Generic entry point (manual loading)
+  PROJECT.md          # Vision, audiences, structure
+  PROJECT-PROFILE.md  # Project type, lifecycle, extensions (agent-maintained)
+  STATE.md            # Decisions, blockers, position, open questions
+  REQUIREMENTS.md     # Scoped features with phase traceability
+  ROADMAP.md        # Phase breakdown with gate criteria
+  PLAN.md           # Current atomic task
+  SUMMARY.md        # Execution history (session audit trail)
+  .context/
+    BASE.md         # Core context -- always loaded with entry point
+  docs/
+    index.md        # Human-facing project dashboard (checkpoint records land here)
+  todos/
+    backlog.md      # Captured ideas for future work
+```
+
+**Setup**: Delete the two entry point files you don't use. Keep the one that matches your agent runtime.
+
+**What you get**: Everything in starter, plus specialist context pairing, dependency cascade, execution history, human dashboard scaffold, backlog capture, full communication point structure (direction, checkpoint, record).
+
+## Template content: guided, not empty
+
+Template files ship with **inline instructions** — structured prompts that show both the user and the agent what goes in each section. The agent can read these instructions and help populate the files.
+
+Example from a guided PROJECT.md:
+```markdown
+# {Your Project Name}
+
+<!-- INSTRUCTION: Replace with a 2-3 sentence description of your project -->
+{Describe what your project does and who it's for}
+
+## Problem
+<!-- INSTRUCTION: What problem does this solve? 2-3 bullet points. -->
+
+## Solution
+<!-- INSTRUCTION: How does the project solve the problem? -->
+```
+
+Example from a guided .context/BASE.md:
+```markdown
+# Base Context — Always Loaded
+
+## What this system is
+<!-- INSTRUCTION: 2-3 sentences describing your project's architecture -->
+
+## Codebase map
+<!-- INSTRUCTION: Table of directories, their purposes, and key patterns -->
+<!-- The agent will help populate this from a codebase scan -->
+| Path | Purpose | Key patterns |
+|------|---------|-------------|
+
+## Pairing protocol
+| Task type | Pair BASE.md with |
+|-----------|-------------------|
+<!-- INSTRUCTION: Add rows as you create specialist .context/ files -->
+```
+
+The inline instructions serve as:
+- **User guidance**: Human sees what to fill in
+- **Agent prompts**: Agent reads the instructions and can help populate
+- **Structure enforcement**: Files have the right sections from day one
+
+## Bootstrapping: new project vs existing codebase
+
+### Greenfield (starting from scratch)
+
+1. Copy template into your project root
+2. Delete the two entry point files you don't use
+3. Fill in PROJECT.md with your project vision
+4. Start a conversation — the agent helps populate .context/BASE.md as you build
+
+### Brownfield (existing codebase)
+
+1. Copy template into your existing project root
+2. Delete the two entry point files you don't use
+3. Fill in PROJECT.md with your project vision
+4. Ask the agent: "Scan the codebase and populate the context files"
+5. Agent activates the **Discovery workflow (WF-08)**:
+   - **Inventory**: Walks entire project structure, maps directories and files
+   - **Map**: Traces dependencies (packages, imports, services)
+   - **Extract**: Identifies patterns, conventions, and architectural decisions
+   - **Assess**: Evaluates technical debt, risks, and improvement opportunities
+   - **Bootstrap**: Writes .context/BASE.md, proposes specialists, updates scoping table
+6. Agent updates PROJECT-PROFILE.md lifecycle stage to "discovery"
+7. You approve specialist files; agent transitions lifecycle to "development" when ready
+
+### Integration profiles
+
+Both templates support three integration profiles that control how much methodology surface area gets installed. This is critical for brownfield projects and lighter models.
+
+| Profile | Target model | What's installed | Entry point budget |
+|---------|-------------|-----------------|-------------------|
+| **Lite** | Haiku, GPT-3.5 | STATE.md + .context/METHODOLOGY.md | 25 lines |
+| **Standard** | Sonnet, GPT-4 | STATE.md, PLAN.md, .context/BASE.md, .context/METHODOLOGY.md | 40 lines |
+| **Full** | Opus, o1 | All intelligence layer files | 60 lines |
+
+For lite and standard profiles, operational details (workflows, extended conventions, do-not rules) overflow to `.context/METHODOLOGY.md` — loaded on-demand via the scoping table, not every session. This keeps the entry point lean enough for lighter models to process reliably.
+
+When setup.sh detects an existing entry point file, it uses the **brownfield merge protocol**: methodology content is appended to the existing file rather than overwriting it.
+
+See `docs/architecture/integration-profiles.md` for the full specification.
+
+### Interaction level (in entry point)
+
+Both templates include an interaction level setting in the entry point:
+
+```markdown
+## Interaction level
+mode: checkpoint    # autonomous | checkpoint | collaborative | supervised
+```
+
+| Level | Agent behavior |
+|-------|---------------|
+| **autonomous** | Executes full plan, reports at completion |
+| **checkpoint** | Proposes plan, executes after approval, reports at completion |
+| **collaborative** | Back-and-forth at each step |
+| **supervised** | Explains intent before every file change |
+
+## Entry points (all three included)
+
+Both templates ship with all three entry point variants. Pick the one that matches your runtime and delete the others:
+
+| File | Runtime | Auto-loaded? |
+|------|---------|:------------:|
+| `CLAUDE.md` | Claude Code | Yes |
+| `.cursorrules` | Cursor | Yes |
+| `AGENT.md` | Any agent (manual loading) | No |
+
+All three contain identical scoping rules, cascade structure, and conventions — only the filename and auto-loading behavior differ.
+
+Standalone entry point files are also available in `entry-points/` for reference or individual use.
+
+## Project-type extensions
+
+The starter and full templates ship with **universal** scoping rules, cascade rules, and workflows that work for any project. For project-type-specific capabilities, apply an extension.
+
+```
+extensions/
+  MANIFEST.md             # Extension composition rules, compatibility matrix
+  code-project.md         # Code-specific: scoping, cascade, WF-02, specialists
+  data-exploration.md     # Data-specific: exploration commands, WF-05, specialists
+  analytical-system.md    # Analytical-specific: chain work, evaluation, WF-06, specialists
+```
+
+### How to apply an extension
+
+1. Open the extension file (e.g., `extensions/code-project.md`)
+2. Copy each section's rows into the corresponding section of your entry point
+3. Create the recommended specialist .context/ files as your project grows
+4. Delete the extension file — it's a reference, not a runtime artifact
+
+### Extensions are additive
+
+Extensions add rows to existing tables — they never override universal content. You can apply multiple extensions for projects that span types:
+
+```
+Base entry point (universal)
+  + code-project.md (code scoping, cascade, WF-02)
+  + data-exploration.md (exploration scoping, cascade, WF-05)
+  + analytical-system.md (chain/evaluation scoping, cascade, WF-06)
+  = Mixed project entry point (any combination)
+```
+
+### Registry-driven derivation
+
+Extensions are derived from the feature registry (`docs/internal/feature-registry.yaml`). Each extension's scoping rules trace to registry `query_patterns`, cascade rules trace to registry `dependencies`, and workflows trace to registry `workflows`. See `docs/internal/entry-point-derivation.md` for the derivation specification.
+
+## What the entry point embeds
+
+The entry point distills the methodology's behavioral protocol into a dense, table-driven file:
+
+- **Scoping rules** — Query-type-to-file mapping. The agent reads the table, loads the right files, and constrains writes. Derived from the 4 universal query types plus project-specific types.
+- **Cascade table** — "When X changes, also update Y." Prevents file drift by making dependencies explicit. The agent checks this after every change.
+- **Workflow selection** — Eight guided workflows: general task (WF-01), code change (WF-02), context refresh (WF-03), bootstrap (WF-04), data exploration (WF-05), analytical system (WF-06), specification project (WF-07), discovery (WF-08). The agent selects based on query type, project type, and lifecycle stage.
+- **Conventions** — Six behavioral rules derived from the agent protocol directives: record decisions immediately, scope to avoid drowning, cascade is not optional, build understanding not just code, surface uncertainty, human controls direction.
+- **Interaction level** — Configurable checkpoint density from autonomous to supervised.
+
+An agent reading the entry point can follow the full behavioral protocol without accessing any other methodology documentation.
+
+## Context maintenance
+
+Context files are living documents. As your project evolves, the agent keeps them current:
+
+- **Code changes** → Agent updates .context/BASE.md codebase map via cascade
+- **New domain areas** → Agent suggests creating specialist .context/ files
+- **Architecture decisions** → Agent records them in relevant .context/ files
+- **Context drift** → Ask the agent "refresh the project context" to resync
+
+See `docs/architecture/context-pairing.md` for the full context maintenance lifecycle.
+
+## How to use
+
+### Recommended: npx
+
+```bash
+npx agent-method init code ~/my-project
+```
+
+Replace `code` with: `context`, `data`, `mix`, or `general`.
+
+### Manual
+
+1. Copy `starter/` or `full/` into your project root
+2. Delete the two entry point files you don't use
+3. Fill in `PROJECT.md` with your project vision
+4. Start a conversation with your agent — it reads the entry point and knows what to do
+5. For existing codebases: ask the agent to scan and populate context files
+
+See `docs/guides/quick-start.md` for a detailed walkthrough.
+
+## CLI Tools (optional)
+
+The methodology works without any tooling. For teams that want additional validation and automation:
+
+```bash
+npx agent-method                        # zero-install (Node.js 18+)
+npm install -g agent-method             # permanent install
+pip install agent-method-tools          # Python alternative
+```
+
+### Developer commands
+
+| Command | Use case |
+|---------|----------|
+| `agent-method check` | Validate entry point (auto-finds CLAUDE.md/.cursorrules/AGENT.md) |
+| `agent-method scan` | Detect project type from directory contents |
+| `agent-method route "<query>"` | Test how a query routes through the pipeline |
+| `agent-method refine` | Extract refinement report (auto-finds SESSION-LOG.md) |
+| `agent-method status` | Check if methodology version is current |
+| `agent-method upgrade` | Brownfield-safe update (adds missing files, updates version) |
+| `agent-method init <type>` | Describe entry point contents for a project type |
+
+### Project types
+
+Use friendly names everywhere — all commands accept aliases:
+
+```bash
+agent-method init code      # software project
+agent-method init context   # analytical/prompt project (e.g. PromptStudy)
+agent-method init data      # data index/querying project (e.g. SysMLv2)
+agent-method init mix       # multi-type project
+```
+
+### Advanced: pipeline subcommands
+
+For debugging routing logic: `agent-method pipeline classify|select|resolve|cascade|test`.
+
+### Dependencies
+
+- Python 3.9+
+- PyYAML >= 6.0
+- Click >= 8.0
+
+### Future enhancements
+
+- MCP server: `pip install agent-method-tools[mcp]` — exposes pipeline as agent-callable tools
+- Registry watcher: `pip install agent-method-tools[watch]` — proactive validation on file changes

package/templates/entry-points/.cursorrules

@@ -0,0 +1,109 @@
+# {Project Name} — Agent Entry Point
+
+<!-- INSTRUCTION: Replace {Project Name} and write a 1-2 sentence project description below -->
+{Describe what your project does, its architecture, and key technologies.}
+
+## On every query
+
+1. This file is auto-loaded — read it first
+2. Read `STATE.md` for current position, decisions, blockers
+3. Scope based on query type (see table below)
+
+## Scoping rules
+
+| Query type | Read before acting | Update after acting |
+|------------|-------------------|-------------------|
+| **Planning / roadmap** | REQUIREMENTS.md, ROADMAP.md | STATE.md, PLAN.md |
+| **Context refresh** | .context/ (all), project structure | .context/, this file (if scoping rules affected) |
+| **{your-domain-type}** | .context/BASE.md + .context/{SPECIALIST}.md | {affected working files} |
+| **Methodology guidance** | .context/METHODOLOGY.md | -- |
+| **Phase completion** | SUMMARY.md | SUMMARY.md, STATE.md, ROADMAP.md |
+| **Backlog / ideas** | todos/backlog.md | todos/backlog.md |
+
+<!-- INSTRUCTION: Replace the {your-domain-type} row with project-specific query types.
+     Each should pair .context/BASE.md with one specialist. Add as many rows as needed. -->
+
+## Dependency cascade
+
+When a file changes, check this table and update dependent files in the same response.
+
+| When this changes | Also update |
+|------------------|-------------|
+| Phase completion | SUMMARY.md (add entry), STATE.md (update position), ROADMAP.md (mark done) |
+| Requirements change | REQUIREMENTS.md, ROADMAP.md, PLAN.md (if current task affected) |
+| New decision made | STATE.md (decisions table — record immediately, never defer) |
+| Open question resolved | STATE.md (mark resolved with resolution text, don't delete) |
+| Project structure | .context/BASE.md (codebase map), this file (if new query types needed) |
+| Intelligence layer file exceeds 300 lines | Restructure into index + components subdirectory (keep active content, archive completed sections) |
+| New domain area | .context/BASE.md, consider new .context/ specialist, this file (if new scoping row) |
+| Session close | SESSION-LOG.md (append micro-entry — workflow, features, cascades, friction, findings) |
+
+<!-- INSTRUCTION: Add project-specific cascade rules below the universal ones above. -->
+
+## Workflow
+
+Select based on query type:
+- **General task** — Review, Plan, Implement, Document, Update
+- **Code change** — Review, Plan, Implement, Context-sync, Update
+- **Context refresh** — Scan, Compare, Update-context, Cascade, Record
+- **First session** — Detect, Initialize, Map, Pair, Ready
+
+## Interaction level
+
+mode: checkpoint
+<!-- autonomous | checkpoint | collaborative | supervised -->
+<!-- checkpoint: propose plan, wait for approval, report at completion (default) -->
+
+## Model tier
+
+tier: standard
+<!-- lite | standard | full -->
+<!-- lite: minimal rules, STATE.md only, 2 cascade rules — for Haiku or simple projects -->
+<!-- standard: core rules + context pairing, overflow to .context/METHODOLOGY.md — for Sonnet (default) -->
+<!-- full: all rules in entry point, all intelligence layer files — for Opus or complex projects -->
+
+## Method version
+
+method_version: 1.5
+<!-- Tracks which methodology version generated this entry point -->
+<!-- Use `agent-method status` to compare against latest -->
+
+## CLI tools (optional)
+
+Available via `npx agent-method` (zero-install) or `pip install agent-method-tools`:
+
+| When you want to... | Run |
+|---------------------|-----|
+| Validate this entry point | `agent-method check` |
+| See what type of project this is | `agent-method scan` |
+| Test how a query routes | `agent-method route "your question"` |
+| Extract a refinement report | `agent-method refine` |
+| Check methodology version | `agent-method status` |
+| Update methodology files | `agent-method upgrade` |
+| See what an entry point should contain | `agent-method init code` / `context` / `data` / `mix` |
+
+<!-- INSTRUCTION: The agent can suggest these commands when the user asks about validation,
+     project setup, or methodology updates. All commands auto-detect project type and find
+     entry points automatically. Add --json for machine-readable output. -->
+
+## Conventions
+
+- Record decisions in STATE.md in the SAME response as the work — never defer
+- Load .context/BASE.md + one specialist per query — never all context files
+- After every file change, check the cascade table — deferred cascades don't happen
+- Every code change is also a context change — update the codebase map
+- Surface uncertainty as open questions in STATE.md — never guess silently
+- Keep intelligence layer files under 300 lines — split into index + components subdirectory when exceeded
+- Propose plans and wait for approval — the human controls direction
+- At session close, append a micro-entry to SESSION-LOG.md — never skip, never read previous entries during normal work
+
+## Do not
+
+- Modify project source code, tests, or pre-existing documentation through methodology operations — only create/modify methodology files (STATE.md, .context/, PLAN.md, etc.)
+- Delete existing project files during brownfield integration — methodology is additive only
+- Load files not in the scoping table's read-set for the current query type
+- Defer STATE.md decision recording to end of session
+- Skip cascade checks after file changes
+- Load multiple specialist .context/ files for a single query
+
+<!-- INSTRUCTION: Add project-specific "do not" rules as you discover common mistakes -->

package/templates/entry-points/AGENT.md

@@ -0,0 +1,109 @@
+# {Project Name} — Agent Entry Point
+
+<!-- INSTRUCTION: Replace {Project Name} and write a 1-2 sentence project description below -->
+{Describe what your project does, its architecture, and key technologies.}
+
+## On every query
+
+1. This file is auto-loaded — read it first
+2. Read `STATE.md` for current position, decisions, blockers
+3. Scope based on query type (see table below)
+
+## Scoping rules
+
+| Query type | Read before acting | Update after acting |
+|------------|-------------------|-------------------|
+| **Planning / roadmap** | REQUIREMENTS.md, ROADMAP.md | STATE.md, PLAN.md |
+| **Context refresh** | .context/ (all), project structure | .context/, this file (if scoping rules affected) |
+| **{your-domain-type}** | .context/BASE.md + .context/{SPECIALIST}.md | {affected working files} |
+| **Methodology guidance** | .context/METHODOLOGY.md | -- |
+| **Phase completion** | SUMMARY.md | SUMMARY.md, STATE.md, ROADMAP.md |
+| **Backlog / ideas** | todos/backlog.md | todos/backlog.md |
+
+<!-- INSTRUCTION: Replace the {your-domain-type} row with project-specific query types.
+     Each should pair .context/BASE.md with one specialist. Add as many rows as needed. -->
+
+## Dependency cascade
+
+When a file changes, check this table and update dependent files in the same response.
+
+| When this changes | Also update |
+|------------------|-------------|
+| Phase completion | SUMMARY.md (add entry), STATE.md (update position), ROADMAP.md (mark done) |
+| Requirements change | REQUIREMENTS.md, ROADMAP.md, PLAN.md (if current task affected) |
+| New decision made | STATE.md (decisions table — record immediately, never defer) |
+| Open question resolved | STATE.md (mark resolved with resolution text, don't delete) |
+| Project structure | .context/BASE.md (codebase map), this file (if new query types needed) |
+| Intelligence layer file exceeds 300 lines | Restructure into index + components subdirectory (keep active content, archive completed sections) |
+| New domain area | .context/BASE.md, consider new .context/ specialist, this file (if new scoping row) |
+| Session close | SESSION-LOG.md (append micro-entry — workflow, features, cascades, friction, findings) |
+
+<!-- INSTRUCTION: Add project-specific cascade rules below the universal ones above. -->
+
+## Workflow
+
+Select based on query type:
+- **General task** — Review, Plan, Implement, Document, Update
+- **Code change** — Review, Plan, Implement, Context-sync, Update
+- **Context refresh** — Scan, Compare, Update-context, Cascade, Record
+- **First session** — Detect, Initialize, Map, Pair, Ready
+
+## Interaction level
+
+mode: checkpoint
+<!-- autonomous | checkpoint | collaborative | supervised -->
+<!-- checkpoint: propose plan, wait for approval, report at completion (default) -->
+
+## Model tier
+
+tier: standard
+<!-- lite | standard | full -->
+<!-- lite: minimal rules, STATE.md only, 2 cascade rules — for Haiku or simple projects -->
+<!-- standard: core rules + context pairing, overflow to .context/METHODOLOGY.md — for Sonnet (default) -->
+<!-- full: all rules in entry point, all intelligence layer files — for Opus or complex projects -->
+
+## Method version
+
+method_version: 1.5
+<!-- Tracks which methodology version generated this entry point -->
+<!-- Use `agent-method status` to compare against latest -->
+
+## CLI tools (optional)
+
+Available via `npx agent-method` (zero-install) or `pip install agent-method-tools`:
+
+| When you want to... | Run |
+|---------------------|-----|
+| Validate this entry point | `agent-method check` |
+| See what type of project this is | `agent-method scan` |
+| Test how a query routes | `agent-method route "your question"` |
+| Extract a refinement report | `agent-method refine` |
+| Check methodology version | `agent-method status` |
+| Update methodology files | `agent-method upgrade` |
+| See what an entry point should contain | `agent-method init code` / `context` / `data` / `mix` |
+
+<!-- INSTRUCTION: The agent can suggest these commands when the user asks about validation,
+     project setup, or methodology updates. All commands auto-detect project type and find
+     entry points automatically. Add --json for machine-readable output. -->
+
+## Conventions
+
+- Record decisions in STATE.md in the SAME response as the work — never defer
+- Load .context/BASE.md + one specialist per query — never all context files
+- After every file change, check the cascade table — deferred cascades don't happen
+- Every code change is also a context change — update the codebase map
+- Surface uncertainty as open questions in STATE.md — never guess silently
+- Keep intelligence layer files under 300 lines — split into index + components subdirectory when exceeded
+- Propose plans and wait for approval — the human controls direction
+- At session close, append a micro-entry to SESSION-LOG.md — never skip, never read previous entries during normal work
+
+## Do not
+
+- Modify project source code, tests, or pre-existing documentation through methodology operations — only create/modify methodology files (STATE.md, .context/, PLAN.md, etc.)
+- Delete existing project files during brownfield integration — methodology is additive only
+- Load files not in the scoping table's read-set for the current query type
+- Defer STATE.md decision recording to end of session
+- Skip cascade checks after file changes
+- Load multiple specialist .context/ files for a single query
+
+<!-- INSTRUCTION: Add project-specific "do not" rules as you discover common mistakes -->