spec-gen-cli 1.2.6 → 1.2.8

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

@@ -0,0 +1,210 @@
+---
+name: spec-gen-execute-refactor
+description: Apply the refactoring plan produced by spec-gen-plan-refactor. Reads .spec-gen/refactor-plan.md and re-reads it before each change to stay on track. Requires a confirmed plan to exist before running.
+license: MIT
+compatibility: spec-gen MCP server
+user-invocable: true
+allowed-tools:
+  - use_mcp_tool
+  - read_file
+  - write_file
+  - str_replace_based_edit
+  - replace_in_file
+  - apply_diff
+  - run_command
+  - spec-gen-plan-refactor
+---
+
+# spec-gen: Execute Refactor
+
+## When to use this skill
+
+Trigger this skill when the user asks to **apply a refactoring plan**, with phrasings like:
+- "apply the refactor plan"
+- "execute the planned refactoring"
+- explicit command `/spec-gen-execute-refactor`
+
+**Prerequisite**: the `spec-gen-plan-refactor` skill must have been run and the plan confirmed.
+The file `.spec-gen/refactor-plan.md` must exist.
+
+---
+
+## Step 1 — Read the plan
+
+Read `.spec-gen/refactor-plan.md` from the project directory.
+
+If the file does not exist, stop immediately:
+> "No refactor plan found at `.spec-gen/refactor-plan.md`. Please run `/spec-gen-plan-refactor` first."
+
+Extract and display a summary:
+- Target function, file, and line range
+- Strategy and risk score
+- Number of changes planned
+- Test command
+- Acceptance criteria
+
+**Ask the user to confirm before proceeding.**
+
+---
+
+## Step 2 — Establish a green baseline
+
+Confirm the test suite is passing using the test command from the plan.
+
+**If tests are already failing, stop and tell the user.** Do not refactor on a red baseline.
+
+If a coverage tool is available, run it on the target file and compare against the coverage baseline in the plan.
+
+**Coverage thresholds:**
+
+| Coverage on files to touch | Recommendation |
+|---|---|
+| ≥ 70% lines | Safe — proceed |
+| 40–69% lines | Caution — write characterisation tests first |
+| < 40% lines | **Stop.** Strongly recommend writing tests first |
+| 0% (no tests) | **Blocked.** Propose a minimal test harness, then restart |
+
+If coverage is below 40%:
+> "Coverage on the target file is X%. Refactoring without test coverage risks introducing silent regressions. Would you like me to suggest test cases based on the function signatures, or do you want to proceed at your own risk?"
+
+Only continue past this point with **explicit user confirmation**.
+
+**Large file warning**: if the target function spans more than 300 lines:
+> "This function is X lines long. Small models (< 13B parameters) may lose code when editing files of this size in a single pass. Recommended approach: apply Change 1 from the plan (smallest extraction) first to reduce the target below 200 lines."
+
+---
+
+## Step 3 — Set the restore point
+
+Verify the working tree is clean:
+
+```bash
+git status            # must show: nothing to commit, working tree clean
+git log --oneline -1  # note this commit hash — your restore point
+```
+
+If there are uncommitted changes, stop and ask the user to commit or stash them first.
+
+Fill in the `Restore point` section of `.spec-gen/refactor-plan.md` with the current commit hash.
+
+---
+
+## Step 4 — Apply changes (one at a time)
+
+**Before each change**, re-read `.spec-gen/refactor-plan.md` to confirm:
+- Which change you are on
+- Exactly what to extract, where to put it, and which call sites to update
+
+### Editing tool rule
+
+Always prefer a targeted edit tool (`replace_in_file`, `str_replace_based_edit`, `apply_diff`) over a full-file rewrite (`write_to_file`). Only use `write_to_file` if the file is under 100 lines. If a change seems to require `write_to_file` on a larger file, stop and split it into smaller targeted edits.
+
+**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 if needed.
+
+### For each change in the plan:
+
+1. **Read the source file** around the lines to extract (do not rely on memory).
+
+2. **Apply the edit**:
+   - Extract or move the identified block
+   - Place it in the target file and target class specified in the plan
+   - If the target file is new, create it with only the extracted code
+   - Update all call sites listed in the plan
+
+3. **Verify the diff** before running tests:
+   ```bash
+   git diff --stat   # only the expected files should appear
+   git diff          # confirm deleted lines are intentional — moved, not lost.
+                     # If deleted lines >> added lines with no new file created,
+                     # code was likely lost — abort immediately.
+   ```
+
+4. **Run the test suite** (command from the plan). If any test fails, restore immediately:
+   ```bash
+   git checkout HEAD -- <file>
+   ```
+   Do **not** accumulate broken state before restoring.
+
+5. **Mark the change as done** in `.spec-gen/refactor-plan.md` by appending `✅` to the change heading, then proceed to the next one.
+
+Repeat until all changes in the plan are marked ✅.
+
+---
+
+## Step 5 — Verify improvement
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>analyze_codebase</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "force": true}</arguments>
+</use_mcp_tool>
+
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_refactor_report</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+```
+
+Check each acceptance criterion from the plan:
+- Priority score dropped below the target
+- Function is no longer in the top-5 list
+- Full test suite passes
+
+If not, investigate and iterate (add a new change to the plan if needed).
+
+Run the full test suite one final time to confirm the refactored state is clean.
+
+---
+
+## Step 6 (optional — requires spec-gen generate to have been run)
+
+> ⚠️ This step proposes irreversible changes (deletions, renames). Do not apply anything without explicit user confirmation at each sub-step.
+
+### 6a — Dead code: orphan functions
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_mapping</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "orphansOnly": true}</arguments>
+</use_mcp_tool>
+```
+
+Present the orphan list (kind `function` or `class` only). For each one, check:
+- Is it exported and potentially consumed by external code?
+- Is it re-exported from an index file?
+- Was it simply missed by the LLM?
+
+**Do not delete anything without the user explicitly approving each function.**
+
+### 6b — Naming alignment: spec vocabulary vs actual names
+
+```xml
+<use_mcp_tool>
+  <server_name>spec-gen</server_name>
+  <tool_name>get_mapping</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+```
+
+Build a table of mismatches and present it before touching any code:
+
+| Current name | Proposed name | File | Confidence |
+|---|---|---|---|
+
+Only renames with `confidence: "llm"` should be proposed automatically. Flag `confidence: "heuristic"` entries for manual verification first.
+
+**Wait for explicit user approval of the full rename table before applying any change. Apply renames one file at a time and run tests after each.**
+
+---
+
+## Absolute constraints
+
+- Always re-read `.spec-gen/refactor-plan.md` before each change
+- Never use `write_to_file` on a file > 100 lines
+- Never accumulate broken state — restore immediately on any test failure
+- Always verify the diff before running tests
+- Never proceed to Step 6 without explicit user request
+- Always flag potentially lost code (deleted lines >> added lines with no new file created)

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

@@ -0,0 +1,245 @@
+---
+name: spec-gen-generate
+description: Reverse-engineer OpenSpec specifications from an existing codebase. Performs "code archaeology" — extracting what code actually does and documenting it as structured OpenSpec specs across all detected domains.
+license: MIT
+version: 1.0.0
+author: Clay Good
+repository: https://github.com/clay-good/spec-gen
+compatibility: spec-gen MCP server
+user-invocable: true
+allowed-tools:
+  - read_file
+  - write_file
+  - list_directory
+  - run_command
+  - use_mcp_tool
+  - spec-gen-analyze-codebase
+  - spec-gen-plan-refactor
+---
+
+# spec-gen: Generate OpenSpec Specifications
+
+## When to use this skill
+
+Trigger this skill when the user asks to **generate specs from an existing codebase**, with phrasings like:
+- "run spec-gen on this codebase"
+- "reverse-engineer the specs"
+- "generate OpenSpec from my code"
+- "document what this code does"
+- explicit command `/spec-gen-generate`
+
+---
+
+## Philosophy
+
+- **Archaeology over Creativity**: document what the code ACTUALLY does, not what you imagine it should do
+- **Evidence-based**: every requirement and scenario must trace back to actual code
+- **OpenSpec-native**: output follows OpenSpec conventions exactly
+
+---
+
+## Phase 1 — Codebase Survey
+
+Understand the project structure before touching any files.
+
+**1. Identify project type** by checking for:
+
+| File | Stack |
+|---|---|
+| `package.json` | Node.js / TypeScript |
+| `pyproject.toml` / `setup.py` | Python |
+| `go.mod` | Go |
+| `Cargo.toml` | Rust |
+| `pom.xml` / `build.gradle` | Java |
+
+**2. Find high-value files** — prioritize:
+- Schema / model files (entities, types, interfaces)
+- Service files (business logic)
+- Route / controller files (API surface)
+- Config files (settings, environment)
+- Entry points (main, index, app)
+
+**3. Identify domains** by looking for:
+- Directory structure (`src/users/`, `src/orders/`, etc.)
+- File naming patterns (`user-service`, `order-controller`)
+- Import clusters (files that import each other heavily)
+
+**4. Detect frameworks** from dependencies and patterns:
+- Web: Express, NestJS, FastAPI, Django, etc.
+- Database: PostgreSQL, MongoDB, etc.
+- Auth: JWT, OAuth, etc.
+
+---
+
+## Phase 2 — Deep Analysis
+
+For each identified domain, analyze the relevant files.
+
+**Extract entities:**
+- What data structures exist?
+- What are their properties and types?
+- How do they relate to each other?
+
+**Extract behaviors:**
+- What operations can be performed?
+- What are the business rules / validations?
+- What side effects occur (emails, payments, etc.)?
+
+**Extract API surface** (if applicable):
+- What endpoints exist?
+- What are the request / response shapes?
+- What authentication is required?
+
+---
+
+## Phase 3 — Generate OpenSpec Specifications
+
+Create the OpenSpec directory structure if it doesn't exist:
+
+```
+openspec/
+├── config.yaml
+└── specs/
+    ├── overview/
+    │   └── spec.md
+    ├── {domain-1}/
+    │   └── spec.md
+    ├── {domain-2}/
+    │   └── spec.md
+    └── architecture/
+        └── spec.md
+```
+
+### Spec file format
+
+Each `spec.md` MUST follow this exact format:
+
+```markdown
+# {Domain} Specification
+
+> Generated by spec-gen on {date}
+> Source files: {list of files analyzed}
+
+## Purpose
+
+{2-3 sentences describing what this domain handles}
+
+## Requirements
+
+### Requirement: {RequirementName}
+
+{The system SHALL/MUST/SHOULD do X...}
+
+Use RFC 2119 keywords:
+- **SHALL/MUST**: Required behavior
+- **SHOULD**: Recommended behavior
+- **MAY**: Optional behavior
+
+#### Scenario: {ScenarioName}
+- **GIVEN** {precondition}
+- **WHEN** {action}
+- **THEN** {expected outcome}
+
+## Technical Notes
+
+- **Implementation**: `{file paths}`
+- **Dependencies**: {related domains/services}
+```
+
+### Critical formatting rules
+
+1. Requirements use RFC 2119 keywords (SHALL, MUST, SHOULD, MAY)
+2. Scenarios use exactly 4 hashtags (`####`)
+3. Scenarios follow Given/When/Then format with **bold** labels
+4. No delta markers (ADDED, MODIFIED, REMOVED) — these are baseline specs
+
+---
+
+## Phase 4 — Update OpenSpec Config
+
+**If `openspec/config.yaml` exists**, preserve all existing content and append:
+
+```yaml
+# Auto-detected by spec-gen
+spec-gen:
+  generatedAt: "{timestamp}"
+  domains:
+    - {domain-1}
+    - {domain-2}
+```
+
+**If it doesn't exist**, create a minimal config:
+
+```yaml
+schema: spec-driven
+context: |
+  {Brief project description based on analysis}
+
+  Tech stack: {detected technologies}
+  Architecture: {detected pattern}
+```
+
+---
+
+## Phase 5 — Drift Detection
+
+When specs already exist and code has changed, check for **spec drift** — divergence between the codebase and its specifications.
+
+**When to check:** before committing code, when reviewing PRs, or when explicitly asked to validate specs.
+
+**Process:**
+
+1. **Identify what changed** — use git to find added, modified, deleted, or renamed source files compared to the base branch. Filter out: test files, generated files, lock files, static assets, CI configs.
+
+2. **Map changes to specs** — for each changed file, determine which spec domain covers it by checking:
+   - `> Source files:` header in each `spec.md`
+   - `**Implementation**:` references in Technical Notes
+   - Directory structure inference (e.g. `src/auth/` → auth domain)
+
+3. **Detect four categories of drift:**
+
+| Category | Meaning |
+|---|---|
+| **Gap** | Code changed but its spec was not updated |
+| **Stale** | Spec references a deleted or renamed file |
+| **Uncovered** | New source file has no matching spec domain |
+| **Orphaned Spec** | Spec declares source files that no longer exist |
+
+4. **Report** each issue with: affected file, domain, and a suggested resolution.
+
+**CLI shorthand:** `spec-gen drift` runs this check. Use `spec-gen drift --install-hook` to add it as a git pre-commit hook.
+
+---
+
+## Output Checklist
+
+Before finishing, verify every item:
+
+- [ ] `openspec/specs/overview/spec.md` exists with system summary
+- [ ] Each domain has `openspec/specs/{domain}/spec.md`
+- [ ] `openspec/specs/architecture/spec.md` describes system structure
+- [ ] All requirements use RFC 2119 keywords
+- [ ] All scenarios use Given/When/Then format
+- [ ] `openspec/config.yaml` is created or updated
+- [ ] No spec drift — run `spec-gen drift` to verify specs match code
+
+---
+
+## Absolute constraints
+
+- **Never invent requirements** — every item must be traceable to actual code
+- Always preserve existing `openspec/config.yaml` content before appending
+- Never use delta markers (ADDED, MODIFIED, REMOVED) in baseline specs
+- Scenarios must use exactly 4 hashtags — never 3 or 5
+- RFC 2119 keywords (SHALL, MUST, SHOULD, MAY) must be uppercase
+
+---
+
+## Suggested next steps after generation
+
+Report what was created, then suggest:
+- `openspec validate --all` — check spec structure
+- `spec-gen drift --install-hook` — catch future drift automatically
+- `openspec list --specs` — see all generated specs
+- Manual review and refinement of generated specs
+- Run `/spec-gen-plan-refactor` to identify refactoring targets now that specs exist