Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@claude-pw/framework) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Claude Project Workflow

English | Español | 中文 | 日本語 | Português

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.

Install

Requires Node.js >= 18 and Claude Code.

npm install -g @claude-pw/framework

Or run directly with npx (no install needed):

npx @claude-pw/framework my-project

Quick start

New project

npx @claude-pw/framework my-project
cd my-project && claude
/cpw-startup

Existing project

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

npx @claude-pw/framework --update

How it works

/cpw-startup → /cpw-next-step (repeat) → plan complete → /cpw-startup (new cycle)

/cpw-startup interviews you, scans existing code (if any), and generates a plan with phases, steps, and architecture docs. On subsequent cycles, loads prior context and appends new phases.
/cpw-discuss identifies gray areas and captures your preferences before building (optional, per phase)
/cpw-next-step runs an adaptive pipeline per step — then closes, commits, and advances automatically
When all phases complete, /cpw-cleanup runs automatically: generates a plan summary, reviews docs for drift, archives all phase files, resets execution state, and leaves the project ready for the next /cpw-startup

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 (`--phase` to plan + auto-advance entire phase)
`/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
`/cpw-cleanup`	Archive completed phases and clean state (auto-detects full reset when plan is done)
`/cpw-update`	Smart framework update — diff, merge conflicts, preserve customizations

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
`cleanupPolicy`	`{...}`	see below	Retention limits for mid-plan cleanup

cleanupPolicy defaults: archiveCompletedPhases: true, keepAppliedLearnings: 20, keepResolvedDebug: 5, keepQuickLogDone: 10

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/       12 slash commands (/cpw-*)
│   ├── agents/         12 specialized agents (4 with persistent memory)
│   ├── 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