Writing Plans

Write comprehensive implementation plans assuming the engineer has zero context for the codebase. Document everything: which files to touch, exact code, how to test, expected output. Bite-sized steps. DRY. YAGNI. TDD. Frequent commits.

Assume the implementer has general programming skills but zero context about this project's codebase, domain, or testing patterns. Spell out everything — file paths, function signatures, exact test code, expected outputs.

Scope Check

If the spec covers multiple independent subsystems, it should have been decomposed during brainstorming. If it wasn't, suggest splitting into separate plans — one per subsystem. Each plan must produce working, testable software on its own.

Monorepo note: For monorepos, scope each plan to one package. Cross-package work gets a coordination plan that references per-package plans.

File Structure

Before defining tasks, map out which files will be created or modified and what each is responsible for:

• Each file has one clear responsibility
• Files that change together live together
• Split by responsibility, not by technical layer
• Prefer smaller, focused files (easier to reason about, more reliable edits)
• In existing codebases, follow established patterns

This structure informs the task decomposition.

Bite-Sized Task Granularity

Each step is one atomic action (one file read, one file write, one command run, or one test assertion):

• "Write the failing test" — one step (include test name and assertions, code block if subagent mode)
• "Run it to verify it fails" — one step
• "Implement minimal code to pass" — one step (describe what to build, code block only if subagent mode)
• "Run tests to verify they pass" — one step
• "Commit" — one step

Plan Document Format

Every plan MUST start with this header and follow this structure:

---
status: pending
spec: docs/specs/YYYY-MM-DD-<topic>-design.md
---

# [Feature Name] Implementation Plan

> **For agentic workers:** Use mbscode:subagent-driven-development (recommended) or mbscode:executing-plans to implement this plan task-by-task.

**Goal:** [One sentence — what this builds]

**Architecture:** [2-3 sentences about approach]

## Resume
Last completed: (none — plan not started)
Next step: Task 1, Step 1
Blockers: none

## Milestones
- Milestone 1 (Tasks 1-3): [description] → autonomous review checkpoint
- Milestone 2 (Tasks 4-7): [description] → autonomous review checkpoint

---

### Task 1: [Component Name]

**Files:** Create: `path/to/file`, Test: `tests/path/to/test`
**Dependencies:** none

- [ ] **Step 1:** Write failing test (test name, assertions, exact code if subagent mode)
- [ ] **Step 2:** Run test → verify FAIL (expected error message)
- [ ] **Step 3:** Write minimal implementation (what to build; exact code if subagent mode)
- [ ] **Step 4:** Run test → verify PASS
- [ ] **Step 5:** Commit with descriptive message

> **Mode note:** Step detail depends on execution mode — see **Plan Detail Levels** below. Inline mode describes intent; subagent mode includes exact code. Adapt language, test commands, and file extensions to the project's actual stack per PROJECT.md.

---

### Task 2: [Next Component]
...

Plan Detail Levels

Execution Mode	Detail Level	What Each Step Contains
Subagent (parallel tasks via subagent-driven-development)	Interface contracts	Function signatures, types, return values, acceptance criteria. Exact code only for tricky APIs, schemas, regexes, migrations.
Inline (sequential tasks via executing-plans)	Acceptance criteria	What the step must achieve, target file, verification command. Agent has project context — no implementation code needed.

Default: Inline (acceptance criteria). Use subagent detail only when tasks will be dispatched to independent subagents without shared context.

Plan File = Progress Tracker

<HARD-GATE> The plan file IS the progress tracker. When a step is completed, you MUST update the checkbox from `- [ ]` to `- [x]` in the plan file immediately. When a task is fully done, ALL its steps must be checked. This is mandatory, not optional. </HARD-GATE>

Step states: - [ ] = pending, - [x] = done, - [~] = skipped (see executing-plans Plan Modifications section for when/how to skip steps).

After completing each task, update the Resume section at the top:

## Resume
Last completed: Task 2, Step 5 (commit) PASS
Next step: Task 3, Step 1 (write failing test)
Blockers: none

Also update the plan's YAML frontmatter status:

• pending → plan written, not started
• in_progress → actively being worked on
• done → all tasks complete and verified
• blocked → cannot proceed (document why in Resume section)

When changing plan status, also update SESSION.md. If status values disagree, SESSION.md is the authority (see mbscode:project-documentation).

Milestone Size Rule

Each milestone should contain 3-7 tasks. If a milestone grows past 7 tasks, split it into two milestones. Large milestones lose the benefit of focused review checkpoints.

No Placeholders — Ever

<HARD-GATE> Before writing any plan, read PROJECT.md's Commands section. Every test/lint/build command in the plan MUST match the actual project commands. Never copy template commands verbatim — adapt to the project's actual stack and tooling.

"No placeholders" means every step must have a clear, actionable description — not that every step needs a full code block. The step must tell the implementer exactly WHAT to build and HOW to verify it. </HARD-GATE>

Good: "Write authenticate(token: string): Promise<User> that validates JWT and returns the user record" — clear target, specific signature. Bad: "Implement auth" — vague, no actionable detail.

These are plan failures — never write them:

Placeholder	Write Instead
"TBD" / "TODO" / "implement later"	The actual requirement with acceptance criteria
"Add appropriate error handling"	Name the specific error types and expected behavior
"Write tests for the above"	Name each test case with input/output expectations
"Similar to Task N"	Repeat the description — implementer may read tasks out of order
"Handle edge cases"	Name each edge case and the expected handling

Acceptance Criteria Per Task

Every task ends with a verification step. These are the minimum — all GATES.md post-task gates also apply:

**Acceptance:**
- [ ] Test passes: `<test command per PROJECT.md>` → 0 failures
- [ ] No lint errors: `<lint command per PROJECT.md>` → 0 errors
- [ ] Build passes: `<build command per PROJECT.md>` → exit code 0
- [ ] All GATES.md post-task gates satisfied (no dead code, DRY, simplest solution, etc.)
- [ ] Committed with descriptive message

Milestone Boundaries

Group tasks into milestones. Each milestone is an autonomous review checkpoint:

---
### Milestone 1 Complete: Core Data Model

**Verify:** `<test command per PROJECT.md>` → all pass
**Review:** Invoke `mbscode:autonomous-review` before proceeding to Milestone 2
---

Self-Review

After writing the complete plan, review it yourself:

1. Spec coverage: Skim each requirement in the spec. Can you point to a task that implements it? List gaps.
2. Placeholder scan: Search for "TBD", "TODO", "similar to", "appropriate", "handle edge cases". Fix them.
3. Type consistency: Do function names, types, and interfaces match across tasks? clearLayers() in Task 3 but clearFullLayers() in Task 7 = bug.
4. Command consistency: Are test commands, file paths, and import paths correct and consistent?
5. Command accuracy: Are all test/lint/build commands correct for THIS project's stack per PROJECT.md?

Fix issues inline. If a spec requirement has no task, add the task.

Execution Handoff

After saving the plan:

1. Update SESSION.md — add the plan to the Active section
2. Present execution options:

Plan saved to `docs/plans/<filename>.md` (directory created if absent).
SESSION.md updated.

Two execution options:
1. **Subagent-Driven** — best for 3+ independent tasks (fresh context per task, parallel review)
2. **Inline Execution** — best for tightly coupled tasks that share state/files

Which approach?

• If Subagent-Driven: invoke mbscode:subagent-driven-development
• If Inline: invoke mbscode:executing-plans
• Autonomous default: If user is unavailable or does not respond, choose Subagent-Driven for 3+ independent tasks, Inline for tightly coupled tasks. State the choice and proceed.

Transitions

Called by: mbscode:brainstorming (after spec approval); also referenced by GATES.md Planned gate After plan saved: mbscode:subagent-driven-development or mbscode:executing-plans (user choice, with autonomous default)

Red Flags

Thought	Reality
"The implementer will figure it out"	No. Show paths, commands, and enough detail for the execution mode (exact code for subagent; clear intent for inline).
"This step is obvious"	Nothing is obvious to someone with zero context
"I'll add details later"	You won't. Write them now.
"One big step is fine"	One atomic action per step. Break it down.
"Tests can come after"	TDD. Test first. Always.