specweave 1.0.593 → 2.0.3

package/plugins/specweave/skills/skill-gen/SKILL.md

@@ -1,186 +0,0 @@
----
-description: "Generate project-specific skills from detected patterns in living docs. Use when saying 'skill-gen', 'generate skills', 'create project skills', 'codify patterns', 'skill generation', 'project-specific skills', or 'detected patterns'. Also use when the user responds to a skill suggestion printed during increment closure."
-version: 1.0.0
-argument-hint: "[--refresh]"
-context: fork
-model: opus
----
-
-# sw:skill-gen — Project-Specific Skill Generation
-
-## Model Selection
-
-This skill does not call an LLM directly — it delegates to Anthropic's `skill-creator` plugin, which runs inside the current Claude Code session and inherits its model. Skill generation is a structured-output task where description wording drives auto-activation for every future invocation, so quality matters more than cost.
-
-- **Default (recommended)**: run the session on the newest Opus. If you are in Claude Code, switch with `/model opus` before starting. The frontmatter above declares `model: opus` so nested invocations prefer it when supported. "Newest Opus" is forward-compatible: today that is Opus 4.7, and the recommendation follows whichever Opus is current.
-- **BYO path (GPT-5, Gemini 3, OpenRouter, LM Studio, Ollama)**: start `npx anymodel proxy --model <model> --port <port>` in a separate shell, then `export ANTHROPIC_BASE_URL=http://localhost:<port>` before launching Claude Code. This only affects downstream tools that honor `ANTHROPIC_BASE_URL` — Claude Code's own chat model is controlled via `/model`.
-- **Rationale & registry**: see ADR `0676-01-skill-gen-model-selection.md`. The authoritative model registry lives in `vskill-platform` (`src/lib/eval/model-registry.ts`); update it there when a newer Opus ships.
-
-## Project Overrides
-
-**Skill Memories**: If `.specweave/skill-memories/skill-gen.md` exists, read and apply its learnings.
-
-Generate project-local skills from recurring patterns detected across increment closures.
-
-## Overview
-
-This skill reads `.specweave/state/skill-signals.json`, displays qualifying patterns (observed in 3+ increments), and generates SKILL.md files in `.claude/skills/` using Anthropic's official skill-creator plugin.
-
-**Key principle**: Skills are generated on-demand only. The signal detection and suggestion system runs passively — this skill is where the user actively decides what to codify.
-
-## Workflow
-
-### Step 1: Load Signals
-
-```bash
-SIGNALS_FILE=".specweave/state/skill-signals.json"
-if [ ! -f "$SIGNALS_FILE" ]; then
-  echo "No signals detected yet. Run a few increments with living docs enabled, then try again."
-  exit 0
-fi
-```
-
-Read `skill-signals.json` and load config for `minSignalCount` (default: 3).
-
-### Step 2: Display Qualifying Patterns
-
-Filter signals where `incrementIds.length >= minSignalCount`. Display ALL qualifying patterns regardless of `declined` status (the user may reconsider).
-
-For each qualifying signal, show:
-- Pattern name and category
-- Number of increments where observed
-- Confidence score
-- Evidence (file paths)
-- Status: `[suggested]`, `[declined]`, `[generated]`, or `[new]`
-
-**If no signals qualify**: Print "No qualifying patterns found. Patterns need to be observed in at least {minSignalCount} increments."
-
-### Step 3: User Selects Pattern
-
-Wait for the user to select a pattern by name or number. The user responds in natural language.
-
-### Step 4: Check Skill-Creator Plugin
-
-Verify Anthropic's official skill-creator is available (local-first, then global fallback):
-
-```bash
-# Check local project copy first (auto-installed by specweave init)
-SKILL_CREATOR_PATH=".claude/skills/skill-creator/SKILL.md"
-if [ ! -f "$SKILL_CREATOR_PATH" ]; then
-  # Fall back to global plugin cache
-  SKILL_CREATOR_PATH=$(find ~/.claude/plugins/cache/claude-plugins-official/skill-creator -name "SKILL.md" -maxdepth 3 2>/dev/null | head -1)
-fi
-if [ -z "$SKILL_CREATOR_PATH" ]; then
-  echo "ERROR: Anthropic's skill-creator plugin is not installed."
-  echo "Install it via: claude install-skill https://github.com/anthropics/claude-code/tree/main/skill-creator"
-  echo ""
-  echo "The skill-creator is required to build tested, benchmarked skills."
-  exit 1
-fi
-```
-
-### Step 5: Delegate to Skill-Creator
-
-**Slug dedup guard** — before delegating, check if a skill with this slug already exists:
-
-```bash
-SKILL_SLUG="$SELECTED_PATTERN_SLUG"   # e.g. "error-handling"
-SKILL_DIR=".claude/skills/$SKILL_SLUG"
-if [ -d "$SKILL_DIR" ] && [ -f "$SKILL_DIR/SKILL.md" ]; then
-  echo "Skill '$SKILL_SLUG' already exists at $SKILL_DIR/SKILL.md -- skipping generation."
-  # Mark signal as generated in skill-signals.json and continue to next pattern
-  exit 0
-fi
-```
-
-Invoke the skill-creator with the selected pattern context:
-
-1. **Provide context** to skill-creator:
-   - Skill name: derive from pattern slug (e.g., `project-error-handling`)
-   - Description: based on the signal's description and evidence
-   - Purpose: codify the detected project convention
-   - Evidence files: provide the file paths from signal evidence for the creator to read
-
-2. **Skill-creator workflow** handles:
-   - Writing SKILL.md with proper frontmatter
-   - Creating evals/evals.json with test cases
-   - Running with-skill vs without-skill benchmarks
-   - Description optimization via run_loop.py
-
-3. **Output location**: `.claude/skills/{pattern-slug}/SKILL.md` (project-local)
-
-### Step 6: Update Signal State
-
-After successful generation:
-
-```typescript
-signal.generated = true;
-// Save updated store
-```
-
-### Step 7: Summary
-
-Print:
-```
-Generated project skill: .claude/skills/{pattern-slug}/SKILL.md
-
-This skill will be active in future conversations for this project.
-To test: start a new conversation and try a task related to {pattern-name}.
-To remove: delete .claude/skills/{pattern-slug}/
-```
-
-## Options
-
-| Flag | Description |
-|------|-------------|
-| `--refresh` | Re-check all existing `.claude/skills/` against current living docs for drift |
-
-### --refresh Mode
-
-When `--refresh` is passed:
-1. Read all `.claude/skills/*.md` files
-2. Compare each against current living docs analysis
-3. Report which skills may be stale
-4. Offer to regenerate stale skills
-
-## Configuration
-
-Controlled via `.specweave/config.json`:
-
-```json
-{
-  "skillGen": {
-    "detection": "on-close",
-    "suggest": true,
-    "minSignalCount": 3,
-    "declinedSuggestions": [],
-    "maxSignals": 100
-  }
-}
-```
-
-| Field | Default | Description |
-|-------|---------|-------------|
-| `detection` | `"on-close"` | When to detect patterns: `"on-close"` or `"off"` |
-| `suggest` | `true` | Print suggestions on increment closure |
-| `minSignalCount` | `3` | Minimum increments for a pattern to qualify |
-| `declinedSuggestions` | `[]` | Pattern IDs permanently excluded from suggestions |
-| `maxSignals` | `100` | Maximum signals to retain |
-
-## Error Handling
-
-- **No signals file**: Inform user to run increments with living docs
-- **No skill-creator**: Print installation instructions
-- **Generation failure**: Catch, log, and offer manual SKILL.md creation as fallback
-
-## When This Skill Activates
-
-This skill activates when the user:
-- Says "skill-gen", "generate skills", "create project skills"
-- Says "codify patterns", "skill generation", "detected patterns"
-- Responds to a suggestion printed during increment closure
-- Runs `sw:skill-gen` explicitly
-
-## Resources
-
-- [Official Documentation](https://verified-skill.com/docs/skills/extensible/skill-generation)

package/plugins/specweave/skills/skill-gen/evals/evals.json

@@ -1,79 +0,0 @@
-{
-  "skill_name": "sw:skill-gen",
-  "evals": [
-    {
-      "id": 1,
-      "name": "display-qualifying-patterns",
-      "prompt": "Run sw:skill-gen. The project has a skill-signals.json with 3 signals: 'error-handling' (4 increments, confidence 0.8), 'api-patterns' (3 increments, confidence 0.6), and 'naming-conventions' (1 increment, confidence 0.33). MinSignalCount is 3.",
-      "expected_output": "Display the 2 qualifying patterns (error-handling and api-patterns) with their details. Do not display naming-conventions (below threshold).",
-      "assertions": [
-        {
-          "id": "a1",
-          "text": "Reads .specweave/state/skill-signals.json to load current signals",
-          "type": "boolean"
-        },
-        {
-          "id": "a2",
-          "text": "Displays error-handling pattern with 4 increments and confidence 0.8",
-          "type": "boolean"
-        },
-        {
-          "id": "a3",
-          "text": "Displays api-patterns with 3 increments and confidence 0.6",
-          "type": "boolean"
-        },
-        {
-          "id": "a4",
-          "text": "Does NOT display naming-conventions (only 1 increment, below minSignalCount of 3)",
-          "type": "boolean"
-        }
-      ]
-    },
-    {
-      "id": 2,
-      "name": "no-signals-available",
-      "prompt": "Run sw:skill-gen. The project has a skill-signals.json with 2 signals, both with only 1 increment ID each. MinSignalCount is 3.",
-      "expected_output": "Inform the user that no qualifying patterns were found and explain the minimum threshold.",
-      "assertions": [
-        {
-          "id": "a1",
-          "text": "Reads .specweave/state/skill-signals.json",
-          "type": "boolean"
-        },
-        {
-          "id": "a2",
-          "text": "Outputs a message indicating no qualifying patterns were found",
-          "type": "boolean"
-        },
-        {
-          "id": "a3",
-          "text": "Does NOT attempt to invoke skill-creator or generate any SKILL.md files",
-          "type": "boolean"
-        }
-      ]
-    },
-    {
-      "id": 3,
-      "name": "missing-signals-file",
-      "prompt": "Run sw:skill-gen. The project does not have a .specweave/state/skill-signals.json file.",
-      "expected_output": "Inform the user that no signals have been detected yet and suggest running increments with living docs enabled.",
-      "assertions": [
-        {
-          "id": "a1",
-          "text": "Checks for .specweave/state/skill-signals.json existence",
-          "type": "boolean"
-        },
-        {
-          "id": "a2",
-          "text": "Outputs a message indicating no signals detected yet",
-          "type": "boolean"
-        },
-        {
-          "id": "a3",
-          "text": "Mentions running increments with living docs as the way to generate signals",
-          "type": "boolean"
-        }
-      ]
-    }
-  ]
-}

package/plugins/specweave/skills/skill-refine/SKILL.md

@@ -1,97 +0,0 @@
----
-description: "Refine an existing skill's SKILL.md against accumulated gate-failure signals. Use when saying 'sw:skill-refine', 'refine skill', 'improve skill', 'skill refinement', or responding to a session-end nudge suggesting refinement. One skill per invocation; user approval required; never runs during an active /sw:do or /sw:done session (ADR-0671-01)."
-version: 1.0.0
-argument-hint: "<skill-slug> [--dry-run] [--show-signals] [--scope project|user] [--last-n N]"
-allowed-tools: Read, Bash
-context: fork
-model: opus
----
-
-# sw:skill-refine — Targeted Skill Refinement Loop
-
-Propose and apply minimal, auditable edits to an existing `SKILL.md` using evidence collected by the closure gates (`sw:judge-llm`, `rubric`, `sw:code-reviewer`).
-
-**Inputs:** `<skill-slug>` (e.g. `sw:architect`) + refinement signals under `.specweave/state/skill-signals.json`.
-**Output:** a reviewed git commit on the local branch (never pushed) plus a ledger entry at `.specweave/state/skill-refinements.json`.
-
-## Red lines (inherited from ADR-0671-01..04)
-
-1. **No runtime mutation.** This skill refuses to run when `SPECWEAVE_SESSION_ACTIVE` is set or `.specweave/state/active-session.lock` exists. Refinements happen *between* sessions, as an explicit human action.
-2. **No auto-apply.** Every diff requires explicit approve / reject / edit from the human at the terminal. There is no `--yes` flag and none will be added.
-3. **One skill per invocation.** `sw:skill-refine sw:a sw:b` is a usage error. Refinements must stay scoped.
-4. **Never pushes.** `git commit` only — reviewing the commit and pushing stays with the user.
-
-## Usage
-
-```bash
-# Inspect signals without proposing a diff (no LLM call)
-sw:skill-refine sw:architect --show-signals
-
-# Propose a diff, print it, do not write anything
-sw:skill-refine sw:architect --dry-run
-
-# Full interactive flow: aggregate → Haiku diff → approve/reject/edit → commit + ledger
-sw:skill-refine sw:architect
-
-# Refine a user-scoped skill at ~/.claude/skills/<dir>/SKILL.md
-sw:skill-refine my-skill --scope user
-
-# Override default N=5 increment window
-sw:skill-refine sw:architect --last-n 3
-```
-
-## Workflow
-
-1. **Parse flags** — `<skill-slug>` (required), `--dry-run`, `--show-signals`, `--scope project|user`, `--last-n N`. Exactly one skill per invocation.
-2. **Session-lock guard** — refuse if in an active `/sw:do` or `/sw:done` session. See ADR-0671-01.
-3. **Resolve SKILL.md path** — `project` ⇒ `.claude/skills/<slug-dir>/SKILL.md`; `user` ⇒ `~/.claude/skills/<slug-dir>/SKILL.md`. Slug `sw:foo` maps to directory `sw-foo` (flat-dir convention).
-4. **Aggregate signals** — read `.specweave/state/skill-signals.json`, filter to refinements targeting the given skill within the last N increments (default 5). Break down by source + severity.
-5. **`--show-signals` short-circuit** — pretty-print the aggregate and exit; no LLM call.
-6. **Haiku diff proposal** — call `claude-haiku-4-5-20251001` at `temperature=0` with `(current SKILL.md, signal aggregate)`. Return `{ diff, rationale }`. Determinism: repeat runs with identical inputs produce byte-identical output (AC-US2-02).
-7. **`--dry-run` short-circuit** — print diff + rationale; exit. No ledger entry, no commit.
-8. **Interactive approval** — show diff + rationale, prompt `approve / reject / edit`. Edit loops at most 3 times before auto-reject.
-9. **On approve** — `git apply` the patch, `git add -- <SKILL.md>`, `git commit -m "refine(<skill>): <rationale>"`. Record the commit SHA in `.specweave/state/skill-refinements.json` with `status: "applied"`. Never pushes.
-10. **On reject** — write a rejection ledger entry with the user's reason. SKILL.md is untouched.
-
-## Signals
-
-Refinement signals are emitted by the closure gates when a gate failure traces to a specific skill's instructions:
-
-| Source | Emitted when |
-|---|---|
-| `judge-llm` | `judge-llm-report.json` finding cites a skill slug as the root cause |
-| `rubric` | A rubric criterion fails and the rationale traces to a skill-directed behavior |
-| `code-reviewer` | A critical finding is attributable to skill-directed behavior |
-
-Attribution is intentionally high-precision / low-recall — a missing signal is better than a wrongly-blamed skill.
-
-## Files
-
-- `plugins/specweave/skills/skill-refine/SKILL.md` — this file (the user-facing skill definition)
-- `src/skills/skill-refine.ts` — CLI entry point (`runSkillRefine`)
-- `src/core/skill-refine/aggregator.ts` — signal aggregation + breakdown
-- `src/core/skill-refine/haiku-diff.ts` — Haiku-backed diff proposal (temperature 0, deterministic)
-- `src/core/skill-refine/approval.ts` — interactive approve/reject/edit (via `@inquirer/prompts`)
-- `src/core/skill-refine/apply.ts` — write + `git apply` + `git commit` + ledger append
-- `src/core/skill-refine/ledger.ts` — append-only `.specweave/state/skill-refinements.json` writer
-- `src/types/skill-refinements.ts` — ledger types + zod schema
-
-## When this skill activates
-
-- User says `sw:skill-refine`, `refine skill`, `improve skill`, `skill refinement`.
-- User responds to a session-end nudge (see `sw:reflect`) that suggests refining a specific skill.
-
-## ADRs
-
-- [ADR-0671-01](../../../../.specweave/docs/internal/architecture/adr/0671-01-no-runtime-skill-mutation.md) — No runtime mutation of active skills.
-- [ADR-0671-02](../../../../.specweave/docs/internal/architecture/adr/0671-02-registry-version-immutability.md) — Registry version immutability.
-- [ADR-0671-03](../../../../.specweave/docs/internal/architecture/adr/0671-03-no-self-improving-marketing.md) — No "self-improving" marketing.
-- [ADR-0671-04](../../../../.specweave/docs/internal/architecture/adr/0671-04-no-goodhart-loop.md) — No Goodhart loop on gate signals.
-
-## Error handling
-
-- Missing SKILL.md → print the resolved path, exit with `no-diff` status.
-- Zero signals → print "no signals for `<skill>` in the last N increments", exit cleanly.
-- Haiku returns malformed JSON → surface the raw output, abort; the ledger is not touched.
-- `git apply` fails → SKILL.md is restored from the pre-call snapshot, no commit, no ledger entry.
-- `ANTHROPIC_API_KEY` unset → clear error before any prompt or write.

package/plugins/specweave/skills/sync-docs/SKILL.md

@@ -1,72 +0,0 @@
----
-description: Sync living docs for an increment. Generates or updates spec files in .specweave/docs/internal/specs/. Use when saying "sync docs", "update living docs", or "sync-docs".
-version: 1.0.0
-argument-hint: "<increment-id> [--review]"
----
-
-# Sync Living Docs
-
-## Project Overrides
-
-**Skill Memories**: If `.specweave/skill-memories/sync-docs.md` exists, read and apply its learnings.
-
-Sync living documentation for an increment. This generates or updates feature specs and user story files under `.specweave/docs/internal/specs/`.
-
-## Usage
-
-```
-sw:sync-docs <increment-id>           # Sync living docs for increment
-sw:sync-docs <increment-id> --review  # Dry-run: validate sync without modifying files
-```
-
-## Workflow
-
-### Step 1: Resolve Increment
-
-1. Parse the increment ID argument (required)
-2. Find the increment directory: `.specweave/increments/NNNN-*/`
-3. Load `spec.md` and `metadata.json`
-
-### Step 2: Detect Mode
-
-- If `--review` argument present: set `dryRun = true`
-- Otherwise: set `dryRun = false`
-
-### Step 3: Execute Sync
-
-Run the living docs sync via CLI:
-
-```bash
-# Normal mode
-specweave sync-living-docs <increment-id>
-
-# Review mode (dry-run)
-specweave sync-living-docs <increment-id> --dry-run
-
-# If CLI command not available, use sync-progress as fallback:
-specweave sync-progress <increment-id> --no-github --no-jira --no-ado
-```
-
-### Step 4: Report Results
-
-Display a summary:
-
-```
-Living Docs Sync Results:
-- Feature spec: created/updated/unchanged
-- User story files: N created, M updated, K unchanged
-- Total files affected: X
-```
-
-In review mode, prefix with: `[DRY RUN] No files were modified.`
-
-### Step 5: Error Handling
-
-If sync fails:
-- Display the error message
-- Suggest: "Check that spec.md has valid frontmatter and user stories are properly formatted"
-- Suggest: "Run `sw:progress-sync` for full external tool sync"
-
-## Resources
-
-- [Official Documentation](https://verified-skill.com/docs/reference/skills#sync-docs)