spec-gen-cli 1.2.6 → 1.2.8

package/examples/bmad/tasks/onboarding.md

@@ -0,0 +1,169 @@
+# Task: Brownfield Onboarding
+
+**Purpose**: Establish a structural baseline on an existing codebase.
+**Phase**: Architecture — run this BEFORE writing architecture documents, planning epics, or creating stories.
+Run once per project, then re-run at the start of each planning cycle (quarterly or after major refactors).
+
+**Who runs this**: Architect Agent (not Dev Agent).
+
+**Output**: populated `openspec/` + `.spec-gen/` + risk register embedded in architecture doc.
+
+**Estimated time**: 5–15 minutes depending on codebase size.
+
+---
+
+## Prerequisites
+
+- spec-gen MCP server connected
+- `spec-gen` CLI available (`npx spec-gen` or local install)
+- Read access to the project directory
+
+---
+
+## Step 1 — Run static analysis
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>analyze_codebase</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "force": false
+  }</arguments>
+</use_mcp_tool>
+```
+
+Expected output: summary with module count, function count, cycle count.
+If `cycles_detected > 0`, note it — this is a brownfield risk signal.
+
+---
+
+## Step 2 — Understand the architecture
+
+```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>
+```
+
+From the result, record:
+- **Domain clusters** (the logical groupings spec-gen detected)
+- **Cross-cluster dependencies** (coupling risks)
+- **Entry points** (where requests enter the system)
+- **Critical hubs** (high fan-in functions — touch with care)
+
+---
+
+## Step 3 — Identify hotspots
+
+```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>
+```
+
+Create a brownfield risk register — a simple table:
+
+| Function | File | Issues | Priority | Action |
+|---|---|---|---|---|
+| ... | ... | high_fan_out | 85 | Refactor before touching |
+| ... | ... | in_cycle | 60 | Isolate cycle first |
+| ... | ... | multi_requirement | 40 | Document carefully |
+
+Functions with priority > 70 are **no-touch zones** until refactored.
+
+---
+
+## Step 4 — Check for duplicate code
+
+```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 any clone groups — they indicate debt that will multiply if features are added naively.
+
+---
+
+## Step 5 — Generate OpenSpec (if no specs exist)
+
+If `openspec/` does not exist or has no specs, generate them:
+
+```bash
+spec-gen analyze --embed
+spec-gen generate
+```
+
+Or trigger the spec-gen skill in your AI agent:
+
+> "Run spec-gen on this codebase and generate OpenSpec specifications."
+
+This creates `openspec/specs/{domain}/spec.md` for each detected domain.
+Commit the result — these become the baseline for drift detection.
+
+---
+
+## Step 6 — Verify spec coverage
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>check_spec_drift</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "base": "HEAD"
+  }</arguments>
+</use_mcp_tool>
+```
+
+At this point drift should be zero (we just generated specs from HEAD).
+If `uncovered` files appear, add them to the backlog as "spec missing" items.
+
+---
+
+## Step 7 — Record the baseline
+
+Create or update `openspec/specs/architecture/spec.md` with a **brownfield baseline** section:
+
+```markdown
+## Brownfield Baseline
+
+> Established: {date}
+
+### Risk Register
+
+| Function | Issues | Priority |
+|---|---|---|
+| ... | ... | ... |
+
+### No-touch zones (priority > 70)
+
+- `functionName` in `path/to/file.ts` — reason
+
+### Known duplicate groups
+
+- N clone groups detected (see `.spec-gen/analysis/`)
+
+### Onboarding notes
+
+- ...
+```
+
+---
+
+## Completion Criteria
+
+- [ ] `spec-gen analyze` completed without error
+- [ ] Architecture overview reviewed and understood
+- [ ] Risk register created with functions priority > 70 flagged
+- [ ] `openspec/` populated (generated or pre-existing)
+- [ ] `check_spec_drift` shows zero drift on HEAD
+- [ ] Baseline documented in `openspec/specs/architecture/spec.md`
+- [ ] BMAD project backlog updated with any "spec missing" items

package/examples/bmad/tasks/refactor.md

@@ -0,0 +1,178 @@
+# Task: Brownfield Refactor
+
+**Purpose**: Plan and execute a safe refactoring on a brownfield codebase before implementing a story.
+Typically triggered by the `dev-brownfield` agent gate when `riskScore ≥ 70`.
+
+**Output**: `.spec-gen/refactor-plan.md` applied and verified.
+
+---
+
+## Inputs
+
+- `$TARGET_FUNCTION` — function identified as high-risk by `analyze_impact`
+- `$PROJECT_ROOT` — absolute path to the project
+
+---
+
+## Step 1 — Confirm target and scope
+
+Present the risk signal to the user:
+
+> "`$TARGET_FUNCTION` has a risk score of $SCORE ($ISSUES).
+> Implementing the planned story on this function as-is risks breaking $CALLERS.
+> This task will refactor it first. Proceed?"
+
+If the user declines, mark the story as blocked with dependency: "Refactor `$TARGET_FUNCTION` first."
+
+---
+
+## Step 2 — Get the refactor report
+
+```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>
+```
+
+Confirm `$TARGET_FUNCTION` appears in the report and note its issues and priority score.
+
+---
+
+## Step 3 — Check for clones
+
+```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>
+```
+
+If `$TARGET_FUNCTION` appears in a clone group:
+> "⚠️ This function has N near-clones. Consolidate them first to reduce blast radius."
+Propose consolidation as Change 0 in the plan.
+
+---
+
+## Step 4 — Analyse the call neighbourhood
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>analyze_impact</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "symbol": "$TARGET_FUNCTION",
+    "depth": 3
+  }</arguments>
+</use_mcp_tool>
+```
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_subgraph</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "functionName": "$TARGET_FUNCTION",
+    "direction": "both",
+    "format": "mermaid"
+  }</arguments>
+</use_mcp_tool>
+```
+
+Show the Mermaid diagram. Identify extraction candidates in the downstream subgraph.
+
+---
+
+## Step 5 — Find safe extraction targets
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_low_risk_refactor_candidates</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "filePattern": "$TARGET_FILE",
+    "limit": 5
+  }</arguments>
+</use_mcp_tool>
+```
+
+Cross-reference with the subgraph: good extraction candidates are already callees of `$TARGET_FUNCTION`.
+
+---
+
+## Step 6 — Find landing zones for extracted helpers
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>suggest_insertion_points</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "description": "extract helper from $TARGET_FUNCTION",
+    "limit": 5
+  }</arguments>
+</use_mcp_tool>
+```
+
+---
+
+## Step 7 — Design the change sequence
+
+Design an ordered sequence of atomic changes. Each change must specify:
+
+- **What**: the exact block to extract (description or line range)
+- **New name**: function name
+- **Target file**: where to place it (existing or new)
+- **Call sites to update**: list each file that calls `$TARGET_FUNCTION` or the extracted block
+
+**Present the full sequence to the user and wait for explicit approval before writing the plan.**
+
+---
+
+## Step 8 — Execute (delegate to spec-gen-execute-refactor)
+
+Once the plan is approved, hand off to the `spec-gen-execute-refactor` skill:
+
+1. Write `.spec-gen/refactor-plan.md` with the full plan (see skill template)
+2. Invoke `/spec-gen-execute-refactor`
+
+The execute skill handles:
+- Green baseline verification
+- Restore point setup
+- Atomic change application with tests after each step
+- Post-refactor risk score verification
+
+---
+
+## Step 9 — Re-run the gate
+
+After the refactor is complete, re-run `analyze_impact` on `$TARGET_FUNCTION`:
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>analyze_impact</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "symbol": "$TARGET_FUNCTION",
+    "depth": 2
+  }</arguments>
+</use_mcp_tool>
+```
+
+- If `riskScore` is now < 70 → return to the story implementation task
+- If `riskScore` is still ≥ 70 → repeat from Step 4 with the updated subgraph
+
+---
+
+## Completion Criteria
+
+- [ ] `riskScore` for `$TARGET_FUNCTION` < 70
+- [ ] Full test suite passes (green)
+- [ ] `check_spec_drift` clean or addressed
+- [ ] Story unblocked — return to `implement-story-brownfield`

package/examples/bmad/tasks/sprint-planning.md

@@ -0,0 +1,168 @@
+# Task: Sprint Planning
+
+**Purpose**: Validate a sprint candidate before committing to it.
+Detects conflicts, blocked stories, and ordering constraints using structural analysis.
+
+**Who runs this**: Scrum Master Agent or Architect Agent, during sprint planning.
+**When**: Before the sprint is locked — after stories are written, before they're assigned.
+
+**Output**: sprint risk report + recommended story order + blocking issues list.
+
+---
+
+## Prerequisites
+
+- Onboarding completed (`bmad/tasks/onboarding.md`)
+- All sprint candidate stories have a `risk_context` section
+- If `risk_context` is missing on any story, run `annotate_story` on it first (not manually)
+
+---
+
+## Step 1 — Refresh the structural analysis
+
+If the last `analyze_codebase` run was more than 24 hours ago, or if code changed since then:
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>analyze_codebase</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT", "force": false}</arguments>
+</use_mcp_tool>
+```
+
+---
+
+## Step 2 — Collect risk data per story
+
+For each story in the sprint candidate list:
+
+**If `risk_context` is already populated** (normal case — architect did their job):
+Read it directly from the story file. No MCP call needed.
+
+**If `risk_context` is absent**, run `annotate_story` now:
+
+```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>
+```
+
+Collect from each story's `risk_context`:
+- `Domains` → which spec domains are touched
+- `Max risk score` + level
+- `Blocking refactors` → any listed
+- `Functions in scope` → for conflict detection
+
+**Also verify story quality:**
+- `## Won't Do` section must be present with at least 1 item
+- Every AC must be testable (specific observable outcome, not a vague quality)
+
+Flag non-compliant stories:
+> "⚠️ Story S-NN is missing `## Won't Do` / has vague ACs — return to author before sprint lock."
+
+---
+
+## Step 3 — Build the sprint risk matrix
+
+| Story | Domains | Risk | Blocking Refactors | Status |
+|---|---|---|---|---|
+| S-01 Add retry | payment | 🔴 82 | `processPayment` | ⛔ blocked |
+| S-02 Email validation | auth | 🟢 18 | none | ✅ ready |
+| S-03 Rate limiting | api | 🟡 45 | none | ⚠️ caution |
+
+**Status rules:**
+- ⛔ **blocked**: max risk ≥ 70 and no refactor story scheduled before it
+- ⚠️ **caution**: max risk 40–69, or story touches a critical hub
+- ✅ **ready**: max risk < 40 and no hub involvement
+
+---
+
+## Step 4 — Detect function conflicts
+
+Find stories whose `functions in scope` overlap.
+
+Get the full hub list to cross-reference:
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_critical_hubs</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT", "limit": 15}</arguments>
+</use_mcp_tool>
+```
+
+For each hub that appears in two or more stories' function scope:
+
+> "⚠️ Stories S-01 and S-04 both touch `processPayment` (fan-in: 12).
+> Parallel risk: merge conflicts and silent regressions.
+> Recommend: sequence them, or assign to the same developer."
+
+---
+
+## Step 5 — Check spec coverage gaps
+
+```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>
+```
+
+For any `uncovered` files already present:
+> "Stories touching these files cannot use `check_spec_drift` as a completion gate.
+> Add a `spec-gen generate` task to the sprint."
+
+---
+
+## Step 6 — Determine story ordering
+
+**Rules:**
+1. Refactor stories before the stories they unblock
+2. Stories touching the same hub: sequence, do not parallelise
+3. Low-risk stories can be parallelised freely
+4. `spec-gen generate` after any story that adds new source files
+
+---
+
+## Step 7 — Sprint readiness verdict
+
+| Criterion | Status |
+|---|---|
+| No ⛔ stories without prior refactor scheduled | ✅ / ⛔ |
+| No parallel stories on the same hub | ✅ / ⚠️ |
+| All stories have `risk_context` | ✅ / ⛔ |
+| All stories have `## Won't Do` and testable ACs | ✅ / ⚠️ |
+| Spec coverage adequate for drift detection | ✅ / ⚠️ |
+
+**If any ⛔ remain: do not lock the sprint.** Resolve blockers first.
+
+---
+
+## Output
+
+Write the sprint plan to `.spec-gen/sprints/sprint-{N}.md`:
+
+```markdown
+# Sprint {N} — Risk Report
+
+Generated: {date}
+
+## Risk Matrix
+{table from Step 3}
+
+## Conflicts
+{list from Step 4}
+
+## Recommended Order
+{from Step 6}
+
+## Readiness
+{verdict from Step 7}
+```

package/examples/bmad/templates/story.md

@@ -0,0 +1,108 @@
+# Story {ID}: {Title}
+
+**Type**: feature | technical-debt | bug | spike
+**Epic**: {epic name}
+**Status**: Draft | Ready | In Progress | Review | Done
+
+---
+
+## User Story
+
+As a **{role}**,
+I want **{capability}**,
+so that **{benefit}**.
+
+---
+
+## Acceptance Criteria
+
+> Each criterion must be testable: describe a specific observable outcome, not a vague quality.
+> ✗ "The UX should be responsive" — not a criterion
+> ✓ "Submitting the form with an empty email field shows a validation error" — testable
+
+- [ ] AC1: {criterion}
+- [ ] AC2: {criterion}
+- [ ] AC3: {criterion}
+
+---
+
+## Won't Do
+
+> What this story explicitly does NOT cover. Minimum 1 item.
+> Prevents scope creep and removes ambiguity for the Dev Agent.
+
+- {out-of-scope item}
+
+---
+
+## Risk Context
+
+> Pre-filled by the Architect Agent using spec-gen.
+> Dev Agent reads this — does NOT rediscover it at implementation time.
+
+- **Domains in scope**: {e.g. auth, api}
+- **Max risk score**: {0–100} {🟢 low | 🟡 medium | 🟠 high | 🔴 critical}
+- **Functions in scope**: {function1 (file), function2 (file)}
+- **Blocking refactors**: {none | "Refactor X first — Story {ID}"}
+- **Parallel risk**: {none | "Conflicts with Story {ID} on function X"}
+- **Insertion points**: {function (strategy, score)}
+- **Spec domains linked**: {domain1/spec.md, domain2/spec.md}
+
+### Structural Notes
+
+{Any architectural constraints, patterns to follow, anti-patterns to avoid.
+ Filled by Architect Agent based on get_architecture_overview output.}
+
+---
+
+## Technical Constraints
+
+- {constraint 1}
+- {constraint 2}
+
+---
+
+## Tasks
+
+> Filled by Dev Agent during implementation.
+
+- [ ] {task 1}
+- [ ] {task 2}
+- [ ] Add/update tests
+- [ ] Run `check_spec_drift` — confirm clean
+
+---
+
+## Dev Agent Record
+
+> Filled by Dev Agent on completion.
+
+### Implementation Summary
+
+- **Insertion point used**: {function} in {file}
+- **Files changed**: {list}
+- **Tests added**: {N}
+- **Spec drift**: ✅ clean | ⚠️ {details}
+
+### Risk Notes
+
+| Function | Actual Risk Score | Delta vs Estimate |
+|---|---|---|
+| | | |
+
+### Scope Notes
+
+{Were any functions touched outside the planned scope? Why?}
+
+---
+
+## Dependencies
+
+- **Blocked by**: {Story ID — reason} | none
+- **Blocks**: {Story ID} | none
+
+---
+
+## Story Points
+
+{estimate} — basis: {risk level, insertion complexity, test surface}