superpowers-mcp 6.3.0 → 6.3.2

package/README.ja.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
 
-[![Version](https://img.shields.io/badge/version-6.3.0-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![バージョン](https://img.shields.io/badge/version-6.3.2-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 このドキュメントは、オリジナルの Superpowers スキルライブラリを独立した MCP Toolpack にパッケージ化するための情報と使用手順をまとめたものです。
@@ -128,7 +128,32 @@
 
 ## 🆕 最近の更新
 
-### v6.3.0（最新）
+### v6.3.2（最新）
+
+- **writing-plans — 2 つのプラン形状（Two Plan Shapes）と骨格優先（Skeleton-First）**：
+  - `skills/writing-plans/SKILL.md` に **Two Plan Shapes** ルーターを追加（`task-by-task` デフォルト vs `skeleton-first` 代替案）。
+  - 新規 [`skills/writing-plans/skeleton-first-plans.md`](skills/writing-plans/skeleton-first-plans.md) で Walking Skeleton（Task 1 で全サブシステムを貫通する最小稼働スライスを作成）、契約型タスク（Task Contracts、コードを直接書かずに厳密な Consumes/Produces インターフェースと観察可能な検証基準を定義）、`Tier: mechanical | judgment` タグを定義。
+- **subagent-driven-development (SDD) — ウェーブディスパッチ（Wave Dispatch）と並列 Worktree プロトコル**：
+  - skeleton-first プランに対して **DISPATCH PLAN** を生成し、ファイルの競合がないタスクをウェーブとして並列ディスパッチ。
+  - **並列 Worktree プロトコル（Parallel Worktree Protocol）**：独立した `.worktrees/task-<N>` で並行タスクを実行し、プラン順序で順次統合。競合時は自動 rebase と implementer 再開で修正。
+  - Step 5 に完了後の `Plan holds` / `Amendment:` チェック行を追加し、進行中タスクの整合性を保ちながら後続タスクに更新された契約を伝播。
+- **SDD — Tier 駆動モデルディスパッチ**：
+  - SDD ディスパッチャーと `implementer-prompt.md` が `Tier:` 指定（`mechanical` → 経済的な軽量モデル、`judgment` → 標準モデル）を直接適用し、トークンを節約。
+- **writing-skills — バイナリ実行セキュリティ強化（`render-graphs.js`）**：
+  - `execSync` から `execFileSync('dot', ['-Tsvg'], ...)` に移行してシェルインジェクションを根絶。10MB バッファ上限、Windows CRLF 対応（`\r?\n`）、`winget` インストール案内を追加。
+- **テストと検証**：MCP プロトコル、セキュリティ、SDD Bash（11 アサーション）、PowerShell（70 アサーション）、Graphviz レンダリングテストのすべてが 100% 合格。
+
+### v6.3.1
+
+- **SDD ワークスペース所有権マーカーと物理パス正規化**：`sdd-workspace`（Bash）と `sdd-workspace.ps1`（PowerShell）は `plan-path` マーカーと物理パス正規化（`pwd -P` および動的 `pwd` 検出）を使用。同名のプラン（`docs/alpha/plan.md` と `docs/beta/plan.md` など）が衝突せず個別の `.superpowers/sdd/` ワークスペースに分離されます。
+- **SDD レビューパッケージ範囲ガード**：`review-package` および `review-package.ps1` は `git merge-base --is-ancestor BASE HEAD` とコミット数を検証し、空や逆転した範囲による誤判定（false-pass）を防止。
+- **実行権限喪失への耐性**：`task-brief` と `review-package` は `"${BASH:-bash}"` で明示的に呼び出し、アーカイブ解凍等で `+x` 権限が失われても安定して動作。
+- **TDD プロジェクトスイート検証フロア**：`skills/test-driven-development/SKILL.md` はタスク完了前にプロジェクト全体のテストコマンド（`npm test`、`pytest` 等）の実行を義務化。
+- **Code Review ゴースト変更防止**：`skills/requesting-code-review/SKILL.md` で複数コミットのレビュー起点を `git merge-base origin/main HEAD` に固定。
+- **Brainstorming ツールチェーン決定ゲート**：`skills/brainstorming/SKILL.md` の設計提示フェーズでツールチェーン設定を事前に確認し、`Global Constraints` に記録。
+- **テスト拡充**：`tests/sdd/test-sdd-workspace.sh`（11 アサーション）を追加、PowerShell スイート（70 アサーション）を拡張。
+
+### v6.3.0
 
 - **上流 obra/superpowers v6.3.0 との同期** — 適用可能な改善をすべて採用し、フォーク固有のセキュリティ強化と PowerShell サポートは維持。
   - **brainstorming — 3 パスルーター**: すべてのリクエストを事前に `spike` / `bounded` / `architectural` に分類し、プロセス量をタスクに合わせて調整。ただし承認ゲートは常に全パスに適用されます。実行中に隠れた複雑さが判明した場合はパスをアップグレード — ダウングレードはありません。

package/README.ko.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
 
-[![Version](https://img.shields.io/badge/version-6.3.0-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![Version](https://img.shields.io/badge/version-6.3.2-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 이 문서는 원본 Superpowers 스킬 라이브러리를 독립적인 MCP Toolpack으로 패키징하기 위한 정보와 사용 지침을 요약한 것입니다.
@@ -128,7 +128,32 @@
 
 ## 🆕 최근 업데이트
 
-### v6.3.0 (최신)
+### v6.3.2 (최신)
+
+- **writing-plans — 2가지 계획 형태(Two Plan Shapes)와 스켈레톤 우선(Skeleton-First)**:
+  - `skills/writing-plans/SKILL.md`에 **Two Plan Shapes** 라우터를 추가(`task-by-task` 기본값 vs `skeleton-first` 대안).
+  - 새 [`skills/writing-plans/skeleton-first-plans.md`](skills/writing-plans/skeleton-first-plans.md)에서 Walking Skeleton(Task 1에서 전체 하위 시스템을 얇게 관통하는 실행 슬라이스 구축), 계약 기반 작업(Task Contracts, 코드 스크립트 대신 엄격한 Consumes/Produces 인터페이스 및 관찰 가능한 성공 기준 명시), `Tier: mechanical | judgment` 태그 정의.
+- **subagent-driven-development (SDD) — 웨이브 디스패치(Wave Dispatch) 및 병렬 Worktree 프로토콜**:
+  - skeleton-first 계획에 대해 **DISPATCH PLAN**을 생성하여 파일 충돌이 없는 작업을 웨이브 단위로 병렬 디스패치.
+  - **병렬 Worktree 프로토콜(Parallel Worktree Protocol)**: 독립된 `.worktrees/task-<N>`에서 동시 작업을 실행하고 계획 순서대로 순차 병합. 충돌 시 자동 rebase 후 implementer를 재개하여 자체 해결.
+  - Step 5에 완료 후 `Plan holds` / `Amendment:` 점검 라인을 추가하여 진행 중인 작업의 무결성을 유지하면서 후속 작업에 변경된 계약 전파.
+- **SDD — Tier 기반 모델 디스패치**:
+  - SDD 디스패처 및 `implementer-prompt.md`가 `Tier:` 지정(`mechanical` → 경제적인 경량 모델, `judgment` → 표준 모델)을 즉시 적용하여 토큰 낭비 방지.
+- **writing-skills — 바이너리 실행 보안 강화(`render-graphs.js`)**:
+  - `execSync` 대신 `execFileSync('dot', ['-Tsvg'], ...)`로 전환하여 쉘 인젝션 위험 근절. 10MB 버퍼 제한, Windows CRLF(`\r?\n`) 호환 및 `winget` 설치 안내 추가.
+- **테스트 및 검증**: MCP 프로토콜, 보안, SDD Bash(11개 어서션), PowerShell(70개 어서션), Graphviz 렌더링 테스트 100% 통과.
+
+### v6.3.1
+
+- **SDD 워크스페이스 소유권 마커 및 물리 경로 정규화**: `sdd-workspace`(Bash) 및 `sdd-workspace.ps1`(PowerShell)은 `plan-path` 마커와 물리 경로 정규화(`pwd -P` 및 동적 `pwd` 감지)를 사용. 동일한 이름의 계획 파일(`docs/alpha/plan.md` 및 `docs/beta/plan.md` 등)이 충돌 없이 별도의 `.superpowers/sdd/` 워크스페이스로 격리됩니다.
+- **SDD 리뷰 패키지 범위 가드**: `review-package` 및 `review-package.ps1`은 `git merge-base --is-ancestor BASE HEAD`와 커밋 수를 검증하여 비어 있거나 역전된 범위로 인한 오탐(false-pass)을 방지합니다.
+- **실행 권한 상실에 대한 복원력**: `task-brief`와 `review-package`는 `"${BASH:-bash}"`로 명시적 호출하여 아카이브 압축 해제 등으로 `+x` 권限이 손실되어도 정상 동작합니다.
+- **TDD 프로젝트 스위트 검증 하한선**: `skills/test-driven-development/SKILL.md`는 작업 완료 선언 전 프로젝트 전체 테스트 명령(`npm test`, `pytest` 등) 실행을 의무화합니다.
+- **Code Review 유령 변경 방지**: `skills/requesting-code-review/SKILL.md`에서 다중 커밋의 리뷰 기준점을 `git merge-base origin/main HEAD`로 고정합니다.
+- **Brainstorming 툴체인 결정 게이트**: `skills/brainstorming/SKILL.md`의 설계 제시 단계에서 툴체인 설정을 사전에 확인하고 `Global Constraints`에 기록합니다.
+- **테스트 확장**: `tests/sdd/test-sdd-workspace.sh`(11개 어서션) 추가 및 PowerShell 스위트(70개 어서션) 확장.
+
+### v6.3.0
 
 - **상류 obra/superpowers v6.3.0 동기화** — 적용 가능한 개선 사항을 모두 채택하고, 포크 고유의 보안 강화와 PowerShell 지원은 유지.
   - **brainstorming — 3경로 라우터**: 모든 요청을 사전에 `spike` / `bounded` / `architectural`로 분류하며, 절차의 양은 작업 규모에 맞춰 조정됩니다. 단 승인 게이트는 모든 경로에 동일하게 적용됩니다. 실행 중 숨은 복잡성이 발견되면 경로를 업그레이드 — 다운그레이드는 없습니다.

package/README.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
 
-[![Version](https://img.shields.io/badge/version-6.3.0-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![Version](https://img.shields.io/badge/version-6.3.2-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 This document summarizes the information and usage instructions for packaging the original Superpowers skills library into an independent MCP Toolpack.
@@ -128,7 +128,32 @@ These skills are designed for orchestrating complex meta-execution patterns with
 
 ## 🆕 Recent Updates
 
-### v6.3.0 (Latest)
+### v6.3.2 (Latest)
+
+- **writing-plans — Two Plan Shapes Router & Skeleton-First Plans**:
+  - `skills/writing-plans/SKILL.md` introduces the **Two Plan Shapes** router (`task-by-task` default vs `skeleton-first` alternative) to determine architecture upfront.
+  - New [`skills/writing-plans/skeleton-first-plans.md`](skills/writing-plans/skeleton-first-plans.md) defines the Walking Skeleton pattern (Task 1 builds the thinnest running end-to-end slice across all subsystems), Task Contracts (strict interfaces and observable behaviors without code scripts), and deliberate `Tier: mechanical | judgment` tagging.
+- **subagent-driven-development (SDD) — Wave Dispatch & Parallel Worktree Protocol**:
+  - SDD controller performs **Dispatch Plan** scanning on skeleton-first plans, grouping mutually file-disjoint tasks into waves for concurrent dispatch.
+  - **Parallel Worktree Protocol**: Runs concurrent tasks in dedicated `.worktrees/task-<N>` worktrees, with sequential plan-order merges and automatic rebase-to-fix loops on merge conflict or test regression.
+  - Step 5 adds the post-completion `Plan holds` / `Amendment:` check line, ensuring in-flight tasks complete cleanly while downstream tasks inherit updated plan contracts.
+- **SDD — Tier-Driven Model Selection**:
+  - SDD dispatcher and `implementer-prompt.md` respect task `Tier:` markings (`mechanical` → fastest/cheapest tier; `judgment` → standard tier), saving tokens without redundant re-adjudication.
+- **writing-skills — Binary Execution Hardening (`render-graphs.js`)**:
+  - Replaced `execSync` shell execution with direct `execFileSync('dot', ['-Tsvg'], ...)` to eliminate shell injection risks. Added 10MB buffer limits, Windows CRLF support (`\r?\n`), and Windows `winget` installation guidance.
+- **Tests & Verification**: Full regression suites pass 100% across MCP protocol, Security Edge Cases, SDD Bash (11 assertions), PowerShell (70 assertions), and Graphviz rendering.
+
+### v6.3.1
+
+- **SDD Ownership Markers & Path Normalization**: `sdd-workspace` (Bash) and `sdd-workspace.ps1` (PowerShell) now manage plan-scoped workspaces using `plan-path` markers with canonical physical path normalization (`pwd -P` and dynamic `pwd` detection). Same-basename plans (e.g. `docs/alpha/plan.md` vs `docs/beta/plan.md`) safely disambiguate into distinct `.superpowers/sdd/` workspaces, preventing artifact and ledger overwrites.
+- **SDD Review Package Range Mechanical Guards**: `review-package` and `review-package.ps1` now enforce `git merge-base --is-ancestor BASE HEAD` and `git rev-list --count BASE..HEAD > 0` (exiting with code 3 on error) to reject invalid or empty commit ranges and prevent false-pass review approvals.
+- **SDD Helper Resilience on Stripped Permissions**: `task-brief` and `review-package` invoke `sdd-workspace` via explicit `"${BASH:-bash}"`, surviving environments where execution bits (`+x`) are stripped during archive extraction.
+- **TDD Verification Floor**: `skills/test-driven-development/SKILL.md` explicitly defines "green" as passing the entire repository test suite (e.g., bare `npm test`, `pytest`, `cargo test`) before declaring a task complete.
+- **Code Review Merge-Base Anchoring**: `skills/requesting-code-review/SKILL.md` now anchors multi-commit review `BASE_SHA` to `git merge-base origin/main HEAD` to prevent phantom deletions when `origin/main` advances.
+- **Brainstorming Tooling Decision Gate**: `skills/brainstorming/SKILL.md` adds a proactive tooling inquiry (linter, formatting, unit/e2e tests, fuzzing) during the Design Presentation phase for new projects, recording choices into the spec's `Global Constraints`.
+- **Tests & Coverage**: Added `tests/sdd/test-sdd-workspace.sh` (11 assertions) and expanded PowerShell suites (70 assertions across 5 files). Full test suites passing 100%.
+
+### v6.3.0
 
 - **Upstream sync with obra/superpowers v6.3.0** — all applicable improvements adopted, fork-specific security hardening and PowerShell support preserved.
   - **brainstorming — three-path router**: every request is classified `spike` / `bounded` / `architectural` up front; the ceremony scales with the task but the approval gate never does. Hidden complexity upgrades the path mid-task — never downgrades.

package/README.zh-TW.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
 
-[![版本](https://img.shields.io/badge/version-6.3.0-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![版本](https://img.shields.io/badge/version-6.3.2-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![授權](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 本文檔總結了將原始 Superpowers 技能庫打包成獨立 MCP Toolpack 的相關資訊與使用說明。
@@ -128,7 +128,32 @@
 
 ## 🆕 最近更新
 
-### v6.3.0 (最新版)
+### v6.3.2 (最新版)
+
+- **writing-plans — 雙計畫形態（Two Plan Shapes）與骨架優先（Skeleton-First）**：
+  - `skills/writing-plans/SKILL.md` 加入 **Two Plan Shapes** 路由機制（`task-by-task` 預設模式 vs `skeleton-first` 骨架優先），在撰寫計畫前提早決定架構模型。
+  - 新增 [`skills/writing-plans/skeleton-first-plans.md`](skills/writing-plans/skeleton-first-plans.md) 定義 Walking Skeleton（Task 1 先完成貫穿所有子系統的真實薄切片）、契約式任務（Task Contracts，嚴格定義 Consumes/Produces 接口與可觀測驗收標準，不預寫代碼腳本）與 `Tier: mechanical | judgment` 標記。
+- **subagent-driven-development (SDD) — 波次派發（Wave Dispatch）與並行工作樹協議**：
+  - 控制器在衝突掃描階段針對 skeleton-first 計畫生成 **DISPATCH PLAN**，將檔案互斥且無未完成介面依賴的任務組成波次並行派發。
+  - **並行工作樹協議（Parallel Worktree Protocol）**：並行任務各於專屬 `.worktrees/task-<N>` 執行，按計畫順序依次合併；若遇衝突或驗證失敗，自動 rebase 並喚醒 implementer 自行修復。
+  - Step 5 增加完工後的 `Plan holds` / `Amendment:` 檢查行，確保並行在途任務順利收斂，並將介面變動直接傳遞給後續任務。
+- **SDD — Tier 驅動模型分派**：
+  - SDD 控制器與 `implementer-prompt.md` 嚴格遵循計畫中的 `Tier:` 標記（`mechanical` → 快速經濟型模型；`judgment` → 標準中階模型），大幅節省 token 且不再重複審議。
+- **writing-skills — 二進位安全加固（`render-graphs.js`）**：
+  - 改用 `execFileSync('dot', ['-Tsvg'], ...)` 徹底杜絕 shell 注入，設置 10MB 緩衝上限，支援 Windows CRLF（`\r?\n`）換行匹配與 `winget` 安裝提示。
+- **測試與驗證**：MCP 協定、邊界安全、SDD Bash（11 項斷言）、PowerShell（70 項斷言）及 Graphviz 渲染測試全數 100% 通過。
+
+### v6.3.1
+
+- **SDD 工作區歸屬標記與實體路徑正規化**：`sdd-workspace`（Bash）與 `sdd-workspace.ps1`（PowerShell）改用 `plan-path` 歸屬標記與標準化實體路徑（`pwd -P` 與動態 `pwd` 偵測）。同名 plan（如 `docs/alpha/plan.md` 與 `docs/beta/plan.md`）會自動解析為獨立的 `.superpowers/sdd/` 工作區，杜絕產物與進度覆蓋。
+- **SDD 審查包範圍機械守衛**：`review-package` 與 `review-package.ps1` 強制校驗 `git merge-base --is-ancestor BASE HEAD` 與 commit 數量大於 0（錯誤時 exit 3），防止空範圍或倒置範圍造成審查假綠燈。
+- **執行權限剝離韌性**：`task-brief` 與 `review-package` 改以 `"${BASH:-bash}"` 調用，在解壓縮或跨系統搬移丟失 `+x` 權限時依然能穩定執行。
+- **TDD 全套件驗證下限**：`skills/test-driven-development/SKILL.md` 明確規定任務完成前必須跑過全專案測試指令（如 `npm test`、`pytest`、`cargo test`）。
+- **Code Review 防幽靈變更**：`skills/requesting-code-review/SKILL.md` 將多 commit 審查起點錨定為 `git merge-base origin/main HEAD`，消除 main 推進引發的幽靈刪除。
+- **Brainstorming 工具鏈決策門禁**：`skills/brainstorming/SKILL.md` 在設計展示階段主動詢問工具鏈配置並記錄於 `Global Constraints`。
+- **測試擴充**：新增 `tests/sdd/test-sdd-workspace.sh`（11 項斷言）並擴充 PowerShell 套件（70 項斷言）。
+
+### v6.3.0
 
 - **對齊上游 obra/superpowers v6.3.0** — 採用所有適用改進，保留本 fork 的安全強化與 PowerShell 支援。
   - **brainstorming — 三路分類流程（three-path router）**：每個請求先分類為 `spike` / `bounded` / `architectural`；流程深度隨任務規模調整，但審批門檻永遠不變。隱藏複雜度會在執行途中升級路徑——絕不降級。

package/out/server.js

@@ -49,7 +49,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 `}var vs=class{constructor(t=hf.default.stdin,r=hf.default.stdout){this._stdin=t,this._stdout=r,this._readBuffer=new gs,this._started=!1,this._ondata=n=>{this._readBuffer.append(n),this.processReadBuffer()},this._onerror=n=>{this.onerror?.(n)}}async start(){if(this._started)throw new Error("StdioServerTransport already started! If using Server class, note that connect() calls start() automatically.");this._started=!0,this._stdin.on("data",this._ondata),this._stdin.on("error",this._onerror)}processReadBuffer(){for(;;)try{let t=this._readBuffer.readMessage();if(t===null)break;this.onmessage?.(t)}catch(t){this.onerror?.(t)}}async close(){this._stdin.off("data",this._ondata),this._stdin.off("error",this._onerror),this._stdin.listenerCount("data")===0&&this._stdin.pause(),this._readBuffer.clear(),this.onclose?.()}send(t){return new Promise(r=>{let n=j_(t);this._stdout.write(n)?r():this._stdout.once("drain",r)})}};var ze=sr(require("fs/promises")),ye=sr(require("path")),$n=10*1024*1024,ys=class{skillsPath;cachedSkills=null;loadingPromise=null;skillMap=new Map;contentCache=new Map;constructor(t){this.skillsPath=t}stripQuotes(t){return t.replace(/^"(.*)"$|^'(.*)'$/,"$1$2").trim()}parseFrontmatter(t){let r=t;if(r.charCodeAt(0)===65279&&(r=r.slice(1)),!r.startsWith("---"))return{name:"",description:""};let n=r.split(/\r?\n/),o=[],i=!1;for(let u=1;u<n.length;u++){if(n[u].trim()==="---"){i=!0;break}o.push(n[u])}if(!i)return{name:"",description:""};let a="",s="",c=!1;for(let u of o){let l=u.match(/^name:\s*(.*?)\s*$/);if(l){a=this.stripQuotes(l[1]),c=!1;continue}let d=u.match(/^description:\s*(.*?)\s*$/);if(d){s=this.stripQuotes(d[1]),c=!0;continue}c&&/^\s+/.test(u)?s+=" "+u.trim():c=!1}return{name:a,description:s}}async exists(t){try{return await ze.access(t),!0}catch{return!1}}async listSkills(t=!1){if(this.cachedSkills&&!t)return this.cachedSkills;if(this.loadingPromise&&!t)return this.loadingPromise;t&&this.contentCache.clear();let r=this.internalListSkills();this.loadingPromise=r;try{return await r}finally{this.loadingPromise===r&&(this.loadingPromise=null)}}async internalListSkills(){if(!await this.exists(this.skillsPath))return this.cachedSkills??[];let t=[],r=new Map,n=!1;try{let o=await ze.readdir(this.skillsPath,{withFileTypes:!0});for(let i of o){if(!i.isDirectory()&&!i.isSymbolicLink())continue;let a=ye.join(this.skillsPath,i.name),s=ye.join(a,"SKILL.md");if(await this.exists(s))try{let c=await this.readFileNoFollow(s,this.skillsPath),{name:u,description:l}=this.parseFrontmatter(c),m={name:u||i.name,description:l,skillPath:s};t.push(m),r.set(m.name.toLowerCase(),m);let p=ye.basename(ye.dirname(m.skillPath)).toLowerCase();r.set(p,m)}catch{process.stderr.write(`Warning: Failed to read skill file in directory "${i.name}"
 `)}}n=!0}catch(o){process.stderr.write(`Error reading skills directory: ${String(o)}
 `)}return n&&(this.skillMap=r,this.cachedSkills=t.sort((o,i)=>o.name.localeCompare(i.name))),this.cachedSkills??[]}async findSkill(t){let r=typeof t=="string"?t.trim():"";if(!(!r||r==="."||r===".."||r.includes("/")||r.includes("\\")||r.includes("\0")))return this.cachedSkills||await this.listSkills(),this.skillMap.get(r.toLowerCase())}async readFileNoFollow(t,r){let n=ye.resolve(t),o=ye.resolve(r),i=async()=>{let l=await ze.realpath(n),d=await ze.realpath(o);if(!(await ze.stat(d)).isDirectory())throw new Error("Skills directory must be a directory");let p=ye.relative(d,l);if(p===".."||p.startsWith(`..${ye.sep}`)||ye.isAbsolute(p))throw new Error("File is outside skills directory");let h=await ze.stat(l);if(!h.isFile()||h.nlink!==1)throw new Error("Skill path is not a regular file");if(h.size>$n)throw new Error("Skill file exceeds size limit");return{realFilePath:l,stat:h}},a=await i(),s=await i();if(a.realFilePath!==s.realFilePath||a.stat.dev!==s.stat.dev||a.stat.ino!==s.stat.ino)throw new Error("File changed while validating its path");let c=process.platform==="win32"?0:ze.constants.O_NOFOLLOW,u=await ze.open(s.realFilePath,ze.constants.O_RDONLY|c);try{let l=await u.stat();if(!l.isFile()||l.nlink!==1||l.dev!==s.stat.dev||l.ino!==s.stat.ino||l.size>$n)throw new Error("File changed while opening");let d=[],m=64*1024,p=0;for(;p<=$n;){let v=Buffer.allocUnsafe(Math.min(m,$n+1-p)),{bytesRead:$}=await u.read(v,0,v.length,null);if($===0)break;if(p+=$,d.push(v.subarray(0,$)),p>$n)throw new Error("Skill file exceeds size limit")}let h=await u.stat();if(h.size>$n||h.dev!==s.stat.dev||h.ino!==s.stat.ino)throw new Error("File changed while reading");return Buffer.concat(d,p).toString("utf-8")}finally{await u.close()}}async readSkillContent(t,r=!1){let n=ye.resolve(t),o=ye.resolve(this.skillsPath),i=n,a=o;try{i=await ze.realpath(n),a=await ze.realpath(o)}catch{}let s=ye.relative(a,i);if(s.startsWith("..")||ye.isAbsolute(s))throw new Error(`Access denied: path "${t}" is outside skills directory`);if(this.contentCache.has(i)&&!r)return this.contentCache.get(i);try{let c=await this.readFileNoFollow(t,this.skillsPath);c.charCodeAt(0)===65279&&(c=c.slice(1));let u=c.replace(/^---\s*\r?\n[\s\S]*?\r?\n---\s*\r?\n?/,"").trim();return this.contentCache.set(i,u),u}catch(c){throw new Error(`Failed to read skill content: ${c instanceof Error?c.message:String(c)}`)}}clearCache(){this.cachedSkills=null,this.loadingPromise=null,this.skillMap.clear(),this.contentCache.clear()}};function jT(){let e=process.env.SKILLS_PATH;if(e){let r=ct.resolve(e),n=ct.normalize(r).toLowerCase(),o=ct.parse(r).root.toLowerCase();if(n===o||["/etc","/var","/bin","/sbin","/usr","/root","/sys","/proc","/dev","c:\\windows","c:\\program files","c:\\program files (x86)"].some(s=>n===s||n.startsWith(s+ct.sep)))process.stderr.write(`Warning: Potentially unsafe SKILLS_PATH: "${e}". Fallback to default.
-`);else return r}let t=ct.join(__dirname,"..","skills");return E_.existsSync(t)?t:ct.join(__dirname,"skills")}var O_=jT(),It=new ys(O_),Pr=new hs({name:"superpowers-mcp",version:"6.3.0"},{capabilities:{resources:{subscribe:!1},prompts:{},tools:{}}});Pr.setRequestHandler(od,async()=>({resources:(await It.listSkills()).map(t=>({uri:`skill://superpowers/${encodeURIComponent(t.name)}`,name:t.name,description:t.description,mimeType:"text/markdown"}))}));Pr.setRequestHandler(ad,async e=>{let t=e.params.uri,r=t.match(/^skill:\/\/superpowers\/(.+)$/);if(!r)throw new D(M.InvalidRequest,`Invalid skill URI: ${t}`);let n;try{n=decodeURIComponent(r[1])}catch{throw new D(M.InvalidRequest,`Invalid skill URI: ${t}`)}let o=await It.findSkill(n);if(!o)throw new D(M.InvalidRequest,`Skill not found: ${n}`);try{let i=await It.readSkillContent(o.skillPath);return{contents:[{uri:t,mimeType:"text/markdown",text:i}]}}catch{throw new D(M.InternalError,"Failed to read skill content safely.")}});Pr.setRequestHandler(sd,async()=>({prompts:[{name:"session-start",description:"Inject the Superpowers context into an AI agent session. Tells the agent it has superpowers and how to use the skill system."}]}));Pr.setRequestHandler(cd,async e=>{if(e.params.name!=="session-start")throw new D(M.InvalidRequest,`Unknown prompt: ${e.params.name}`);let t=await It.findSkill("using-superpowers"),r="";if(t)try{r=await It.readSkillContent(t.skillPath)}catch{r=`# Superpowers
+`);else return r}let t=ct.join(__dirname,"..","skills");return E_.existsSync(t)?t:ct.join(__dirname,"skills")}var O_=jT(),It=new ys(O_),Pr=new hs({name:"superpowers-mcp",version:"6.3.2"},{capabilities:{resources:{subscribe:!1},prompts:{},tools:{}}});Pr.setRequestHandler(od,async()=>({resources:(await It.listSkills()).map(t=>({uri:`skill://superpowers/${encodeURIComponent(t.name)}`,name:t.name,description:t.description,mimeType:"text/markdown"}))}));Pr.setRequestHandler(ad,async e=>{let t=e.params.uri,r=t.match(/^skill:\/\/superpowers\/(.+)$/);if(!r)throw new D(M.InvalidRequest,`Invalid skill URI: ${t}`);let n;try{n=decodeURIComponent(r[1])}catch{throw new D(M.InvalidRequest,`Invalid skill URI: ${t}`)}let o=await It.findSkill(n);if(!o)throw new D(M.InvalidRequest,`Skill not found: ${n}`);try{let i=await It.readSkillContent(o.skillPath);return{contents:[{uri:t,mimeType:"text/markdown",text:i}]}}catch{throw new D(M.InternalError,"Failed to read skill content safely.")}});Pr.setRequestHandler(sd,async()=>({prompts:[{name:"session-start",description:"Inject the Superpowers context into an AI agent session. Tells the agent it has superpowers and how to use the skill system."}]}));Pr.setRequestHandler(cd,async e=>{if(e.params.name!=="session-start")throw new D(M.InvalidRequest,`Unknown prompt: ${e.params.name}`);let t=await It.findSkill("using-superpowers"),r="";if(t)try{r=await It.readSkillContent(t.skillPath)}catch{r=`# Superpowers
 
 You have superpowers. Use the read_skill and list_skills tools to discover and load skills.`}else{let o=ct.join(O_,"using-superpowers","SKILL.md");try{r=await It.readSkillContent(o)}catch{r=`# Superpowers
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "superpowers-mcp",
   "displayName": "Superpowers MCP",
   "description": "Superpowers skills library (TDD, debugging, collaboration workflows) as an MCP server for VSCode and Antigravity",
-  "version": "6.3.0",
+  "version": "6.3.2",
   "publisher": "superpowers",
   "license": "MIT",
   "repository": {

package/skills/brainstorming/SKILL.md

@@ -184,6 +184,7 @@ is the whole process.
 - Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
 - Ask after each section whether it looks right so far
 - Cover: architecture, components, data flow, error handling, testing
+- For a new project (or one with no configured tooling), the design presentation includes a short tooling question alongside the architecture: which of these to set up from the start — cheapest before any code exists: aggressive linting + auto-formatting (the stack's standard, e.g. ruff+format / eslint+prettier / clippy+rustfmt); unit-test infrastructure (runner, layout, a first passing fixture); end-to-end test infrastructure; fuzz or mutation testing where the stack supports it. The user's selections land in the spec's Global Constraints so every later plan and task inherits them.
 - Be ready to go back and clarify if something doesn't make sense
 
 **Design for isolation and clarity:**

package/skills/requesting-code-review/SKILL.md

@@ -25,7 +25,7 @@ Dispatch a code reviewer subagent to catch issues before they cascade. The revie
 
 **1. Get git SHAs:**
 ```bash
-BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
+BASE_SHA=$(git rev-parse HEAD~1)  # or: git merge-base origin/main HEAD
 HEAD_SHA=$(git rev-parse HEAD)
 ```
 

package/skills/subagent-driven-development/SKILL.md

@@ -173,6 +173,14 @@ its own text agrees with itself — the tests it specifies against the code it
 specifies, the files it creates against the files it later touches. "The scan
 is clean" without those rows is not a scan you ran.
 
+**When the plan's header declares `Plan shape: skeleton-first`,** the
+table gets a final section: the DISPATCH PLAN — group the pending tasks
+into waves. Tasks in the same wave are mutually file-disjoint and consume
+no interface still under construction — dispatch each wave's implementers
+concurrently, one worktree per task, and integrate before the next wave;
+tasks that fail those conditions serialize. On a skeleton-first plan, a
+scan without a dispatch plan is not a scan you ran.
+
 Write the table to the ledger. Rule on everything you find before execution
 begins — each finding against the plan text that mandates it — and record
 each ruling in the ledger. If the scan is clean, proceed without comment.
@@ -187,6 +195,10 @@ Use the least powerful model that can handle each role to conserve cost and incr
 
 **Mechanical implementation tasks** (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified.
 
+When a task carries a **Tier:** field, follow it — the planner already
+ruled: mechanical → the cheapest available model; judgment → a standard
+model. Do not re-litigate the tier at dispatch.
+
 **Integration and judgment tasks** (multi-file coordination, pattern matching, debugging): use a standard model.
 
 **Architecture and design tasks**: use the most capable available model.
@@ -208,7 +220,10 @@ most expensive — which silently defeats this section.
 **Turn count beats token price.** Wall-clock and context cost scale with how
 many turns a subagent takes, and the cheapest models routinely take 2-3× the
 turns on multi-step work — costing more overall. Use a mid-tier model as the
-floor for reviewers and for implementers working from prose descriptions.
+floor for reviewers and for implementers working from task contracts or
+prose descriptions — unless the task's Tier line says mechanical: the
+planner has already ruled the deliverable fully specified, so treat a
+mechanical-tier contract like spelled-out content.
 When the task's plan text contains the complete code to write, the
 implementation is transcription plus testing: use the cheapest tier for
 that implementer. Single-file mechanical fixes also take the cheapest tier.
@@ -260,7 +275,13 @@ and fix-round diffs need it.
   know; (4) your resolution of any ambiguity you noticed in the brief;
   (5) the report-file path and report contract. Exact values (numbers,
   magic strings, signatures, test cases) appear only in the brief. Never
-  make a subagent read the whole plan file.
+  make a subagent read the whole plan file. When the brief is a contract
+  (goal, success criteria, interfaces) rather than written-out code, item
+  (3) also carries the elaboration the contract leaves to dispatch time:
+  the interfaces as actually built by completed tasks, environment facts
+  and discoveries from earlier reports, and any amendment rulings. There
+  the success criteria name the cases the tests must cover, and the
+  implementer designs its own code and tests within the contract.
 - **Report file:** name the implementer's report file after the brief
   (brief `…/task-N-brief.md` → report `…/task-N-report.md`) and put it in
   the dispatch prompt. The implementer writes the full report there and
@@ -281,6 +302,26 @@ and fix-round diffs need it.
 - Record the implementer's agent identity from the dispatch result —
   fix-loop rounds 1-3 resume this agent.
 - Never dispatch multiple implementation subagents in parallel (conflicts).
+  The one exception is a skeleton-first plan whose dispatch plan shows two
+  or more pending tasks mutually file-disjoint with none consuming an
+  interface still under construction. Dispatch those implementers
+  concurrently, each in its own worktree:
+  - Record the integration base commit in the ledger before the first
+    concurrent dispatch.
+  - Create one worktree per concurrent task off that base
+    (`git worktree add <repo-root>/.worktrees/task-<N> -b task-<N>
+    <base>`); each dispatch's `Work from:` is its own worktree, and its
+    BASE is that worktree's HEAD.
+  - Review each task's diff as usual when it reports. Integrate reviewed
+    branches in plan order: merge each into the integration branch
+    (`git merge --no-ff task-<N>`), and run that task's verification
+    commands after each merge.
+  - A merge conflict or post-merge verification failure is that task's
+    fix-loop round 1: rebase the task branch onto the current
+    integration head in its worktree, then resume its implementer
+    there. Never resolve conflicts yourself.
+  - Remove each worktree (`git worktree remove`) once its branch is
+    integrated, and record the integrated range in the ledger as usual.
 
 Template: [implementer-prompt.md](implementer-prompt.md)
 
@@ -442,6 +483,19 @@ message as your other bookkeeping:
 - `Task <N>: complete (commits <base7>..<head7>, <K> parked)` after a
   tripped breaker
 
+**On a skeleton-first plan,** write one plan-check line with the
+completion line. Re-read the remaining tasks against what this task
+actually established — interfaces as built, environment facts,
+discoveries in the report — and append either `Plan holds` or
+`Amendment: Task <M>: <what changes and why>` to the ledger. An
+amendment is plan authority applied at the plan layer: from then on the
+amended text IS the plan's text, and it rides into every affected task's
+dispatch under item (3). In-flight tasks in the same concurrent wave are
+not aborted mid-flight; any interface divergences are surfaced and
+resolved through the standard integration merge, rebase, and fix-loop
+protocol. Never dispatch a task whose brief a completed task's report has
+already invalidated.
+
 Then mark the todo complete and move on. Never move to the next task while
 the review has open Critical/Important issues that are neither fixed nor
 parked-with-ruling at the cap.

package/skills/subagent-driven-development/implementer-prompt.md

@@ -5,8 +5,11 @@ Use this template when dispatching an implementer subagent.
 ```
 Subagent (general-purpose):
   description: "Implement Task N: [task name]"
-  model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted
-         model silently inherits the session's most expensive one]
+  model: [MODEL — REQUIRED: when the brief carries a Tier line, set from it:
+         mechanical → the cheapest model the subagent tool offers; judgment →
+         a standard mid-tier model. Otherwise choose per SKILL.md Model
+         Selection. An omitted model silently inherits the session's most
+         expensive one]
   prompt: |
     You are implementing Task N: [task name]
 

package/skills/subagent-driven-development/scripts/review-package

@@ -22,10 +22,20 @@ head=$3
 git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
 git rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; }
 
+git merge-base --is-ancestor "$base" "$head" || {
+  echo "HEAD ($head) is not a descendant of BASE ($base)" >&2
+  exit 3
+}
+
+if [ "$(git rev-list --count "${base}..${head}")" -eq 0 ]; then
+  echo "empty commit range: ${base}..${head}" >&2
+  exit 3
+fi
+
 if [ $# -eq 4 ]; then
   out=$4
 else
-  dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
+  dir=$("${BASH:-bash}" "$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
   out="$dir/review-$(git rev-parse --short "$base")..$(git rev-parse --short "$head").diff"
 fi
 

package/skills/subagent-driven-development/scripts/review-package.ps1

@@ -31,6 +31,18 @@ if ($LASTEXITCODE -ne 0) {
     exit 2
 }
 
+& git merge-base --is-ancestor $base $head *> $null
+if ($LASTEXITCODE -ne 0) {
+    [Console]::Error.WriteLine("HEAD ($head) is not a descendant of BASE ($base)")
+    exit 3
+}
+
+$commitCount = (& git rev-list --count "${base}..${head}").Trim()
+if ([int]$commitCount -eq 0) {
+    [Console]::Error.WriteLine("empty commit range: ${base}..${head}")
+    exit 3
+}
+
 if ($args.Count -eq 4) {
     $out = $args[3]
 } else {
@@ -53,7 +65,7 @@ $content.Add("")
 $content.Add("## Diff")
 (& git diff -U10 "${base}..${head}") | ForEach-Object { $content.Add($_) }
 
-Set-Content -Path $out -Value $content -Encoding utf8
+Set-Content -LiteralPath $out -Value $content -Encoding utf8
 $commits = (& git rev-list --count "${base}..${head}").Trim()
 $bytes = (Get-Item -LiteralPath $out).Length
 Write-Output "wrote ${out}: $commits commit(s), $bytes bytes"

package/skills/subagent-driven-development/scripts/sdd-workspace

@@ -3,11 +3,17 @@
 # short-lived artifacts: task briefs, implementer reports, review packages,
 # and the progress ledger. Print the plan directory's absolute path.
 #
-# One directory per plan (.superpowers/sdd/<plan-basename>/) so a follow-up
+# One directory per plan (.superpowers/sdd/<plan-slug>/) so a follow-up
 # plan in the same working tree can never read or overwrite another plan's
 # artifacts. A stale ledger misread as current progress makes controllers
 # skip whole task sequences — plan-scoping removes that failure structurally.
 #
+# Ownership markers (plan-path file in the workspace directory) disambiguate
+# same-basename plans (e.g. docs/alpha/plan.md vs docs/beta/plan.md) by appending
+# the parent-directory name, then a counter. A workspace with no marker
+# predates the marker scheme and is adopted for the current plan so in-flight
+# workspaces keep resolving.
+#
 # The workspace lives in the working tree (not under .git/) because Claude Code
 # treats .git/ as a protected path and denies agent writes there — which blocks
 # an implementer subagent from writing its report file. A self-ignoring
@@ -28,13 +34,46 @@ fi
 plan=$1
 [ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
 
-slug=$(basename "$plan" .md)
+slug=$(basename -- "$plan" .md)
 [ -n "$slug" ] && [ "$slug" != "." ] && [ "$slug" != ".." ] \
   || { echo "cannot derive a workspace name from: $plan" >&2; exit 2; }
 
 root=$(git rev-parse --show-toplevel)
+root=$(CDPATH= cd -- "$root" && pwd -P)
 base="$root/.superpowers/sdd"
+
+# Normalize the plan path (physical directory, so relative/absolute/../
+# spellings of one plan compare equal) and express it as the marker value:
+# repo-relative when the plan lives under the repo root, absolute otherwise.
+plan_dir=$(CDPATH= cd -- "$(dirname -- "$plan")" && pwd -P)
+plan_abs="$plan_dir/$(basename -- "$plan")"
+case "$plan_abs" in
+  "$root"/*) plan_id=${plan_abs#"$root"/} ;;
+  *)         plan_id=$plan_abs ;;
+esac
+
+# True when the workspace at $1 is (or becomes) this plan's: an existing
+# marker must name this plan; a missing marker means a new workspace or a
+# pre-marker legacy one, and either way the plan claims it by writing one.
+owns() {
+  if [ -e "$1/plan-path" ]; then
+    [ "$(cat "$1/plan-path")" = "$plan_id" ]
+  else
+    mkdir -p "$1"
+    printf '%s\n' "$plan_id" > "$1/plan-path"
+  fi
+}
+
 dir="$base/$slug"
-mkdir -p "$dir"
+if ! owns "$dir"; then
+  parent=$(basename -- "$plan_dir")
+  dir="$base/$slug-$parent"
+  if ! owns "$dir"; then
+    n=2
+    while ! owns "$base/$slug-$parent-$n"; do n=$((n + 1)); done
+    dir="$base/$slug-$parent-$n"
+  fi
+fi
+
 printf '*\n' > "$base/.gitignore"
-cd "$dir" && pwd
+CDPATH= cd -- "$dir" && pwd

package/skills/subagent-driven-development/scripts/sdd-workspace.ps1

@@ -30,7 +30,69 @@ if ([string]::IsNullOrEmpty($slug) -or $slug -eq "." -or $slug -eq "..") {
 
 $root = (& git rev-parse --show-toplevel).Trim()
 $base = Join-Path $root ".superpowers/sdd"
+
+function Get-PhysicalDirectoryPath($path) {
+    if (-not (Test-Path -LiteralPath $path)) { return $path }
+    if ($IsWindows) {
+        return (Resolve-Path -LiteralPath $path).Path
+    }
+    $orig = Get-Location
+    try {
+        Set-Location -LiteralPath $path
+        $pwdCmd = (Get-Command -Type Application pwd -ErrorAction SilentlyContinue).Source
+        if ($pwdCmd) {
+            return (& $pwdCmd -P).Trim()
+        } else {
+            return (Resolve-Path -LiteralPath $path).Path
+        }
+    } finally {
+        Set-Location $orig
+    }
+}
+
+# Normalize the plan path (physical directory, so relative/absolute/../
+# spellings of one plan compare equal) and express it as the marker value:
+# repo-relative when the plan lives under the repo root, absolute otherwise.
+$planLeaf = Split-Path -Leaf $plan
+$planParent = Split-Path -Parent $plan
+if ([string]::IsNullOrEmpty($planParent)) { $planParent = "." }
+
+$planDir = Get-PhysicalDirectoryPath $planParent
+$rootPhys = Get-PhysicalDirectoryPath $root
+
+$planAbs = (Join-Path $planDir $planLeaf) -replace '\\', '/'
+$rootNorm = $rootPhys -replace '\\', '/'
+
+if ($planAbs.StartsWith($rootNorm + "/", [System.StringComparison]::OrdinalIgnoreCase)) {
+    $planId = $planAbs.Substring($rootNorm.Length + 1)
+} else {
+    $planId = $planAbs
+}
+
+function Test-And-Claim-Workspace($targetDir, $id) {
+    $markerPath = Join-Path $targetDir "plan-path"
+    if (Test-Path -LiteralPath $markerPath -PathType Leaf) {
+        $existingId = (Get-Content -LiteralPath $markerPath -Raw).Trim()
+        return ($existingId -eq $id)
+    } else {
+        New-Item -ItemType Directory -Force -Path $targetDir | Out-Null
+        Set-Content -LiteralPath $markerPath -Value $id -Encoding ascii
+        return $true
+    }
+}
+
 $dir = Join-Path $base $slug
-New-Item -ItemType Directory -Force -Path $dir | Out-Null
-Set-Content -Path (Join-Path $base ".gitignore") -Value "*" -NoNewline -Encoding ascii
-(Resolve-Path $dir).Path
+if (-not (Test-And-Claim-Workspace $dir $planId)) {
+    $parent = Split-Path -Leaf $planDir
+    $dir = Join-Path $base "$slug-$parent"
+    if (-not (Test-And-Claim-Workspace $dir $planId)) {
+        $n = 2
+        while (-not (Test-And-Claim-Workspace (Join-Path $base "$slug-$parent-$n") $planId)) {
+            $n++
+        }
+        $dir = Join-Path $base "$slug-$parent-$n"
+    }
+}
+
+Set-Content -LiteralPath (Join-Path $base ".gitignore") -Value "*" -NoNewline -Encoding ascii
+(Resolve-Path -LiteralPath $dir).Path

package/skills/subagent-driven-development/scripts/task-brief

@@ -21,7 +21,7 @@ n=$2
 if [ $# -eq 3 ]; then
   out=$3
 else
-  dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
+  dir=$("${BASH:-bash}" "$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
   out="$dir/task-${n}-brief.md"
 fi
 

package/skills/subagent-driven-development/scripts/task-brief.ps1

@@ -42,7 +42,7 @@ foreach ($line in [System.IO.File]::ReadLines((Resolve-Path -LiteralPath $plan).
     }
 }
 
-Set-Content -Path $out -Value $selected -Encoding utf8
+Set-Content -LiteralPath $out -Value $selected -Encoding utf8
 if ((-not (Test-Path -LiteralPath $out)) -or ((Get-Item -LiteralPath $out).Length -eq 0)) {
     [Console]::Error.WriteLine("task $taskNumber not found in $plan (no heading matching 'Task $taskNumber')")
     exit 3

package/skills/test-driven-development/SKILL.md

@@ -182,6 +182,16 @@ Confirm:
 
 **Other tests fail?** Fix now.
 
+**"Other tests" means the project's suite, not just your file.** A
+green run of the test you wrote is not a green suite. Before you call
+the change done, run the project's test command (bare `pytest`,
+`npm test`, `cargo test` — whatever the repo uses) even when your task
+named only one test file. A scope statement in your task bounds the
+deliverable, not your verification. Any failure that run shows —
+including one you didn't cause — goes in your report by name; a red
+test you watched scroll past and didn't mention is a report falsified
+by omission.
+
 ### REFACTOR - Clean Up
 
 After green only:

package/skills/writing-plans/SKILL.md

@@ -22,6 +22,30 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
 
 If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
 
+## Two Plan Shapes
+
+Before mapping files, classify the plan's shape and say the
+classification out loud — "this composes three subsystems, so I'll plan
+it skeleton-first" — so your human partner can override it:
+
+- **Task-by-task (default)** — tasks build the feature a component at a
+  time, each step carrying the actual content the engineer needs. Use it
+  for changes to code that already exists, for a spec that touches one
+  subsystem, and whenever the alternative's conditions do not clearly
+  hold. The rest of this skill describes this shape.
+- **Skeleton-first (alternative)** — Task 1 is the thinnest end-to-end
+  slice through every subsystem the spec composes; later tasks widen it
+  one component at a time, each from a contract rather than written-out
+  code. Use it when the spec composes more than one subsystem AND a
+  running end-to-end slice early is worth a longer total build. Read
+  [skeleton-first-plans.md](skeleton-first-plans.md) before writing one
+  — it adds one line to the plan header and replaces this skill's task
+  granularity, task template, and plan-failure list.
+
+When in doubt, plan task-by-task. Skeleton-first buys an earlier running
+system and pays for it in total wall clock; it is a trade, not an
+upgrade.
+
 ## File Structure
 
 Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.

package/skills/writing-plans/skeleton-first-plans.md

@@ -0,0 +1,131 @@
+# Skeleton-First Plans
+
+The alternative plan shape from writing-plans' Two Plan Shapes router.
+Each section below replaces the same-named section of
+[SKILL.md](SKILL.md); everything SKILL.md says that is not named here
+still binds — Scope Check, File Structure, Task Right-Sizing, the plan
+header, Self-Review, and the Execution Handoff.
+
+## Overview
+
+Write a plan that carries the decisions, not the keystrokes:
+decomposition, file structure, interfaces, constraints, and a precise
+contract per task. Assume the engineer is skilled and designs their own
+code and tests from a precise contract, but knows nothing about our
+codebase, toolset, or problem domain — every name, path, constraint, and
+behavior they must match is stated explicitly. DRY. YAGNI. TDD.
+Frequent commits.
+
+## When This Shape Fits
+
+Use it when the spec composes more than one subsystem and a running
+end-to-end slice early is worth a longer total build: the value arrives
+as soon as real input reaches real output, and every later task widens
+something that already runs.
+
+Do not use it for a change to one subsystem, or when the whole point is
+to land the finished thing as fast as possible. This shape spends its
+first task on a slice that does almost nothing, and it spends planning
+effort on contracts and interfaces the task-by-task shape gets for free
+by writing the code out.
+
+## Plan Document Header
+
+The header is SKILL.md's, plus one line directly under the **Goal:**
+line, which is how executors know which shape they are running:
+
+```markdown
+**Plan shape:** skeleton-first
+```
+
+## Walking Skeleton First
+
+Task 1 builds the thinnest end-to-end slice through every subsystem the
+spec composes — real input to real output — before any task deepens a
+single layer; later tasks widen the skeleton.
+
+The test of a skeleton is that it runs. A first task that builds the
+data loader, the schema, or the config layer is a foundation, not a
+skeleton: nothing runs until something above it exists. A skeleton
+reaches the output — thinly, with one real case — through every
+subsystem the spec names.
+
+## Task Contracts, Not Task Scripts
+
+A task states WHAT must exist when it is done, precisely enough that a
+skilled engineer can build it without asking you anything, without
+prescribing HOW:
+
+- **Goal:** one short paragraph naming the deliverable and its role in
+  the feature.
+- **Success criteria:** concrete, checkable behaviors — exact commands
+  to run and what they must show, the cases tests must cover (including
+  failure cases), constraints that bind the implementation.
+- **Notes:** what the engineer needs and cannot discover alone — spec
+  sections to read, files worth reading first, known pitfalls.
+
+The Interfaces block carries the exact names, signatures, and types;
+the success criteria carry the behaviors; the engineer supplies the
+code and the test design. TDD and frequent commits remain required.
+
+## Task Structure
+
+````markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test.py`
+
+**Interfaces:**
+- Consumes: [what this task uses from earlier tasks — exact signatures]
+- Produces: [what later tasks rely on — exact function names, parameter
+  and return types. A task's implementer sees only their own task; this
+  block is how they learn the names and types neighboring tasks use.]
+
+**Goal:** [one paragraph — the deliverable and its role in the feature]
+
+**Success criteria:**
+- Run: `pytest tests/exact/path/to/test.py -v` — all tests pass; tests
+  cover [the specific behaviors and failure cases, named concretely]
+- [observable behavior the deliverable must exhibit, with the exact
+  command or input/output that demonstrates it]
+- [constraint that binds the implementation, copied from the spec]
+
+**Notes:** [spec sections to read; files to read first; known pitfalls]
+
+**Tier:** mechanical | judgment. Mechanical = the deliverable is fully
+specified by Files + Interfaces + success criteria above (most tasks in
+a well-specified plan are mechanical); judgment = multi-file
+coordination, debugging, or real design latitude remains. The
+implementer's model follows this field — mark it deliberately.
+
+**Commit:** one commit ending the task; message named here.
+````
+
+## No Vague Contracts
+
+Every contract must be checkable by someone who did not write it. These
+are **plan failures** — never write them:
+- "TBD", "TODO", "implement later", "fill in details"
+- Goals naming activity instead of a deliverable ("improve error handling")
+- Success criteria with no observable check ("works correctly", "handles edge cases")
+- Interfaces blocks omitting a name, signature, or type another task consumes
+- "Similar to Task N" (state this task's own contract in full — the engineer may be reading tasks out of order)
+- References to types, functions, or methods not defined in any task's Interfaces block
+
+## Self-Review
+
+Run SKILL.md's Self-Review checklist, reading step 2 against "No Vague
+Contracts" above rather than "No Placeholders".
+
+## Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "Task 1 is the data loader — that's the foundation" | A foundation is a layer. The skeleton runs real input to real output through every subsystem the spec names, thinly. |
+| "The skeleton can return a hardcoded value for now" | It may be thin, but the path must be real: real input, real wiring, real output. A hardcoded response tests nothing end to end. |
+| "A contract without the code is vague" | Vague is an uncheckable success criterion. Exact names, exact commands, exact expected output — no code. |
+| "I'll write the test code into the task to be safe" | The success criteria name the cases; the implementer designs the tests. Written-out tests are the task-by-task shape. |
+| "Skeleton-first is the better shape, so I'll use it here" | It costs total wall clock. Without more than one subsystem and a reason to want an early running slice, plan task-by-task. |

package/skills/writing-skills/render-graphs.js

@@ -15,11 +15,11 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
+const { execFileSync } = require('child_process');
 
 function extractDotBlocks(markdown) {
   const blocks = [];
-  const regex = /```dot\n([\s\S]*?)```/g;
+  const regex = /```dot\r?\n([\s\S]*?)```/g;
   let match;
 
   while ((match = regex.exec(markdown)) !== null) {
@@ -69,7 +69,7 @@ ${bodies.join('\n\n')}
 
 function renderToSvg(dotContent) {
   try {
-    return execSync('dot -Tsvg', {
+    return execFileSync('dot', ['-Tsvg'], {
       input: dotContent,
       encoding: 'utf-8',
       maxBuffer: 10 * 1024 * 1024
@@ -110,11 +110,12 @@ function main() {
   // Check if dot is available. Run the binary directly rather than probing
   // with `which`, which is not a command on Windows.
   try {
-    execSync('dot -V', { stdio: 'ignore', encoding: 'utf-8' });
+    execFileSync('dot', ['-V'], { stdio: 'ignore' });
   } catch {
     console.error('Error: graphviz (dot) not found. Install with:');
-    console.error('  brew install graphviz    # macOS');
-    console.error('  apt install graphviz     # Linux');
+    console.error('  brew install graphviz         # macOS');
+    console.error('  apt install graphviz          # Linux');
+    console.error('  winget install Graphviz.Graphviz # Windows');
     process.exit(1);
   }