specweave 1.0.577 → 1.0.578

package/plugins/specweave/skills/code-reviewer/SKILL.md

@@ -1,15 +1,58 @@
 ---
-description: "Elite multi-agent code review system. Spawns parallel specialized reviewers for logic, security, performance, silent failures, type design, spec compliance, comments, and test coverage — then validates findings independently. Use when saying 'review code', 'code review', 'audit code', 'review PR', 'review changes', 'check code quality'."
-argument-hint: "[--pr N] [--changes] [--increment NNNN] [--cross-repo] [path]"
+description: "Multi-agent code review system. Spawns 3 parallel reviewers (security, logic, performance) with inline self-critique. Use when saying 'review code', 'code review', 'audit code', 'review PR', 'review changes', 'check code quality'."
+argument-hint: "[--pr N] [--changes] [--increment NNNN] [--cross-repo] [--full-fanout] [path]"
 context: fork
 model: opus
 ---
 
 # Code Reviewer
 
-**Parallel multi-agent code review with specialized reviewers and independent finding validation.**
+**Parallel multi-agent code review with 3 core reviewers (security, logic, performance) and inline self-critique.**
 
-Spawns up to 8 specialized reviewer agents that analyze code simultaneously, validates each finding independently, then aggregates results into a unified report with deduplication and severity ranking.
+Default path spawns **3 reviewer agents** (security, logic, performance) that analyze code simultaneously. Each reviewer re-reads its own findings before emitting, validates evidence claims, and rates confidence 1–5. The 3-reviewer default balances coverage with token cost for typical reviews.
+
+**`--full-fanout`** restores the 8-reviewer + 10-validator path for maximum coverage at higher token cost. Reach for it on pre-release audits, large refactors, or security-sensitive PRs where thoroughness beats cost.
+
+## Tool-Use Rationale
+
+- **Read**: Load spec.md, rubric.md, CLAUDE.md, and the files under review so reviewers share identical context.
+- **Grep**: Locate call sites, try/catch patterns, and AC markers across the touched files.
+- **Bash**: Run `gh pr diff`, `git diff`, and `find` to build the file list and extract PR metadata.
+
+## Model Configuration
+
+**Default effort**: `xhigh` — recommended for all code-review tasks per Opus 4.7 conventions.
+**Opt-in max**: `--effort max` enables maximum effort with a warning: "max effort risks overthinking on straightforward problems."
+**Legacy mode**: Set `quality.thinkingBudget: "legacy"` in config to pass a fixed `thinking` parameter (for pre-4.7 models only).
+
+## Prompt Caching
+
+`sw:code-reviewer` uses Anthropic's ephemeral prompt caching so the shared context (project rules, active spec, rubric) is reused across the parallel reviewer fan-out and between fix-loop iterations. This is especially impactful during `sw:done`, where the fix loop can invoke code-reviewer up to 5 times per closure.
+
+**Files cached by default** (via `static-context-loader`):
+- `CLAUDE.md` (project root)
+- `.specweave/config.json`
+- The active increment's `spec.md`
+- The active increment's `rubric.md` (if present)
+
+**Cache window**: 5-minute TTL (Anthropic's `cache_control: { type: "ephemeral" }` breakpoint). Successive reviewer spawns that share this prefix read from cache.
+
+**Extending the list**: Add paths to `cache.staticContextFiles` in `.specweave/config.json`:
+```json
+{
+  "cache": {
+    "staticContextFiles": [
+      "CLAUDE.md",
+      ".specweave/config.json",
+      ".specweave/docs/internal/architecture/adr/ADR-001-something.md"
+    ]
+  }
+}
+```
+
+**Disable caching**: Set `cache.staticContextFiles: []` in `.specweave/config.json`. Reviewer agents will still run, but without the shared prefix cache.
+
+See `.specweave/docs/internal/specs/config-reference.md` and `opus-47-migration.md` for the full caching setup.
 
 ## MANDATORY: Orchestrator Identity
 
@@ -132,75 +175,81 @@ fi
 
 ## 1. Smart Reviewer Routing
 
-Not all 6 reviewers are needed for every review. Route based on what files changed.
+**Default (3 reviewers)**: security, logic, performance — each with inline self-critique.
+**`--full-fanout`**: restores the legacy 8-reviewer path (plus the 10-validator finding-validation fan-out).
 
-### Available Reviewers
+### Default Reviewers (always spawned)
 
 | Reviewer | Agent Template | Model | Specialization |
 |----------|---------------|-------|----------------|
-| **Logic** | `agents/reviewer-logic.md` (from team-lead) | **opus** | Bugs, edge cases, error handling |
 | **Security** | `agents/reviewer-security.md` (from team-lead) | **opus** | OWASP, auth, secrets, injection |
-| **Performance** | `agents/reviewer-performance.md` (from team-lead) | sonnet | N+1, memory, blocking ops |
-| **Silent Failures** | `agents/reviewer-silent-failures.md` | sonnet | Empty catches, swallowed errors |
-| **Type Design** | `agents/reviewer-types.md` | sonnet | Type quality, invariants, assertions |
-| **Spec Compliance** | `agents/reviewer-spec-compliance.md` | sonnet | AC verification, scope creep |
-| **Comments** | `agents/reviewer-comments.md` | sonnet | Stale/misleading comments, JSDoc accuracy |
-| **Tests** | `agents/reviewer-tests.md` | sonnet | Behavioral test coverage gaps |
+| **Logic** | inline (see §2 Logic Checklist) | **opus** | Bugs, edge cases, error handling, silent failures, type invariants, spec compliance |
+| **Performance** | inline (see §2 Performance Checklist) | sonnet | N+1, memory, blocking ops |
+
+The default logic reviewer absorbs silent-failures, types, spec-compliance, comments, and tests checks via its expanded checklist — a single careful reviewer with self-critique typically catches what 5 narrower reviewers would.
+
+**Model tiering rationale**: Security and Logic need deep reasoning (Opus). Performance is pattern-matching and uses Sonnet. Non-Claude environments (Cursor, Copilot, etc.) ignore model hints gracefully.
 
-**Model tiering rationale**: Logic and Security need deep reasoning (Opus). Pattern-matching reviewers (Performance, Silent Failures, Types, Spec Compliance) use Sonnet for cost efficiency. Non-Claude environments (Cursor, Copilot, etc.) ignore model hints gracefully — the review still runs on whatever model is available.
+### Full-Fanout Reviewers (`--full-fanout` only)
+
+| Reviewer | Agent Template | Model | Specialization |
+|----------|---------------|-------|----------------|
+| Silent Failures | `agents/reviewer-silent-failures.md` | sonnet | Empty catches, swallowed errors |
+| Type Design | `agents/reviewer-types.md` | sonnet | Type quality, invariants, assertions |
+| Spec Compliance | `agents/reviewer-spec-compliance.md` | sonnet | AC verification, scope creep |
+| Comments | `agents/reviewer-comments.md` | sonnet | Stale/misleading comments, JSDoc accuracy |
+| Tests | `agents/reviewer-tests.md` | sonnet | Behavioral test coverage gaps |
 
 ### Routing Rules
 
 ```
-ALWAYS include:
-  - reviewer-logic (runs on every review)
-  - reviewer-security (runs on every review)
+DEFAULT (3 reviewers, always spawned):
+  - security  (runs on every review)
+  - logic     (runs on every review, with expanded checklist)
+  - performance (runs on every review)
 
-Include IF file patterns match:
+WITH --full-fanout, also include IF file patterns match:
   - reviewer-types        → *.ts, *.tsx files present
   - reviewer-silent-failures → *.ts, *.tsx, *.js files with try/catch or .catch patterns
-  - reviewer-performance  → database files (prisma/, *.sql), API routes, data-heavy code
   - reviewer-spec-compliance → increment scope provided (--increment or active increment found)
   - reviewer-comments  → significant changes (> 50 changed lines)
   - reviewer-tests     → non-test source files changed
 
-Cap: --max-reviewers N (default: 8)
+Cap: --max-reviewers N (default: 3; with --full-fanout: 8)
 ```
 
 ### Routing Decision
 
 ```bash
-REVIEWERS=("logic" "security")  # Always
-
-# TypeScript files → add type reviewer
-if echo "$FILES" | grep -qE '\.(ts|tsx)$'; then
-  REVIEWERS+=("types")
-fi
+# Default: security + logic + performance — all three always spawn
+REVIEWERS=("security" "logic" "performance")
 
-# Code files → add silent failures
-if echo "$FILES" | grep -qE '\.(ts|tsx|js|jsx)$'; then
-  REVIEWERS+=("silent-failures")
-fi
+if [ "$FULL_FANOUT" = "true" ]; then
+  # TypeScript files → add type reviewer
+  if echo "$FILES" | grep -qE '\.(ts|tsx)$'; then
+    REVIEWERS+=("types")
+  fi
 
-# Database/API → add performance
-if echo "$FILES" | grep -qE '(prisma|\.sql|api/|routes/|controllers/)'; then
-  REVIEWERS+=("performance")
-fi
+  # Code files → add silent failures
+  if echo "$FILES" | grep -qE '\.(ts|tsx|js|jsx)$'; then
+    REVIEWERS+=("silent-failures")
+  fi
 
-# Increment context → add spec compliance
-if [ "$SCOPE" = "increment" ] || [ -n "$INCREMENT_PATH" ]; then
-  REVIEWERS+=("spec-compliance")
-fi
+  # Increment context → add spec compliance
+  if [ "$SCOPE" = "increment" ] || [ -n "$INCREMENT_PATH" ]; then
+    REVIEWERS+=("spec-compliance")
+  fi
 
-# Significant changes → add comment reviewer
-if [ "$(echo "$FILES" | wc -l)" -gt 10 ]; then
-  REVIEWERS+=("comments")
-fi
+  # Significant changes → add comment reviewer
+  if [ "$(echo "$FILES" | wc -l)" -gt 10 ]; then
+    REVIEWERS+=("comments")
+  fi
 
-# Source files (non-test) → add test coverage reviewer
-if echo "$FILES" | grep -qE '\.(ts|tsx|js|jsx)$'; then
-  if echo "$FILES" | grep -vqE '\.(test|spec)\.(ts|tsx|js|jsx)$'; then
-    REVIEWERS+=("tests")
+  # Source files (non-test) → add test coverage reviewer
+  if echo "$FILES" | grep -qE '\.(ts|tsx|js|jsx)$'; then
+    if echo "$FILES" | grep -vqE '\.(test|spec)\.(ts|tsx|js|jsx)$'; then
+      REVIEWERS+=("tests")
+    fi
   fi
 fi
 ```
@@ -298,20 +347,28 @@ Multiple reviewers may flag the same issue (e.g., logic + silent-failures both c
 
 ---
 
-## 3.5 Independent Finding Validation
+## 3.5 Inline Self-Critique (default)
 
-After aggregation, validate CRITICAL and HIGH findings with independent subagents. This catches hallucinated findings and reduces false positives.
+Default reviews use **inline self-critique** instead of spawning separate validator subagents. Each reviewer re-reads its own findings before emitting, validates evidence claims, and rates confidence 1–5.
 
-### Validation Scope
+### Self-Critique Contract
+
+Every reviewer prompt includes this closing instruction:
+
+```
+Before emitting REVIEW_COMPLETE, perform self-critique:
+  1. Re-read each finding you produced.
+  2. For each finding, re-open the cited file at the cited line and confirm the described issue is really there.
+  3. Rate confidence 1–5 (5 = certain, 1 = speculative).
+  4. Drop any finding where confidence < 3.
+  5. Emit remaining findings with a "confidence": N field.
+```
 
-- **CRITICAL**: ALWAYS validate
-- **HIGH**: ALWAYS validate
-- **MEDIUM/LOW/INFO**: Skip (trust the reviewer)
-- **Skip entirely**: `--fast` flag or `codeReview.skipValidation: true` in config
+Each finding therefore ships with a confidence score. Findings with confidence ≥ 3 keep their severity. Findings with confidence < 3 are dropped during the reviewer's own pass (never emitted).
 
-### Spawn Validators
+### Full-Fanout Validator Path (`--full-fanout` only)
 
-For each CRITICAL/HIGH finding (max 10 concurrent, haiku model):
+When `--full-fanout` is passed, the orchestrator additionally spawns (on the haiku tier) up to 10 independent verify-findings subagents for CRITICAL and HIGH findings (original behaviour):
 
 ```typescript
 Task({
@@ -343,7 +400,7 @@ RESPOND WITH EXACTLY ONE LINE:
 });
 ```
 
-### Process Results
+Process results (full-fanout only):
 
 | Result | Action |
 |--------|--------|
@@ -515,7 +572,7 @@ Produce a single report with sections per repo:
 
 ```typescript
 // Shutdown each reviewer
-SendMessage({ type: "shutdown_request", recipient: "reviewer-logic", content: "Review complete" });
+SendMessage({ type: "shutdown_request", recipient: "logic-inline", content: "Review complete" });
 SendMessage({ type: "shutdown_request", recipient: "reviewer-security", content: "Review complete" });
 // ... for each spawned reviewer
 ```

package/plugins/specweave/skills/do/SKILL.md

@@ -20,11 +20,20 @@ Execute a SpecWeave increment by running tasks from tasks.md with automatic AC-s
 ```
 sw:do <increment-id>    # Execute specific increment
 sw:do                   # Auto-select best candidate
-sw:do <id> --model haiku|sonnet|opus  # Override model for all tasks
+sw:do <id> --model <model-id>  # Override the model (effort stays at xhigh)
 ```
 
 - `<increment-id>`: Optional. Supports "001", "0001", "1", "0042", or "0153-feature-name" formats.
-- `--model <tier>`: Optional. Overrides per-task model hints.
+- `--model <model-id>`: Optional. Overrides the model. Effort stays at `xhigh`.
+
+All tasks execute at the `xhigh` effort tier (Opus 4.7 default). Use `--model` to override the model if needed, but effort stays at xhigh.
+
+## Tool-Use Rationale
+
+- **Read**: Load spec.md, plan.md, tasks.md, and any referenced living docs before executing a task.
+- **Edit**: Apply task-scoped code changes and flip `[ ]` → `[x]` in tasks.md after verification passes.
+- **Write**: Create new files the task defines (source, tests, migrations).
+- **Bash**: Run the task's test command and project-level verification (`npx vitest run`, `pytest`, `go test ./...`).
 
 ---
 
@@ -133,7 +142,7 @@ If TDD mode active:
 ### Step 4: Smart Resume
 
 1. Parse tasks.md, find first incomplete task (`[ ]`)
-2. Extract model hints per task (haiku/sonnet/opus)
+2. Run every task at the `xhigh` effort tier (Opus 4.7 default) — legacy tiered hints in tasks.md are ignored
 3. Show resume context with completion percentage
 
 ### Step 5: Update Status
@@ -155,8 +164,8 @@ Before marking ANY task `[x]`, you MUST run verification and see it pass:
 
 For each task:
 
-1. **Read task details**: ID, model hint, description, ACs, file paths
-2. **Select model**: Use task hint or `--model` override
+1. **Read task details**: ID, description, ACs, file paths
+2. **Run at xhigh effort**: All tasks execute at the `xhigh` effort tier (Opus 4.7 default). `--model` only overrides the model; effort stays at xhigh.
 3. **Execute**: Follow plan.md architecture, implement, write clean code
 4. **Verify**: Run the task's test command (see Iron Law above). Only proceed if green.
 5. **Mark complete**: Change `[ ]` to `[x]` in tasks.md — ONLY after verification passes

package/plugins/specweave/skills/done/SKILL.md

@@ -5,6 +5,41 @@ argument-hint: "<increment-id> [--auto]"
 
 # Close Increment (PM Validated)
 
+## Tool-Use Rationale
+
+- **Bash**: Invoke the CLI closure gate (`specweave complete`), run `npx vitest run` and `npx playwright test` to verify the suite is green, and read `jq` values from `.specweave/config.json`.
+- **Read**: Load `code-review-report.json`, `grill-report.json`, `judge-llm-report.json`, and `rubric.md` to evaluate gate outcomes.
+- **Edit**: Update `metadata.json` status and any inline docs (CLAUDE.md, CHANGELOG.md) touched by the closure step.
+
+## Prompt Caching
+
+`sw:done` is a closure orchestrator that chains `code-reviewer`, `simplify`, `grill`, and `judge-llm`. Because the same increment context is loaded four times over, Anthropic's ephemeral prompt caching gives closure a substantial cost/latency win.
+
+**Files cached by default** (via `static-context-loader`):
+- `CLAUDE.md` (project root)
+- `.specweave/config.json`
+- The active increment's `spec.md`
+- The active increment's `rubric.md` (if present)
+
+**Cache window**: 5-minute TTL (Anthropic's `cache_control: { type: "ephemeral" }` breakpoint). Consecutive gate invocations within the TTL read the cached prefix instead of re-tokenizing it.
+
+**Extending the list**: Add paths to `cache.staticContextFiles` in `.specweave/config.json`:
+```json
+{
+  "cache": {
+    "staticContextFiles": [
+      "CLAUDE.md",
+      ".specweave/config.json",
+      ".specweave/docs/internal/specs/team-conventions.md"
+    ]
+  }
+}
+```
+
+**Disable caching**: Set `cache.staticContextFiles: []` in `.specweave/config.json`. Closure gates will still run but without the shared prefix cache.
+
+See `.specweave/docs/internal/specs/config-reference.md` and `opus-47-migration.md` for the full caching setup.
+
 ## Project Overrides
 
 **Skill Memories**: If `.specweave/skill-memories/done.md` exists, read and apply its learnings.
@@ -46,7 +81,7 @@ If closing a SpecWeave framework increment, show post-closure reminders: update
 **The CLI blocks closure if `code-review-report.json` is missing (when required).** Do NOT skip this step.
 
 1. Check config: `jq -r '.codeReview.required // true' .specweave/config.json` — if `false`, skip to Step 3
-2. Read max iterations: `MAX_ITER=$(jq -r '.codeReview.maxFixIterations // 3' .specweave/config.json 2>/dev/null)`
+2. Read max iterations: `MAX_ITER=$(jq -r '.codeReview.maxFixIterations // 5' .specweave/config.json 2>/dev/null)` — default cap is **5** in SpecWeave 1.1.0 (Opus 4.7 converges faster per iteration, so a higher cap catches edge cases without stalling closure)
 3. Read blocking severities: defaults are `critical`, `high`, `medium` (configurable via `codeReview.blockingSeverities`)
 4. **Iteration loop** (ITERATION=1):
    a. Invoke `Skill({ skill: "sw:code-reviewer", args: "--increment <id>" })`

package/plugins/specweave/skills/github-issue-standard/SKILL.md

@@ -1,229 +1,13 @@
 ---
-description: Mandatory format standard for ALL GitHub issues created by SpecWeave with checkable acceptance criteria and proper metadata. Use when creating GitHub issues, formatting issue content, or ensuring consistent issue structure. Covers user stories, epics, features, and increments.
-user-invokable: false
+name: sw/github-issue-standard
+description: "[DEPRECATED] GitHub issue formatting standard. See docs/internal/specs/github-issue-standard.md"
+version: 1.0.0
+deprecated: true
 ---
 
-# GitHub Issue Standard - Universal Format
+> ⚠️ DEPRECATED: Content moved to `.specweave/docs/internal/specs/github-issue-standard.md`
 
-**CRITICAL**: This is the **MANDATORY** format for ALL GitHub issues created by SpecWeave, whether for:
-- User stories (individual us-*.md files)
-- Epics/Features (FS-* folders)
-- Increments (0001-* folders)
-- Specs (spec-*.md files)
+See: [github-issue-standard.md](../../../.specweave/docs/internal/specs/github-issue-standard.md)
 
-## Issue Title Format (MANDATORY)
-
-### ✅ ONLY Allowed Title Formats
-
-```
-[FS-XXX][US-YYY] User Story Title    ← STANDARD (User Stories)
-[FS-XXX] Feature Title               ← Rare (Feature-level only)
-```
-
-**Examples**:
-- ✅ `[FS-059][US-003] Hook Optimization (P0)`
-- ✅ `[FS-054][US-001] Fix Reopen Desync Bug (P0)`
-- ✅ `[FS-048] Smart Pagination Feature`
-
-### ❌ PROHIBITED Title Formats (NEVER USE)
-
-```
-[BUG] Title                          ← WRONG! Bug is a LABEL, not title prefix
-[HOTFIX] Title                       ← WRONG! Hotfix is a LABEL
-[FEATURE] Title                      ← WRONG! Feature is a LABEL
-[DOCS] Title                         ← WRONG! Docs is a LABEL
-[Increment XXXX] Title               ← DEPRECATED! Old format
-```
-
-**Why?** Type-based prefixes like `[BUG]` break traceability:
-- Cannot link to Feature Spec (FS-XXX)
-- Cannot link to User Story (US-YYY)
-- Violates SpecWeave's data flow: `Increment → Living Docs → GitHub`
-
-**What to do instead?**
-1. Link work to a Feature (FS-XXX) in living docs
-2. Create User Story (US-YYY) under that feature
-3. Use GitHub **labels** for categorization: `bug`, `enhancement`, `hotfix`
-
-### Validation
-
-The GitHub client (`github-client-v2.ts`) enforces this:
-- Rejects titles starting with `[BUG]`, `[HOTFIX]`, `[FEATURE]`, etc.
-- Rejects deprecated `[Increment XXXX]` format
-- Only allows `[FS-XXX][US-YYY]` or `[FS-XXX]` formats
-
----
-
-## The Standard Format
-
-### ✅ Required Elements
-
-Every GitHub issue MUST include:
-
-1. **Checkable Acceptance Criteria**
-   - Use GitHub task checkbox format: `- [x]` or `- [ ]`
-   - Include AC ID, description, priority, and testable flag
-   - Example: `- [x] **AC-US4-01**: Description (P1, testable)`
-
-2. **Checkable Tasks**
-   - Link to increment tasks.md with GitHub URLs (not relative paths)
-   - Use GitHub task checkbox format
-   - Example: `- [x] [T-008: Title](https://github.com/owner/repo/tree/develop/.specweave/increments/0031/tasks.md#t-008-title)`
-
-3. **Working GitHub URLs** (v5.0.0+ - NO _features folder)
-   - Feature links: `https://github.com/owner/repo/tree/develop/.specweave/docs/internal/specs/{project}/FS-031`
-   - User story links: `https://github.com/owner/repo/tree/develop/.specweave/docs/internal/specs/{project}/FS-031/us-004-*.md`
-   - Task links: `https://github.com/owner/repo/tree/develop/.specweave/increments/0031/tasks.md#task-anchor`
-   - Increment links: `https://github.com/owner/repo/tree/develop/.specweave/increments/0031`
-
-   **Note**: Feature ID is DERIVED from increment (0031 → FS-031)
-
-4. **Extracted Priority**
-   - Extract from ACs (highest priority wins: P1 > P2 > P3)
-   - Show ONLY if priority exists (don't show "undefined")
-   - Example: `**Priority**: P1`
-
-5. **NO Project Field**
-   - Don't include `**Project**: ...` - not needed for GitHub issues
-   - Project is determined by repository context
-
-### ❌ Never Use
-
-- ❌ Relative paths (`../../{project}/FS-031`)
-- ❌ Undefined values (`**Priority**: undefined`)
-- ❌ Project field in metadata
-- ❌ Plain bullet points for ACs (must be checkboxes)
-- ❌ Plain bullet points for tasks (must be checkboxes with links)
-
-## Implementation
-
-### UserStoryContentBuilder (✅ REFERENCE IMPLEMENTATION)
-
-**File**: `plugins/specweave-github/lib/user-story-content-builder.ts`
-
-This is the **gold standard** implementation. All other builders must follow this pattern.
-
-**Key features**:
-```typescript
-// 1. Accept GitHub repo parameter
-async buildIssueBody(githubRepo?: string): Promise<string>
-
-// 2. Auto-detect repo from git remote
-private async detectGitHubRepo(): Promise<string | null>
-
-// 3. Extract priority from ACs
-private extractPriorityFromACs(criteria: AcceptanceCriterion[]): string | null
-
-// 4. Generate GitHub URLs (not relative) - v5.0.0+: No _features folder
-const featureUrl = `https://github.com/${repo}/tree/develop/.specweave/docs/internal/specs/${project}/${featureId}`;
-
-// 5. Convert task links to GitHub URLs
-if (repo && taskLink.startsWith('../../')) {
-  const relativePath = taskLink.replace(/^\.\.\/\.\.\//, '.specweave/');
-  taskLink = `https://github.com/${repo}/tree/develop/${relativePath}`;
-}
-```
-
-### Template
-
-```markdown
-**Feature**: [FS-031](https://github.com/owner/repo/tree/develop/.specweave/docs/internal/specs/{project}/FS-031)
-**Status**: complete
-**Priority**: P1
-
----
-
-## User Story
-
-**As a** user
-**I want** feature
-**So that** benefit
-
-📄 View full story: [`us-004-name.md`](https://github.com/owner/repo/tree/develop/.specweave/docs/internal/specs/{project}/FS-031/us-004-name.md)
-
----
-
-## Acceptance Criteria
-
-Progress: 4/6 criteria met (67%)
-
-- [x] **AC-US4-01**: Description (P1, testable)
-- [x] **AC-US4-02**: Description (P1, testable)
-- [ ] **AC-US4-03**: Description (P2, testable)
-- [ ] **AC-US4-04**: Description (P2, testable)
-
----
-
-## Implementation Tasks
-
-Progress: 3/6 tasks complete (50%)
-
-**Increment**: [0031-name](https://github.com/owner/repo/tree/develop/.specweave/increments/0031-name)
-
-- [x] [T-008: Title](https://github.com/owner/repo/tree/develop/.specweave/increments/0031/tasks.md#t-008-title)
-- [x] [T-009: Title](https://github.com/owner/repo/tree/develop/.specweave/increments/0031/tasks.md#t-009-title)
-- [ ] [T-010: Title](https://github.com/owner/repo/tree/develop/.specweave/increments/0031/tasks.md#t-010-title)
-
----
-
-🤖 Auto-synced by SpecWeave
-```
-
-## Implementation
-
-### Content Builders
-
-All GitHub issue content is generated by these builders:
-
-1. **UserStoryIssueBuilder** (`plugins/specweave-github/lib/user-story-issue-builder.ts`)
-   - Creates issues from `us-*.md` files
-   - Generates `[FS-XXX][US-YYY] Title` format
-   - Extracts ACs and tasks as checkboxes
-   - Uses GitHub URLs (not relative paths)
-
-2. **GitHubFeatureSync** (`plugins/specweave-github/lib/github-feature-sync.ts`)
-   - Syncs Features as GitHub Milestones
-   - Syncs User Stories as GitHub Issues via UserStoryIssueBuilder
-   - Universal Hierarchy: Feature → Milestone, User Story → Issue
-
-### Commands
-
-All GitHub sync commands use the Universal Hierarchy:
-
-- `sw-github:sync` - Sync increments via Feature/UserStory hierarchy
-- `sw-github:create-issue` - Create issue using standard format
-- `sw-github:update-user-story` - Update user story issue
-
-## Validation Checklist
-
-When creating/updating a GitHub issue, verify:
-
-- [ ] Feature link is clickable GitHub URL (not `../../`)
-- [ ] User story link is clickable GitHub URL
-- [ ] All task links are clickable GitHub URLs
-- [ ] ACs are checkable (GitHub checkboxes work in UI)
-- [ ] Tasks are checkable (GitHub checkboxes work in UI)
-- [ ] Priority shows actual value (P1/P2/P3) or is omitted
-- [ ] No "Project: undefined" field
-- [ ] Progress percentages are correct
-- [ ] Increment link is clickable GitHub URL
-
-## Benefits
-
-- ✅ **Links work**: No more broken relative paths
-- ✅ **Checkable**: ACs and tasks can be checked/unchecked in GitHub UI
-- ✅ **Clean metadata**: No undefined values cluttering the issue
-- ✅ **Consistent**: Same format across all issue types
-- ✅ **Traceable**: Direct links to source files in repository
-
-## When to Use
-
-**Always!** This is the ONLY acceptable format for GitHub issues created by SpecWeave.
-
-No exceptions. No shortcuts. Every issue follows this standard.
-
-## Related Files
-
-- **User Story Builder**: `plugins/specweave-github/lib/user-story-issue-builder.ts`
-- **Feature Sync**: `plugins/specweave-github/lib/github-feature-sync.ts`
-- **Example Issue**: https://github.com/anton-abyzov/specweave/issues/501
+Migration: This was a documentation standard, not an executable skill.
+Use `sw-github:push` for GitHub sync operations.

package/plugins/specweave/skills/github-multi-project/SKILL.md

@@ -1,10 +1,18 @@
 ---
-description: Expert at organizing specs and splitting tasks across multiple GitHub repositories for monorepo, polyrepo, and parent repo architectures. Use when managing specs across multiple repos, coordinating cross-repo work, or allocating tasks to different teams/repositories.
+description: "[DEPRECATED] Use `sw:multi-project --tool github` instead. Organizes specs and splits tasks across multiple GitHub repositories. This skill will be removed in SpecWeave v1.3.0."
 user-invokable: false
 ---
 
 # GitHub Multi-Project Management Skill
 
+## Migration
+
+> Deprecated. Use: `sw:multi-project --tool github`
+
+This skill has been consolidated into the unified `sw:multi-project` skill. Replace any invocation of `sw:github-multi-project` with `sw:multi-project --tool github`. The flag-based skill supports GitHub, Azure DevOps, and Jira under a single interface. See `plugins/specweave/skills/multi-project/SKILL.md`.
+
+Scheduled for removal in SpecWeave v1.3.0.
+
 Expert skill for managing SpecWeave projects across multiple GitHub repositories.
 
 ## Core Capabilities

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

@@ -1,6 +1,21 @@
 ---
-description: Two-way synchronization between SpecWeave specs and GitHub Projects (push & pull by default). Use when asking about GitHub integration setup, troubleshooting sync issues, or configuring sync settings. For actual syncing, use sw-github:sync-spec command.
+description: "[DEPRECATED] Two-way synchronization between SpecWeave specs and GitHub Projects (push & pull by default). Use when asking about GitHub integration setup, troubleshooting sync issues, or configuring sync settings. For actual syncing, use sw-github:sync-spec command."
 user-invokable: false
+deprecated: true
+---
+
+> ⚠️ DEPRECATED: Use `sw-github:sync-spec` instead. This skill will be removed in v1.3.0.
+
+## Migration
+
+This skill has been deprecated as part of the Opus 4.7 framework alignment (increment 0669).
+
+- **Use instead**: `sw-github:sync-spec` for push/pull operations
+- **Removal**: Scheduled for v1.3.0 (2 minor releases after v1.1.0)
+- **Why**: Consolidated sync logic moved to the `sw-github:*` command family. This skill's guidance content is now covered by `sw-github:sync-spec` help text and `.specweave/docs/internal/specs/github-sync.md`.
+
+For the migration policy, see `.specweave/docs/internal/specs/skill-deprecation-policy.md`.
+
 ---
 
 # GitHub Sync - Two-way Spec ↔ Project Synchronization