CLAUDE.md

Workflow

Before touching code, create SCOPE.md, TASKS.md, QUESTIONS.md and PROGRESS.md in docs/projects/<project-name>/. Run /plan-start <project-name> to scaffold them.

The plan is split into pull requests - one topic each, under 400 changed lines of code and 600 in total counting tests and docs, the lockfile excluded - and each pull request carries acceptance criteria agreed with the repo owner before any of its tasks start. A pull request has one branch; its first task opens it as a draft, its last marks it ready, and it reaches the default branch only when the repo owner reviews and merges it. Its branch prefix, title prefix, labels, assignee and stacking follow pullRequests in .claude/workflow.json.

One task per commit, applied one at a time. Every task declares the model that must take it, and its change is made by a subagent spawned on that model. Tests come first: each task's tests are derived from the criteria and watched failing for the right reason before the implementation is written to make them pass. The repo owner sees all of a pull request's tests once, up front, with why each matters, and each pull request is reviewed by an independent opus agent before it is marked ready. A task that changes no behaviour says so and why.

The tier binds the subagent that makes the change, and the mapping lives in .claude/workflow.json. A task applied on the wrong model is a deviation for the session log even when the diff is fine.

Gates before every commit: npm run version:check. There is no lint, type check, unit or e2e suite. The pre-commit hook runs version:check.

Commit messages and pull requests carry no AI signature - no Co-Authored-By trailer for an AI, no "Generated with Claude Code" line - unless .claude/workflow.json sets aiSignature: true.

A bug fix ships a test verified failing against the old behaviour. Deviations from the plan go in the session log.

Git force flags are a last resort. Try the way without force first - --force-with-lease, a stash, a new branch. When force is the only way, the command's description says why it is necessary, not what it does; the guard hook refuses a force flag without one.

Open questions live in QUESTIONS.md, each carrying a recommendation - why, a concrete example per option, the cost, how to reverse it - and a ⬜ / 🚧 / ✅ status that flips the moment it is answered, and sitting in PROGRESS.md directly above the task it blocks. They are put to the repo owner when the run reaches that task and not before, and an answer given ahead of time is recorded with where it came from, rather than re-asked. Questions are for decisions only: anything this repository can answer, the agent reads for itself. An unanswered question blocks its task, whatever its mark. The mark sets how the question is put: 🟦 routine goes over in a line, while ⚠️ critical - hard, unreversible, or carrying a security consequence - leads with what the wrong answer costs.

Commands

npm run version:check  # plugin.json version bumped
npm run check          # the pre-commit gates

Which doc owns what