@claude-pw/framework 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dcdeve
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,173 @@
+# Claude Project Workflow
+
+[![npm version](https://img.shields.io/npm/v/@claude-pw/framework)](https://www.npmjs.com/package/@claude-pw/framework) [![Tests](https://img.shields.io/github/actions/workflow/status/dcdeve/claude-pw/test.yml?label=tests)](https://github.com/dcdeve/claude-pw/actions) [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+[English](README.md) | **Español** | [中文](README.zh-cn.md) | [日本語](README.ja.md) | [Português](README.pt-br.md)
+
+Workflow estructurado para proyectos con Claude Code.
+
+Claude Code es potente pero sin estructura, los proyectos no triviales se vuelven caóticos — sin plan, sin gestión de contexto, sin quality gates, sin continuidad entre sesiones. claude-pw soluciona esto instalando comandos, agentes, reglas y hooks sobre las features nativas de Claude Code. Node.js + markdown, agnóstico al lenguaje.
+
+## Inicio rápido
+
+### Proyecto nuevo
+
+```bash
+npx @claude-pw/framework mi-proyecto
+cd mi-proyecto && claude
+/cpw-startup
+```
+
+### Proyecto existente
+
+```bash
+cd mi-proyecto-existente
+npx @claude-pw/framework .
+claude
+/cpw-startup
+```
+
+`/cpw-startup` detecta tu codebase automáticamente y pregunta cómo proceder:
+- **Brownfield** — agregar estructura sobre tu código existente (incluye auditoría de tooling)
+- **Bluefield** — planificar una reescritura o migración
+
+### Actualizar
+
+```bash
+npx @claude-pw/framework --update
+```
+
+## Cómo funciona
+
+```
+/cpw-startup → /cpw-discuss → /cpw-next-step (repetir hasta terminar)
+```
+
+1. **`/cpw-startup`** te entrevista, escanea código existente (si hay), y genera un plan con fases, pasos y docs de arquitectura
+2. **`/cpw-discuss`** identifica zonas grises y captura tus preferencias antes de construir (opcional, por fase)
+3. **`/cpw-next-step`** ejecuta un pipeline adaptativo por paso — luego cierra, commitea y avanza automáticamente
+
+Cada paso pasa por:
+
+```
+SPIKE? → DESIGN → BUILD-OR-BUY? → FEASIBILITY? → COMPATIBILITY? → IMPLEMENT → TEST → ACCEPTANCE → CLOSE
+```
+
+Las etapas opcionales se saltan con razón. Las obligatorias (DESIGN, IMPLEMENT, TEST, ACCEPTANCE, CLOSE) siempre corren. Cuando una fase se completa, validación + user acceptance testing corren automáticamente.
+
+STATUS.md siempre le dice a Claude dónde estás y qué cargar. Los sub-planes son pequeños (uno por fase). Los resets de contexto son seguros — `/cpw-next-step` retoma exactamente donde quedaste.
+
+## Ejemplo de sesión
+
+```
+> /cpw-next-step
+
+Fase 1, Paso 1.2: Middleware de contexto de tenant
+
+Pipeline:
+- SPIKE: skip (patrón estándar)
+- DESIGN: ok
+- BUILD-OR-BUY: skip (middleware custom)
+- COMPATIBILITY: ok (verificar contra interfaz Auth)
+- IMPLEMENT: ok
+- TEST: ok
+- ACCEPTANCE: ok
+- CLOSE: ok
+
+¿Procedo con DESIGN?
+```
+
+Cuando todos los pasos de una fase se completan:
+
+```
+Validación de fase... APROBADA
+Walkthrough de UAT:
+
+[1/3] Login de usuario — ¿Funciona? > sí
+[2/3] Cambio de tenant — ¿Funciona? > el selector no cambia el contexto
+
+Issue capturado. ¿Arreglar ahora? (sí/no)
+```
+
+## Qué lo hace diferente
+
+| | claude-pw | BMAD | GSD | Taskmaster |
+|---|---|---|---|---|
+| **Pipeline** | 9 etapas adaptativas por paso | Fijo por macro-fase | 3 etapas fijas por fase | Ninguno |
+| **Contexto** | Puntero STATUS.md (~50 líneas) + monitor runtime | Docs progresivos pesados | Monitor de contexto + subagentes frescos | Sin gestión |
+| **Quality gates** | Validador de fase + UAT + pre-commit + RFC | Readiness check + code review + DoD | Verificador + UAT | Checker opcional |
+| **Self-learning** | Captura por hook + reflect + extracción de skills | Ninguno | Ninguno | Básico |
+| **Protección de interfaces** | Contratos protegidos por RFC + contract tests | Docs de arquitectura | Ninguno | Ninguno |
+| **Automatización** | 3 modos (manual / auto / yolo) | Manual | Totalmente autónomo | Semi-auto |
+
+**Solo en claude-pw:**
+- Pipeline adaptativo que evalúa qué etapas aplican por paso (SPIKE, BUILD-OR-BUY, FEASIBILITY, COMPATIBILITY se saltan con razón cuando no aplican)
+- Desarrollo interface-first con protección RFC y contract tests
+- Correcciones capturadas automáticamente y ruteadas al comando que las causó (skill routing)
+- Descubrimientos no obvios auto-extraídos como skills reutilizables para retrieval semántico
+- SPIKE y BUILD-OR-BUY como etapas de primera clase en el pipeline
+- Modos de startup (greenfield / brownfield / bluefield) con entrevista estructurada adaptada a cada uno
+- Auditoría de tooling para proyectos brownfield (linter, tests, CI, pre-commit, dependencias)
+
+## Comandos
+
+| Comando | Qué hace |
+|---------|----------|
+| `/cpw-startup` | Sesión de discovery — detecta modo, entrevista, genera plan |
+| `/cpw-discuss` | Captura preferencias y resuelve ambigüedades antes de construir |
+| `/cpw-next-step` | Ejecuta pipeline, cierra pasos, valida fases, corre UAT |
+| `/cpw-pause` | Guarda estado de sesión para retomar después |
+| `/cpw-quick` | Tarea ad-hoc fuera del pipeline (detección de scope-creep, `--auto`) |
+| `/cpw-debug` | Sesión de debug persistente — sobrevive resets de contexto |
+| `/cpw-health` | Verifica y repara estado del proyecto |
+| `/cpw-todos` | Captura ideas para después o revisa todos pendientes |
+| `/cpw-reflect` | Revisa correcciones capturadas, convierte en learnings (`--scan-history`, `--dedupe`) |
+| `/cpw-impact` | Analiza impacto de decisiones en todo el plan |
+
+## Configuración
+
+`/cpw-startup` pregunta tus preferencias y las guarda en `.planning/config.json`:
+
+| Setting | Opciones | Default | Qué hace |
+|---------|----------|---------|----------|
+| `autoAdvance` | `off` / `auto` / `yolo` | `off` | `off` = aprobar cada etapa. `auto` = auto-avanzar, pausar para UAT. `yolo` = pausar solo en errores. |
+| `granularity` | `coarse` / `standard` / `fine` | `standard` | Cuántas fases: 3-5 / 5-8 / 8-12 |
+| `modelProfile` | `quality` / `balanced` / `budget` | `balanced` | Modelos de agentes: opus / sonnet+haiku / mayormente haiku |
+| `modelOverrides` | `{}` | `{}` | Overrides por agente: `{"researcher": "opus"}` |
+| `gitStrategy` | `trunk-based` / `feature-branch` / `gitflow` | `trunk-based` | `trunk-based` = push a main. `feature-branch` = rama por fase, PR para merge. `gitflow` = develop + feature branches. |
+| `commitPlanning` | `true` / `false` | `false` | Trackear `.planning/` en git (para equipos) |
+| `autoReflect` | `off` / `remind` / `auto` | `remind` | Auto-procesar learnings al fin de sesión o en CLOSE |
+
+## Qué va en git
+
+| Qué | Commiteado | Gitignored | Por qué |
+|-----|------------|------------|---------|
+| `.claude/` (comandos, agentes, reglas, hooks) | Sí | — | Workflow compartido — todo el equipo usa el mismo pipeline |
+| `CLAUDE.md`, `PLAN.md`, `Makefile` | Sí | — | Estructura e instrucciones del proyecto |
+| `plans/`, `docs/` | Sí | — | Planes, arquitectura, decisiones, convenciones |
+| `.planning/` (config, learnings, debug, quick log) | Configurable | Default: gitignored | Usar `commitPlanning: true` para compartir estado con el equipo |
+| `STATUS.md` | — | Siempre | Puntero de sesión personal — cada dev tiene el suyo |
+| `.claude/settings.local.json` | — | Siempre | Settings personales de Claude Code |
+
+## Qué se instala
+
+```
+mi-proyecto/
+├── .claude/
+│   ├── commands/       10 slash commands (/cpw-*)
+│   ├── agents/         11 agentes especializados
+│   ├── rules/          3 reglas context-aware (git, interfaces, testing)
+│   ├── hooks/          Hooks Node.js (statusline, monitor de contexto)
+│   └── settings.json
+├── plans/              Sub-planes por fase + log de decisiones
+├── docs/               Arquitectura, interfaces, convenciones
+├── .planning/          Estado local (gitignored)
+├── CLAUDE.md           Instrucciones para el agente
+├── PLAN.md             Índice del proyecto
+├── STATUS.md           Puntero de sesión (gitignored)
+└── Makefile            make status / plan / check / commit / push
+```
+
+## Licencia
+
+MIT

package/README.ja.md

@@ -0,0 +1,173 @@
+# Claude Project Workflow
+
+[![npm version](https://img.shields.io/npm/v/@claude-pw/framework)](https://www.npmjs.com/package/@claude-pw/framework) [![Tests](https://img.shields.io/github/actions/workflow/status/dcdeve/claude-pw/test.yml?label=tests)](https://github.com/dcdeve/claude-pw/actions) [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+[English](README.md) | [Español](README.es.md) | [中文](README.zh-cn.md) | **日本語** | [Português](README.pt-br.md)
+
+Claude Code のための構造化プロジェクトワークフロー。
+
+Claude Code は強力ですが、構造がなければ非自明なプロジェクトは混沌とします — 計画なし、コンテキスト管理なし、品質ゲートなし、セッション間の継続性なし。claude-pw は Claude Code のネイティブ機能の上にコマンド、エージェント、ルール、フックをインストールすることでこれを解決します。純粋な Node.js + markdown、言語非依存。
+
+## クイックスタート
+
+### 新規プロジェクト
+
+```bash
+npx @claude-pw/framework my-project
+cd my-project && claude
+/cpw-startup
+```
+
+### 既存プロジェクト
+
+```bash
+cd my-existing-project
+npx @claude-pw/framework .
+claude
+/cpw-startup
+```
+
+`/cpw-startup` はコードベースを自動検出し、進め方を確認します：
+- **Brownfield** — 既存コードの上に構造を追加（ツール健全性チェック含む）
+- **Bluefield** — リライトまたはマイグレーションを計画
+
+### アップデート
+
+```bash
+npx @claude-pw/framework --update
+```
+
+## 仕組み
+
+```
+/cpw-startup → /cpw-discuss → /cpw-next-step（完了まで繰り返し）
+```
+
+1. **`/cpw-startup`** インタビューを行い、既存コード（あれば）をスキャンし、フェーズ・ステップ・アーキテクチャドキュメントを含む計画を生成
+2. **`/cpw-discuss`** グレーゾーンを特定し、ビルド前にあなたの好みを把握（任意、フェーズごと）
+3. **`/cpw-next-step`** ステップごとに適応型パイプラインを実行 — 完了後、自動的にクローズ・コミット・次へ進行
+
+各ステップは以下を経由します：
+
+```
+SPIKE? → DESIGN → BUILD-OR-BUY? → FEASIBILITY? → COMPATIBILITY? → IMPLEMENT → TEST → ACCEPTANCE → CLOSE
+```
+
+オプションステージは理由付きでスキップされます。必須ステージ（DESIGN, IMPLEMENT, TEST, ACCEPTANCE, CLOSE）は常に実行されます。フェーズ完了時、バリデーション + ユーザー受入テストが自動実行されます。
+
+STATUS.md は常に Claude に現在地と読み込むべきものを伝えます。サブプランは小さく保たれます（フェーズごとに1つ）。コンテキストリセットは安全です — `/cpw-next-step` は中断した場所から正確に再開します。
+
+## セッション例
+
+```
+> /cpw-next-step
+
+Phase 1, Step 1.2: Tenant context middleware
+
+Pipeline:
+- SPIKE: skip (standard pattern)
+- DESIGN: ok
+- BUILD-OR-BUY: skip (custom middleware)
+- COMPATIBILITY: ok (verify against Auth interface)
+- IMPLEMENT: ok
+- TEST: ok
+- ACCEPTANCE: ok
+- CLOSE: ok
+
+Proceed with DESIGN?
+```
+
+フェーズ内の全ステップが完了すると：
+
+```
+Phase validation... APPROVED
+UAT walkthrough:
+
+[1/3] User login — Does it work? > yes
+[2/3] Tenant switching — Does it work? > selector doesn't switch context
+
+Issue captured. Fix now? (yes/no)
+```
+
+## 他との違い
+
+| | claude-pw | BMAD | GSD | Taskmaster |
+|---|---|---|---|---|
+| **パイプライン** | ステップごとに9つの適応型ステージ | マクロフェーズごとに固定 | フェーズごとに3つの固定ステージ | なし |
+| **コンテキスト** | STATUS.md ポインター（約50行）+ ランタイムモニター | 重い漸進的ドキュメント | コンテキストモニター + 新規サブエージェント | 管理なし |
+| **品質ゲート** | フェーズバリデーター + UAT + pre-commit + RFC | 準備チェック + コードレビュー + DoD | ベリファイヤー + UAT | オプションチェッカー |
+| **自己学習** | フックキャプチャ + リフレクト + スキル抽出 | なし | なし | 基本的 |
+| **インターフェース保護** | RFC 保護されたコントラクト + コントラクトテスト | アーキテクチャドキュメント | なし | なし |
+| **自動化** | 3モード（manual / auto / yolo） | 手動 | 完全自律 | 半自動 |
+
+**claude-pw だけの機能：**
+- ステップごとに適用するステージを評価する適応型パイプライン（SPIKE, BUILD-OR-BUY, FEASIBILITY, COMPATIBILITY は該当しない場合、理由付きでスキップ）
+- RFC 保護とコントラクトテストによるインターフェースファーストの開発
+- 修正が自動キャプチャされ、原因となったコマンドにルーティング（スキルルーティング）
+- 非自明な発見がセマンティック検索用の再利用可能スキルとして自動抽出
+- SPIKE と BUILD-OR-BUY をファーストクラスのパイプラインステージとして搭載
+- スタートアップモード（greenfield / brownfield / bluefield）と各モードに適応した構造化インタビュー
+- Brownfield プロジェクト向けツール健全性チェック（リンター、テスト、CI、pre-commit、依存関係）
+
+## コマンド
+
+| コマンド | 機能 |
+|---------|-------------|
+| `/cpw-startup` | ディスカバリーセッション — モード検出、インタビュー、計画生成 |
+| `/cpw-discuss` | ビルド前に好みの把握と曖昧さの解消 |
+| `/cpw-next-step` | パイプライン実行、ステップクローズ、フェーズバリデーション、UAT 実行 |
+| `/cpw-pause` | セッション状態を保存して後で再開 |
+| `/cpw-quick` | パイプライン外のアドホックタスク（スコープクリープ検出、`--auto`） |
+| `/cpw-debug` | 永続デバッグセッション — コンテキストリセット後も継続 |
+| `/cpw-health` | プロジェクト状態のチェックと修復 |
+| `/cpw-todos` | アイデアの記録または保留中の TODO の確認 |
+| `/cpw-reflect` | キャプチャした修正をレビューし、学習に変換（`--scan-history`, `--dedupe`） |
+| `/cpw-impact` | 計画全体にわたる意思決定の影響分析 |
+
+## 設定
+
+`/cpw-startup` で好みを確認し、`.planning/config.json` に保存します：
+
+| 設定 | オプション | デフォルト | 機能 |
+|---------|---------|---------|-------------|
+| `autoAdvance` | `off` / `auto` / `yolo` | `off` | `off` = 各ステージを承認。`auto` = 自動進行、UAT で一時停止。`yolo` = エラー時のみ一時停止。 |
+| `granularity` | `coarse` / `standard` / `fine` | `standard` | フェーズ数：3-5 / 5-8 / 8-12 |
+| `modelProfile` | `quality` / `balanced` / `budget` | `balanced` | エージェントモデル：opus / sonnet+haiku / ほぼ haiku |
+| `modelOverrides` | `{}` | `{}` | エージェントごとのオーバーライド：`{"researcher": "opus"}` |
+| `gitStrategy` | `trunk-based` / `feature-branch` / `gitflow` | `trunk-based` | `trunk-based` = main にプッシュ。`feature-branch` = フェーズごとにブランチ、PR でマージ。`gitflow` = develop + feature ブランチ。 |
+| `commitPlanning` | `true` / `false` | `false` | `.planning/` を git で追跡（チーム向け） |
+| `autoReflect` | `off` / `remind` / `auto` | `remind` | セッション終了時または CLOSE ステージで学習を自動処理 |
+
+## git に入れるもの
+
+| 対象 | コミット | Gitignore | 理由 |
+|------|-----------|------------|-----|
+| `.claude/`（コマンド、エージェント、ルール、フック） | する | — | 共有ワークフロー — チーム全員が同じパイプラインを使用 |
+| `CLAUDE.md`, `PLAN.md`, `Makefile` | する | — | プロジェクト構造と手順 |
+| `plans/`, `docs/` | する | — | 計画、アーキテクチャ、決定事項、規約 |
+| `.planning/`（設定、学習、デバッグ、クイックログ） | 設定可能 | デフォルト：gitignore | `commitPlanning: true` でチームと計画状態を共有 |
+| `STATUS.md` | — | 常に | 個人のセッションポインター — 各開発者が独自に持つ |
+| `.claude/settings.local.json` | — | 常に | 個人の Claude Code 設定 |
+
+## 生成されるもの
+
+```
+my-project/
+├── .claude/
+│   ├── commands/       10個のスラッシュコマンド (/cpw-*)
+│   ├── agents/         11個の専門エージェント
+│   ├── rules/          3つのコンテキスト対応ルール（git、インターフェース、テスト）
+│   ├── hooks/          Node.js フック（ステータスライン、コンテキストモニター）
+│   └── settings.json
+├── plans/              フェーズごとのサブプラン + 決定ログ
+├── docs/               アーキテクチャ、インターフェース、規約
+├── .planning/          ローカル状態（gitignore）
+├── CLAUDE.md           エージェント向け手順
+├── PLAN.md             プロジェクトインデックス
+├── STATUS.md           セッションポインター（gitignore）
+└── Makefile            make status / plan / check / commit / push
+```
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,173 @@
+# Claude Project Workflow
+
+[![npm version](https://img.shields.io/npm/v/@claude-pw/framework)](https://www.npmjs.com/package/@claude-pw/framework) [![Tests](https://img.shields.io/github/actions/workflow/status/dcdeve/claude-pw/test.yml?label=tests)](https://github.com/dcdeve/claude-pw/actions) [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+**English** | [Español](README.es.md) | [中文](README.zh-cn.md) | [日本語](README.ja.md) | [Português](README.pt-br.md)
+
+Structured Project Workflow for Claude Code.
+
+Claude Code is powerful but without structure, non-trivial projects get chaotic — no plan, no context management, no quality gates, no continuity between sessions. claude-pw fixes this by installing commands, agents, rules, and hooks on top of Claude Code's native features. Pure Node.js + markdown, language-agnostic.
+
+## Quick start
+
+### New project
+
+```bash
+npx @claude-pw/framework my-project
+cd my-project && claude
+/cpw-startup
+```
+
+### Existing project
+
+```bash
+cd my-existing-project
+npx @claude-pw/framework .
+claude
+/cpw-startup
+```
+
+`/cpw-startup` auto-detects your codebase and asks how you want to proceed:
+- **Brownfield** — add structure on top of your existing code (includes tooling health check)
+- **Bluefield** — plan a rewrite or migration
+
+### Update
+
+```bash
+npx @claude-pw/framework --update
+```
+
+## How it works
+
+```
+/cpw-startup → /cpw-discuss → /cpw-next-step (repeat until done)
+```
+
+1. **`/cpw-startup`** interviews you, scans existing code (if any), and generates a plan with phases, steps, and architecture docs
+2. **`/cpw-discuss`** identifies gray areas and captures your preferences before building (optional, per phase)
+3. **`/cpw-next-step`** runs an adaptive pipeline per step — then closes, commits, and advances automatically
+
+Every step goes through:
+
+```
+SPIKE? → DESIGN → BUILD-OR-BUY? → FEASIBILITY? → COMPATIBILITY? → IMPLEMENT → TEST → ACCEPTANCE → CLOSE
+```
+
+Optional stages are skipped with reason. Mandatory stages (DESIGN, IMPLEMENT, TEST, ACCEPTANCE, CLOSE) always run. When a phase completes, validation + user acceptance testing run automatically.
+
+STATUS.md always tells Claude where you are and what to load. Sub-plans stay small (one per phase). Context resets are safe — `/cpw-next-step` picks up exactly where you left off.
+
+## Example session
+
+```
+> /cpw-next-step
+
+Phase 1, Step 1.2: Tenant context middleware
+
+Pipeline:
+- SPIKE: skip (standard pattern)
+- DESIGN: ok
+- BUILD-OR-BUY: skip (custom middleware)
+- COMPATIBILITY: ok (verify against Auth interface)
+- IMPLEMENT: ok
+- TEST: ok
+- ACCEPTANCE: ok
+- CLOSE: ok
+
+Proceed with DESIGN?
+```
+
+When all steps in a phase complete:
+
+```
+Phase validation... APPROVED
+UAT walkthrough:
+
+[1/3] User login — Does it work? > yes
+[2/3] Tenant switching — Does it work? > selector doesn't switch context
+
+Issue captured. Fix now? (yes/no)
+```
+
+## What makes it different
+
+| | claude-pw | BMAD | GSD | Taskmaster |
+|---|---|---|---|---|
+| **Pipeline** | 9 adaptive stages per step | Fixed per macro-phase | 3 fixed stages per phase | None |
+| **Context** | STATUS.md pointer (~50 lines) + runtime monitor | Heavy progressive docs | Context monitor + fresh subagents | No management |
+| **Quality gates** | Phase validator + UAT + pre-commit + RFC | Readiness check + code review + DoD | Verifier + UAT | Optional checker |
+| **Self-learning** | Hook capture + reflect + skill extraction | None | None | Basic |
+| **Interface protection** | RFC-protected contracts + contract tests | Architecture docs | None | None |
+| **Automation** | 3 modes (manual / auto / yolo) | Manual | Full autonomous | Semi-auto |
+
+**Only in claude-pw:**
+- Adaptive pipeline that evaluates which stages apply per step (SPIKE, BUILD-OR-BUY, FEASIBILITY, COMPATIBILITY skipped with reason when they don't apply)
+- Interface-first development with RFC protection and contract tests
+- Corrections captured automatically and routed back to the command that caused them (skill routing)
+- Non-obvious discoveries auto-extracted as reusable skills for semantic retrieval
+- SPIKE and BUILD-OR-BUY as first-class pipeline stages
+- Startup modes (greenfield / brownfield / bluefield) with structured interview adapted to each
+- Tooling health check for brownfield projects (linter, tests, CI, pre-commit, dependencies)
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/cpw-startup` | Discovery session — detect mode, interview, generate plan |
+| `/cpw-discuss` | Capture preferences and resolve ambiguities before building |
+| `/cpw-next-step` | Execute pipeline, close steps, validate phases, run UAT |
+| `/cpw-pause` | Save session state for later resume |
+| `/cpw-quick` | Ad-hoc task outside the pipeline (scope-creep detection, `--auto`) |
+| `/cpw-debug` | Persistent debug session — survives context resets |
+| `/cpw-health` | Check and repair project state |
+| `/cpw-todos` | Capture ideas for later or review pending todos |
+| `/cpw-reflect` | Review captured corrections, convert to learnings (`--scan-history`, `--dedupe`) |
+| `/cpw-impact` | Analyze decision impact across the entire plan |
+
+## Configuration
+
+`/cpw-startup` asks your preferences and saves them to `.planning/config.json`:
+
+| Setting | Options | Default | What it does |
+|---------|---------|---------|-------------|
+| `autoAdvance` | `off` / `auto` / `yolo` | `off` | `off` = approve each stage. `auto` = auto-advance, pause for UAT. `yolo` = pause only on errors. |
+| `granularity` | `coarse` / `standard` / `fine` | `standard` | How many phases: 3-5 / 5-8 / 8-12 |
+| `modelProfile` | `quality` / `balanced` / `budget` | `balanced` | Agent models: opus / sonnet+haiku / mostly haiku |
+| `modelOverrides` | `{}` | `{}` | Per-agent overrides: `{"researcher": "opus"}` |
+| `gitStrategy` | `trunk-based` / `feature-branch` / `gitflow` | `trunk-based` | `trunk-based` = push to main. `feature-branch` = branch per phase, PR to merge. `gitflow` = develop + feature branches. |
+| `commitPlanning` | `true` / `false` | `false` | Track `.planning/` in git (for teams) |
+| `autoReflect` | `off` / `remind` / `auto` | `remind` | Auto-process learnings at session end or CLOSE stage |
+
+## What goes in git
+
+| What | Committed | Gitignored | Why |
+|------|-----------|------------|-----|
+| `.claude/` (commands, agents, rules, hooks) | Yes | — | Shared workflow — everyone on the team uses the same pipeline |
+| `CLAUDE.md`, `PLAN.md`, `Makefile` | Yes | — | Project structure and instructions |
+| `plans/`, `docs/` | Yes | — | Plans, architecture, decisions, conventions |
+| `.planning/` (config, learnings, debug, quick log) | Configurable | Default: gitignored | Set `commitPlanning: true` to share planning state with your team |
+| `STATUS.md` | — | Always | Personal session pointer — each dev has their own |
+| `.claude/settings.local.json` | — | Always | Personal Claude Code settings |
+
+## What you get
+
+```
+my-project/
+├── .claude/
+│   ├── commands/       10 slash commands (/cpw-*)
+│   ├── agents/         11 specialized agents
+│   ├── rules/          3 context-aware rules (git, interfaces, testing)
+│   ├── hooks/          Node.js hooks (statusline, context monitor)
+│   └── settings.json
+├── plans/              Sub-plans per phase + decisions log
+├── docs/               Architecture, interfaces, conventions
+├── .planning/          Local state (gitignored)
+├── CLAUDE.md           Agent instructions
+├── PLAN.md             Project index
+├── STATUS.md           Session pointer (gitignored)
+└── Makefile            make status / plan / check / commit / push
+```
+
+## License
+
+MIT