Planning in Small Increments
All work must be done in small, known-good increments. Each increment leaves the codebase in a working state where all tests pass.
Use the /plan command to create plans. Use the /continue command to resume work after a merged PR.
Plans Directory
Plans live in plans/ at the project root. Each plan is a self-contained file named descriptively (e.g., plans/gift-tracking.md, plans/email-validation.md).
To discover active plans: ls plans/
Multiple plans can coexist — each is independent and won't conflict across branches or worktrees because they have unique filenames.
When a plan is complete: delete the plan file. If plans/ is empty, delete the directory.
Prefer Multiple Small PRs
Break work into the smallest independently mergeable units. Each PR should be reviewable in isolation and deliver a coherent slice of value.
Why this matters: Small PRs are easier to review, easier to revert, and easier to reason about. When something breaks, the cause is obvious. When a PR sits in review, it doesn't block unrelated work. The goal is to stay as close to main as possible at all times.
A PR is too big when the reviewer needs to hold multiple unrelated concepts in their head to understand it, or when you'd struggle to write a clear 1-3 sentence summary of what it does.
There will be exceptions — some changes are inherently coupled and splitting them would create broken intermediate states. Use judgement. But the default should always be to ask "can this be split?"
What Makes a "Known-Good Increment"
Each step MUST:
- Leave all tests passing
- Be independently deployable
- Have clear done criteria
- Fit in a single commit
- Be describable in one sentence
If you can't describe a step in one sentence, break it down further.
Step Size Heuristics
Too big if:
- Takes more than one session
- Requires multiple commits to complete
- Has multiple "and"s in description
- You're unsure how to test it
Right size if:
- One clear test case
- One logical change
- Can explain to someone quickly
- Obvious when done
- Single responsibility
TDD Integration
Every step follows RED-GREEN-REFACTOR-MUTATE. See testing skill for factory patterns.
FOR EACH STEP:
│
├─► RED: Write failing test FIRST
│ - Test describes expected behavior
│ - Test fails for the right reason
│
├─► GREEN: Write MINIMUM code to pass
│ - No extra features
│ - No premature optimization
│ - Just make the test pass
│
├─► REFACTOR: Assess improvements
│ - See `refactoring` skill
│ - Only if it adds value
│ - All tests still pass
│
├─► MUTATE: Verify test effectiveness
│ - Run `mutation-testing` skill
│ - Fix any surviving mutants
│
└─► STOP: Wait for commit approvalNo exceptions. No "I'll add tests later."
Commit Discipline
NEVER commit without user approval.
After completing a step (RED-GREEN-REFACTOR):
- Verify all tests pass
- Verify static analysis passes
- STOP and ask: "Ready to commit [description]. Approve?"
Only proceed with commit after explicit approval.
Why Wait for Approval?
- User maintains control of git history
- Opportunity to review before commit
- Prevents accidental commits of incomplete work
- Creates natural checkpoint for discussion
Plan File Structure
Each plan file in plans/ follows this structure:
# Plan: [Feature Name]
**Branch**: feat/feature-name
**Status**: Active
## Goal
[One sentence describing the outcome]
## Acceptance Criteria
[Behaviour-driven criteria — describe observable business outcomes, not implementation details.
Tests at every level (unit, browser, integration) should verify behaviour.]
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3
## Steps
Every step follows RED-GREEN-REFACTOR-MUTATE. No production code without a failing test.
Read the project's CLAUDE.md and testing rules before writing steps.
### Step 1: [One sentence description]
**RED**: What failing test will we write? (Describes expected behaviour, not implementation.)
**GREEN**: What minimum code makes the test pass?
**REFACTOR**: Assess improvements (only if they add value).
**MUTATE**: Run `mutation-testing` skill to verify tests catch real bugs.
**Done when**: How do we know it's complete?
### Step 2: [One sentence description]
**RED**: ...
**GREEN**: ...
**REFACTOR**: ...
**MUTATE**: ...
**Done when**: ...
## Pre-PR Quality Gate
Before each PR:
1. Mutation testing — run `mutation-testing` skill
2. Refactoring assessment — run `refactoring` skill
3. Typecheck and lint pass
4. DDD glossary check — if the project uses DDD, verify all domain terms match the canonical glossary
---
*Delete this file when the plan is complete. If `plans/` is empty, delete the directory.*Plan Changes Require Approval
If the plan needs to change:
- Explain what changed and why
- Propose updated steps
- Wait for approval before proceeding
Plans are not immutable, but changes must be explicit and approved.
End of Feature
When all steps are complete:
- Verify completion — all acceptance criteria met, all tests passing
- Merge learnings — if significant insights were gained, use the
learnagent for CLAUDE.md updates oradragent for architectural decisions - Delete plan file — remove from
plans/, deleteplans/if empty
Anti-Patterns
❌ Committing without approval
- Always wait for explicit "yes" before committing
❌ Steps that span multiple commits
- Break down further until one step = one commit
❌ Writing code before tests
- RED comes first, always
❌ Plans that change silently
- All plan changes require discussion and approval
❌ Keeping plan files after feature complete
- Delete them; knowledge lives in CLAUDE.md, ADRs, and git history
Quick Reference
START FEATURE
│
├─► Create plan in plans/ (get approval)
│
│ FOR EACH STEP:
│ │
│ ├─► RED: Failing test
│ ├─► GREEN: Make it pass
│ ├─► REFACTOR: If valuable
│ ├─► MUTATE: Verify tests catch bugs
│ └─► **WAIT FOR COMMIT APPROVAL**
│
END FEATURE
│
├─► Verify all criteria met
├─► Merge learnings if significant (learn agent, adr agent)
└─► Delete plan file from plans/