Story implementation planner

Story Implementation Planner

Turn a clear story and repo context into an implementation plan sized for the model, agent, or human who will execute it.

When To Use

• create an actionable implementation plan from a story card and repo context
• optimize a plan for a named model, local model, coding agent, or human
• prepare a handoff before implementation starts
• break a story into ordered steps, risks, and validation targets

Not For

• clarifying vague product behavior; use user-story-clarifier
• finding relevant repo files; use story-repo-scout
• direct code edits after a plan already exists
• broad architecture strategy or open-ended technical design

Core Workflow

1. Read the Story Card, Repo Context, acceptance criteria, open questions, and relevant file list before planning.
2. Select a model profile:
   • standard-agent by default when the user is unsure
   • frontier-gpt for strong GPT/Codex-style agents with broad context and reliable multi-file reasoning
   • local-small for smaller local models such as Qwen-class 20B-30B models
   • human when the plan is primarily for a developer to execute manually
3. Check readiness. If behavior, repo context, or blockers are too unclear to plan honestly, list the missing inputs instead of inventing work.
4. Define the implementation boundary:
   • files likely to change
   • files likely to read only
   • files likely unrelated or explicitly not to touch
   • tests or validation targets
   • explicit non-goals and assumptions
5. Decide task shape before writing steps:
   • prefer vertical slices that produce working behavior
   • keep shared design decisions above the tasks that depend on them
   • mark dependencies and parallelizable work explicitly
6. Produce ordered steps that preserve behavior and reduce context load.
7. Attach the smallest validation path that proves the story.
8. Run a self-review before finishing: check acceptance-criteria coverage, placeholders, dependency order, risky assumptions, and rollback needs.
9. Tighten the plan for the selected model profile before finishing.

Model Profiles

standard-agent

• Use 4-8 ordered steps.
• Treat 9-12 steps as a warning range that may need re-splitting.
• Keep each step tied to known files or behavior.
• Include assumptions, blockers, and validation commands when known.
• Avoid broad refactors unless the story requires them.

frontier-gpt

• Allow parallelizable tracks when file ownership is clear. Express as named tracks (e.g., Track A: API, Track B: UI) with explicit join points.
• Permit reading >5 files in parallel before the first edit when multi-file reasoning is required.
• Allow refactors when the story warrants and the repo's existing patterns support it; flag the refactor scope explicitly so it can be approved or cut.
• Require an invariant matrix when changes touch shared state across files (rows: invariants; columns: files affected).
• Include cross-file invariants, sequencing risks, and integration checks.
• Call out where deeper repo reading should happen before editing.
• Treat 9-12 top-level steps or tracks as a warning range that may need re-splitting.
• Keep the plan concise; do not use model strength as a reason to overplan.

local-small

• Use simple linear steps with one main goal per step.
• Limit the first edit pass to 1-3 files when possible.
• Treat more than 8 steps as too large for this profile unless the user explicitly accepts the risk.
• Prefer explicit file paths, exact search terms, and concrete checkpoints.
• Avoid implicit architecture leaps, broad renames, and speculative abstractions.
• Include a First Action block with exact files to open, first change or decision, first validation checkpoint, and stop condition.
• Add a stop-and-report checkpoint before any risky or unclear change.
• Output budget. Plan ≤200 lines. Each step ≤5 lines. No inline code blocks longer than 10 lines unless naming an exact existing function signature.

human

• Use a concise task list with rationale and validation notes.
• Surface decisions-needed-from-human as explicit checkpoints (Decide: lines).
• Name the runnable git/build/test commands the human will use, not pseudo- commands. Example: pnpm test packages/auth -- --run, not run the tests.
• Omit agent-only constructs (First Action, Stop if, model token budgets); the human reads the whole plan.
• Annotate steps with rough complexity (~5 min, ~30 min, half-day) so the human can sequence around their own time.
• Name decisions the human should confirm before coding starts.
• Keep implementation details practical, not agent-instructional.
• Human plans may be longer than agent plans, but large plans should still name decision checkpoints and validation milestones.

Implementation Plan Output

Use this structure by default:

## Implementation Plan

Plan Status: Ready | Needs Inputs | Blocked

### Target Executor
Model/profile and why it was chosen.

### Size
Small | Medium | Large - relative to the executor profile. For agent profiles,
9-12 top-level steps/tracks is a warning range and more than 12 should be
re-split. For `local-small`, more than 8 steps should be re-split or accepted
explicitly by the user.

### Goal
The behavior to implement, in one or two sentences.

### Inputs
- Story card, repo context, assumptions, and blockers used for planning.

### First Action
Required for `local-small`, optional for agent profiles when it reduces
handoff ambiguity, and omitted for `human`.

- Open:
- Do:
- Check:
- Stop if:

### Files
- Change: path/to/file.ext - expected reason.
- Read: path/to/file.ext - context needed.
- Test: path/to/test.ext - validation target.
- Do Not Touch: path/to/file.ext - boundary reason.

### Steps
1. Ordered, concrete implementation step.

### Dependencies
- Step ordering, blockers, and safe parallel work.

### Risks and Blockers
- Anything that could change the plan or needs confirmation.

### Validation
- Smallest checks, tests, or manual probes that prove the acceptance criteria.

### Rollback
- How to back out or pause safely if the plan is risky.

### Handoff Notes
- What the implementing agent or human should do first.

Omit empty sections when they add no signal. Never invent paths, commands, or repo structure not supported by the story or repo context.

Plan Status legend: Ready = plan is executable as written; Needs Inputs = listed blockers must be resolved first; Blocked = cannot plan honestly without missing repo or story input. See story-implementation-orchestrator for the canonical vocabulary block when run end-to-end.

Planning Rules

• Preserve the story boundary; split the plan if the work spans unrelated goals.
• Prefer existing repo patterns over new abstractions.
• Keep steps observable: each step should produce code, tests, or a decision.
• Put validation close to the behavior it proves.
• Preserve Do Not Touch boundaries from repo scouting unless the story or user explicitly changes scope.
• For local-small, the First Action block must be executable without reading the whole plan again.
• Every verification step must name a runnable command, manual probe, or a clear reason validation is not yet available.
• If repo context is weak, include a scouting follow-up instead of guessing.
• If acceptance criteria and repo context disagree, flag the contradiction before planning implementation.
• Migration / flag / rollout. If the change alters persisted data, schema, wire format, public API, or shared file format: include a forward migration step, a backward-compatibility or rollback step, a backfill plan when data is rewritten, and a feature-flag or staged-rollout step. Risky or irreversible changes default to flag-gated. Note when the rollout requires coordinated deploys (e.g., consumer first, producer second).
• Re-splitting. If the plan exceeds 12 top-level steps or tracks for standard-agent or frontier-gpt, or 8 steps for local-small, recommend re-splitting the story instead of compressing steps. Return Plan Status: Needs Inputs with a split rationale unless the user explicitly accepts the larger plan.
• Incremental delivery. When possible, order steps so a working, verifiable checkpoint exists every 2-3 steps. Do not front-load all refactors before any behavior is visible.
• Spike steps. When a critical unknown (API contract, data shape, performance budget) blocks honest planning, include a Spike: step with a time-box, a concrete question to answer, and a stop-and-report checkpoint. Do not guess past a spike.

Anti-Patterns

Reject and rewrite when these appear in a draft plan:

• Vague refactor step. Refactor X for clarity without a named target, observable change, or test that proves equivalence.
• Vague test step. Add tests without naming the assertion, fixture, or command that runs them.
• Mixed-layer step. A single step that touches DB schema and API surface and UI all at once. Split by layer with explicit ordering.
• Missing rollback. Plan changes production data, schema, or external contracts but has no rollback or backout entry.
• Invented path. Step references a file or symbol not present in repo context. Re-scout instead of guessing.
• Placeholder padding. Steps such as Handle edge cases, Polish, or Finalize without concrete behavior or verification.
• Oversized plan. A plan that exceeds the warning or split budget for its executor profile without flagging re-splitting or explicit acceptance.

Composition Boundaries

• Pipeline position. Input comes from user-story-clarifier (story card) and story-repo-scout (Repo Context). Output is consumed by the executor named in Target Executor.
• Shared vocabulary. Plan Status (Ready / Needs Inputs / Blocked) joins story Status and Confidence from the upstream skills. See story-implementation-orchestrator for the canonical vocabulary block.
• Downstream skills. When the executor is an agent and the story implies repo-owned code changes, the plan should hand off to project-core-dev, plus the matching coding-guidance-<lang> overlay (e.g., coding-guidance-go, coding-guidance-python) and any relevant systems overlay (backend-systems-guidance, ui-guidance, ui-design-guidance). Use documenter for docs-only implementation plans and project-config-and-tests when config behavior or deterministic test coverage is the primary concern. Add tester-mindset when validation design, risk coverage, or acceptance-oracle quality is central to the story.
• Re-scout, do not guess. If repo context is weak or stale, return a Needs Inputs plan that asks for a re-scout instead of inventing paths.
• Use user-story-clarifier first when the story is unclear.
• Use story-repo-scout first when relevant files are missing.
• Use tester-mindset when the main question is what risk to cover.
• Use security for exploit-focused review.

Examples

• Create an actionable implementation plan from this story card and repo context. -> choose a model profile and output Implementation Plan.
• Plan this ticket for a local qwen coding agent using the relevant files found. -> use the local-small profile and simple checkpoints.
• Make a GPT-optimized plan from this story and repo scout output. -> use frontier-gpt unless the user names a weaker executor.
• Scour the repo and append relevant file paths. -> use story-repo-scout.