agent-method 1.5.3 → 1.5.6

package/docs/internal/doc-tokens.yaml

@@ -0,0 +1,452 @@
+# Documentation Token Registry
+# Single source of truth for values AND names that appear across documentation.
+# When a value or name changes, update this file FIRST, then propagate to all docs.
+#
+# Two sections:
+#   tokens:  — values that change (CLI commands, version numbers, counts, thresholds)
+#   names:   — terminology that must stay consistent (concepts, workflows, stages, file roles)
+#
+# Usage: Agent reads this file before writing or updating any docs/ file.
+# Cascade rule: when this file changes, check all docs/ for stale token values or name inconsistencies.
+
+# ============================================================
+# SECTION 1: VALUES (things that change)
+# ============================================================
+
+tokens:
+
+  # --- CLI and distribution ---
+  cli_command: wwa                              # Primary command after global install
+  npm_package: agent-method                     # npm package name (npx agent-method)
+  pip_package: wwa-tools                        # pip package name
+  npx_zero_install: "npx agent-method"          # Zero-install invocation
+  npm_global_install: "npm install -g agent-method"
+  pip_install: "pip install wwa-tools"
+  mcp_server_start: "npx agent-method serve"    # MCP server command
+  watcher_start: "npx agent-method watch"       # Watcher command
+
+  # --- Project identity ---
+  project_name: wwa
+  repo_url: "https://github.com/anthropics/wwa.git"
+  npm_version: "1.5.1"
+
+  # --- Registry and capability counts ---
+  registry_version: "v1.5"
+  feature_count: 32
+  domain_count: 8
+  directive_count: 10
+  workflow_count: 8
+  query_pattern_count: 29
+
+  # --- Integration profiles (model names) ---
+  lite_models: "Haiku, GPT-3.5, Gemini Flash"
+  standard_models: "Sonnet, GPT-4, Gemini Pro, Codex"
+  full_models: "Opus, o1, Gemini Ultra"
+
+  # --- File thresholds ---
+  max_file_lines: 300                           # Intelligence layer file split threshold
+  base_md_max_lines: 100                        # .context/BASE.md target
+  specialist_max_lines: 150                     # Specialist context file target
+  entry_point_target_lines: 60                  # Agent-parsed entry point content target
+
+  # --- Template tiers ---
+  starter_file_count: 18                        # 3 entry points + PROJECT.md + STATE.md + ROADMAP.md + PLAN.md + PROJECT-PROFILE.md + SESSION-LOG.md + SUMMARY.md + .context/{BASE,METHODOLOGY,DOCS-MAP}.md + Management/{DIGEST,STATUS}.md + Reviews/INDEX.md + agentWorkflows/INDEX.md + intro/README.md
+  full_file_count: 32                           # Starter + REQUIREMENTS.md + .context/{REGISTRY,COMPOSITION}.md + todos/backlog.md + Reviews/6 drill-downs + agentWorkflows/3 analysis files
+
+  # --- Developer commands (primary format: wwa <cmd>) ---
+  cmd_init: "wwa init"
+  cmd_check: "wwa check"
+  cmd_scan: "wwa scan"
+  cmd_route: "wwa route"
+  cmd_plan: "wwa plan"
+  cmd_implement: "wwa implement"
+  cmd_review: "wwa review"
+  cmd_digest: "wwa digest"
+  cmd_close: "wwa close"
+  cmd_refine: "wwa refine"
+  cmd_status: "wwa status"
+  cmd_upgrade: "wwa upgrade"
+  cmd_casestudy: "wwa casestudy"
+  cmd_docs: "wwa docs"
+  cmd_serve: "wwa serve"
+  cmd_watch: "wwa watch"
+  cmd_completion: "wwa completion"
+
+  # --- Developer command count ---
+  developer_cmd_count: 14                         # check, scan, route, refine, status, upgrade, init, plan, implement, review, digest, close, casestudy, docs
+  pipeline_cmd_count: 5                           # classify, select, resolve, cascade, test
+  server_cmd_count: 2                             # serve, watch
+  completion_cmd_count: 1                         # completion (bash/zsh/fish/powershell)
+  total_cmd_count: 22                             # all commands (14 dev + 5 pipeline + 2 server + 1 completion)
+
+  # --- Node.js requirements ---
+  node_min_version: "18"
+  python_min_version: "3.9"
+
+# ============================================================
+# SECTION 2: NAMES (terminology that must stay consistent)
+# ============================================================
+# Each entry has:
+#   canonical:  the standard form to use in documentation
+#   aliases:    variant forms (abbreviations, CLI names, display names)
+#   context:    where/how this name is typically used
+
+names:
+
+  # --- 1. Workflow stages (the 6 sequential stages) ---
+  workflow_stages:
+    - canonical: Initialize
+      aliases: [init, cold start, session start]
+      context: "First stage. Agent loads entry point + STATE.md."
+    - canonical: Scope
+      aliases: [scoping, query classification]
+      context: "Agent classifies query against scoping table, loads relevant files."
+    - canonical: Plan
+      aliases: [planning, task planning]
+      context: "Agent proposes structured plan. Primary checkpoint."
+    - canonical: Execute
+      aliases: [execution, implement, implementation]
+      context: "Agent implements approved plan. Records decisions in STATE.md."
+    - canonical: Verify
+      aliases: [verification, validation]
+      context: "Agent checks work against plan criteria."
+    - canonical: Close
+      aliases: [session close, wrap-up]
+      context: "Agent writes SUMMARY.md entry, updates STATE.md position."
+
+  # --- 2. Interaction levels (4 density settings) ---
+  interaction_levels:
+    - canonical: autonomous
+      context: "Routine, low-risk work. Agent handles independently."
+    - canonical: checkpoint
+      context: "Default. Approve plan, trust execution, report at completion."
+    - canonical: collaborative
+      context: "Complex tasks. Iterate on each step."
+    - canonical: supervised
+      context: "Learning methodology, high-risk, or debugging."
+
+  # --- 3. Integration profiles (3 tiers) ---
+  integration_profiles:
+    - canonical: lite
+      aliases: [Lite]
+      context: "Minimal rules, STATE.md only, 2 cascade rules. For Haiku, GPT-3.5, Gemini Flash."
+    - canonical: standard
+      aliases: [Standard]
+      context: "Default. Core rules + context pairing, overflow to METHODOLOGY.md. For Sonnet, GPT-4, Gemini Pro, Codex."
+    - canonical: full
+      aliases: [Full]
+      context: "All rules inline, all intelligence layer files. For Opus, o1, Gemini Ultra."
+
+  # --- 4. Template tiers (2 tiers) ---
+  template_tiers:
+    - canonical: starter
+      aliases: [Starter]
+      context: "7 files. Entry point, PROJECT.md, STATE.md, ROADMAP.md, PLAN.md, .context/BASE.md, PROJECT-PROFILE.md."
+    - canonical: full
+      aliases: [Full]
+      context: "11+ files. Adds REQUIREMENTS.md, SUMMARY.md, .context/REGISTRY.md, .context/COMPOSITION.md, todos/backlog.md."
+
+  # --- 5. Project types (5 types + CLI aliases) ---
+  project_types:
+    - canonical: general
+      cli_alias: general
+      context: "Universal rules only. No extensions."
+    - canonical: code
+      cli_alias: code
+      context: "Software development. Code change, bug fix, dependency, database, API, deployment."
+    - canonical: data
+      cli_alias: data
+      context: "Dataset analysis, document exploration. Data ingest, schema, exploration."
+    - canonical: analytical
+      cli_alias: context
+      context: "Research, evaluation, prompt/context work. Chain work, evaluation, composition."
+    - canonical: mixed
+      cli_alias: mix
+      context: "Multiple extensions combined. Code + data, code + analytical."
+
+  # --- 6. Guided workflows (8 workflows) ---
+  guided_workflows:
+    - id: WF-01
+      canonical: standard-task
+      display: "Standard task"
+      context: "Review → Plan → Implement → Document → Update. Default for general queries."
+    - id: WF-02
+      canonical: code-change
+      display: "Code change"
+      context: "Review → Plan → Implement → Context-sync → Update. Code projects."
+    - id: WF-03
+      canonical: context-refresh
+      display: "Context refresh"
+      context: "Scan → Compare → Update context → Cascade → Record."
+    - id: WF-04
+      canonical: agent-guided-onboarding
+      display: "Agent-guided onboarding"
+      aliases: [bootstrap, first session]
+      context: "Ask → Populate → Confirm. Greenfield (4 stages) and brownfield (5 stages)."
+    - id: WF-05
+      canonical: data-exploration
+      display: "Data exploration"
+      context: "Ingest → Map → Reference → Explore → Refine. Data projects."
+    - id: WF-06
+      canonical: analytical-system
+      display: "Analytical system"
+      context: "Discover → Map chains → Build context → Compose → Evaluate → Refine."
+    - id: WF-07
+      canonical: specification-project
+      display: "Specification project"
+      context: "For spec writing projects."
+    - id: WF-08
+      canonical: discovery
+      display: "Discovery"
+      aliases: [brownfield discovery]
+      context: "Inventory → Map → Extract → Assess → Bootstrap. Brownfield projects."
+
+  # --- 7. Feature domains (8 domains) ---
+  feature_domains:
+    - id: CTX
+      canonical: Context management
+      feature_range: "CTX-01 through CTX-06"
+      context: "Bootstrap, maintain, evolve .context/ files."
+    - id: QRY
+      canonical: Query routing
+      feature_range: "QRY-01 through QRY-03"
+      context: "Session init, query classification, cascade propagation."
+    - id: STT
+      canonical: State management
+      feature_range: "STT-01 through STT-03"
+      context: "Decision capture, uncertainty tracking, position tracking."
+    - id: TSK
+      canonical: Task execution
+      feature_range: "TSK-01 through TSK-04"
+      context: "Planning, verification, session close, audit trail."
+    - id: HAI
+      canonical: Human-agent interaction
+      feature_range: "HAI-01 through HAI-05"
+      context: "Checkpoints, interaction levels, audience separation, docs triggers, model capability."
+    - id: TPL
+      canonical: Template and bootstrap
+      feature_range: "TPL-01 through TPL-03"
+      context: "Project init, runtime detection, structure selection."
+    - id: EXP
+      canonical: Data exploration
+      feature_range: "EXP-01 through EXP-04"
+      context: "Data ingest, reference building, exploration commands, abstraction management."
+    - id: SCAN
+      canonical: Project discovery
+      aliases: [Brownfield discovery]
+      feature_range: "SCAN-01 through SCAN-04"
+      context: "Codebase inventory, dependency mapping, pattern extraction, debt assessment."
+
+  # --- 8. Protocol directives (10 directives) ---
+  protocol_directives:
+    - id: P-01
+      canonical: Build understanding
+      short: "Every change is also a context change"
+    - id: P-02
+      canonical: Maintain for future self
+      short: "Record decisions in STATE.md in the SAME response"
+    - id: P-03
+      canonical: Cascade is not optional
+      short: "After every file change, check the cascade table"
+    - id: P-04
+      canonical: Scope to avoid drowning
+      short: "Load BASE.md + one specialist per query"
+    - id: P-05
+      canonical: Surface uncertainty
+      short: "Surface uncertainty as open questions in STATE.md"
+    - id: P-06
+      canonical: Human controls direction
+      short: "Propose plans and wait for approval"
+    - id: P-07
+      canonical: Keep files loadable
+      short: "Intelligence layer files under 300 lines"
+    - id: P-08
+      canonical: Methodology is additive only
+      short: "Never modify source code, never delete existing files"
+    - id: P-09
+      canonical: Surface capability limitations
+      short: "Agent self-monitors and alerts user to degradation"
+    - id: P-10
+      canonical: Document proportionally
+      short: "Match documentation effort to task significance"
+
+  # --- 9. Methodology concepts (~10 key terms) ---
+  methodology_concepts:
+    - canonical: context pairing
+      aliases: [BASE + specialist model]
+      context: "Loading BASE.md + one specialist file per query type."
+    - canonical: dependency cascade
+      aliases: [cascade, cascade table, cascade rules]
+      context: "When X changes, also update Y. Prevents file drift."
+    - canonical: scoping rules
+      aliases: [scoping table, query routing]
+      context: "Query type → file set mapping in entry point."
+    - canonical: intelligence layer
+      aliases: [project intelligence layer]
+      context: "PROJECT/STATE/REQUIREMENTS/ROADMAP/PLAN/SUMMARY files."
+    - canonical: interaction level
+      context: "Configurable checkpoint density: autonomous/checkpoint/collaborative/supervised."
+    - canonical: entry point
+      aliases: [agent entry point]
+      context: "Auto-loaded file (CLAUDE.md/.cursorrules/AGENT.md) with scoping + cascade."
+    - canonical: specialist context
+      aliases: [specialist file, specialist]
+      context: "Domain-specific .context/ file loaded per scoping rule."
+    - canonical: phase gate
+      aliases: [gate, gate criteria]
+      context: "Testable criteria that define done per phase."
+    - canonical: codebase map
+      context: "Table of paths, purposes, patterns in BASE.md for code projects."
+    - canonical: context refresh
+      context: "Agent rescans project and updates .context/ files."
+    - canonical: scale management
+      aliases: [file splitting, index + components]
+      context: "When files exceed 300 lines, split into index + components subdirectory."
+
+  # --- 10. Intelligence layer files ---
+  intelligence_layer_files:
+    - file: PROJECT.md
+      role: "Project vision, audiences, principles"
+      audience: human
+    - file: PROJECT-PROFILE.md
+      role: "Project type, lifecycle stage, active extensions"
+      audience: agent
+    - file: STATE.md
+      role: "Current position, decisions, blockers, open questions"
+      audience: both
+    - file: REQUIREMENTS.md
+      role: "Formal requirements with traceability"
+      tier: full
+    - file: ROADMAP.md
+      role: "Phase breakdown with deliverables and gate criteria"
+      audience: both
+    - file: PLAN.md
+      role: "Current atomic task with verification criteria"
+      audience: agent
+    - file: SUMMARY.md
+      role: "Session audit trail (chronological record of work done)"
+      audience: both
+    - file: SESSION-LOG.md
+      role: "Session metrics and refinement tracking"
+      audience: agent
+    - file: ".context/BASE.md"
+      role: "System model, always loaded with entry point"
+      audience: agent
+    - file: ".context/REGISTRY.md"
+      role: "Navigation registry for split file trees"
+      tier: full
+    - file: ".context/METHODOLOGY.md"
+      role: "Workflow and convention overflow for lite/standard profiles"
+      audience: agent
+    - file: "Management/DIGEST.md"
+      role: "High-effort task digest for managers and leads"
+      audience: human
+    - file: "Management/STATUS.md"
+      role: "Project health snapshot — phase, blockers, decisions, risk"
+      audience: human
+    - file: "Reviews/INDEX.md"
+      role: "Synthesized project intelligence dashboard"
+      audience: both
+    - file: "agentWorkflows/INDEX.md"
+      role: "Agent workflow performance overview"
+      audience: both
+
+  # --- 11. Communication point types ---
+  communication_points:
+    - canonical: direction
+      context: "Human → agent. Drives work. Queries, approvals, redirects."
+    - canonical: checkpoint
+      context: "Agent → human. Surfaces state. Plans, status, questions."
+    - canonical: record
+      context: "Persistent artifacts. STATE.md, SUMMARY.md, .context/ files."
+
+  # --- 12. Interaction patterns (7 patterns) ---
+  interaction_patterns:
+    - canonical: Cold start
+      aliases: [session start, initialization]
+      context: "Two-file load: entry point + STATE.md."
+    - canonical: Scoped reading
+      aliases: [query scoping]
+      context: "Query classification → file set loading."
+    - canonical: Decision recording
+      context: "Immediate capture in STATE.md decisions table."
+    - canonical: Cascade updating
+      context: "Post-change propagation via cascade table."
+    - canonical: Uncertainty flagging
+      context: "Open questions surfaced in STATE.md."
+    - canonical: Audit trail
+      context: "SUMMARY.md session entries at close."
+    - canonical: Session metrics
+      context: "Effort, ambiguity, context, tokens, time, user response tracking."
+
+  # --- 13. Entry point runtimes ---
+  entry_point_runtimes:
+    - file: CLAUDE.md
+      runtime: Claude Code
+      auto_loaded: true
+    - file: ".cursorrules"
+      runtime: Cursor
+      aliases: [Cursor Composer]
+      auto_loaded: true
+    - file: AGENT.md
+      runtime: Other
+      aliases: [Gemini, Codex, Cline, Aider]
+      auto_loaded: false
+      note: "Paste or reference manually"
+
+# ============================================================
+# SECTION 3: PROPAGATION TRACKING
+# ============================================================
+# Files known to use tokens/names from this registry.
+# When tokens change, check these files for stale values.
+# When names change, check docs for inconsistent terminology.
+
+propagation_targets:
+  docs:
+    - docs/guides/quick-start.md
+    - docs/guides/for-developers.md
+    - docs/guides/for-developers/cli-tools.md
+    - docs/guides/for-managers.md
+    - docs/guides/mcp-integration.md
+    - docs/index.md
+    - docs/architecture/file-roles.md
+    - docs/architecture/scoping-rules.md
+    - docs/architecture/dependency-cascade.md
+    - docs/architecture/context-pairing.md
+    - docs/architecture/integration-profiles.md
+    - docs/architecture/project-lifecycle.md
+    - docs/architecture/feature-tree.md
+    - docs/architecture/workflow-extensions.md
+    - docs/workflow/stages.md
+    - docs/workflow/interaction-patterns.md
+    - docs/workflow/communication-points.md
+    - docs/workflow/human-agent-contract.md
+    - docs/workflow/session-protocol.md
+    - docs/workflow/task-structure.md
+  templates:
+    - templates/README.md
+    - templates/starter/CLAUDE.md
+    - templates/starter/AGENT.md
+    - templates/starter/.cursorrules
+    - templates/full/CLAUDE.md
+    - templates/full/AGENT.md
+    - templates/full/.cursorrules
+    - templates/entry-points/CLAUDE.md
+    - templates/entry-points/AGENT.md
+    - templates/entry-points/.cursorrules
+    - templates/extensions/code-project.md
+    - templates/extensions/data-exploration.md
+    - templates/extensions/analytical-system.md
+    - templates/extensions/MANIFEST.md
+  project:
+    - README.md
+    - PROJECT.md
+    - CHANGELOG.md
+    - REQUIREMENTS.md
+  case_studies:
+    - case-studies/framework.md
+  internal:
+    - docs/internal/features.md
+    - docs/internal/feature-registry.yaml
+    - docs/internal/doc-update-policy.md
+    - docs/internal/docs-navigation-agent.md

package/docs/internal/feature-registry.yaml

@@ -1176,6 +1176,18 @@ protocol:
         model or a lighter integration profile. Two rules followed
         consistently beat ten rules followed inconsistently.
 
+    - id: P-10
+      name: Document proportionally
+      project_types: [universal]
+      directive: >
+        Match documentation effort to task significance. Low-effort tasks
+        (status checks, lookups, clarifications) need no STATE.md or
+        SESSION-LOG updates beyond the cascade contract. Medium-effort tasks
+        get targeted recording (decisions yes, session log optional).
+        High-effort tasks get full recording including session metrics and
+        refinement tracking. The agent self-assesses materiality and documents
+        accordingly. Never record routine queries in STATE.md or SESSION-LOG.md.
+
   workflow_selection: >
     When a query arrives, the agent selects the appropriate guided workflow:
     - First session / template just copied → WF-04 (bootstrap)
@@ -1517,7 +1529,7 @@ versions:
   v1.5:
     features: 32
     workflows: 8
-    protocol_directives: 9
+    protocol_directives: 10
     query_patterns: 29
     notes: >
       Adds HAI-05 modelCapabilityCheck (degradation detection + user surfacing).