Implementation planner

Implementation Planner

Mental model

An implementation plan is a navigable contract between an agent and a codebase. Each file answers a single question: "What do I need to do next, how do I do it, and how do I prove it is done?"

Two failure modes to avoid:

1. The monolith — one giant plan.md nobody reads because everything is in one file
2. The skeleton — directories with empty READMEs that give no useful signal

The sweet spot is a tree where every node either navigates (README) or implements (task file), and every leaf has a runnable verification command.

Quick Start

Mode 1 — Create a new plan from a PRD:

sh scripts/new-plan.sh url-shortener-service
sh scripts/new-phase.sh url-shortener-service 01 workspace-bootstrap
sh scripts/new-task.sh url-shortener-service 01 01 initialise-npm-package
sh scripts/validate-plan.sh url-shortener-service

Mode 2 — Split a monolithic document:

# 1. Create hierarchy manually (steps below) or from JSON:
sh scripts/generate-structure.sh --plan plan.json
# 2. Validate before removing source
sh scripts/validate-structure.sh docs/refactoring/phases

When to use each mode

Signal	Mode
User provides a PRD, spec, or requirements description	Mode 1
User provides a single large planning document to split	Mode 2
User provides flat phase files to reorganise	Mode 2
User says "add a phase" to an existing plan	Mode 1 (additive)
User says "split", "organise", "refactor this plan"	Mode 2

Trigger phrases

Creating a new plan:

• "create an implementation plan"
• "plan this out in phases"
• "break this PRD into tasks"
• "generate a phased plan"
• "write a detailed implementation plan"
• "create tasks from this spec"
• "decompose this into phases and tasks"
• "create a project plan / roadmap"
• "break down tasks" / "task breakdown"
• "sprint planning"

Restructuring an existing plan:

• "split this plan"
• "organize phases"
• "break down implementation docs"
• "create task hierarchy"
• "refactor this planning doc"
• "split this into separate files"

Recognition examples

These show how to map real user input to the correct mode and expected output:

User says	Mode	Expected output
"Here's the PRD — create a phased plan"	Mode 1	.context/plans/plan-<slug>/ with README, phase READMEs, and task files
"Break this spec into tasks"	Mode 1	Plan with tasks scoped to individual files + runnable verification commands
"I need a project roadmap for this feature"	Mode 1	Plan with phases matching delivery milestones, gate criteria per phase
"Here is my big planning doc — split it into files"	Mode 2	Hierarchical directory under docs/refactoring/phases/
"Organise these phase files into a proper structure"	Mode 2	Phase directories with READMEs, activities grouped, validate-structure.sh exits 0
"Add phase 4 to the existing plan"	Mode 1 (additive)	New phase-04-<slug>/ directory with tasks; existing files untouched
"The PRD has auth, ingestion, pipeline, storage, query, viz, multi-tenancy, ops, DX"	Mode 1 (guardrail)	STOP — 9 phases detected; message user with A/B/C options; zero files created

When not to use

• The user wants a high-level roadmap only (no tasks) — use a simple markdown doc instead.
• The work is a single atomic task (one file change) — a plan directory adds no value.
• The project has no clear phases (e.g. pure hotfix) — flat task list is sufficient.
• An existing plan already covers the scope — add phases to it instead of creating a new one.

---

Mode 1 — Create New Plan

Inputs

Input	Description
PRD / spec	A document, inline description, or file path describing what to build
Phase count	Optional — infer from scope if not provided
Output path	Optional — defaults to .context/plans/

Output structure

.context/plans/
  plan-<slug>/
    README.md                         # root index: goal, all phases, status table
    phases/
      phase-01-<slug>/
        README.md                     # phase overview: goal, gate, tasks summary
        tasks/
          task-P01T01-<slug>.md       # task: goal, file, implementation, verification
          task-P01T02-<slug>.md
      phase-02-<slug>/
        README.md
        tasks/
          task-P02T01-<slug>.md
          task-P02T02-<slug>.md

Each file is self-contained: an agent can work on a single task file without reading the rest of the plan.

Step 1 — Read and analyse the requirements

Read the PRD in full. Identify:

• The primary goal and non-negotiable constraints
• Natural delivery milestones (bootstrapping, core features, integration, hardening, etc.)
• Dependencies between areas of work

Step 2 — Design phases

FIRST: count the natural phases before designing anything.

Each distinct domain, capability area, or labelled section in the PRD counts as one phase unless two sections share a single atomic deliverable that cannot be tested independently. When in doubt, count them separately — err on the side of a higher count to avoid missing the guardrail.

Scan the PRD, count every distinct section or domain, and record the total. If the count is 9 or more, STOP immediately — do not design phases, do not run any scripts, do not create any files. Instead, message the user with the count and 2–3 concrete options:

I've identified N natural phases from the requirements. Before I create any files,
please choose one of these approaches:

A. Split into two plans: plan-<core-slug> (phases 1–5) and plan-<surface-slug> (phases 6–N)
B. Consolidate to 7 phases by merging [phase X] and [phase Y] into one
C. Proceed with all N phases in a single plan

Which would you prefer?

Wait for the user's answer before doing anything else. Do not silently cap at 8 and omit scope. Do not proceed with any number of phases without the user choosing when N ≥ 9.

Once the phase count is confirmed to be ≤ 8 (either naturally or after consolidation), continue designing:

Group work into sequential phases where each phase delivers a testable, deployable increment. Each phase must have:

• A clear goal statement
• A gate (pass/fail acceptance criteria that can be verified by running commands)
• Explicit dependencies on prior phases or existing artefacts

Typical phase progression for a greenfield project:

1. Workspace bootstrap (scaffolding, toolchain, CI skeleton)
2. Data model / schema foundation
3. Core domain logic
4. API / integration layer
5. UI / consumer surface
6. Quality hardening (observability, error handling, performance)
7. Release preparation

Adapt freely — fewer phases for small projects, more for large ones.

Step 3 — Decompose phases into tasks

Each task must be:

• Completable in isolation (no hidden cross-task dependencies unless declared)
• Verifiable with a concrete shell command or observable output
• Scoped to a single file or a tightly coupled set of files

Use the identifier format P{phase_number}T{task_number}, both zero-padded. Example: P02T03 = phase 2, task 3. Use 1-based numbering (01, 02, …) for consistent alphabetical sorting.

Step 4 — Scaffold and write output files

MUST use the scaffold scripts — never create directories or files manually. The scripts stamp the correct stubs that validate-plan.sh expects. Using mkdir or writing files from scratch will produce structures that fail validation.

MUST NOT modify existing files — all operations are additive only. When appending phases to an existing plan, run new-phase.sh and new-task.sh for the new content only. Never edit, rename, or delete files that already exist in the plan. Existing phase directories, task files, and the root README must remain byte-for-byte identical after the operation, except that the root README may have new phase entries appended to its phase listing.

# 1. Create the plan root — MUST run first (skip if plan already exists)
sh scripts/new-plan.sh <plan-slug>

# 2. Create each phase directory — MUST use this for every phase
sh scripts/new-phase.sh <plan-slug> <phase-number> <phase-slug>

# 3. Create each task file inside its phase — MUST use this for every task
sh scripts/new-task.sh <plan-slug> <phase-number> <task-number> <task-slug>

Slugs are lowercase kebab-case summaries of the title. Examples:

• Plan "E-commerce Checkout Redesign" → plan-ecommerce-checkout-redesign
• Phase "Workspace Bootstrap" → phase-01-workspace-bootstrap
• Task P01T02 "Root package.json" → task-P01T02-root-package-json.md

After scaffolding, fill in the generated stub files following the structure defined in references/templates/plan.yaml, references/templates/phase.yaml, and references/templates/task.yaml.

Do not embed implementation detail in the root README.md — keep it as a navigation index only. Detail belongs in phase and task files.

Step 5 — Validate all output files

MUST run before reporting to the user — no exceptions.

sh scripts/validate-plan.sh <plan-slug>

The script checks each file against its schema in references/schemas/:

File	Schema
plan-<slug>/README.md	references/schemas/plan.schema.json
phases/phase-NN-<slug>/README.md	references/schemas/phase.schema.json
phases/phase-NN-<slug>/tasks/task-*.md	references/schemas/task.schema.json

If any file fails: fix the violation and re-run validate-plan.sh. Repeat until exit 0. Do not report completion until exit 0 is confirmed.

Every task file MUST include a verification section with a concrete, runnable shell command. Gates MUST be exit-code-based (exit 0 / non-zero, file exists, URL returns 200). Gates MUST NOT use vague language like "works correctly" or "tests pass" without specifying the exact command.

Step 6 — Report to the user

After writing all files, output a summary:

Created implementation plan at .context/plans/plan-<slug>/

  README.md
  phases/phase-01-workspace-bootstrap/README.md  (N tasks)
  phases/phase-01-workspace-bootstrap/tasks/task-P01T01-*.md
  ...

---

Mode 2 — Restructure Existing Plans

Use this mode when the source is a monolithic document or flat set of phase files that needs to be reorganised into a navigable hierarchy.

Decision table

Source type	Approach	Automation
Flat .md phase files	Manual workflow (steps 1–7 below)	Run validate-structure.sh after
JSON plan definition	Automated	Run generate-structure.sh, then validate
Existing structure	Validation only	Run validate-structure.sh

Resource loading rules

Load scripts and templates only when needed:

• Always load scripts/validate-structure.sh after completing a manual split or when asked to validate
• Always load scripts/generate-structure.sh when the user provides a JSON plan file
  • Load references/templates/*.yaml only when using automation or customising output
  • Load references/schemas/*.json only when debugging validation errors
• Do not load scripts/schemas/templates when doing a purely manual split

Expert heuristics

When to flatten vs subdivide:

Signal	Action
Item has <3 children	Flatten — merge with sibling or parent
All children fit on one README screen (<20 lines)	Flatten
Navigation depth would exceed 4 levels	Flatten intermediate level
Item has >10 children	Subdivide
Children cluster into distinct semantic groups	Subdivide
Parallel work streams or different team ownership	Subdivide

Rule of thumb: 3–7 items per group is the sweet spot.

Naming conventions that scale:

step-1-extract-movement-logic/     # GOOD: survives refactors
step-1-refactor-game-code/         # BAD: vague, becomes meaningless

activity-1-analysis-complete/      # GOOD: outcome-oriented
step-1-initial-setup/              # BAD: "initial" becomes misleading later
step-1-project-bootstrap/          # GOOD: timeless

Pre-split verification

Before splitting, confirm:

1. Source type detected (use decision table above)
2. Natural groupings identified (phases → activities/steps → groups)
3. Numbering convention detected (step-1.1, step-1.2 belong together)

Ask yourself:

• Does each phase/step have 3–10 child items?
• Are there natural breaks in the content (headings, numbered sections)?
• Will a reader understand the hierarchy without opening every file?

Step 1 — Establish structure

docs/refactoring/phases/
  phase-{number}-{name}/
    README.md
    activities/              # OR steps/
      README.md
      activity-{number}-{description}/
        README.md
        activity-{number}.{sub}-*.md

Max depth: 4 levels (phase → activities/steps → group → leaf). Flatten if deeper.

Never use numeric-only directory names (step-1/, activity-2/) and never use generic names (step-1-stuff/) — contributors cannot navigate without opening every file.

Step 2 — Write leaf file content

Each leaf file must contain: title, description, checklist, acceptance criteria, status.

See references/templates/step-file.yaml for the exact structure.

Step 3 — Write README files

Every non-leaf directory needs a README explaining its purpose and listing its children. Minimum 3 lines. See references/templates/phase-readme.yaml, references/templates/group-readme.yaml, and references/templates/intermediate-readme.yaml.

Step 4 — Apply names

Format: {type}-{number}-{kebab-description}. Use naming heuristics above.

Step 5 — Group related items

Items with the same prefix (1.x, 2.x) go in the same parent directory. Never mix groups (no step-2.1 inside step-1-extract/).

Step 6 — Update README links

Update all README links after restructuring. Verify with validate-structure.sh.

Step 7 — Cleanup and validate

Create the new hierarchy first, validate, then remove the old flat files — never delete source before the new structure is confirmed valid.

sh scripts/validate-structure.sh docs/refactoring/phases
# Exit 0 = valid, 1 = invalid

Validation checklist

Before marking complete:

• Every phase has its own directory
• Every directory has a README.md
• All step/activity directories have descriptive names
• Related items are grouped (1.1, 1.2 together; not 1.x with 2.x)
• All README links resolve correctly
• Old flat files removed
• Each leaf file has: title, description, checklist, acceptance criteria, status

sh scripts/validate-structure.sh <phases-dir>
# Exit 0 = valid, 1 = one or more violations (details printed to stdout)

For automation (JSON plan generation), error recovery recipes, and legacy naming conventions see references/mode2-advanced.md.

---

Anti-patterns

See references/anti-patterns.md for Mode 1 anti-patterns, Mode 2 anti-patterns, and cross-cutting NEVER rules.

---

Worked examples

See references/worked-examples.md for URL shortener (Mode 1), scope guardrail, and restructure migration examples.

---

Reference

Deep dives

Topic	Location
Anti-patterns (Mode 1, Mode 2, NEVER rules)	references/anti-patterns.md
Worked examples (URL shortener, scope guardrail, restructure)	references/worked-examples.md
Mode 2 automation, error recovery, legacy naming	references/mode2-advanced.md
Before/after structure transformation example	references/example-transformation.md
File format templates and schemas	below

File Format Reference

Template	Schema	Purpose
references/templates/plan.yaml	references/schemas/plan.schema.json	Root index structure (Mode 1)
references/templates/phase.yaml	references/schemas/phase.schema.json	Phase overview structure (Mode 1)
references/templates/task.yaml	references/schemas/task.schema.json	Individual task structure (Mode 1)
references/templates/phase-readme.yaml	references/schemas/readme-file.schema.json	Phase directory README (Mode 2)
references/templates/group-readme.yaml	references/schemas/readme-file.schema.json	Group/intermediate README (Mode 2)
references/templates/intermediate-readme.yaml	references/schemas/readme-file.schema.json	Activities/steps dir README (Mode 2)
references/templates/step-file.yaml	references/schemas/step-file.schema.json	Leaf step/activity file (Mode 2)

See references/example-transformation.md for a before/after structure comparison. See references/mode2-advanced.md for automation, error recovery, and legacy naming guidance.

---

Notes

• Existing .context/plans/ content is never deleted; new files are additive.
• If a plan already exists, append new phases rather than overwriting.