@claude-pw/framework 0.3.0

package/README.pt-br.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) | [日本語](README.ja.md) | **Português**
+
+Fluxo de trabalho estruturado para projetos com Claude Code.
+
+Claude Code é poderoso, mas sem estrutura, projetos não triviais viram caos — sem plano, sem gestão de contexto, sem portões de qualidade, sem continuidade entre sessões. claude-pw resolve isso instalando comandos, agentes, regras e hooks sobre os recursos nativos do Claude Code. Node.js puro + markdown, agnóstico de linguagem.
+
+## Início rápido
+
+### Novo projeto
+
+```bash
+npx @claude-pw/framework my-project
+cd my-project && claude
+/cpw-startup
+```
+
+### Projeto existente
+
+```bash
+cd my-existing-project
+npx @claude-pw/framework .
+claude
+/cpw-startup
+```
+
+`/cpw-startup` detecta automaticamente seu código e pergunta como você quer prosseguir:
+- **Brownfield** — adicionar estrutura sobre seu código existente (inclui verificação de saúde do tooling)
+- **Bluefield** — planejar uma reescrita ou migração
+
+### Atualização
+
+```bash
+npx @claude-pw/framework --update
+```
+
+## Como funciona
+
+```
+/cpw-startup → /cpw-discuss → /cpw-next-step (repetir até concluir)
+```
+
+1. **`/cpw-startup`** entrevista você, analisa o código existente (se houver) e gera um plano com fases, etapas e documentos de arquitetura
+2. **`/cpw-discuss`** identifica áreas cinzentas e captura suas preferências antes de construir (opcional, por fase)
+3. **`/cpw-next-step`** executa um pipeline adaptativo por etapa — então fecha, commita e avança automaticamente
+
+Cada etapa passa por:
+
+```
+SPIKE? → DESIGN → BUILD-OR-BUY? → FEASIBILITY? → COMPATIBILITY? → IMPLEMENT → TEST → ACCEPTANCE → CLOSE
+```
+
+Estágios opcionais são pulados com justificativa. Estágios obrigatórios (DESIGN, IMPLEMENT, TEST, ACCEPTANCE, CLOSE) sempre executam. Quando uma fase é concluída, validação + testes de aceitação do usuário executam automaticamente.
+
+STATUS.md sempre diz ao Claude onde você está e o que carregar. Sub-planos permanecem pequenos (um por fase). Resets de contexto são seguros — `/cpw-next-step` retoma exatamente de onde você parou.
+
+## Exemplo de sessão
+
+```
+> /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?
+```
+
+Quando todas as etapas de uma fase são concluídas:
+
+```
+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)
+```
+
+## O que torna diferente
+
+| | claude-pw | BMAD | GSD | Taskmaster |
+|---|---|---|---|---|
+| **Pipeline** | 9 estágios adaptativos por etapa | Fixo por macro-fase | 3 estágios fixos por fase | Nenhum |
+| **Contexto** | Ponteiro STATUS.md (~50 linhas) + monitor em runtime | Documentação progressiva pesada | Monitor de contexto + subagentes novos | Sem gestão |
+| **Portões de qualidade** | Validador de fase + UAT + pre-commit + RFC | Verificação de prontidão + revisão de código + DoD | Verificador + UAT | Verificador opcional |
+| **Auto-aprendizado** | Captura via hook + reflexão + extração de skills | Nenhum | Nenhum | Básico |
+| **Proteção de interfaces** | Contratos protegidos por RFC + testes de contrato | Documentos de arquitetura | Nenhum | Nenhum |
+| **Automação** | 3 modos (manual / auto / yolo) | Manual | Totalmente autônomo | Semi-auto |
+
+**Apenas no claude-pw:**
+- Pipeline adaptativo que avalia quais estágios se aplicam por etapa (SPIKE, BUILD-OR-BUY, FEASIBILITY, COMPATIBILITY pulados com justificativa quando não se aplicam)
+- Desenvolvimento interface-first com proteção por RFC e testes de contrato
+- Correções capturadas automaticamente e roteadas de volta ao comando que as causou (roteamento de skills)
+- Descobertas não óbvias auto-extraídas como skills reutilizáveis para recuperação semântica
+- SPIKE e BUILD-OR-BUY como estágios de primeira classe no pipeline
+- Modos de inicialização (greenfield / brownfield / bluefield) com entrevista estruturada adaptada a cada um
+- Verificação de saúde do tooling para projetos brownfield (linter, testes, CI, pre-commit, dependências)
+
+## Comandos
+
+| Comando | O que faz |
+|---------|-----------|
+| `/cpw-startup` | Sessão de descoberta — detectar modo, entrevistar, gerar plano |
+| `/cpw-discuss` | Capturar preferências e resolver ambiguidades antes de construir |
+| `/cpw-next-step` | Executar pipeline, fechar etapas, validar fases, executar UAT |
+| `/cpw-pause` | Salvar estado da sessão para retomar depois |
+| `/cpw-quick` | Tarefa avulsa fora do pipeline (detecção de scope-creep, `--auto`) |
+| `/cpw-debug` | Sessão de debug persistente — sobrevive a resets de contexto |
+| `/cpw-health` | Verificar e reparar estado do projeto |
+| `/cpw-todos` | Capturar ideias para depois ou revisar todos pendentes |
+| `/cpw-reflect` | Revisar correções capturadas, converter em aprendizados (`--scan-history`, `--dedupe`) |
+| `/cpw-impact` | Analisar impacto de decisões em todo o plano |
+
+## Configuração
+
+`/cpw-startup` pergunta suas preferências e salva em `.planning/config.json`:
+
+| Configuração | Opções | Padrão | O que faz |
+|---------|---------|---------|-----------|
+| `autoAdvance` | `off` / `auto` / `yolo` | `off` | `off` = aprovar cada estágio. `auto` = avançar automaticamente, pausar para UAT. `yolo` = pausar apenas em erros. |
+| `granularity` | `coarse` / `standard` / `fine` | `standard` | Quantas fases: 3-5 / 5-8 / 8-12 |
+| `modelProfile` | `quality` / `balanced` / `budget` | `balanced` | Modelos dos agentes: opus / sonnet+haiku / maioria haiku |
+| `modelOverrides` | `{}` | `{}` | Overrides por agente: `{"researcher": "opus"}` |
+| `gitStrategy` | `trunk-based` / `feature-branch` / `gitflow` | `trunk-based` | `trunk-based` = push para main. `feature-branch` = branch por fase, PR para merge. `gitflow` = develop + feature branches. |
+| `commitPlanning` | `true` / `false` | `false` | Rastrear `.planning/` no git (para equipes) |
+| `autoReflect` | `off` / `remind` / `auto` | `remind` | Processar aprendizados automaticamente no fim da sessão ou no estágio CLOSE |
+
+## O que vai no git
+
+| O quê | Commitado | Gitignored | Por quê |
+|-------|-----------|------------|---------|
+| `.claude/` (comandos, agentes, regras, hooks) | Sim | — | Fluxo compartilhado — todos na equipe usam o mesmo pipeline |
+| `CLAUDE.md`, `PLAN.md`, `Makefile` | Sim | — | Estrutura e instruções do projeto |
+| `plans/`, `docs/` | Sim | — | Planos, arquitetura, decisões, convenções |
+| `.planning/` (config, aprendizados, debug, log de quick) | Configurável | Padrão: gitignored | Defina `commitPlanning: true` para compartilhar o estado de planejamento com sua equipe |
+| STATUS.md | — | Sempre | Ponteiro de sessão pessoal — cada dev tem o seu |
+| `.claude/settings.local.json` | — | Sempre | Configurações pessoais do Claude Code |
+
+## O que você recebe
+
+```
+my-project/
+├── .claude/
+│   ├── commands/       10 slash commands (/cpw-*)
+│   ├── agents/         11 agentes especializados
+│   ├── rules/          3 regras sensíveis ao contexto (git, interfaces, testes)
+│   ├── hooks/          Hooks Node.js (statusline, monitor de contexto)
+│   └── settings.json
+├── plans/              Sub-planos por fase + log de decisões
+├── docs/               Arquitetura, interfaces, convenções
+├── .planning/          Estado local (gitignored)
+├── CLAUDE.md           Instruções para agentes
+├── PLAN.md             Índice do projeto
+├── STATUS.md           Ponteiro de sessão (gitignored)
+└── Makefile            make status / plan / check / commit / push
+```
+
+## Licença
+
+MIT

package/README.zh-cn.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.ja.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 你在哪里以及需要加载什么。子计划保持小巧（每个阶段一个）。上下文重置是安全的——`/cpw-next-step` 会准确地从你离开的地方继续。
+
+## 会话示例
+
+```
+> /cpw-next-step
+
+阶段 1，步骤 1.2：租户上下文中间件
+
+流水线：
+- SPIKE: skip（标准模式）
+- DESIGN: ok
+- BUILD-OR-BUY: skip（自定义中间件）
+- COMPATIBILITY: ok（针对 Auth 接口验证）
+- IMPLEMENT: ok
+- TEST: ok
+- ACCEPTANCE: ok
+- CLOSE: ok
+
+继续 DESIGN？
+```
+
+当一个阶段的所有步骤完成时：
+
+```
+阶段验证... 通过
+UAT 演练：
+
+[1/3] 用户登录 — 是否正常？> 是
+[2/3] 租户切换 — 是否正常？> 选择器没有切换上下文
+
+问题已捕获。现在修复？（是/否）
+```
+
+## 差异化优势
+
+| | claude-pw | BMAD | GSD | Taskmaster |
+|---|---|---|---|---|
+| **流水线** | 每步 9 个自适应阶段 | 按宏阶段固定 | 每阶段 3 个固定阶段 | 无 |
+| **上下文** | STATUS.md 指针（约 50 行）+ 运行时监控 | 重型渐进式文档 | 上下文监控 + 新子代理 | 无管理 |
+| **质量门控** | 阶段验证器 + UAT + pre-commit + RFC | 就绪检查 + 代码审查 + DoD | 验证器 + UAT | 可选检查器 |
+| **自学习** | Hook 捕获 + reflect + 技能提取 | 无 | 无 | 基础 |
+| **接口保护** | RFC 保护的契约 + 契约测试 | 架构文档 | 无 | 无 |
+| **自动化** | 3 种模式（手动 / 自动 / yolo） | 手动 | 完全自主 | 半自动 |
+
+**claude-pw 独有：**
+- 自适应流水线，评估每步适用哪些阶段（SPIKE、BUILD-OR-BUY、FEASIBILITY、COMPATIBILITY 不适用时附带原因跳过）
+- 接口优先开发，RFC 保护和契约测试
+- 自动捕获修正并路由回导致它们的命令（技能路由）
+- 非显而易见的发现自动提取为可重用技能，用于语义检索
+- SPIKE 和 BUILD-OR-BUY 作为流水线的一等阶段
+- 启动模式（greenfield / brownfield / bluefield），每种都有适配的结构化访谈
+- Brownfield 项目的工具健康检查（linter、测试、CI、pre-commit、依赖）
+
+## 命令
+
+| 命令 | 功能 |
+|------|------|
+| `/cpw-startup` | 发现会话——检测模式、访谈、生成计划 |
+| `/cpw-discuss` | 构建前捕获偏好和解决歧义 |
+| `/cpw-next-step` | 执行流水线、关闭步骤、验证阶段、运行 UAT |
+| `/cpw-pause` | 保存会话状态以便稍后恢复 |
+| `/cpw-quick` | 流水线外的临时任务（范围蔓延检测、`--auto`） |
+| `/cpw-debug` | 持久化调试会话——跨上下文重置存活 |
+| `/cpw-health` | 检查和修复项目状态 |
+| `/cpw-todos` | 捕获想法或查看待办事项 |
+| `/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` | 在 git 中跟踪 `.planning/`（团队使用） |
+| `autoReflect` | `off` / `remind` / `auto` | `remind` | 在会话结束或 CLOSE 阶段自动处理学习成果 |
+
+## Git 中的内容
+
+| 内容 | 提交 | Gitignored | 原因 |
+|------|------|------------|------|
+| `.claude/`（命令、代理、规则、钩子） | 是 | — | 共享工作流——团队中每个人使用相同的流水线 |
+| `CLAUDE.md`、`PLAN.md`、`Makefile` | 是 | — | 项目结构和指令 |
+| `plans/`、`docs/` | 是 | — | 计划、架构、决策、约定 |
+| `.planning/`（配置、学习、调试、快速日志） | 可配置 | 默认：gitignored | 设置 `commitPlanning: true` 与团队共享规划状态 |
+| `STATUS.md` | — | 始终 | 个人会话指针——每个开发者有自己的 |
+| `.claude/settings.local.json` | — | 始终 | 个人 Claude Code 设置 |
+
+## 安装内容
+
+```
+my-project/
+├── .claude/
+│   ├── commands/       10 个斜杠命令（/cpw-*）
+│   ├── agents/         11 个专用代理
+│   ├── rules/          3 个上下文感知规则（git、interfaces、testing）
+│   ├── hooks/          Node.js 钩子（状态栏、上下文监控）
+│   └── settings.json
+├── plans/              每阶段子计划 + 决策日志
+├── docs/               架构、接口、约定
+├── .planning/          本地状态（gitignored）
+├── CLAUDE.md           代理指令
+├── PLAN.md             项目索引
+├── STATUS.md           会话指针（gitignored）
+└── Makefile            make status / plan / check / commit / push
+```
+
+## 许可证
+
+MIT

package/RELEASES.md

@@ -0,0 +1,66 @@
+# Releases
+
+Formato: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+
+## [0.3.0] - 2026-03-15
+
+### Added
+- Auto-advance mode: `off`, `auto`, `yolo` — control how much approval is needed per pipeline stage
+- Granularity setting: `coarse`, `standard`, `fine` — control how finely `/cpw-startup` slices phases (3-5, 5-8, 8-12)
+- Model profiles: `quality`, `balanced`, `budget` — control which model each agent uses, with per-agent overrides
+- Central config file `.planning/config.json` for all workflow preferences
+- npm distribution: `npx @claude-pw/framework my-project` as alternative to local install
+- `make apply-config` target to re-apply model profiles after config change
+- Configuration interview in `/cpw-startup` (step 3.7)
+- Auto-skill extraction: non-obvious discoveries saved as reusable skills in `.claude/skills/`
+- Skill routing: corrections routed back to the command/agent that caused them
+- Auto-reflection hooks: Stop hook reminds about pending learnings, auto-reflect in CLOSE stage
+- Runtime context monitor: statusline + PostToolUse hook warns at 65% (WARNING) and 80% (CRITICAL)
+- Tooling health check for brownfield projects (linter, tests, CI, pre-commit, dependencies)
+- Interface-reviewer agent integrated into COMPATIBILITY stage and /cpw-health
+- `/cpw-discuss` command for pre-implementation discussion
+- `/cpw-pause` command for session handoff/resume
+- `/cpw-todos` command for capturing and reviewing ideas
+
+### Changed
+- `/cpw-next-step` is now the main workhorse — handles pipeline, phase validation, UAT, tooling audit, skill self-check, auto-reflect
+- Consolidated `/close-step` and `/new-phase` into `/cpw-next-step` (no longer separate commands)
+- Replaced `install.sh` with `install.js` (Node.js, cross-platform, no bash/jq dependency)
+- All commands use `/cpw-` prefix
+- Pipeline stage names standardized to English (DESIGN, CLOSE, etc.)
+- Settings.json merge uses native JSON (no jq dependency)
+
+### Removed
+- `/close-step` command (merged into `/cpw-next-step` CLOSE stage)
+- `/new-phase` command (merged into `/cpw-next-step` phase validation)
+- `/spike` command (available as SPIKE pipeline stage in `/cpw-next-step`)
+- `/map-codebase` command (available via `/cpw-startup` brownfield scan)
+- `/interface-check` command (available via `/cpw-health` and COMPATIBILITY stage)
+- `install.sh` (replaced by `install.js`)
+
+## [0.2.0] - 2026-03-15
+
+### Added
+- Update system with version tracking
+- Version comparison (installed vs new)
+- Changelog display between versions on update
+- Settings.json merge (preserves custom hooks, adds new ones)
+- .gitignore merge (appends missing lines)
+- Orphan file detection in commands/agents
+- Auto-creation of new directories/files from template
+- `.claude/.claude-pw-version` tracking file
+
+### Changed
+- `--update` shows changelog, compares versions, does intelligent merge
+- Backup only created when there are real changes to apply
+
+## [0.1.0] - 2026-03-15
+
+### Added
+- Installer with new project and `--update` modes
+- 10 commands: `/cpw-startup`, `/cpw-next-step`, `/cpw-quick`, `/cpw-debug`, `/cpw-reflect`, `/cpw-health`, `/cpw-impact`, `/cpw-discuss`, `/cpw-pause`, `/cpw-todos`
+- 11 agents: plan-checker, debugger, researcher, learning-extractor, session-recovery, phase-validator, interface-reviewer, decision-impact, spike-explorer, codebase-mapper, implementer
+- 3 rules: interfaces, testing, git
+- Templates for CLAUDE.md, PLAN.md, STATUS.md, CHANGELOG.md
+- Local planning structure (.planning/)
+- Automatic correction capture hooks (settings.json)