specweave 1.0.593 → 2.0.3

package/plugins/specweave/.lint/skill-lint.test.ts

@@ -89,3 +89,96 @@ name: sw/test
     expect(result.errors).toHaveLength(0);
   });
 });
+
+/**
+ * Repo-surface lint (2.0): scripts/lint-skills.mjs is the guard that keeps the shipped
+ * skill surface honest — no `name:` frontmatter, no model/effort/context pins, short
+ * descriptions, and every `specweave <cmd>` / `sw:<name>` reference resolvable.
+ */
+// @ts-expect-error — zero-dep .mjs linter, no type declarations by design
+import { lintContent, lintRepo, readRegisteredCommands, readShippedSkills } from '../../../scripts/lint-skills.mjs';
+
+const ctx = {
+  commands: new Set(['verify', 'complete', 'task', 'status']),
+  skills: new Set(['do', 'done', 'review']),
+  isSkillFile: true,
+};
+const body = (fm: string, rest = '\n# Body\n') => `---\n${fm}\n---\n${rest}`;
+const rules = (r: { errors: Array<{ rule: string }> }) => r.errors.map((e) => e.rule);
+
+describe('lint-skills: shipped skill surface', () => {
+  it('rejects a `name:` frontmatter key (the directory is the skill name)', () => {
+    const r = lintContent('skills/x/SKILL.md', body('name: sw/x\ndescription: short'), ctx);
+    expect(rules(r)).toContain('forbidden-key');
+    expect(r.errors[0].line).toBe(2);
+  });
+
+  it('rejects model / effort / context pins', () => {
+    const r = lintContent(
+      'skills/x/SKILL.md',
+      body('description: short\nmodel: opus\neffort: xhigh\ncontext: fork'),
+      ctx,
+    );
+    expect(r.errors.filter((e: { rule: string }) => e.rule === 'forbidden-key')).toHaveLength(3);
+  });
+
+  it('rejects a description longer than 200 characters', () => {
+    const r = lintContent('skills/x/SKILL.md', body(`description: ${'x'.repeat(201)}`), ctx);
+    expect(rules(r)).toContain('description-length');
+  });
+
+  it('accepts a description of exactly 200 characters', () => {
+    const r = lintContent('skills/x/SKILL.md', body(`description: ${'x'.repeat(200)}`), ctx);
+    expect(r.errors).toHaveLength(0);
+  });
+
+  it('rejects a `specweave <cmd>` that is not registered in the CLI', () => {
+    const r = lintContent(
+      'skills/x/SKILL.md',
+      body('description: short', '\nRun `specweave metrics` then `specweave verify`.\n'),
+      ctx,
+    );
+    expect(rules(r)).toEqual(['unknown-cli']);
+    expect(r.errors[0].message).toMatch(/specweave metrics/);
+  });
+
+  it('does not flag prose that merely mentions the CLI', () => {
+    const r = lintContent(
+      'skills/x/SKILL.md',
+      body('description: short', '\nThe specweave CLI is optional; specweave commands are documented.\n'),
+      ctx,
+    );
+    expect(r.errors).toHaveLength(0);
+  });
+
+  it('rejects an `sw:<name>` with no skill directory', () => {
+    const r = lintContent(
+      'skills/x/SKILL.md',
+      body('description: short', '\nHand off to `sw:grill`, then `sw:done`.\n'),
+      ctx,
+    );
+    expect(rules(r)).toEqual(['unknown-skill']);
+    expect(r.errors[0].message).toMatch(/sw:grill/);
+  });
+
+  it('reads the real CLI command registry and the real skill list', () => {
+    const commands = readRegisteredCommands();
+    expect(commands.has('verify')).toBe(true);
+    expect(commands.has('complete')).toBe(true);
+    expect(commands.has('metrics')).toBe(false);
+
+    const skills = readShippedSkills();
+    for (const core of ['increment', 'do', 'done', 'review', 'team', 'handoff', 'sync', 'auto', 'brainstorm', 'qa']) {
+      expect(skills.has(core), `core skill ${core} missing`).toBe(true);
+    }
+  });
+
+  it('the shipped tree passes the linter', () => {
+    const report = lintRepo();
+    const failures = report.results
+      .flatMap((r: { file: string; errors: Array<{ line: number; message: string }> }) =>
+        r.errors.map((e) => `${r.file}:${e.line} ${e.message}`),
+      );
+    expect(failures).toEqual([]);
+  });
+});

package/plugins/specweave/PLUGIN.md

@@ -1,120 +1,55 @@
-# SpecWeave Core
+# SpecWeave plugin (`sw`)
 
-**Version**: 1.0.227
-**Author**: SpecWeave Contributors
-**License**: MIT
+The Claude Code surface for SpecWeave: **10 skills, 4 hooks, 1 closer agent**.
+Everything deterministic lives in the `specweave` CLI; a skill exists only where a
+procedure needs model judgement. There is no `commands/` namespace in 2.0.
 
-## Description
+## Skills
 
-SpecWeave framework core plugin. Provides increment planning (PM, Architect, Tech Lead agents), specification generation, TDD workflow, living docs sync, and brownfield support. Essential for all SpecWeave projects.
+| Skill | What it does |
+|---|---|
+| `sw:increment` | Plan a unit of work → `spec.md` (Problem, Scope, ACs, Approach) + `tasks.md` |
+| `sw:do` | Work the increment task by task through the ledger, with evidence per task |
+| `sw:done` | Close it: ledger check → `specweave verify` → optional review → `specweave complete` |
+| `sw:review` | Adversarial fresh-context review; every finding cites `path:line` |
+| `sw:team` | Several agents on one increment: a worktree each, claims through the ledger |
+| `sw:handoff` | Portable, secret-scrubbed handoff doc so the work continues in any tool |
+| `sw:sync` | GitHub / Jira / ADO: push, pull, status, setup |
+| `sw:auto` | Unattended loop driven by the Stop hook |
+| `sw:brainstorm` | Expand the option space before committing to one |
+| `sw:qa` | Risk-scored quality assessment (`specweave qa`) |
 
-## Skills
+Optional procedures (tdd-cycle, e2e, debug, diagrams, release-expert) are **not** in the
+plugin — they ship from `skills-optional/` via
+`npx vskill install anton-abyzov/specweave/skills-optional/<name>`.
 
-| Skill | Description |
-|-------|-------------|
-| pm | Product Manager for spec-driven development with user stories, acceptance criteria, and MVP planning |
-| architect | System architect for scalable, maintainable technical designs and ADRs |
-| roadmap-planner | Product roadmap and feature prioritization with RICE, MoSCoW, and Kano frameworks |
-| code-simplifier | Code refinement agent that simplifies and improves code clarity |
-| performance | Performance engineering for web apps, databases, and distributed systems |
-| security | Security engineer for vulnerability assessment and secure code review |
-| security-patterns | Real-time security pattern detector for dangerous code patterns |
-| compliance-architecture | Enterprise compliance architecture for SOC 2, HIPAA, GDPR, PCI-DSS |
-| serverless-recommender | Serverless platform selection expert for AWS Lambda, Azure Functions, etc. |
-| service-connect | Smart external service connection orchestrator (MCP, REST, SDK, CLI) |
-| external-sync-wizard | Guide for bidirectional sync with GitHub, JIRA, Azure DevOps |
-| update-instructions | Smart merge for CLAUDE.md and AGENTS.md instruction files |
-| translator | LLM-native translation skill for SpecWeave content |
-| framework | Expert on SpecWeave framework structure, rules, and conventions |
-| detector | Detects SpecWeave context and provides workflow documentation |
-| progress-sync | Progress synchronization for multi-system sync |
-| grill | Critical code review before increment completion |
-| self-validating-example | Example skill demonstrating self-validating REST API generation |
-| lsp | Language Server Protocol support for code navigation |
-| brainstorm | Multi-perspective ideation with cognitive lenses, persistent idea trees, and sw:increment handoff |
-| code-reviewer | Elite multi-agent code review with parallel specialized reviewers for logic, security, performance, silent failures, type design, and spec compliance |
+## Hooks
 
-## Commands
+Four, all exec-form `node hooks/run.mjs <event>` (no shell, Windows-safe):
 
-| Command | Description |
-|---------|-------------|
-| sw:increment | Plan new Product Increment with spec.md, plan.md, tasks.md |
-| sw:do | Execute increment implementation following spec and plan |
-| sw:progress | Show detailed progress for active increments |
-| sw:done | Close increment with PM validation (3-gate quality check) |
-| sw:auto | Start autonomous execution with stop hook feedback loop |
-| sw:auto-status | Show current auto session status and progress |
-| sw:cancel-auto | Emergency cancel of running auto session |
-| sw:auto-parallel | Enable parallel agent execution for multi-domain features |
-| sw:save | Smart save with auto-generated commits and git handling |
-| sw:validate | Validate increment with rule-based checks and AI assessment |
-| sw:qa | Run quality assessment with risk scoring and gate decisions |
-| sw:judge-llm | Ultrathink LLM-as-Judge validation of completed work |
-| sw:status | Show increment status overview (active, backlog, paused, etc.) |
-| sw:next | Smart increment transition - auto-close and suggest next work |
-| sw:pause | Pause an active increment |
-| sw:resume | Resume a paused or backlog increment |
-| sw:abandon | Abandon an incomplete increment |
-| sw:archive | Manually archive completed increments |
-| sw:restore | Restore archived increments back to active |
-| sw:reopen | Reopen a completed increment for additional work |
-| sw:backlog | Move an increment to backlog |
-| sw:plan | Generate plan.md and tasks.md using Architect Agent |
-| sw:increment-quality-judge-v2 | AI-powered quality assessment with BMAD risk scoring |
-| sw:tdd-cycle | Execute comprehensive TDD workflow with strict discipline |
-| sw:tdd-red | Write comprehensive failing tests (TDD red phase) |
-| sw:tdd-green | Implement minimal code to make tests pass (TDD green phase) |
-| sw:tdd-refactor | Refactor code with comprehensive test safety net |
-| sw:sync-docs | Strategic documentation sync (review or export) |
-| sw:sync-progress | Comprehensive progress sync to all systems |
-| sw:sync-status | Detect and fix status desyncs |
-| sw:living-docs | Launch Living Docs Builder independently |
-| sw:import-external | Auto-import external work items (GitHub/JIRA/ADO) |
-| sw:discrepancies | View and manage code-to-spec discrepancies |
-| sw:discrepancy-to-increment | Convert discrepancies into new increment |
-| sw:fix-duplicates | Detect and resolve duplicate increments |
-| sw:reconcile | Reconcile increment ID collisions after merge |
-| sw:reflect | Analyze session and extract learnings to CLAUDE.md |
-| sw:reflect-on | Enable automatic reflection on session end |
-| sw:reflect-off | Disable automatic reflection |
-| sw:reflect-status | Show reflection configuration and statistics |
-| sw:reflect-check | Diagnostic tool for reflection system health |
-| sw:reflect-clear | Clear specific learnings from Skill Memories |
-| sw:code-reviewer | Elite multi-agent code review system |
-| sw:code-standards-analyzer | Generate coding standards from codebase patterns |
-| sw:grill | Comprehensive implementation auditor |
-| sw:feature-dev | Feature Development Workflow (7-phase structured approach) |
-| sw:role-orchestrator | Multi-agent orchestration for complex tasks |
-| sw:docs-writer | Technical documentation writer |
-| sw:translate | Translate SpecWeave project content |
-| sw:skill | Create and validate Claude Code skills |
-| sw:npm | Full patch release with npm publish |
-| sw-media:image | AI image generation (Google Imagen 4 / Pollinations.ai) |
-| sw-media:video | AI video generation (Google Veo 3.1 / Pollinations.ai) |
-| sw-media:remotion | Programmatic video from React with Remotion |
-| sw:analytics | Show usage analytics dashboard |
+| Hook | Job |
+|---|---|
+| `SessionStart` | Inject the active increment + next task as context |
+| `PreToolUse` (Write\|Edit) | Guard writes under `.specweave/increments/` |
+| `Stop` | Drive the `sw:auto` loop; `{}` for every ordinary session |
+| `PreCompact` | Write a handoff doc before context is compacted |
 
-## Subagents
+## Agents
 
-SpecWeave uses specialized subagents for different phases of the increment workflow. These run in isolated contexts to keep the main agent's context clean.
+| Agent | Purpose |
+|---|---|
+| `sw:sw-closer` | Runs closure in a fresh context after implementation finishes |
 
-| Subagent | Purpose | When to Use |
-|----------|---------|-------------|
-| `sw:sw-closer` | Runs full `sw:done` closure pipeline in fresh context | After team-lead/team-merge completes, prevents context overflow |
-| `sw:sw-pm` | Writes spec.md with user stories and acceptance criteria | During `sw:increment` planning phase |
-| `sw:sw-architect` | Writes plan.md with architecture decisions | During `sw:increment` planning phase |
-| `sw:sw-planner` | Writes tasks.md with BDD test plans | During `sw:increment` planning phase |
+Team lane templates live in `skills/team/agents/` and are loaded by `specweave team`.
+
+## Requirements
 
-Agent definitions live in `plugins/specweave/agents/`.
+- Claude Code 2.1.0+, Node.js 18+, Git
+- The `specweave` CLI on PATH (`npm i -g specweave`). Skills degrade to documented
+  manual steps when it is absent; they never silently no-op.
 
-## Installation
+## Install
 
 ```bash
-vskill add specweave --plugin sw
+claude plugin install sw@specweave     # or: specweave refresh-plugins
 ```
-
-## Requirements
-
-- Claude Code 2.1.0+
-- Node.js 18+ (for CLI tools)
-- Git (for version control integration)

package/plugins/specweave/agents/sw-closer.md

@@ -1,41 +1,32 @@
 ---
 name: sw-closer
-description: Increment closer that runs the full sw:done closure pipeline (code-review, simplify, grill, judge-llm, PM validation, sync) in a fresh context. Use when closing increments after task completion to avoid context overflow.
+description: Closes a SpecWeave increment in a fresh context - ledger check, verify, optional review, complete. Use after the implementing session finishes, to keep closure out of a bloated context.
 model: opus
 memory: project
 skills:
   - sw:done
-  - sw:code-reviewer
 ---
 
 # Increment Closer Subagent
 
-You are an Increment Closer. Your sole job is to close a SpecWeave increment by running the full `sw:done` pipeline. You run in a fresh context specifically to avoid the context overflow that occurs when closure runs inside a bloated implementation session.
+You close one SpecWeave increment and report back. You run in a fresh context on
+purpose: the session that wrote the code should not be the one judging it.
 
-Your prompt will contain: increment ID and increment path.
-
-The `sw:done` skill is preloaded with the full closure pipeline including quality gates (grill, judge-llm, PM validation) and post-closure hooks. Follow its instructions for the complete closure workflow.
+Your prompt contains the increment id (and optionally its path).
 
 ## Workflow
 
-1. Read the increment's `metadata.json` to verify status
-2. If status is `planned`, set it to `active` first (agents may have left it in planned state)
-3. Follow the preloaded `sw:done` skill instructions for the full closure pipeline
-4. Report your result back to the caller
-
-## Retry Awareness
-
-If `sw:done` fails on Gate 0 (desync, missing ACs, task count mismatch), attempt these auto-fixes before retrying:
-
-1. Run `specweave sync-acs <id>` to sync AC status between spec.md and tasks.md
-2. Verify task count in tasks.md frontmatter matches actual checked tasks
-3. If code-review, grill, or judge-llm produced output but did not persist the report file, write the report from the output
-
-Retry `sw:done` once after fixes. If the second attempt fails, report the failure with specific gate details — do not loop.
+1. `specweave task list <id>` — every task must be `done` or `skipped`. Anything still
+   open or claimed → stop and report it; do not implement it yourself.
+2. `specweave verify <id>` — writes `reports/verify.json`. Red → report the failure, do not close.
+3. Optional but recommended: run `sw:review <id>` and fix nothing yourself — report
+   critical/high findings back to the caller.
+4. `specweave complete <id> --yes`. It refuses without a green `verify.json` unless the
+   caller supplied a `--reason`; never edit `metadata.json` by hand.
+5. Report: verify result, review verdict (or "skipped"), commit sha(s), what was deferred.
 
-## Critical Reminders
+## Rules
 
-- Do NOT re-implement tasks or modify source code — only fix closure metadata issues
-- The `specweave complete <id> --yes` CLI command is the ONLY path to set status=completed
-- If grill finds BLOCKERs or CRITICALs (shipReadiness: NOT READY), report failure — do NOT force closure
-- Always report your final result: SUCCESS with closure summary, or FAILURE with the specific gate that failed and why
+- Never mark tasks done, never write code, never re-run the implementation.
+- If `metadata.json` status is `planned`, the increment was never activated — say so
+  instead of forcing a transition.

package/plugins/specweave/defaults/rubric-defaults.md

@@ -33,25 +33,25 @@ status: defaults
 
 ### R-D02: No critical or high code review findings [blocking]
 - **Source**: project-default
-- **Evaluator**: sw:code-reviewer
-- **Verify**: code-review-report.json summary
-- **Threshold**: critical === 0 AND high === 0 AND medium === 0
+- **Evaluator**: sw:review
+- **Verify**: review.json findings
+- **Threshold**: critical === 0 AND high === 0
 - **Result**: [ ] PENDING
 
 ---
 
 ## Independent Evaluation
 
-### R-D03: Grill ship readiness verified [blocking]
+### R-D03: Review verdict is ship [blocking]
 - **Source**: project-default
-- **Evaluator**: sw:grill
-- **Verify**: grill-report.json shipReadiness
-- **Threshold**: shipReadiness !== "NOT READY"
+- **Evaluator**: sw:review
+- **Verify**: review.json ok
+- **Threshold**: ok !== false
 - **Result**: [ ] PENDING
 
-### R-D04: LLM judge verdict acceptable [blocking]
+### R-D04: Independent reviewer was a fresh context [advisory]
 - **Source**: project-default
-- **Evaluator**: sw:judge-llm
-- **Verify**: judge-llm-report.json verdict
-- **Threshold**: verdict !== "REJECTED"
+- **Evaluator**: manual
+- **Verify**: review.md "Reviewer context" line
+- **Threshold**: subagent or new session (never the authoring session)
 - **Result**: [ ] PENDING

package/plugins/specweave/hooks/hooks.json

@@ -1,99 +1,47 @@
 {
+  "description": "SpecWeave hooks: portable command strings and bounded worker execution.",
   "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Write|Edit",
-        "matcher_content": "\"file_path\"\\s*:\\s*\"[^\"]*\\.specweave/increments/",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash -c 'command -v specweave &>/dev/null && specweave hook pre-tool-use || { cat >/dev/null; echo \"{\\\"continue\\\":true}\"; }'"
-          }
-        ]
-      },
-      {
-        "matcher": "TeamCreate",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash -c 'command -v specweave &>/dev/null && specweave hook pre-tool-use || { cat >/dev/null; echo \"{\\\"continue\\\":true}\"; }'"
-          }
-        ]
-      }
-    ],
     "SessionStart": [
       {
         "hooks": [
           {
             "type": "command",
-            "command": "bash -c 'command -v specweave &>/dev/null && specweave hook session-start || { cat >/dev/null; echo \"{\\\"continue\\\":true}\"; }'"
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash -c 'command -v specweave &>/dev/null && specweave hook user-prompt-submit || { cat >/dev/null; echo \"{\\\"decision\\\":\\\"approve\\\"}\"; }'"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs\" session-start",
+            "timeout": 10
           }
         ]
       }
     ],
-    "PreCompact": [
+    "PreToolUse": [
       {
+        "matcher": "Write|Edit",
         "hooks": [
           {
             "type": "command",
-            "command": "bash -c 'command -v specweave &>/dev/null && specweave hook pre-compact || { cat >/dev/null; echo \"{\\\"continue\\\":true}\"; }'"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs\" pre-tool-use",
+            "timeout": 10
           }
         ]
       }
     ],
-    "PostToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "matcher_content": "\"file_path\"\\s*:\\s*\"[^\"]*\\.specweave/increments/",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash -c 'command -v specweave &>/dev/null && specweave hook post-tool-use || { cat >/dev/null; echo \"{\\\"continue\\\":true}\"; }'"
-          }
-        ]
-      },
+    "Stop": [
       {
-        "matcher": "Skill|Task",
         "hooks": [
           {
             "type": "command",
-            "command": "bash -c 'command -v specweave &>/dev/null && specweave hook post-tool-use-analytics || { cat >/dev/null; echo \"{\\\"continue\\\":true}\"; }'"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs\" stop",
+            "timeout": 30
           }
         ]
       }
     ],
-    "Stop": [
+    "PreCompact": [
       {
         "hooks": [
           {
             "type": "command",
-            "command": "bash -c 'command -v specweave &>/dev/null && specweave hook stop-reflect || { cat >/dev/null; echo \"{\\\"decision\\\":\\\"approve\\\"}\"; }'",
-            "timeout": 15000
-          },
-          {
-            "type": "command",
-            "command": "bash -c 'command -v specweave &>/dev/null && specweave hook stop-auto || { cat >/dev/null; echo \"{\\\"decision\\\":\\\"approve\\\"}\"; }'",
-            "timeout": 15000
-          },
-          {
-            "type": "command",
-            "command": "bash -c 'command -v specweave &>/dev/null && specweave hook stop-sync || { cat >/dev/null; echo \"{\\\"decision\\\":\\\"approve\\\"}\"; }'",
-            "timeout": 15000
-          },
-          {
-            "type": "command",
-            "command": "bash -c 'command -v specweave &>/dev/null && specweave hook stop || { cat >/dev/null; echo \"{\\\"decision\\\":\\\"approve\\\"}\"; }'",
-            "timeout": 15000
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs\" pre-compact",
+            "timeout": 10
           }
         ]
       }