Planning Systems
Unlocking /ck:plan with --deep mode and --tdd flag
Not every task needs a heavy mode. This article clarifies when to use --deep, when to add --tdd, and when a lighter approach is enough.
Mode vs Flag
/ck:plan takes 2 types of parameters. Confusing them leads to wrong choices.
Modes (pick one)
--fast Quick run, concise plan --hard Deeper research, fits complex domains --deep Per-phase scout, file inventory, dependency map --parallel Multiple independent modules, run in parallel --two Compare 2 approaches before choosing Flags (composable)
--tdd Adds tests-first structure to phase files and cook flow --no-tasks Skip task list creation after plan Each command uses only ONE mode. Flags can compose with any mode.
--deep: When the plan needs a map
--deep solves the risk: not knowing enough scope
- Runs 2-3 researchers for high-level architecture analysis
- Scouts EACH phase: file inventory, test gap, dependency map
- Red-team review + post-plan validation
- Phase files include: file inventory table, test scenario matrix, dependency map, function/interface checklist
Major refactor, 5+ areas, architectural debt → use --deep
--tdd: When refactoring might break behavior
--tdd solves the risk: refactor breaking existing behavior
- Phase files add: test before refactor → refactor → additional tests → end-of-phase gate
- Cook runs in order: write tests protecting current behavior → refactor → compile/test gate
- Doesn't create new agents, only changes phase file structure and cook order
- Much lower cost than --deep
Most valuable for: async patterns, stateful workflows, database transactions, public API contracts
Why --deep --tdd often go together
| Risk | Needs | Option |
|---|---|---|
| Not knowing enough scope | Per-phase scout, file inventory, dependency map | --deep |
| Refactor breaking behavior | Test before refactor, regression gate during cook | --tdd |
Wide task → --deep. Must preserve behavior → add --tdd. Both → use the pair.
Decision Matrix
/ck:plan --fast /ck:plan (auto) /ck:plan --hard /ck:plan --parallel /ck:plan --two /ck:plan --deep Any mode + --tdd /ck:plan --deep --tdd Best practices before cook
- Clean worktree Commit/stash before big plans, or use /ck:worktree
- Review phase files Don't cook before reading plan.md and phase files
- Declare test commands Repo uses unusual tools? Declare them in the task
- /clear between plan and cook Plan context is heavy → /clear → /ck:cook {path}/plan.md
Pitfalls to avoid
- Forgetting --tdd on /ck:cook Cook won't enforce test-first order without the flag
- --deep for small tasks Under ~5 files, use --hard or --fast instead
- --tdd for greenfield New code has no existing behavior to capture in tests
- Blindly trusting phase files Still review: does a later phase silently depend on an earlier one?
- --tdd capturing buggy code Declare known bugs or split into 2 plans: fix → refactor
- Combining --deep + --parallel Both are modes, can't compose. Use --parallel --tdd if needed
--tdd Cook Flow
Tip: Regression Gate needs specific commands (e.g. go test ./...). If your project uses unusual tools, declare them in the task description.
General Template
Note:
If the plan used --tdd, add --tdd to cook as well:
Read the full article
Read the full article with billing module case study, detailed pipeline, command templates, and internal mechanism analysis →