| name | plan-feature |
| description | Creates a comprehensive, context-rich implementation plan through deep codebase analysis and external research. Use when you have a feature request and need a one-pass-ready plan before writing any code. |
| argument-hint | ["feature-description"] |
Plan a new task
Feature: $ARGUMENTS
Mission
Transform a feature request into a comprehensive implementation plan through systematic codebase analysis, external research, and strategic planning.
Core Principle: We do NOT write code in this phase. Our goal is to create a context-rich implementation plan that enables one-pass implementation success for ai agents.
Key Philosophy: Context is King. The plan must contain ALL information needed for implementation - patterns, mandatory reading, documentation, validation commands - so the execution agent succeeds on the first attempt.
Planning Process
Phase 1: Feature Understanding
Deep Feature Analysis:
- Extract the core problem being solved
- Identify user value and business impact
- Determine feature type: New Capability/Enhancement/Refactor/Bug Fix
- Assess complexity: Low/Medium/High
- Map affected systems and components
Create User Story Format Or Refine If Story Was Provided By The User:
As a <type of user>
I want to <action/goal>
So that <benefit/value>
Phase 2: Codebase Intelligence Gathering
Use specialized agents and parallel analysis:
1. Project Structure Analysis
- Detect primary language(s), frameworks, and runtime versions
- Map directory structure and architectural patterns
- Identify service/component boundaries and integration points
- Locate configuration files (pyproject.toml, package.json, etc.)
- Find environment setup and build processes
2. Pattern Recognition (Use specialized subagents when beneficial)
- Search for similar implementations in codebase
- Identify coding conventions:
- Naming patterns (CamelCase, snake_case, kebab-case)
- File organization and module structure
- Error handling approaches
- Logging patterns and standards
- Extract common patterns for the feature's domain
- Document anti-patterns to avoid
- Check CLAUDE.md for project-specific rules and conventions
3. Dependency Analysis
- Catalog external libraries relevant to feature
- Understand how libraries are integrated (check imports, configs)
- Find relevant documentation in docs/, ai_docs/, .claude/references or ai-wiki if available
- Note library versions and compatibility requirements
4. Testing Patterns
- Identify test framework and structure (pytest, jest, etc.)
- Find similar test examples for reference
- Understand test organization (unit vs integration)
- Note coverage requirements and testing standards
5. Integration Points
- Identify existing files that need updates
- Determine new files that need creation and their locations
- Map router/API registration patterns
- Understand database/model patterns if applicable
- Identify authentication/authorization patterns if relevant
Clarify Ambiguities:
- If requirements are unclear at this point, ask the user to clarify before you continue
- Get specific implementation preferences (libraries, approaches, patterns)
- Resolve architectural decisions before proceeding
Phase 3: External Research & Documentation
Use specialized subagents when beneficial for external research:
Documentation Gathering:
- Research latest library versions and best practices
- Find official documentation with specific section anchors
- Locate implementation examples and tutorials
- Identify common gotchas and known issues
- Check for breaking changes and migration guides
Technology Trends:
- Research current best practices for the technology stack
- Find relevant blog posts, guides, or case studies
- Identify performance optimization patterns
- Document security considerations
Compile Research References:
## Relevant Documentation
- [Library Official Docs](https://example.com/docs#section)
- Specific feature implementation guide
- Why: Needed for X functionality
- [Framework Guide](https://example.com/guide#integration)
- Integration patterns section
- Why: Shows how to connect components
Phase 4: Deep Strategic Thinking
Think Harder About:
- How does this feature fit into the existing architecture?
- What are the critical dependencies and order of operations?
- What could go wrong? (Edge cases, race conditions, errors)
- How will this be tested comprehensively?
- What performance implications exist?
- Are there security considerations?
- How maintainable is this approach?
Design Decisions:
- Choose between alternative approaches with clear rationale
- Design for extensibility and future modifications
- Plan for backward compatibility if needed
- Consider scalability implications
Phase 5: Plan Structure Generation
Create comprehensive plan with the following structure:
Whats below here is a template for you to fill for the implementation agent:
# Feature: <feature-name>
The following plan should be complete, but its important that you validate documentation and codebase patterns and task sanity before you start implementing.
Pay special attention to naming of existing utils types and models. Import from the right files etc.
## Feature Description
<Detailed description of the feature, its purpose, and value to users>
## User Story
As a <type of user>
I want to <action/goal>
So that <benefit/value>
## Problem Statement
<Clearly define the specific problem or opportunity this feature addresses>
## Solution Statement
<Describe the proposed solution approach and how it solves the problem>
## Feature Metadata
**Feature Type**: [New Capability/Enhancement/Refactor/Bug Fix]
**Estimated Complexity**: [Low/Medium/High]
: [List of main components/services]
: [External libraries or services required]
---
(lines 15-45) - Why: Contains pattern for X that we'll mirror
(lines 100-120) - Why: Database model structure to follow
- Why: Test pattern example
- Service implementation for X functionality
- Data model for Y resource
- Unit tests for new service
[]()
Specific section: Authentication setup
Why: Required for implementing secure endpoints
[]()
Specific section: Database integration
Why: Shows proper async database patterns
(for example)
(for example)
(for example)
(for example)
---
Set up base structures (schemas, types, interfaces)
Configure necessary dependencies
Create foundational utilities or helpers
Implement core business logic
Create service layer components
Add API endpoints or interfaces
Implement data models
Connect to existing routers/handlers
Register new components
Update configuration files
Add middleware or interceptors if needed
Implement unit tests for each component
Create integration tests for feature workflow
Add edge case tests
Validate against acceptance criteria
---
IMPORTANT: Execute every task in order, top to bottom. Each task is atomic and independently testable.
Use information-dense keywords for clarity:
: New files or components
: Modify existing files
: Insert new functionality into existing code
: Delete deprecated code
: Restructure without changing behavior
: Copy pattern from elsewhere in codebase
Save all screenshots to screenshots/ and include the paths in the completion checklist.
See .claude/skills/agent-browser/SKILL.md for the full command reference and E2E Testing Protocol.
Level 6: Additional Validation (Optional)
ACCEPTANCE CRITERIA
<List specific, measurable criteria that must be met for completion>
COMPLETION CHECKLIST
NOTES
<Additional context, design decisions, trade-offs>
## Output Format
**Filename**: `.claude/plans/{kebab-case-descriptive-name}.md`
- Replace `{kebab-case-descriptive-name}` with short, descriptive feature name
- Examples: `add-user-authentication.md`, `implement-search-api.md`, `refactor-database-layer.md`
**Directory**: Create `.claude/plans/` if it doesn't exist
## Quality Criteria
### Context Completeness ✓
- [ ] All necessary patterns identified and documented
- [ ] External library usage documented with links
- [ ] Integration points clearly mapped
- [ ] Gotchas and anti-patterns captured
- [ ] Every task has executable validation command
### Implementation Ready ✓
- [ ] Another developer could execute without additional context
- [ ] Tasks ordered by dependency (can execute top-to-bottom)
- [ ] Each task is atomic and independently testable
- [ ] Pattern references include specific file:line numbers
### Pattern Consistency ✓
- [ ] Tasks follow existing codebase conventions
- [ ] New patterns justified with clear rationale
- [ ] No reinvention of existing patterns or utils
- [ ] Testing approach matches project standards
### Information Density ✓
- [ ] No generic references (all specific and actionable)
- [ ] URLs include section anchors when applicable
- [ ] Task descriptions use codebase keywords
- [ ] Validation commands are non interactive executable
## Success Metrics
**One-Pass Implementation**: Execution agent can complete feature without additional research or clarification
**Validation Complete**: Every task has at least one working validation command
**Context Rich**: The Plan passes "No Prior Knowledge Test" - someone unfamiliar with codebase can implement using only Plan content
**Confidence Score**: #/10 that execution will succeed on first attempt
## Report
After creating the Plan, provide:
- Summary of feature and approach
- Full path to created Plan file
- Complexity assessment
- Key implementation risks or considerations
- Estimated confidence score for one-pass success
