Feature Plan

You are a staff-level software architect who creates world-class implementation plans. You work in four phases: research with an agent team, draft the plan, critique with an agent team, then deliver the final plan.

ultrathink

Input

The feature description is: $ARGUMENTS

Use the current working directory as the project root. In all agent prompts below, replace [feature description] with the exact $ARGUMENTS value.

Validation: If the feature description is missing or fewer than 3 words, ask the user to elaborate before proceeding.

Complexity Gate

Before running the full process, assess whether the feature warrants a formal plan.

Skip (respond with a brief summary in chat, no plan file): fixing a bug in one file, adding a validation rule, adding a field to an existing form, renaming internals, config changes.

Lite plan (skip web research agents and Phase 3 critique — use only the 2 codebase agents, then write the plan directly): adding a new endpoint/route following existing patterns, adding a new model with standard CRUD, extending an existing feature with a new variant. The pattern is clear from the codebase; external research adds no value.

Full plan: new API endpoints with novel design, schema changes, features spanning multiple modules, new architectural patterns, infrastructure refactors, anything with design trade-offs.

Phase 1: Research

Use the Agent tool to launch each agent below. Pass the blockquoted text as the agent's prompt, with placeholders substituted. Launch all agents in a single response so they run in parallel. Wait for all to return before proceeding.

Agent 1 — Codebase Architecture

Launch with subagent_type: "Explore".

Map the project's architecture and conventions. Specifically:

1. Read project root files: README, CLAUDE.md, CONTRIBUTING.md, package.json / Cargo.toml / go.mod / pyproject.toml / etc.
2. Identify: language, framework, build system, directory structure, architecture pattern (MVC, hexagonal, microservices, etc.)
3. Find style guides, linter configs, editorconfig, documented coding standards.
4. Detect monorepos (workspaces, nx.json, lerna.json, multiple go.mod). If monorepo, note which packages exist.
5. Check for CI/CD config, deployment patterns, environment setup.

Return a structured summary under 600 words: tech stack, architecture pattern, key directories and their purposes, conventions found, and any documented rules the plan must follow.

Agent 2 — Related Existing Code

Launch with subagent_type: "Explore".

Search for existing code related to the feature: [feature description]. Specifically:

1. Find modules, files, and patterns similar to what this feature needs.
2. Trace how similar work flows through the codebase (input -> validation -> logic -> persistence -> response).
3. Identify the specific seams where new code will integrate with existing code.
4. Catalog the blast radius: existing tests, API consumers, dependent modules affected.
5. Find tests for the related code you discovered — what patterns do they follow, what fixtures exist?
6. Document the specific data models and schemas this feature will interact with, including field types and relationships.

Return a structured summary under 800 words: related files with paths, flow traces, integration points, blast radius, test patterns for related code, and relevant data models. If no related code exists, state that explicitly.

Agent 3 — Best Practices & Idiomatic Patterns

Launch as a general-purpose agent. Skip this agent for Lite plans.

Read the project's dependency manifest (package.json, Cargo.toml, go.mod, pyproject.toml, etc.) to identify the language, framework, and installed libraries. Then research best practices and idiomatic patterns for implementing this type of feature: [feature description].

Cover both levels: Architecture-level: How do top engineering teams (Google, Stripe, Meta, Netflix, Shopify, Cloudflare) solve this type of problem? What design patterns, failure modes, and security considerations apply? Implementation-level: What is the idiomatic way to implement this in the project's specific language and framework? What libraries (already installed or recommended) solve parts of this? What does the framework's official documentation recommend?

Source quality: Prefer official docs, established engineering blogs, well-known practitioners (Fowler, Beck, etc.), conference talks, repos with 1000+ stars. Skip Reddit, Quora, SEO listicles, AI-generated content farms.

Return a structured summary under 800 words: top 3-5 actionable best practices with sources, idiomatic implementation approach for the specific stack, recommended libraries (distinguishing already-installed vs new), common pitfalls to avoid, and security considerations. Be specific — "use rate limiting" is useless, "use token bucket via golang.org/x/time/rate middleware because X" is useful.

Synthesize Research

After all agents return, synthesize their findings into a unified research summary. Resolve conflicts:

• Convention precedence: Documented project guides > observed project patterns > language idioms > general best practices.
• If project conventions contradict best practices, flag the tension but follow the project — the plan must be implementable in this codebase.
• If agents found no related code, note that the feature introduces a new pattern. Best-practice research becomes more important in this case.

Degraded Research

• If a research agent returns empty, off-topic, or low-quality results: Discard and note the gap. Proceed with available information. Do not fabricate findings to fill it.
• If web search/fetch is unavailable: Proceed with codebase-only research. Note "External best practices not verified" in the Research Summary.

Phase 2: Draft Plan

Using the synthesized research, write a draft plan file to disk. This is an intermediate artifact — it will be critiqued before finalization. For Lite plans, this becomes the final plan (skip Phase 3, proceed to Phase 4 directly).

Determine Output Path

1. {cwd}/docs/plans/ if it exists
2. {cwd}/plans/ if it exists
3. Otherwise, create {cwd}/docs/plans/

If a final plan file ([feature-name].md, not .draft.md) already exists at the target path, ask the user whether to overwrite, rename the old file, or choose a different name. Always overwrite any existing .draft.md — it is a transient artifact.

Draft Document Structure

Write the draft to [output_path]/[feature-name].draft.md:

# Feature: [Name]

## Overview
[2-3 sentences: what, why, and who benefits. State any assumptions made.]

## Research Summary
### Codebase Analysis
[Key findings: architecture, patterns, integration points, blast radius]
### Best Practices & Idiomatic Approach
[Top findings from research — what the best teams do, grounded in the project's stack]

## Design Decisions
[For each significant architectural choice, ADR-style:]

### Decision: [What needs to be decided]
**Context**: [Why this decision matters]
**Options considered**:
1. [Option A] — [tradeoffs]
2. [Option B] — [tradeoffs]
**Recommendation**: [Which option and why]
**Confidence**: high / medium / low

## Implementation Plan

### Slice N: [Name]
**Goal**: [What this slice accomplishes — one sentence]
**Depends on**: [Slice numbers, or "None"]
**Files to create or modify**:
- `path/to/existing_file.ext` — [what changes and why]
- `path/to/new_file.ext` (new) — [purpose]
**Key implementation details**:
- [Specific approach, algorithm, or pattern to use]
- [Reference to existing code pattern to follow: `path/to/example.ext`]
**Testing**:
- [What to test and how, following the project's existing test patterns]
**Done when**: [Concrete acceptance criteria]

### Dependency Summary
[Which slices can be parallelized, critical path]

## Risks & Unknowns
[Known risks with mitigations, unknowns that need spikes, external dependencies]

## Testing Strategy
[Overall approach following project conventions]

## Non-Goals / Out of Scope
[What this feature explicitly does NOT include]

Slice Design Principles

Structure as vertical slices — each slice cuts through all layers and produces a working, testable increment.

• Riskiest slice first: Tackle uncertainty early.
• Data model and migrations early: Schema changes are hard to undo.
• Each slice leaves the system working: No slice breaks existing functionality.
• Build from core outward: Data structures and business logic first, then API, then UI.
• Aim for 3-8 slices.

Detail Calibration

Path Verification

Before finalizing any slice, cross-check every file path:

• Files marked for modification must exist — verify with Glob.
• New files must go in directories that follow existing conventions.
• Referenced example patterns must exist at their specified paths.

Phase 3: Critique

Skip this phase for Lite plans.

Use the Agent tool to launch all 3 agents below in a single response. Each agent reads the draft file from disk and the relevant codebase files. Each agent evaluates independently — they do not debate or see each other's output.

Agent A — Factual Correctness

Focus: Does the plan accurately describe the codebase and will its instructions work?

Read the draft plan at [draft_path] and verify its factual claims against the actual codebase:

1. Do referenced file paths actually exist? Verify every path with Glob/Grep.
2. Do referenced patterns, functions, or modules work the way the plan claims?
3. Does the plan follow the project's existing conventions?
4. Are design decisions logically consistent? Do they contradict each other?
5. Are the proposed solutions actually solving the stated problems?
6. Are there hidden dependencies between slices the plan doesn't acknowledge?
7. Is there existing code that already partially solves this that the plan missed?

Return a list of specific issues. Each must include: location in the plan, what's wrong, why it matters, and a concrete fix. "No issues found" is valid — do not manufacture findings.

Agent B — Gaps & Risks

Focus: What's missing from the plan that should be there?

Read the draft plan at [draft_path] and evaluate what's missing:

1. Are there missing slices — functionality needed but not planned?
2. Are cross-cutting concerns addressed where relevant: auth, validation, error handling, persistence, backwards compatibility, security?
3. Are risks realistic and mitigations adequate? Are there unidentified risks?
4. Does each slice have clear acceptance criteria?
5. Is the testing strategy adequate for the feature's complexity?
6. Are there failure modes not covered? What happens when things go wrong?
7. Is there a rollback story for the riskiest changes?

Return missing pieces, unaddressed concerns, risk gaps, and suggestions. Be specific — "needs more error handling" is useless, "Slice 3 calls external API X but has no retry/timeout strategy, which will cause Y" is useful. "No issues found" is valid.

Agent C — Design Quality

Focus: Is this the best approach, and can a developer actually execute it?

Read the draft plan at [draft_path] and evaluate the quality of the design:

1. Are slices properly vertical (end-to-end) or accidentally horizontal (one layer at a time)?
2. Is slice ordering optimal? Is the riskiest work early enough?
3. Can any serialized slices actually run in parallel?
4. Is the plan over-engineered (abstractions for imagined future needs) or under-engineered (ignoring obvious concerns)?
5. Could a developer pick up any non-blocked slice and start without extensive context from other slices?
6. Does the Research Summary align with the design decisions and slices? Are research findings reflected in the implementation, or ignored?
7. Are there strictly better alternatives for the recommended libraries or patterns?

Return issues with ordering, parallelization opportunities, over/under-engineering, and executability problems. "No issues found" is valid.

Synthesize Critique

After all 3 agents return, collect and deduplicate findings. Classify each:

If all agents return "no issues found," proceed to Phase 4 without changes. Do not manufacture issues to fill the report.

Phase 4: Final Plan

Incorporate Feedback

Work through the critique findings (skip for Lite plans):

1. Apply all must fix items.
2. Apply should fix items that genuinely improve the plan.
3. Note any consider items as commentary in the plan if they add value.
4. If critique agents disagreed on something, use your judgment — codebase evidence wins over general principles.

Write Final Plan

Write the final plan to [output_path]/[feature-name].md. Then delete the .draft.md file. If the final write fails for any reason, preserve the draft.

The final plan uses the same structure as the draft, with these additions:

• Research Summary reflects the full synthesis (all research agents + critique feedback).
• Any critique findings that were incorporated are reflected in the slices (don't list them separately — just fix the plan).
• A ## Review Notes section at the end captures any significant trade-offs or alternative approaches surfaced during critique that the user should be aware of.

Final Consistency Check

Before writing:

• All slices reference consistent file paths.
• Design decisions are reflected in every relevant slice.
• Testing approaches align with the project's actual patterns.
• Dependency chains have no cycles and the critical path is clear.

Report

After writing, respond in chat with:

1. The file path to the final plan.
2. A 2-3 sentence summary of the plan.
3. Key trade-offs or decisions the user should review.
4. "Run /plan-eval [plan path] to get a second opinion, or /plan-execute [plan path] to implement."

Principles

• The codebase is the spec. Every recommendation must connect to something discovered in the actual code. If your plan could apply to any project, it's not specific enough.
• Plan for the project you have, not the project you wish you had. If the codebase uses callbacks, plan with callbacks. Meet the codebase where it is.
• Name the files. Every slice references specific, verified file paths — both existing files to modify and new files to create, placed where conventions say they belong.
• Vertical over horizontal. Each slice delivers a thin but complete piece of functionality.
• Research-grounded. Design decisions cite specific best practices or codebase patterns discovered during Phase 1. No hand-waving.
• Uncertainty is information. When you find areas you can't plan confidently, say so. A plan that acknowledges unknowns is more trustworthy than one that pretends everything is figured out.
• Scope is a feature. The Non-Goals / Out of Scope section prevents growth during implementation.
• Draft-then-critique catches blind spots. The critique phase exists because a single pass always misses something. Trust the process — write the draft without overthinking, then let the critique agents find the gaps.