spec-gen-cli 1.2.6 → 1.2.8

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

@@ -0,0 +1,274 @@
+---
+name: spec-gen-implement-story
+description: Implement a story on a brownfield codebase using spec-gen structural context. Runs orient + risk check before coding, validates against specs, enforces a test gate before drift check.
+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-execute-refactor
+---
+
+# spec-gen: Implement Story
+
+## When to use this skill
+
+Trigger this skill when the user asks to **implement a story or task** on a codebase that has
+spec-gen analysis available, with phrasings like:
+- "implement story X"
+- "work on task Y"
+- "start implementing this feature"
+- explicit command `/spec-gen-implement-story`
+
+**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 — Read the story and risk context
+
+Read the story file. Extract:
+- `$STORY_TITLE`, `$AC` (acceptance criteria), `$PROJECT_ROOT`
+- `$RISK_CONTEXT` — the `risk_context` section if present (pre-filled by Architect Agent)
+
+| Situation | Approach |
+|---|---|
+| `risk_context` present, risk 🟢 < 40 | Skip to Step 3 — use insertion point from context |
+| `risk_context` present, risk 🟡 40–69 | Run Step 2 impact check, then proceed |
+| `risk_context` present, risk 🔴 ≥ 70 | Stop — a blocking refactor story must be resolved first |
+| `risk_context` absent | Run the full Step 2 orientation |
+
+---
+
+## Step 2 — Orient and assess risk
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>orient</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "task": "$STORY_TITLE",
+    "limit": 7
+  }</arguments>
+</use_mcp_tool>
+```
+
+For the top 2 functions returned, check risk:
+
+```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 any function has `riskScore ≥ 70`: stop.**
+Do not implement. Run `/spec-gen-execute-refactor` on the blocking function first, or create a
+blocking refactor task and return to this story once the risk is resolved.
+
+---
+
+## Step 2.5 — Stack inventory (conditional)
+
+Based on the story title and orient results, call the relevant inventory tool(s) **before reading any source file**. Skip if the story clearly involves none of these areas.
+
+| Story involves | Tool | Purpose |
+|---|---|---|
+| Data models / ORM / database / tables | `get_schema_inventory` | See existing tables and fields — don't re-invent what already exists |
+| HTTP routes / API / endpoints | `get_route_inventory` | See existing routes before adding new ones |
+| Config / env vars / secrets | `get_env_vars` | Identify which vars are required vs have defaults |
+| UI components | `get_ui_components` | See existing component props and framework |
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_schema_inventory</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+Use the results to ground the implementation in existing schemas/routes — the plan cannot contradict what already exists.
+
+---
+
+
+## Step 3 — Check the spec
+
+First, verify that OpenSpec specs exist:
+
+```bash
+ls $PROJECT_ROOT/openspec/specs/ 2>/dev/null | wc -l
+```
+
+**If 0 specs found:**
+> No OpenSpec specs exist yet. `search_specs` will return empty results and
+> `check_spec_drift` (Step 7) will flag everything as uncovered.
+>
+> Recommended: run `/spec-gen-generate` after this story to create a spec baseline.
+> You only need to do this once.
+>
+> Continuing with structural analysis only.
+
+Skip the `search_specs` call 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 any code.
+Note any constraints that apply.
+
+---
+
+## Step 3.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 4 without action.
+
+---
+
+## Step 4 — Find the insertion point
+
+Use `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 challenge
+
+Before writing any code, state explicitly what could break with this approach.
+If `.claude/antipatterns.md` exists, read it and 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 identified in Step 2 / `risk_context` without
+re-running the gate.
+
+**Small model constraint**: if the model is under 13B parameters (Mistral Small, Phi, Gemma…),
+each edit must touch a contiguous block of at most 50 lines. Split larger changes.
+
+---
+
+## Step 6 — Tests
+
+Both levels required before proceeding to Step 7.
+
+**Mandatory — existing tests must not regress:**
+Run the full test suite. If any pre-existing test breaks, fix the regression before continuing.
+
+**Recommended — at least one new test per AC:**
+Write a test that directly exercises the behaviour described in the acceptance criterion.
+
+| 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. |
+
+---
+
+## 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 | Note it — propose `spec-gen generate` post-sprint |
+| `gap` on existing domain | Run `spec-gen generate --domains $DOMAIN` |
+| `stale` | Fix the reference |
+| No drift | Done |
+
+---
+
+## Absolute constraints
+
+- Do not write code before Step 4 confirmation
+- If `riskScore ≥ 70` — stop, do not work around it, run `/spec-gen-execute-refactor` first
+- Do not run `check_spec_drift` before tests are green
+- Do not propose a spec update on untested code

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

@@ -0,0 +1,251 @@
+---
+name: spec-gen-plan-refactor
+description: Identify the highest-priority refactoring target using static analysis, assess its blast radius, and produce a detailed written plan saved to .spec-gen/refactor-plan.md. Makes no code changes.
+license: MIT
+compatibility: spec-gen MCP server
+user-invocable: true
+allowed-tools:
+  - ask_followup_question
+  - use_mcp_tool
+  - read_file
+  - write_file
+  - spec-gen-analyze-codebase
+  - spec-gen-execute-refactor
+---
+
+# spec-gen: Plan Refactor
+
+## When to use this skill
+
+Trigger this skill whenever the user asks to **plan a refactoring** on a codebase, with phrasings like:
+- "plan a refactoring of X"
+- "analyze my code and prepare a refactor plan"
+- "generate a refactoring plan"
+- "I want to refactor this function / this file"
+- explicit command `/spec-gen-plan-refactor`
+
+**This skill modifies no code files.** It only produces `.spec-gen/refactor-plan.md`.
+To apply the plan, use the `spec-gen-execute-refactor` skill.
+
+---
+
+## Step 1 — Confirm the project directory
+
+Ask the user which project to analyze, or confirm the current workspace root.
+
+---
+
+## Step 2 — Run static analysis
+
+Analyze the project via the `spec-gen` MCP server. If a recent analysis already exists, skip unless the user explicitly requests a fresh run.
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>analyze_codebase</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+```
+
+---
+
+## Step 3 — Get the refactoring report
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_refactor_report</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+```
+
+Present the top 5 candidates:
+
+| Function | File | Issues | Priority score |
+|---|---|---|---|
+
+---
+
+## Step 3b — Check for duplicate code
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_duplicate_report</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+```
+
+If a top candidate appears in a clone group, prepend a **deduplication note** to the plan:
+> "⚠️ `<function>` has N near-clones. Consolidate them first to reduce the blast radius of this refactor."
+
+---
+
+## Step 3c — Check test coverage
+
+Detect the coverage tool from the project and run it on the candidate files:
+
+| Ecosystem | Command |
+|---|---|
+| Node.js | `npm test -- --coverage --collectCoverageFrom="<files>"` |
+| Python | `pytest --cov=<module> --cov-report=term-missing` |
+| Rust | `cargo tarpaulin --include-files <files>` |
+| Go | `go test -cover ./...` |
+
+Enrich the candidate table:
+
+| Function | File | Priority | Coverage |
+|---|---|---|---|
+| ... | ... | ... | 72% ✅ / 35% ⚠️ / 0% 🚫 |
+
+**Thresholds:**
+
+| Coverage | Badge | Meaning |
+|---|---|---|
+| ≥ 70% lines | ✅ | Safe to refactor |
+| 40–69% lines | ⚠️ | Write characterisation tests first |
+| < 40% lines | 🛑 | Strongly discouraged |
+| 0% (no tests) | 🚫 | Blocked — propose a test harness first |
+
+If **all candidates are below 40%**:
+> "Every high-priority target has insufficient test coverage (< 40%). I recommend writing a minimal test harness for at least one target before proceeding. Would you like me to suggest test cases based on the function signatures?"
+
+---
+
+## Step 4 — Analyze impact
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>analyze_impact</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "symbol": "$FUNCTION_NAME"}</arguments>
+</use_mcp_tool>
+```
+
+Note: risk score (0–100), recommended strategy (`extract` / `split` / `facade` / `delegate`), top 5 upstream callers and downstream callees.
+
+---
+
+## Step 5 — Visualise the call neighbourhood
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_subgraph</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "functionName": "$FUNCTION_NAME", "direction": "both", "format": "mermaid"}</arguments>
+</use_mcp_tool>
+```
+
+Show the Mermaid diagram to the user.
+
+---
+
+## Step 6 — Find safe entry points (bottom-up)
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_low_risk_refactor_candidates</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "filePattern": "$TARGET_FILE", "limit": 5}</arguments>
+</use_mcp_tool>
+```
+
+Cross-reference with the subgraph from Step 5: a good first extraction candidate already appears as a callee of the target function.
+
+---
+
+## Step 7 — Design the change sequence
+
+Design an ordered sequence of atomic changes based on the strategy from Step 4. Each change must specify:
+
+- **What**: the exact block to move (line range or description)
+- **New name**: the function or method name to give it
+- **Target file**: existing or new file (with justification)
+- **Target class** (if applicable)
+- **Call sites to update**: list each `file:line`
+
+**Rules per strategy:**
+
+| Strategy | Rule |
+|---|---|
+| `split` | Decompose into N sub-functions in the same file unless they clearly belong elsewhere |
+| `extract` | Place in the nearest cohesive module or create a new file if none exists |
+| `facade` | Keep the original signature, delegate to smaller functions; companion module if > 300 lines |
+| `delegate` | Move ownership logic to callers; update every caller file in the upstream chain |
+
+**Present the full sequence and wait for confirmation before writing the plan file.**
+
+---
+
+## Step 8 — Write `.spec-gen/refactor-plan.md`
+
+Fill every section — **leave nothing as "TBD"**.
+
+```markdown
+# Refactor Plan
+
+Generated: <ISO date>
+Workflow: /spec-gen-plan-refactor → /spec-gen-execute-refactor
+
+## Target
+- **Function**: <name>
+- **File**: <relative path>
+- **Lines**: <start>–<end>
+- **Risk score**: <0–100>
+- **Strategy**: <extract | split | facade | delegate>
+- **Priority score before refactor**: <value>
+
+## Why
+- <issue 1>
+- <issue 2>
+
+## Callers (upstream — must not break)
+| Caller | File |
+|---|---|
+
+## Callees (downstream — candidates for extraction)
+| Callee | File |
+|---|---|
+
+## Coverage baseline
+- **File**: <target file>
+- **Coverage**: <X>% lines, <Y>% branches
+- **Status**: ✅ safe / ⚠️ caution / 🛑 discouraged
+- **Test command**: <exact command>
+
+## Change sequence
+Apply in order. Run tests after each step.
+
+### Change 1 — <short label>
+- **What**: extract lines <start>–<end> (logic: <one-line description>)
+- **New function name**: `<name>`
+- **Target file**: `<path>` (<new file | existing file — reason>)
+- **Target class**: `<ClassName>` or none
+- **Call sites to update**: <list each file:line>
+- **Expected diff**: +<N> lines in <target file>, -<M> lines in <source file>
+
+### Change 2 — <short label>
+...
+
+## Acceptance criteria
+- Priority score drops below <target score> in `get_refactor_report`
+- Function exits the top-5 list
+- Full test suite passes (green)
+- `git diff --stat` shows only the expected files
+
+## Restore point
+Hash: <to be filled by the execute workflow>
+```
+
+Once the file is written:
+> "Plan written to `.spec-gen/refactor-plan.md`. Review it, then run `/spec-gen-execute-refactor` to apply the changes."
+
+---
+
+## Absolute constraints
+
+- **No code modifications** in this workflow
+- Always read the source file to confirm exact line numbers
+- Never leave a section empty or as "TBD"
+- Prefer candidates with higher coverage when scores are otherwise close
+- If the user does not pick a target, default to the top candidate

package/examples/openspec-analysis/README.md

@@ -0,0 +1,59 @@
+# Example: OpenSpec CLI Analysis
+
+This directory contains the output of running `spec-gen analyze` against the OpenSpec CLI codebase itself.
+
+## How This Was Generated
+
+```bash
+cd /path/to/OpenSpec-main
+spec-gen init
+spec-gen analyze
+```
+
+## Output Files
+
+| File | Description |
+|------|-------------|
+| `config.json` | spec-gen configuration for the project |
+| `SUMMARY.md` | Human-readable analysis summary |
+| `repo-structure.json` | Complete file metadata and significance scores |
+| `dependency-graph.json` | Import/export relationships between files |
+| `llm-context.json` | Optimized context for LLM generation |
+| `dependencies.mermaid` | Visual dependency graph |
+
+## Key Findings
+
+From analyzing the OpenSpec CLI:
+
+- **221 files analyzed** (TypeScript, Markdown, JSON)
+- **50 high-value files** identified for spec generation
+- **37 domain clusters** detected
+
+### Detected Domains
+
+1. **completions** - Shell completion providers (16 files)
+2. **command-generation** - IDE command generation (26 files)
+3. **artifact-graph** - Artifact dependency resolution (7 files)
+4. **schemas** - Configuration schemas (9 files)
+5. **validation** - Spec validation (3 files)
+6. **commands** - CLI commands (14 files)
+7. **parsers** - Markdown/requirement parsing (3 files)
+
+### Top Significant Files
+
+1. `src/core/completions/types.ts` (score: 65)
+2. `src/core/command-generation/types.ts` (score: 65)
+3. `src/core/artifact-graph/types.ts` (score: 65)
+4. `src/core/config-schema.ts` (score: 65)
+5. `src/core/schemas/change.schema.ts` (score: 60)
+
+## Next Steps
+
+To generate full specifications, run:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+spec-gen generate
+```
+
+This will create OpenSpec-format specifications in `openspec/specs/`.

package/examples/openspec-analysis/SUMMARY.md

@@ -0,0 +1,72 @@
+# Repository Analysis: @fission-ai/openspec
+
+## Overview
+- **Type**: Node.js/TypeScript
+- **Frameworks**: Vitest, GitHub Actions
+- **Files Analyzed**: 221 of 231 (10 skipped)
+- **Analysis Date**: 2026-01-31T15:45:00.646Z
+
+## Architecture Pattern
+This appears to be a **unknown** architecture.
+
+**Detected Layers:**
+- Infrastructure Layer: Configuration, middleware, and utilities (30 files)
+
+## Language Breakdown
+| Language | Files | Percentage |
+|----------|-------|------------|
+| TypeScript | 172 | 78.0% |
+| Markdown | 26 | 12.0% |
+| JSON | 7 | 3.0% |
+|  | 4 | 2.0% |
+| JavaScript | 3 | 1.0% |
+
+## Detected Domains
+These domains will become OpenSpec specifications:
+
+| Domain | Files | Key Entities | Spec Path |
+|--------|-------|--------------|-----------|
+| completions | 16 | CompletionProvider, Factory, BashGenerator | `openspec/specs/completions/spec.md` |
+| command-generation | 26 | Registry, Cursor, Windsurf | `openspec/specs/command-generation/spec.md` |
+| artifact-graph | 7 | Schema, Resolver, InstructionLoader | `openspec/specs/artifact-graph/spec.md` |
+| schemas | 9 | ChangeSchema, BaseSchema, SchemaYaml | `openspec/specs/schemas/spec.md` |
+| validation | 3 | Validator | `openspec/specs/validation/spec.md` |
+| commands | 14 | Schemas, Feedback, Schema | `openspec/specs/commands/spec.md` |
+| parsers | 3 | RequirementBlocks, ChangeParser, MarkdownParser | `openspec/specs/parsers/spec.md` |
+| templates | 2 | SkillTemplates | `openspec/specs/templates/spec.md` |
+| users | 5 | LlmContextJson, SUMMARYMd, DependencyGraphJson | `openspec/specs/users/spec.md` |
+| ui | 2 | AsciiPatterns, WelcomeScreen | `openspec/specs/ui/spec.md` |
+
+## Dependency Insights
+
+**Most Connected Files:**
+- `package.json` (5 connections)
+- `src/commands/feedback.ts` (1 connections)
+- `src/core/init.ts` (1 connections)
+
+**Orphan Files**: 215 file(s) with no imports or exports
+
+## Files Selected for Deep Analysis
+The following files were selected as most significant:
+
+1. `src/core/completions/types.ts` (score: 65) - high-value-name
+2. `src/core/command-generation/types.ts` (score: 65) - high-value-name
+3. `src/core/artifact-graph/types.ts` (score: 65) - high-value-name
+4. `src/core/config-schema.ts` (score: 65) - schema, high-value-name
+5. `src/core/schemas/change.schema.ts` (score: 60) - schema, high-value-name
+6. `src/core/schemas/base.schema.ts` (score: 60) - schema, high-value-name
+7. `src/core/validation/types.ts` (score: 60) - high-value-name
+8. `src/core/artifact-graph/schema.ts` (score: 60) - schema, high-value-name
+9. `src/core/global-config.ts` (score: 60) - config, high-value-name
+10. `src/core/project-config.ts` (score: 60) - config, high-value-name
+11. `src/core/completions/completion-provider.ts` (score: 55) - service
+12. `src/core/config.ts` (score: 55) - config, high-value-name
+13. `src/commands/workflow/schemas.ts` (score: 55) - schema, high-value-name
+14. `src/commands/feedback.ts` (score: 55) - high-value-name
+15. `src/telemetry/config.ts` (score: 55) - config, high-value-name
+
+## Recommendations
+- Review 215 orphan file(s) that may be unused
+
+---
+*Generated by spec-gen v1.0.0*

package/examples/openspec-analysis/config.json

@@ -0,0 +1,16 @@
+{
+  "version": "1.0.0",
+  "projectType": "nodejs",
+  "openspecPath": "./openspec",
+  "analysis": {
+    "maxFiles": 500,
+    "includePatterns": [],
+    "excludePatterns": []
+  },
+  "generation": {
+    "model": "claude-sonnet-4-20250514",
+    "domains": "auto"
+  },
+  "createdAt": "2026-01-31T15:44:29.845Z",
+  "lastRun": null
+}