spec-gen-cli 1.2.6 → 1.2.8

package/examples/bmad/agents/architect.md

@@ -0,0 +1,226 @@
+# Agent: Architect — spec-gen extension
+
+> **This file is a sidecar for the BMAD `architect` agent.**
+>
+> **Setup (one-time):**
+> ```bash
+> # 1. Copy this file into your BMAD project
+> cp examples/bmad/agents/architect.md _bmad/_memory/architect-sidecar/spec-gen.md
+>
+> # 2. Install the customization that tells BMAD to load it
+> cp examples/bmad/setup/architect.customize.yaml \
+>    _bmad/_config/customizations/architect.customize.yaml
+>
+> # 3. Recompile BMAD agents
+> npx bmad-method install
+> ```
+>
+> After that, the Architect agent loads this file automatically at session start.
+> No manual step needed in the conversation.
+>
+> Requires: spec-gen MCP server connected and onboarding completed
+> (see `tasks/onboarding.md`).
+
+---
+
+## Core Principle
+
+The architecture document MUST reflect the reality of the code,
+not just the desired target state. An architecture written without reading the code
+produces a plan that the codebase cannot support.
+
+**Produce two documents:**
+1. **Structural Reality** — what the code actually is (spec-gen output)
+2. **Target Architecture** — what you want it to become (your design)
+
+The gap between them is the technical debt backlog.
+
+---
+
+## Phase 0 — Structural Reality (run before any design work)
+
+### Step 0.1 — Architecture overview
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_architecture_overview</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+Extract:
+- **Domain clusters** → existing logical boundaries
+- **Cross-cluster dependencies** → where coupling is highest
+- **Critical hubs** → functions that act as bottlenecks
+- **Entry points** → where control enters the system
+
+If this returns an error, run `analyze_codebase` first.
+
+### Step 0.2 — Risk landscape
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_refactor_report</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+Classify each high-priority candidate:
+
+| Function | Issues | Priority | Classification |
+|---|---|---|---|
+| ... | high_fan_out | 85 | 🔴 no-touch zone |
+| ... | in_cycle | 62 | 🟠 isolate before touching |
+| ... | multi_requirement | 38 | 🟡 document carefully |
+
+**No-touch zones** (priority ≥ 70): any story touching these functions is **blocked**
+until a refactor story is completed first.
+
+### Step 0.3 — Structural debt
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_duplicate_report</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+Note clone groups — they amplify the cost of any feature that touches duplicated logic.
+
+### Step 0.4 — Critical hubs
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_critical_hubs</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT", "limit": 10, "minFanIn": 3}</arguments>
+</use_mcp_tool>
+```
+
+Hubs with high fan-in are the riskiest insertion points. Note their recommended approach
+(`extract`, `split`, `facade`, `delegate`).
+
+---
+
+## Phase 1 — Feature / Epic Impact Assessment
+
+For each epic or major feature in scope, generate a change proposal:
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>generate_change_proposal</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "description": "$EPIC_DESCRIPTION",
+    "slug": "$EPIC_SLUG"
+  }</arguments>
+</use_mcp_tool>
+```
+
+From each proposal:
+- **domainsAffected** → which spec domains this epic touches
+- **maxRiskScore** → overall risk level of this epic
+- **requirementsTouched** → existing requirements this epic overlaps or extends
+
+Build an epic risk matrix:
+
+| Epic | Domains | Max Risk | Blocking Refactors |
+|---|---|---|---|
+| Add payment retry | payment, api | 🔴 82 | refactor `processPayment` first |
+| User email validation | auth, user | 🟢 18 | none |
+
+---
+
+## Phase 2 — Architecture Document
+
+Write `docs/architecture.md` (or the BMAD equivalent) with two mandatory sections:
+
+### Section: Structural Reality
+
+```markdown
+## Structural Reality (as-is)
+
+> Generated from spec-gen analysis on {date}.
+> Re-run `spec-gen analyze --force` before each planning cycle.
+
+### Domain Map
+
+{paste architecture overview clusters and dependencies}
+
+### No-Touch Zones
+
+Functions that MUST NOT be modified without a prior refactor story:
+
+| Function | File | Risk | Issues |
+|---|---|---|---|
+
+### Known Debt
+
+- N clone groups detected
+- N cyclic dependencies
+
+### Critical Hubs
+
+Functions requiring the most careful change management:
+
+| Function | Fan-in | Recommended approach |
+|---|---|---|
+```
+
+### Section: Target Architecture
+
+Design the future state here — new domains, desired boundaries, patterns to introduce.
+**For each structural gap between reality and target, create a technical debt story.**
+
+---
+
+## Phase 3 — Technical Debt Backlog
+
+For every no-touch zone, create a **refactor story** in the BMAD backlog:
+
+Use the template `bmad/templates/story.md` with:
+- Story type: `technical-debt`
+- Title: `Refactor {function}: {issue}`
+- Blocking: list stories that cannot proceed until this is done
+- **Won't Do**: at minimum one item — scope the refactor tightly (e.g. "Won't change the public API", "Won't refactor callers")
+- **Acceptance Criteria**: must be testable — state observable outcomes (e.g. "riskScore drops below 70", "no caller changes required")
+
+These stories MUST be sprint-scheduled before any story that depends on the refactored function.
+
+---
+
+## Phase 4 — Annotate Stories with Risk Context
+
+For each story in the backlog, run `annotate_story` — do not fill `risk_context` manually.
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>annotate_story</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "storyFilePath": "$STORY_FILE_PATH",
+    "description": "$STORY_TITLE — $PRIMARY_AC"
+  }</arguments>
+</use_mcp_tool>
+```
+
+The tool reads the story file, runs `orient` + `analyze_impact`, and writes the
+`risk_context` section directly. Existing sections are replaced, not appended.
+
+Re-run after any completed refactor story — risk scores change as the code evolves.
+
+The Dev Agent reads this context at sprint time — it does **not** discover it.
+
+---
+
+## Absolute Constraints
+
+- Never write a target architecture without first completing Phase 0
+- Never assign a story touching a no-touch zone without a blocking refactor story in the backlog
+- Always run `annotate_story` on stories before they enter a sprint — never fill risk_context manually
+- Re-run Phase 0 at the start of each planning cycle — the structural reality changes

package/examples/bmad/agents/dev-brownfield.md

@@ -0,0 +1,69 @@
+# Agent: Developer — No-Planning Fallback
+
+> **Load this ONLY when:**
+> - No architect analysis was done and stories have no `risk_context`
+> - Onboarding to a completely unknown codebase mid-project
+> - The sprint planning task was skipped
+>
+> In normal usage, `bmad/tasks/implement-story.md` is sufficient —
+> the risk context from planning makes this override unnecessary.
+
+---
+
+## What this adds
+
+When `risk_context` is absent from a story, this override enforces a full
+structural gate at implementation time as a safety net.
+
+For every story, before writing code:
+
+1. Call `orient` with the story description
+2. Call `analyze_impact` on the top 3 functions
+3. If any `riskScore ≥ 70`: stop, propose a refactor story, do not proceed
+
+This replicates at dev time what should have happened at planning time.
+
+---
+
+## When to stop using this
+
+Once the Architect Agent has run `bmad/tasks/onboarding.md` and
+`bmad/agents/architect.md`, and stories have `risk_context` populated,
+**remove this override**. It adds cost (extra MCP calls) with no benefit
+once planning is done correctly.
+
+---
+
+## Gate
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>orient</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "task": "$STORY_TITLE — $AC1",
+    "limit": 7
+  }</arguments>
+</use_mcp_tool>
+```
+
+For each of the top 3 functions:
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>analyze_impact</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "symbol": "$FUNCTION_NAME",
+    "depth": 2
+  }</arguments>
+</use_mcp_tool>
+```
+
+| riskScore | Action |
+|---|---|
+| < 40 | Proceed |
+| 40–69 | Proceed with care — protect listed callers |
+| ≥ 70 | Stop — create refactor story, block this story |

package/examples/bmad/setup/architect.customize.yaml

@@ -0,0 +1,14 @@
+# spec-gen extension for the BMAD Architect agent
+#
+# Drop this file at: _bmad/_config/customizations/architect.customize.yaml
+# Then re-run: npx bmad-method install
+#
+# What it does: instructs the Architect agent to load the spec-gen structural
+# analysis instructions as a sidecar before starting any design work.
+
+customize:
+  metadata:
+    hasSidecar: true
+  critical-actions:
+    Appends:
+      - "Load COMPLETE file {project-root}/_bmad/_memory/architect-sidecar/spec-gen.md"

package/examples/bmad/tasks/implement-story.md

@@ -0,0 +1,254 @@
+# Task: Implement Story
+
+**Purpose**: Implement a BMAD story on any codebase — new or existing.
+Structural analysis is used proportionally to the risk level already known from planning.
+
+---
+
+## Inputs
+
+From the story file:
+- `$STORY_TITLE`, `$AC`, `$PROJECT_ROOT`
+- `$RISK_CONTEXT` — the `risk_context` section (pre-filled by Architect Agent at planning time)
+
+If `.claude/antipatterns.md` exists, read it and store as `$ANTIPATTERNS`.
+This list will be cross-checked at Step 4b.
+
+---
+
+## Step 1 — Read the risk context
+
+Open the story file and check whether `risk_context` is populated.
+
+### If risk_context IS present (normal case — planning was done)
+
+Use it directly. Do not re-run structural analysis unless something feels wrong.
+
+| Risk level in story | Approach |
+|---|---|
+| 🟢 low (< 40) | Proceed to Step 3. Quick orient to confirm insertion point. |
+| 🟡 medium (40–69) | Run Step 2 impact check. Proceed with callers protected. |
+| 🔴 high / critical (≥ 70) | Story should have a blocking refactor. If not scheduled, stop and flag it. |
+
+### If risk_context is ABSENT (planning was skipped or story is new)
+
+Run the full orientation in Step 2 before proceeding.
+
+---
+
+## Step 2 — Orient (full or confirm)
+
+**Full orient** (risk_context absent, or medium+ risk):
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>orient</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "task": "$STORY_TITLE — $AC1",
+    "limit": 7
+  }</arguments>
+</use_mcp_tool>
+```
+
+If orient returns `"error": "no cache"` → run `analyze_codebase` first, then retry.
+
+**For medium+ risk**, also run impact on the top 2 functions:
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>analyze_impact</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "symbol": "$FUNCTION_NAME",
+    "depth": 2
+  }</arguments>
+</use_mcp_tool>
+```
+
+If a function has `riskScore ≥ 70` that was NOT flagged at planning: **stop**.
+Create a blocking refactor story and do not implement until it's resolved.
+
+---
+
+## Step 2.5 — Audit spec coverage of the target domain
+
+Run a parity audit to check if the domain you're about to touch has spec gaps.
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>audit_spec_coverage</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+From the result, check:
+- `staleDomains` — if the target domain appears here, its spec is outdated.
+  Recommend running `spec-gen generate --domains $DOMAIN` before implementing.
+- `hubGaps` — uncovered hub functions. If the feature touches one of these,
+  add it to the adversarial check in Step 4b (high blast radius + no spec = risk).
+
+If both are clean, continue to Step 3 without action.
+
+---
+
+## Step 3 — Check the spec
+
+First verify that OpenSpec specs exist for this project:
+
+```bash
+ls $PROJECT_ROOT/openspec/specs/ 2>/dev/null | wc -l
+```
+
+**If 0 specs found:**
+> No OpenSpec specs exist yet for this project. `search_specs` will return empty
+> results and `check_spec_drift` (Step 7) will flag all files as uncovered.
+>
+> The Architect agent should have run `spec-gen generate` during onboarding.
+> If it hasn't been run yet, note it in the Dev Agent Record and proceed with
+> structural analysis only. The spec baseline can be created post-sprint with
+> `spec-gen generate $PROJECT_ROOT`.
+
+Skip `search_specs` and go to Step 4.
+
+**If specs exist:**
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>search_specs</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "query": "$STORY_TITLE",
+    "limit": 5
+  }</arguments>
+</use_mcp_tool>
+```
+
+If relevant requirements are found, read the domain spec before writing code.
+Note any constraints that apply to the implementation.
+
+---
+
+## Step 4 — Find the insertion point
+
+Use the `insertion_points` from `risk_context` if present. Otherwise:
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>suggest_insertion_points</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "description": "$STORY_TITLE",
+    "limit": 5
+  }</arguments>
+</use_mcp_tool>
+```
+
+Read the skeleton of the target file:
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_function_skeleton</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "filePath": "$TARGET_FILE"
+  }</arguments>
+</use_mcp_tool>
+```
+
+Confirm the approach with the user before writing code.
+
+### Step 4b — Adversarial self-check
+
+Before writing any code, state explicitly what could break with this approach.
+If `$ANTIPATTERNS` was loaded (see Inputs), include any applicable patterns.
+
+> "Risk check on `$INSERTION_POINT`:
+> - `$CALLER_A` and `$CALLER_B` depend on this function — verify their assumptions hold after the change.
+> - `$EDGE_CASE` is not covered by the current test suite — add it in Step 6.
+> - [if antipatterns apply] AP-NNN (`$PATTERN_NAME`) — `$RULE` — applies here because `$REASON`."
+
+This is not a gate — do not wait for user input. It is a mandatory self-check
+that must appear in the output before the first line of code is written.
+
+---
+
+## Step 5 — Implement
+
+Apply changes in this order:
+1. New types/interfaces (if needed)
+2. Core logic at the insertion point
+3. Updated call sites (if any)
+
+Do not touch functions outside the scope from Step 2/risk_context without re-running the gate.
+
+---
+
+## Step 6 — Tests
+
+Two levels, both required before proceeding:
+
+**Mandatory — existing tests must not regress:**
+Run the full test suite. If any pre-existing test breaks, fix the regression before continuing.
+A green CI on existing tests is the minimum gate.
+
+**Recommended — at least one new test per AC:**
+Write a test that directly exercises the new behaviour described in the acceptance criterion.
+This is the proof that the implementation matches the intent — without it, the spec update in Step 7 has no evidence.
+
+| Situation | Action |
+|---|---|
+| All tests green, new tests written | Proceed to Step 7 |
+| Existing test broken | Fix regression. Do not proceed. |
+| New test reveals a misunderstanding of the AC | Return to Step 5, adjust implementation |
+| Brownfield: no existing test coverage | Write the new test anyway. Note the coverage gap in the Dev Agent Record. |
+
+---
+
+## Step 7 — Verify drift
+
+Only run once tests are green.
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>check_spec_drift</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+| Drift type | Resolution |
+|---|---|
+| `uncovered` on new files | Propose `spec-gen generate` post-sprint |
+| `gap` on existing domain | Run `spec-gen generate --domains $DOMAIN` |
+| `stale` | Fix the reference |
+| No drift | ✅ |
+
+If drift is found on a domain touched by this story, note it in the Dev Agent Record — the spec update can be proposed after the sprint, not mid-implementation.
+
+---
+
+## Step 8 — Update the story
+
+Fill in the **Dev Agent Record** section of the story file and mark as `Review`.
+
+Include:
+- test files written / modified
+- whether existing coverage was sufficient or a gap remains
+- any drift found in Step 7
+
+---
+
+## Absolute constraints
+
+- Do not write code before Step 4 confirmation
+- Step 4b adversarial self-check is mandatory — never skip it
+- If riskScore ≥ 70 was not caught at planning — stop, do not work around it
+- Do not run `check_spec_drift` before tests are green
+- Do not propose a spec update on untested code