agent-method 1.5.12

package/docs/internal/cli-commands.yaml

@@ -0,0 +1,259 @@
+#
+# CLI Command Metadata — agent-readable reference for wwa CLI.
+#
+# Purpose:
+#   - Single source of truth for command semantics that agents can read
+#   - Avoids scraping human docs to discover which commands are safe to run
+#   - Describes routable workflow commands and append-only `wwa add` variants
+#
+# Conventions:
+#   - name:        Logical command identifier (no `wwa` prefix)
+#   - cli:         Full CLI invocation pattern (human + agent)
+#   - category:    setup | workflow | routable | add | analysis | pipeline | server | completion
+#   - tier:        developer | pipeline | server | completion
+#   - safe_for_agent:
+#       - true  → safe to auto-run from an agent (read-only or append-only to methodology files)
+#       - false → require explicit human approval before running
+#   - query_type:  For routable workflow commands, the fixed query_type they simulate
+#   - reads:       High-level file paths or categories the command reads
+#   - writes:      High-level file paths or categories the command writes (may be empty)
+#   - when_to_use: Short description of usage context
+#   - examples:    Short example invocations
+#
+
+version: "v1.0"
+
+cli_commands:
+  # ---------------------------------------------------------------------------
+  # Routable workflow commands (Phase 7p)
+  # ---------------------------------------------------------------------------
+
+  - name: project-discovery
+    cli: "wwa project-discovery"
+    category: routable
+    tier: developer
+    safe_for_agent: true
+    query_type: project_discovery
+    description: "Run discovery workflow routing for brownfield scans and project-wide discovery."
+    when_to_use: "When the agent needs to understand an existing project before making changes."
+    reads:
+      - "Entry point (CLAUDE.md/.cursorrules/AGENT.md)"
+      - "STATE.md"
+      - "Project directory structure"
+      - "Package files (package.json, pyproject.toml, requirements.txt, etc.)"
+    writes: []
+    examples:
+      - "wwa project-discovery -p code"
+      - "wwa project-discovery -p data --json"
+
+  - name: context-refresh
+    cli: "wwa context-refresh"
+    category: routable
+    tier: developer
+    safe_for_agent: true
+    query_type: context_refresh
+    description: "Run context refresh workflow routing to update .context/ after changes."
+    when_to_use: "After code or structure changes, before the next session, to keep .context/ in sync."
+    reads:
+      - ".context/BASE.md"
+      - "Project directory structure"
+      - "Entry point"
+    writes: []
+    examples:
+      - "wwa context-refresh -p code"
+      - "wwa context-refresh --json"
+
+  - name: phase-complete
+    cli: "wwa phase-complete"
+    category: routable
+    tier: developer
+    safe_for_agent: true
+    query_type: phase_completion
+    description: "Run phase completion routing to see which files participate in a phase gate."
+    when_to_use: "When a ROADMAP phase is complete and the agent needs to see required gate updates."
+    reads:
+      - "ROADMAP.md"
+      - "PLAN.md"
+      - "STATE.md"
+    writes: []
+    examples:
+      - "wwa phase-complete"
+      - "wwa phase-complete -p code --json"
+
+  - name: backlog
+    cli: "wwa backlog"
+    category: routable
+    tier: developer
+    safe_for_agent: true
+    query_type: backlog
+    description: "Show routing for backlog work: which files to read/write when adding backlog items."
+    when_to_use: "When planning to add or reorganize backlog entries and wanting correct read/write sets."
+    reads:
+      - "todos/backlog.md"
+      - "Entry point scoping + cascade tables"
+    writes: []
+    examples:
+      - "wwa backlog"
+      - "wwa backlog --json"
+
+  - name: plan-create
+    cli: "wwa plan-create"
+    category: routable
+    tier: developer
+    safe_for_agent: true
+    query_type: planning
+    description: "Run planning workflow routing to see which files to read/write when creating or updating PLAN.md."
+    when_to_use: "Before creating or significantly updating PLAN.md for a new task or phase."
+    reads:
+      - "PLAN.md"
+      - "STATE.md"
+      - "ROADMAP.md"
+    writes: []
+    examples:
+      - "wwa plan-create -p code"
+      - "wwa plan-create --json"
+
+  - name: dependency-analysis
+    cli: "wwa dependency-analysis"
+    category: routable
+    tier: developer
+    safe_for_agent: true
+    query_type: dependency_analysis
+    description: "Run dependency analysis routing to inspect how dependency analysis should read/write context."
+    when_to_use: "When analyzing code or document dependencies before large refactors or docs changes."
+    reads:
+      - "Project directory structure"
+      - "Package and dependency manifests"
+      - ".context/BASE.md"
+    writes: []
+    examples:
+      - "wwa dependency-analysis -p code"
+      - "wwa dependency-analysis --json"
+
+  - name: debt-assessment
+    cli: "wwa debt-assessment"
+    category: routable
+    tier: developer
+    safe_for_agent: true
+    query_type: debt_assessment
+    description: "Run debt assessment routing to see how a technical-debt assessment would read/write methodology files."
+    when_to_use: "When the agent needs to assess technical debt, patterns, or risks before planning remediation."
+    reads:
+      - ".context/BASE.md"
+      - "Key source files (per SCAN features)"
+      - "STATE.md"
+    writes: []
+    examples:
+      - "wwa debt-assessment -p code"
+      - "wwa debt-assessment --json"
+
+  - name: docs-update
+    cli: "wwa docs-update"
+    category: routable
+    tier: developer
+    safe_for_agent: true
+    query_type: docs_update
+    description: "Run docs update routing to understand which docs and scaffolding rules apply."
+    when_to_use: "Before editing docs/ so the agent knows which docs and context files to touch."
+    reads:
+      - ".context/DOCS-MAP.md"
+      - "docs/ directory inventory"
+      - "Entry point cascade table"
+    writes: []
+    examples:
+      - "wwa docs-update -p code"
+      - "wwa docs-update --json"
+
+  - name: cross-reference
+    cli: "wwa cross-reference"
+    category: routable
+    tier: developer
+    safe_for_agent: true
+    query_type: cross_reference
+    description: "Run cross-reference routing to check which specs/docs should be compared for consistency."
+    when_to_use: "When ensuring consistency across specs and docs before or after a change."
+    reads:
+      - "Relevant specs/docs as determined by registry"
+      - "Entry point scoping + cascade tables"
+    writes: []
+    examples:
+      - "wwa cross-reference -p code"
+      - "wwa cross-reference --json"
+
+  # ---------------------------------------------------------------------------
+  # Append-only commands (wwa add …)
+  # ---------------------------------------------------------------------------
+
+  - name: add-backlog
+    cli: "wwa add backlog"
+    category: add
+    tier: developer
+    safe_for_agent: true
+    description: "Append a backlog item to todos/backlog.md in the standard checklist format."
+    when_to_use: "When capturing an idea, task, or follow-up item that should live in the backlog."
+    reads:
+      - "todos/backlog.md (if it exists)"
+    writes:
+      - "todos/backlog.md"
+    examples:
+      - "wwa add backlog \"Add workflow trigger queries as CLI tools\""
+      - "echo \"- [ ] **Title** — description\" | wwa add backlog --file -"
+
+  - name: add-decision
+    cli: "wwa add decision"
+    category: add
+    tier: developer
+    safe_for_agent: true
+    description: "Append a decision row to the STATE.md decisions table with date and rationale."
+    when_to_use: "Immediately after a decision is made so it is preserved in STATE.md."
+    reads:
+      - "STATE.md"
+    writes:
+      - "STATE.md"
+    examples:
+      - "wwa add decision \"2026-03-16 | Use PostgreSQL for persistence | Single source of truth\""
+
+  - name: add-finding
+    cli: "wwa add finding"
+    category: add
+    tier: developer
+    safe_for_agent: true
+    description: "Append a methodology finding to the appropriate docs/internal review file."
+    when_to_use: "When the agent discovers a methodology-related issue or improvement during work."
+    reads:
+      - "docs/internal/review/* (if present)"
+    writes:
+      - "docs/internal/review/findings.md"
+    examples:
+      - "wwa add finding \"Parser doesn't handle SESSION-LOG section headers\""
+
+  - name: add-session
+    cli: "wwa add session"
+    category: add
+    tier: developer
+    safe_for_agent: true
+    description: "Append a complete session entry block to SESSION-LOG.md."
+    when_to_use: "At or near session close, after the agent has prepared a full Entry-format block."
+    reads:
+      - "SESSION-LOG.md"
+    writes:
+      - "SESSION-LOG.md"
+    examples:
+      - "wwa add session --file session-entry.md"
+      - "wwa add session < session-entry.md"
+
+  - name: add-summary
+    cli: "wwa add summary"
+    category: add
+    tier: developer
+    safe_for_agent: true
+    description: "Append a summary block to SUMMARY.md, preserving the audit trail format."
+    when_to_use: "After a high-effort task or phase, to extend the management-facing audit trail."
+    reads:
+      - "SUMMARY.md"
+    writes:
+      - "SUMMARY.md"
+    examples:
+      - "wwa add summary --file summary-block.md"
+      - "wwa add summary < summary-block.md"
+