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. 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 │ └─► STOP: Wait for commit approval

No 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

• Criterion 1
• Criterion 2
• Criterion 3

Steps

Step 1: [One sentence description]

Test: What failing test will we write? Implementation: What code will we write? Done when: How do we know it's complete?

Step 2: [One sentence description]

Test: ... Implementation: ... 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 applicable)

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 learn agent for CLAUDE.md updates or adr agent for architectural decisions

• Delete plan file — remove from plans/ , delete plans/ 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 │ └─► WAIT FOR COMMIT APPROVAL │ END FEATURE │ ├─► Verify all criteria met ├─► Merge learnings if significant (learn agent, adr agent) └─► Delete plan file from plans/