spec-gen-cli 1.2.6 → 1.2.8

package/examples/mistral-vibe/skills/spec-gen-brainstorm/SKILL.md

@@ -0,0 +1,379 @@
+---
+name: spec-gen-brainstorm
+description: Transform a feature idea into an annotated story. Detects greenfield vs brownfield automatically — uses Domain Sketch for greenfield (no existing code), Constrained Option Tree for brownfield (existing codebase with spec-gen analysis).
+license: MIT
+compatibility: spec-gen MCP server
+user-invocable: true
+allowed-tools:
+  - ask_followup_question
+  - use_mcp_tool
+  - read_file
+  - write_file
+  - str_replace_based_edit
+  - run_command
+---
+
+# spec-gen: Brainstorm
+
+## When to use this skill
+
+Trigger this skill when the user wants to **explore or design a new feature** before
+writing any code, with phrasings like:
+- "I want to add feature X"
+- "how should I approach this?"
+- "let's brainstorm this story"
+- explicit command `/spec-gen-brainstorm`
+
+---
+
+## Step 1 — Detect mode
+
+Capture `$PROJECT_ROOT`, `$FEATURE_DESCRIPTION`, and
+`$FEATURE_SLUG` (kebab-case, ≤ 5 words, e.g. `payment-retry-flow`).
+
+Then probe the structural index:
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>orient</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "task": "$FEATURE_DESCRIPTION",
+    "limit": 7
+  }</arguments>
+</use_mcp_tool>
+```
+
+Set `$MODE` based on the result:
+
+| Result | `$MODE` | Meaning |
+|---|---|---|
+| Returns functions with score > 0 | `brownfield` | Existing indexed codebase |
+| Returns `"error": "no cache"` or 0 functions | `greenfield` | No structural index yet |
+
+Inform the user:
+- Brownfield: "I found existing code related to this feature. Using structural analysis to guide design."
+- Greenfield: "No structural index found. Using Domain Sketch — structural analysis will be available after `spec-gen analyze` is run on the first implementation."
+
+**Load project antipatterns (both modes):**
+
+If `.claude/antipatterns.md` exists, read it and store as `$ANTIPATTERNS`.
+These will be used as a failure mode source in Step 5. If absent, `$ANTIPATTERNS = none`.
+
+---
+
+## Steps 2–4 — Structural analysis (brownfield only)
+
+*Skip to Step 5 if `$MODE = greenfield`.*
+
+### Step 2 — 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>
+```
+
+Note hub functions and cross-domain dependencies in `$DOMAINS_AFFECTED`.
+
+### Step 3 — Generate change proposal
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>generate_change_proposal</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "description": "$FEATURE_DESCRIPTION",
+    "slug": "$FEATURE_SLUG"
+  }</arguments>
+</use_mcp_tool>
+```
+
+Chains `orient` + `search_specs` + `analyze_impact` and writes
+`openspec/changes/$FEATURE_SLUG/proposal.md`.
+
+Extract:
+- **`$MAX_RISK_SCORE`** — overall risk level
+- **`$REQUIREMENTS_TOUCHED`** — existing requirements this feature overlaps
+- **`$BLOCKING_REFACTORS`** — functions with risk ≥ 70
+
+### Step 4 — Risk gate
+
+| Score | Action |
+|---|---|
+| 🟢 < 40 | Proceed to Step 5 |
+| 🟡 40–69 | Proceed, flag impacted callers to protect during design |
+| 🔴 ≥ 70 | Stop — propose a blocking refactor story before continuing |
+
+If blocked:
+> "This feature touches `$BLOCKING_FUNCTION` (risk score: $SCORE).
+> A refactor story must be completed first. I can create it now if you'd like."
+
+Do not continue until the user accepts the refactor story or explicitly overrides.
+
+---
+
+## Step 5 — Brainstorming
+
+### If `$MODE = brownfield` — Constrained Option Tree
+
+**5a — Establish the constraint space**
+
+Derive from Steps 2–4 and present before generating options:
+
+```
+Hard constraints (non-negotiable):
+  - Functions with riskScore ≥ 70: $BLOCKED_FUNCTIONS
+  - Requirements that must be preserved: $REQUIREMENTS_TOUCHED
+  - Domain boundaries that must not be crossed: $DOMAIN_BOUNDARIES
+
+Soft constraints (preferred):
+  - Existing insertion points: $INSERTION_POINTS
+  - Patterns already used in $DOMAINS_AFFECTED
+```
+
+Ask: "Are there additional constraints before we explore approaches?"
+
+**5b — Generate 2–3 options**
+
+Each option must respect hard constraints. Name them clearly
+(e.g. Option A — Extend existing, Option B — New service, Option C — Facade).
+
+If `$ANTIPATTERNS ≠ none`, cross-check each option against the list.
+Flag any option that would reproduce a known failure pattern with ⚠ and the relevant AP-NNN.
+
+| | Option A | Option B | Option C |
+|---|---|---|---|
+| Insertion point | | | |
+| Domains touched | | | |
+| Risk score impact | | | |
+| Requirements affected | | | |
+| Estimated scope (files) | | | |
+| Trade-off | | | |
+
+**5c — Recommend**
+
+State one recommendation with a single structural reason:
+
+> "Recommend Option B — inserts at `$SAFE_FUNCTION` (risk 18), avoids `$HUB`
+> (fan-in 14) entirely. Option A is valid but adds unnecessary blast radius."
+
+**5d — Confirm**
+
+Do not proceed to Step 5e until the user chooses. If they want a hybrid,
+produce a revised option table.
+
+**5e — Adversarial challenge**
+
+Before writing the story, switch roles: challenge the chosen option as a skeptic.
+
+State exactly 2 failure modes grounded in the structural data and, if `$ANTIPATTERNS ≠ none`,
+any applicable antipatterns from `.claude/antipatterns.md`:
+
+> "Devil's advocate on Option B:
+> 1. `$CALLER_A` calls `$INSERTION_POINT` with `$EDGE_CASE` — this path is not covered
+>    by the proposed approach and could silently break.
+> 2. The proposal scores risk at $SCORE but `$HUB` (fan-in $N) is one hop away —
+>    a regression there would not be caught until `check_spec_drift`."
+
+Then ask the user: "Do these failure modes change your choice, or should we add
+mitigations to the story constraints?"
+
+Only proceed to Step 6 once the user has acknowledged the failure modes.
+Mitigations go into `## Technical Constraints` in the story.
+
+> Note: this IS a gate (waits for user input) because brainstorm is a design phase
+> where changing course is cheap. In contrast, `spec-gen-implement-story` Step 4b
+> is a mandatory self-check that does NOT gate — because by implementation time
+> the design decision is already made.
+
+Ask: "What is explicitly out of scope for this story?" List the answers as `$WONT_DO`.
+
+---
+
+### If `$MODE = greenfield` — Domain Sketch
+
+No existing structure to constrain — the method builds the structure from scratch.
+
+**5a — Entities**
+
+Ask the user: "What are the core data objects this feature creates or transforms?"
+
+List them as nouns with a one-line definition each:
+```
+$ENTITY_1 — definition
+$ENTITY_2 — definition
+```
+
+**5b — Operations**
+
+For each entity, identify the operations the feature needs (create, read,
+transform, delete, emit, receive…):
+
+```
+$ENTITY_1: $OP_1, $OP_2
+$ENTITY_2: $OP_1
+```
+
+Identify which operations cross a system boundary (external API, database,
+event bus, CLI…) — these are the riskiest integration points.
+
+**5c — Boundaries**
+
+Define where the feature sits relative to the system:
+
+```
+Entry point:   $HOW_IT_IS_TRIGGERED (HTTP request / CLI command / event / cron)
+Data in:       $INPUT_FORMAT
+Data out:      $OUTPUT_FORMAT or side-effects
+External deps: $THIRD_PARTY_SERVICES or "none"
+```
+
+**5d — Architecture decisions**
+
+State 2–3 decisions that must be made before coding. For each, list the options
+and a recommendation:
+
+| Decision | Options | Recommendation |
+|---|---|---|
+| e.g. Storage | in-memory / DB / file | DB — survives restarts |
+| e.g. Coupling | new module / extend existing | new module — clear boundary |
+
+Ask the user to confirm or override each decision before proceeding to Step 6.
+
+Ask: "What is explicitly out of scope for this story?" List the answers as `$WONT_DO`.
+
+---
+
+## Step 6 — Write the story
+
+Produce a story file at `$STORIES_DIR/$FEATURE_SLUG.md`.
+
+If a story template exists at `$PROJECT_ROOT/_bmad/spec-gen/templates/story.md`
+or `$PROJECT_ROOT/examples/bmad/templates/story.md`, use it. Otherwise:
+
+**Brownfield template:**
+
+```markdown
+# $STORY_TITLE
+
+## Goal
+
+$FEATURE_DESCRIPTION
+
+## Acceptance Criteria
+
+Each AC must be verifiable by a test. State the observable outcome, not the intent.
+✗ "Should handle errors correctly" — ✓ "Returns HTTP 400 with `{error: 'X'}` when Y is absent"
+
+- [ ] $AC_1
+- [ ] $AC_2
+
+## Won't Do
+
+- $WONT_DO_1
+- $WONT_DO_2
+
+## Risk Context
+
+<!-- Filled by annotate_story in Step 7 -->
+
+## Technical Constraints
+
+$BLOCKING_REFACTORS and caller protection notes from the proposal.
+
+## Notes
+
+- Chosen approach: $CHOSEN_OPTION — $TRADE_OFF
+- Domains affected: $DOMAINS_AFFECTED
+- Requirements touched: $REQUIREMENTS_TOUCHED
+- Max risk score: $MAX_RISK_SCORE
+```
+
+**Greenfield template:**
+
+```markdown
+# $STORY_TITLE
+
+## Goal
+
+$FEATURE_DESCRIPTION
+
+## Acceptance Criteria
+
+Each AC must be verifiable by a test. State the observable outcome, not the intent.
+✗ "Should handle errors correctly" — ✓ "Returns HTTP 400 with `{error: 'X'}` when Y is absent"
+
+- [ ] $AC_1
+- [ ] $AC_2
+
+## Won't Do
+
+- $WONT_DO_1
+- $WONT_DO_2
+
+## Domain Sketch
+
+### Entities
+$ENTITIES
+
+### Operations
+$OPERATIONS
+
+### Boundaries
+$BOUNDARIES
+
+## Architecture Decisions
+
+$DECISIONS_TABLE
+
+## Notes
+
+- First implementation — run `spec-gen analyze && spec-gen generate` after
+  to enable structural analysis for future stories.
+```
+
+---
+
+## Step 7 — Annotate the story
+
+**Brownfield only.** Skip if `$MODE = greenfield`.
+
+```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"
+  }</arguments>
+</use_mcp_tool>
+```
+
+Patches `## Risk Context` directly. Story is now ready for `spec-gen-implement-story`.
+
+**Greenfield:** confirm to the user:
+> "Story written to `$STORY_FILE_PATH`. No risk context yet — run
+> `spec-gen analyze` after the first implementation sprint to enable
+> structural analysis for future stories."
+
+---
+
+## Absolute constraints
+
+- Do not ask design questions before Step 5 (both modes)
+- Brownfield: do not proceed past Step 4 if `$MAX_RISK_SCORE ≥ 70` without acknowledgement
+- Brownfield: do not fill `## Risk Context` manually — always use `annotate_story`
+- Greenfield: do not call `annotate_story` — there is nothing to annotate yet
+- Do not propose implementation steps — this skill ends at story creation
+- Every AC must be verifiable by a test — reject vague ACs ("should work", "handles errors") and rewrite them before proceeding
+- `## Won't Do` is mandatory in the story — at minimum one item
+- Brownfield: `generate_change_proposal` creates `openspec/changes/$FEATURE_SLUG/proposal.md`
+  on disk. Inform the user at session end:
+  "A proposal file was created at `openspec/changes/$FEATURE_SLUG/proposal.md`.
+  Delete it if this idea is not pursued."

package/examples/mistral-vibe/skills/spec-gen-debug/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: spec-gen-debug
+description: Debug a problem by anchoring root-cause analysis in spec-gen structural knowledge. Uses orient + search_specs + analyze_impact to form an explicit hypothesis before reading code. Enforces RED/GREEN test verification.
+license: MIT
+compatibility: spec-gen MCP server
+user-invocable: true
+allowed-tools:
+  - ask_followup_question
+  - use_mcp_tool
+  - read_file
+  - write_file
+  - str_replace_based_edit
+  - replace_in_file
+  - run_command
+---
+
+# spec-gen: Debug
+
+## When to use this skill
+
+Trigger this skill when the user reports **a bug or unexpected behaviour** on a codebase
+that has spec-gen analysis available, with phrasings like:
+- "this is broken"
+- "X is not working"
+- "something is wrong with Y"
+- "debug this"
+- explicit command `/spec-gen-debug`
+
+**The rule**: form an explicit hypothesis before reading any code. Do not browse
+files speculatively.
+
+**Prerequisite**: spec-gen analysis must exist (`spec-gen analyze` has been run).
+If `orient` returns `"error": "no cache"` → run `analyze_codebase` first, then retry.
+
+---
+
+## Step 1 — Reproduce
+
+Ask the user for:
+1. **Steps to reproduce** — minimal sequence that triggers the bug
+2. **Expected behaviour** — what should happen
+3. **Observed behaviour** — what actually happens
+4. **`$PROJECT_ROOT`** — project root directory
+
+Do not proceed to Step 2 until all four are known.
+
+If the user cannot reproduce the bug reliably, note it and proceed anyway — but
+flag that the fix may be speculative until reproduction is confirmed.
+
+Capture:
+- `$BUG_DESCRIPTION` — one-line summary of the symptom (e.g. "payment retry does not reset counter after success")
+- `$REPRO_STEPS` — reproduction sequence
+
+---
+
+## Step 2 — Orient
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>orient</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "task": "$BUG_DESCRIPTION",
+    "limit": 7
+  }</arguments>
+</use_mcp_tool>
+```
+
+Extract:
+- **`$CANDIDATE_FUNCTIONS`** — top 3–5 functions structurally related to the symptom
+- **`$DOMAINS_AFFECTED`** — spec domains involved
+- **`$CALL_PATHS`** — call chains relevant to the symptom
+
+---
+
+## Step 3 — Search specs
+
+If `openspec/specs/` exists:
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>search_specs</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "query": "$BUG_DESCRIPTION",
+    "limit": 5
+  }</arguments>
+</use_mcp_tool>
+```
+
+Look for:
+- **Documented constraints** that the buggy behaviour violates
+- **Requirements** that define what "correct" means for `$DOMAINS_AFFECTED`
+- **Known edge cases** documented in the spec that may explain the symptom
+
+If no specs exist, skip this step and note the absence.
+
+---
+
+## Step 4 — Isolate and hypothesize
+
+For the top 2 candidate functions from Step 2, check their structural properties:
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>analyze_impact</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "symbol": "$CANDIDATE_FUNCTION",
+    "depth": 2
+  }</arguments>
+</use_mcp_tool>
+```
+
+If the repro involves a request flow (HTTP request, event, message queue), confirm the call chain before forming the hypothesis:
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>trace_execution_path</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "from": "$ENTRY_POINT",
+    "to": "$CANDIDATE_FUNCTION"
+  }</arguments>
+</use_mcp_tool>
+```
+
+This replaces speculative file browsing — the path is structural fact, not inference. Skip if `$ENTRY_POINT` is unknown or the repro is not request-driven.
+
+Using the call paths, risk scores, spec constraints, and traced path gathered so far,
+**state an explicit hypothesis before reading any code**:
+
+> "Hypothesis: `$FUNCTION` does not reset `$STATE` when `$CONDITION` because
+> it is called from `$CALLER` which does not pass `$PARAMETER`."
+
+The hypothesis must:
+- Name a specific function
+- State a specific mechanism (state not reset, condition not checked, wrong caller, etc.)
+- Be falsifiable by reading the code
+
+**Do not read source files before forming this hypothesis.**
+
+---
+
+## Step 5 — Verify the hypothesis
+
+Read the source of the hypothesised function(s):
+
+```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>
+```
+
+Then read the full function body if needed.
+
+| Result | Action |
+|---|---|
+| Hypothesis confirmed | Proceed to Step 6 |
+| Hypothesis refuted | Return to Step 4 with a revised hypothesis (max 3 iterations before asking the user for more context) |
+| Cause is in a caller, not the function itself | Extend `analyze_impact` one level up, revise hypothesis |
+
+Document the confirmed hypothesis explicitly before writing any fix.
+
+---
+
+## Step 6 — Fix
+
+Apply the **minimal fix** that resolves the confirmed hypothesis.
+
+Do not modify functions outside the scope identified in Steps 2–5 without
+re-running the gate (`orient` + `analyze_impact`) on the new scope.
+
+**Small model constraint**: each edit must touch a contiguous block of at most
+50 lines. Split larger fixes into sequential edits.
+
+Do not refactor, rename, or clean up unrelated code while fixing the bug.
+
+---
+
+## Step 7 — Verify
+
+**RED first (if no existing test covers this case):**
+
+Write a test that reproduces the bug using `$REPRO_STEPS`. Run it. It must fail
+(RED) — confirming the bug is real and the test is meaningful.
+
+**Apply the fix**, then run the test again. It must pass (GREEN).
+
+**Full suite:**
+
+Run the full test suite. If any pre-existing test breaks, fix the regression
+before closing the bug.
+
+| Situation | Action |
+|---|---|
+| New test RED → fix → GREEN, suite green | Proceed to Step 8 |
+| Cannot reproduce in a test | Note it, apply fix, confirm manually, add a note in the story/issue |
+| Suite regression introduced | Fix regression. Do not proceed. |
+
+---
+
+## Step 8 — Drift check
+
+Only if the fix changes a documented behaviour:
+
+```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 |
+|---|---|
+| `gap` on modified function | The spec described expected behaviour that changed — update the spec |
+| `stale` | Fix the stale reference |
+| `uncovered` | Not caused by this fix — note it, propose `spec-gen generate` |
+| No drift | Proceed to Step 9 |
+
+---
+
+## Step 9 — Spec invariant feedback
+
+Every real bug reveals an invariant that was not documented. Capture it so future
+agents benefit from this discovery via `search_specs`.
+
+**9a — Identify the invariant**
+
+State the invariant that was violated, in one sentence:
+
+> "`$FUNCTION` must always `$CONDITION` when `$TRIGGER` — violating this causes
+> `$OBSERVED_SYMPTOM`."
+
+If the bug was caused by a missing guard, a wrong assumption about caller order,
+or an undocumented state constraint — that is the invariant.
+
+**9b — Locate the spec**
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_spec</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "domain": "$DOMAIN_AFFECTED"
+  }</arguments>
+</use_mcp_tool>
+```
+
+**9c — Add the invariant**
+
+Append to the relevant domain spec under a `### Known Invariants` section
+(create it if absent). Wrap the section in `<!-- manual -->` / `<!-- /manual -->`
+markers so `spec-gen generate` preserves it on re-generation:
+
+```markdown
+<!-- manual -->
+### Known Invariants
+
+- `$FUNCTION`: $INVARIANT_STATEMENT
+  — discovered via bug fix on $DATE, root cause: $ROOT_CAUSE_SUMMARY
+<!-- /manual -->
+```
+
+If the domain spec does not exist yet (`uncovered` from Step 8), note the
+invariant in the story/issue instead and flag it for the next `spec-gen generate` run.
+
+**9d — Evaluate cross-cutting scope**
+
+Ask: is this bug an instance of a general failure pattern, or specific to this domain?
+
+| Signal | Cross-cutting antipattern? |
+|---|---|
+| Bug involves an assumption about external state, ordering, or caller contract | Yes |
+| Bug is reproducible in other domains with the same pattern | Yes |
+| Bug is specific to a data invariant in `$DOMAIN` | No — domain spec only |
+
+If cross-cutting, append to `.claude/antipatterns.md` (if absent, create it with the
+header from the [antipatterns template](../../antipatterns-template.md)):
+
+```markdown
+## AP-{NNN} — {pattern name}
+
+- **Class**: {state | concurrency | boundary | assumption | resource | ordering}
+- **Symptom**: {what broke — one sentence}
+- **Rule**: {detection rule — "When X, always verify Y"}
+- **Discovered**: $DATE via $BUG_DESCRIPTION
+```
+
+**9e — Inform the user**
+
+> "Invariant added to `openspec/specs/$DOMAIN/spec.md`."
+
+If an antipattern was added:
+> "Cross-cutting antipattern AP-{NNN} added to `.claude/antipatterns.md`.
+> Future brainstorm and implementation sessions will check this rule."
+
+---
+
+## Absolute constraints
+
+- Do not read source code before forming a hypothesis in Step 4
+- Hypothesis is mandatory — even when the cause seems obvious
+- Do not skip Step 1 (reproduction) — a fix without reproduction is speculation
+- Do not touch functions outside the confirmed scope without re-running the gate
+- Do not run `check_spec_drift` before tests are green
+- Each edit ≤ 50 lines on small models
+- Do not skip Step 9 — every bug fix must produce a documented invariant or an
+  explicit note explaining why no invariant applies