A structured workflow for AI-assisted development. Converts freeform ideas into executable plans, implements them with human checkpoints, and tracks what gets deferred so nothing is silently dropped.
When using AI agents for non-trivial features, two things go wrong:
-
Specs go stale. Big ideas produce big plans. You're asked to approve 15 tasks and 10 open questions upfront, but by Phase 3 the codebase has shifted and half the spec is wrong. You either follow the stale plan (worse code) or re-plan it (wasted effort).
-
Not everything is fire-and-forget. Some tasks — UI layout, animation timing, query tuning — depend on human judgment. The agent can't just implement and move on. You need to see the result, react, and iterate.
Everything moves through a lifecycle:
Conversation / brainstorm → idea doc → /plan → /implement → /test → /review
Ideas are freeform markdown docs in docs/ideas/. There's no required format. You can:
- Write one yourself — jot down what you want, why, any constraints, and what's still open.
- Have a conversation with the agent — brainstorm a feature, explore trade-offs. When you've landed on a direction, ask the agent to summarize it as an idea doc.
The agent writes docs/ideas/<name>.idea.md capturing the what, why, constraints, and open areas. Not every idea becomes a plan — some sit in docs/ideas/ until you're ready.
/plan takes an idea (or a description) and produces a structured plan at docs/plans/<name>.plan.md. The plan breaks the work into phases and tasks, records design decisions, and presents it for your approval before any code is written.
The key insight: only Phase 1 is fully specified. Later phases get a summary, scope bullets, and open questions — not full task breakdowns. This is explained in Phased Planning below.
/implement executes the plan's tasks in dependency order. Each task is one of two types:
- Deterministic — clear, verifiable outcome. The agent implements, validates (typecheck, lint), and marks complete. No human input needed.
- Iterative — outcome depends on taste or experimentation. The agent implements a first pass, marks
needs-review, and stops. You inspect the result, provide feedback or approve, and the agent continues.
When multiple deterministic tasks have all their dependencies met, the agent runs them concurrently — parallelism is inferred from the dependency graph, not declared in the plan.
When /implement reaches a deferred phase, it expands it using the current codebase state, resolves open questions with you, and gets approval before executing. Phase 3's tasks are planned with full knowledge of what Phases 1–2 actually built.
/test runs typecheck, linting, and formatting checks. /review diffs your changes against project conventions, design system, and security checklist.
Ideas narrow into plans. Plans narrow during implementation. At every stage, what gets excluded is recorded in the plan's Post-Completion Log with pointers back to idea docs. When a plan completes, the agent prints what was deferred so you know what to pick up next.
Idea (broad) → Plan (narrowed) → Implementation (further narrowed)
↓ ↓
Deferred Scope Deferred Scope
(recorded in plan) (added during impl)
↓ ↓
Post-Completion Log ← merged on completion
↓
"Pick up with /plan" ← printed to user
/plan <feature description> # Plan from a description
/plan from ideas/hub-polish # Plan from an idea doc
/plan # Interactive picker — shows draft plans + unplanned ideas
Creates a plan document at docs/plans/<name>.plan.md. Presents the plan for your approval before any code is written. When run with no arguments, shows both draft plans and unplanned ideas.
/implement <plan-name> # Start/resume a plan
/implement <plan-name> phase 2 # Execute a specific phase
/implement <plan-name> task 1.2 # Execute a specific task
/implement next # Pick up next pending task from active plan
/implement # Interactive picker — shows non-complete plans
Executes plan tasks in dependency order. Handles branching, progress tracking, phase expansion, and scope breadcrumbs on completion.
Resume behavior:
- Finds
in-progresstasks → resumes them - Finds
needs-reviewtasks → asks for your feedback before continuing
/test # Run full validation suite
/test web # Scope to a specific package
/test full # Include dev server smoke check
Runs typecheck, linting, formatting checks. Reports errors with file:line references.
/review # Review current changes
Reviews git diff against project conventions, design system, security checklist, and architecture rules.
# Plan: <Title>
> Status: DRAFT | APPROVED | IN_PROGRESS | COMPLETE
> Branch: `plan/<plan-name>`
> Created: YYYY-MM-DD
> Completed: —
## Context
**Goal:** <1-2 sentence description>
**Source docs:** <what informed this plan>
**Existing code:** <files explored during planning>
## Phases
### Phase 1: <Name>
> Fully specified — ready for implementation.
#### Task 1.1: <Description>
- **Status:** pending | in-progress | complete | needs-review
- **Type:** deterministic | iterative
- **Action:** create | modify | refactor
- **Files:** <target files>
- **Details:** <what to implement>
- **Depends on:** none | <task references>
### Phase 2: <Name>
> Depends on: Phase 1
> Planned: no
<1-3 sentence summary.>
**Scope:** <bullet list>
**Open questions:**
- <deferred decisions>
## Design Decisions
<numbered list — the "why" behind key choices>
## Verification
- [ ] <project-specific checks>
## Post-Completion Log
### Deferred Scope
- <what was narrowed out> → `docs/ideas/<name>.idea.md`
### Bugs / Issues
- **[YYYY-MM-DD] <description>** — <resolution>Later phases are intentionally underspecified during /plan for two reasons:
Specs go stale. When you plan Phase 3 upfront, you're specifying tasks based on how you think Phases 1–2 will turn out. But implementation always deviates — a function gets a different signature, a component gets split in two, an open question gets resolved differently than expected. By the time you reach Phase 3, half its task details are wrong.
Decision fatigue compounds. A 4-phase plan with full task breakdowns might have 15 tasks and 10 open questions. You can only meaningfully evaluate Phase 1 — the later phases are too abstract to have real opinions about yet. Questions like "should the hover animation be 150ms or 200ms?" aren't useful to answer before the component exists.
Phase 1 is fully specified because it's actionable right now — the codebase is in a known state, the dependencies are clear, and you can make real decisions. Later phases get a summary so you see the big picture, but the details wait until you have the context to make them well.
When to skip phased deferral. Not every plan needs it. When scope is tight and well-understood — introducing a test framework, adding a config file, renaming a module — the stale-spec and decision-fatigue problems don't apply. There are no open questions, no taste-dependent decisions, and the codebase won't shift meaningfully between phases. In these cases, fully specify every phase upfront.
How expansion works. When /implement reaches a phase marked > Planned: no, it:
- Reads the phase summary and open questions
- Explores the codebase as it exists now (after previous phases changed it)
- Presents open questions to you via interactive prompts
- Writes full task breakdowns into the plan document
- Gets your approval before executing
Deterministic (default) — for tasks with clear, verifiable outcomes. The agent implements, validates, and marks complete without stopping.
Examples: API endpoints, database queries, type definitions, data wiring, configuration changes.
Iterative — for tasks where the outcome depends on taste, visual feedback, or experimentation. The agent implements a first pass, marks needs-review, and stops. You inspect the result, then:
- "approve" or "looks good" → marks complete, continues to next task
- Provide feedback → agent refines, re-validates, pauses again
- Loop until you approve
Examples: UI/UX design, animation timing, layout exploration, color/typography choices, query performance tuning.
Mark iterative only when the outcome genuinely depends on human judgment. Most tasks are deterministic.
The examples/ folder contains a complete walkthrough of a "User Authentication" feature moving through the entire lifecycle:
| File | Status | What it demonstrates |
|---|---|---|
| user-auth.idea.md | — | A freeform idea doc with what/why/constraints/open areas |
| 1-approved.plan.md | APPROVED | Phase 1 fully specified, Phases 2–3 deferred with open questions, deferred scope recorded |
| 2-in-progress.plan.md | IN_PROGRESS | Phase 1 complete, Phase 2 expanded (questions resolved), Task 2.4 is needs-review (iterative), first bug logged |
| 3-complete.plan.md | COMPLETE | All phases done, iterative tasks show feedback history, 3 bugs logged, deferred scope grew during implementation |
Idea → Plan narrowing. The idea mentions password reset, rate limiting, "remember me", email verification, and OAuth. The plan defers all of them and records them in Deferred Scope.
Phase expansion. Compare Phase 2 in 1-approved (summary + open questions) vs 2-in-progress (fully expanded with resolved questions). The open questions about validation style, password requirements, and error messages are answered before tasks are written.
Iterative tasks. Task 2.4 (navbar user display) and Task 3.2 (profile edit) are both iterative. In the complete plan, you can see the feedback history: Task 2.4 went from full name → initial avatar. Task 3.2 went from modal → inline edit.
Bug log. Three bugs documented with dates, descriptions, and resolutions — a knowledge base for future work.
Design decisions grow. The approved plan has 6 decisions. The complete plan has 10 — decisions 7–10 were added as phases were expanded and iterative tasks were refined.
Ideas are freeform, but good ones include:
- What you want (the feature/change)
- Why it matters (the motivation)
- Constraints (things you've already decided)
- Open areas (things you haven't decided and want the planner to explore)
- Keep tasks small. Each task should be implementable and validatable in isolation. If the description exceeds ~15 lines, it's probably two tasks.
- Let later phases be vague. That's the point — they'll be expanded with better context later.
- Scope open questions to their phase. "What animation timing?" belongs in Phase 2 (UI), not in a global bucket.
- Push back on scope. If the agent plans 6 phases for what should be 2, say so.
- Review iterative tasks promptly. The agent stops and waits — it can't continue until you respond.
- Use
/implement nextfor quick pickup when resuming work. - Don't skip
/testand/review. They catch things the agent missed. - Check the Post-Completion Log when a plan finishes — it tells you what to plan next.
needs-reviewblocks progress. If an iterative task is waiting for review and you start a new conversation,/implementwill detect it and ask for feedback before continuing.- Branch management.
/implementcreates branches but never force-pushes or auto-switches. If you're on the wrong branch, it warns you. - Sub-agent reconciliation. When a task uses a sub-agent, the parent reads the generated files afterward to stay in sync. This is handled automatically but occasionally needs manual verification.
Serena provides LSP-powered code intelligence. The workflow uses it for symbol search, reference finding, symbol-level edits, and persistent project memories. Not required — the workflow functions without it.
Context is split across three layers to avoid duplication:
| Layer | What belongs | Loaded when |
|---|---|---|
| CLAUDE.md | Behavioral guidelines, workflow rules, architecture, lint commands | Every conversation (auto) |
| Serena memories | Domain knowledge — routes, design system, patterns | On demand |
| Auto-memory (MEMORY.md) | Session-learned gotchas, things not in the other two | Every conversation (auto, size-limited) |
docs/
├── ideas/ # {name}.idea.md — raw feature ideas (freeform)
├── plans/ # {name}.plan.md — structured, executable plans
├── reference/ # Long-lived reference docs (design system, etc.)
└── archive/ # Completed ideas + plans (moved here manually)
Ideas and plans share the same {name} stem: error-tracking.idea.md → error-tracking.plan.md.
Archive rule: Never read from docs/archive/ unless the user explicitly asks. It contains completed/stale history and should not be loaded as context.
See setup.md for a step-by-step guide to adding this workflow to a new project.
workflow/
├── README.md # This file
├── setup.md # Setup guide (AI-guided)
├── examples/
│ ├── user-auth.idea.md # Example idea doc
│ ├── 1-approved.plan.md # Plan after /plan — APPROVED
│ ├── 2-in-progress.plan.md # Plan mid-/implement — IN_PROGRESS
│ └── 3-complete.plan.md # Plan after /implement — COMPLETE
└── skills/
├── plan.md # /plan skill definition
├── implement.md # /implement skill definition
├── test.md # /test skill definition
└── review.md # /review skill definition