From Feature Idea to Plan to Handoff¶

This page walks through a single, durable workflow for building a real feature with an AI agent: brainstorm → converge on a design → write the plan to a file → execute against that plan → hand off. It is the everyday backbone of using AI as a development tool, and it is deliberately built around the AI's weaknesses rather than against them.

The two limits this fights. An agent's memory is fragile and degrades as its context fills (limitation #1), and it does no real thinking or learning between sessions — every new session starts cold (limitation #2). A written plan is the cure for both: it is durable external memory and a frozen record of the reasoning you did, readable by the next agent or the next human.

Brainstorm → plan → execute → hand off, all five stages — 1 min 58 s.

The flow at a glance¶

Stage	You do	The AI does	The artifact
1. Brainstorm	Describe the goal, constraints, unknowns	Asks questions, surfaces options and trade-offs	A shared understanding
2. Converge	Pick a direction, reject alternatives	Sharpens the chosen design	An agreed design
3. Write the plan	Review and approve	Writes a step-by-step plan to a `.md` file	`plan.md` (durable)
4. Execute	Supervise, check off steps	Implements one step at a time	Working code + updated plan
5. Hand off	—	—	A plan anyone can resume

Stage 1 — Brainstorm with the AI¶

Resist the urge to say "build feature X" and walk away. Start a conversation. A good brainstorming pass has the agent ask you questions before proposing anything: What is the actual goal? What already exists? What are the constraints — performance, deadlines, the database you are stuck with? What could go wrong?

This is where you, the human, contribute the things the AI cannot know: product intent, organizational context, the reason behind a constraint. The agent contributes breadth — options you had not considered, edge cases, prior art.

Tip: treat disagreement as a feature. If the agent only ever agrees with you, you are not brainstorming, you are dictating. Ask it for the strongest case against your idea.

Stage 2 — Converge on a design¶

Out of the options, pick one. Say so explicitly: "We are going with the queue-based approach; drop the others." Have the agent restate the chosen design in your own context so you can confirm it understood. The goal is a design small enough that you can actually read and agree with it — not a vague gesture at "a queue thing."

This convergence is real thinking, and right now it lives only in the chat history — which is exactly the fragile place limitation #1 warns about. So move it somewhere safe.

Stage 3 — Write the plan to a file¶

This is the load-bearing step. Have the agent write the agreed design and an ordered, step-by-step implementation plan into a markdown file in the repo (e.g. docs/plans/feature-x.md). A good plan has:

A short statement of the goal and the design decision (the "why," captured once).
Bite-sized, ordered tasks — each small enough to verify on its own.
For each task: which files it touches and how you will check it is done.
Open questions or risks called out explicitly.

First-party version: Claude Code's built-in Plan mode is exactly this loop — it researches and drafts a plan for your approval before touching any code, keeping the design phase separate from execution. See Getting started.

# Plan: Add rate limiting to the public API

## Goal
Prevent abuse of /api/v1/* without hurting normal users.

## Design decision
Token-bucket per API key, enforced in middleware. (Rejected: per-IP — breaks behind shared NAT.)

## Steps
- [ ] 1. Add `RateLimiter` middleware in `api/middleware/ratelimit.py`
- [ ] 2. Wire it into the request pipeline in `api/app.py`
- [ ] 3. Add config (limits per tier) in `config/limits.yaml`
- [ ] 4. Tests: burst, steady-state, exempt internal keys

Why the file matters so much¶

The .md file becomes a durable artifact that serves two readers:

The agent that executes later. A fresh session has none of the brainstorming context — limitation #2 in action. The plan file is that context, re-loadable on demand. The agent reads the plan, not a half-remembered chat.
The human who picks the feature up later. Maybe it is a teammate. Maybe it is you in three weeks. The plan explains not just what to build but why this way — the reasoning that would otherwise have been lost when the chat scrolled off.

The plan captures the thinking. The agent cannot carry its reasoning across sessions, but the file can. You did the thinking once; the file makes it reusable. That is the whole trick.

For more on why design-first beats code-first with AI, see Plan and design first.

Stage 4 — Execute in a fresh session¶

Open a new session — clean context — and point it at the plan: "Execute the plan in docs/plans/feature-x.md, one step at a time." Then:

Check off steps as they complete. The checkboxes are a live progress tracker that survives a context reset.
Keep the plan updated. If reality diverges — a step turns out wrong, a new sub-task appears — edit the plan. The file should always reflect the current truth, not the original guess.
Verify each step before moving on, rather than letting the agent run the whole plan unsupervised.

Because the plan is external, you can stop after step 2 today and resume at step 3 tomorrow in yet another fresh session, losing nothing. The fragile in-session memory no longer matters — the durable file carries the state. This is also your escape hatch when a session goes bad mid-execution: see Knowing when to reset.

Stage 5 — Handoff¶

When you stop, the plan is the handoff. Anyone — a colleague, a future agent, future-you — opens the file and sees the goal, the design rationale, what is done, and what remains. No "let me reconstruct what I was thinking." The thinking is on disk.

A ready-made embodiment: Superpowers¶

You do not have to invent this flow from scratch. The Superpowers workflow packages exactly these stages as self-triggering skills:

brainstorming — refines the idea through questions, explores alternatives, saves a design document (Stages 1–2).
writing-plans — breaks the approved design into small, verifiable tasks with file paths and checks, written to a plan file (Stage 3).
executing-plans / subagent-driven-development — works through the plan, with review checkpoints, either across sessions or by dispatching a fresh sub-agent per task (Stage 4).

It is a clean, opinionated implementation of the brainstorm → plan → execute → hand off loop described here.