Smithery is now a part of Arcade.dev! Read more in our announcement here
Generates implementation plans with code reuse analysis, architecture design, and complexity estimation during the /plan phase...
This skill orchestrates the /plan phase, which runs after /spec (or /clarify) and before /tasks in the feature workflow.
Core responsibilities:
Inputs: spec.md (feature specification), docs/project/*.md (8 files), existing codebase Outputs: plan.md (implementation plan), research.md (reuse findings and project context) Expected duration: 1-3 hours
Key principle: Research before designing. Maximize code reuse. Align with project documentation.
See resources/ directory for detailed workflows on each step.
If specification incomplete, return to /spec or /clarify phase.
Read all 8 project documentation files for constraint extraction.
Files to load (from docs/project/):
Extraction process:
# Read all 8 project docs
for doc in docs/project/*.md; do
echo "Reading: $doc"
cat "$doc"
done
# Extract key constraints
TECH_STACK=$(grep -A 20 "Technology Stack" docs/project/tech-stack.md)
DATABASE=$(grep -A 5 "Database" docs/project/tech-stack.md)
ARCHITECTURE=$(grep -A 10 "Architecture Style" docs/project/system-architecture.md)
API_STYLE=$(grep -A 5 "API Style" docs/project/api-strategy.md)
Brownfield fallback (if docs/project/ missing):
Output: Document constraints in research.md under "Project Context" section
See resources/project-docs-integration.md for complete extraction workflow.
Search codebase for similar features and reusable components before designing.
Search strategy:
# Search for similar features (by name similarity)
grep -r "authentication" src/
grep -r "user profile" src/
grep -r "dashboard" src/
# Search for reusable components (by function)
grep -r "class.*Service" src/ # Service layer
grep -r "export.*Repository" src/ # Repository pattern
grep -r "function validate" src/ # Validation utilities
grep -r "export.*schema" src/ # Data schemas
Expected findings: 5-15 reuse opportunities per feature
Reuse categories:
Documentation:
## Reuse Opportunities (research.md)
### Services (3 found)
- src/services/AuthService.ts - Reuse for user authentication flow
- src/services/ValidationService.ts - Reuse for form validation
- src/services/EmailService.ts - Reuse for notification emails
### Components (7 found)
- src/components/UserForm.tsx - Adapt for profile editing
- src/components/DataTable.tsx - Reuse for user list display
...
Anti-pattern: Designing from scratch without searching for reuse (wastes time, creates duplication)
See resources/code-reuse-analysis.md for search patterns and anti-duplication strategies.
Design component structure, layers, and design patterns.
Layers (typical web application):
Component design:
## Architecture (plan.md)
### Components
**Frontend** (Next.js):
- pages/users/profile.tsx - User profile page
- components/ProfileForm.tsx - Editable profile form
- hooks/useUser.ts - User data fetching hook
**Backend** (Node.js + Express):
- routes/users.ts - User API routes
- controllers/UserController.ts - Request handling logic
- services/UserService.ts - Business logic (validation, transformation)
- repositories/UserRepository.ts - Database access (PostgreSQL)
**Database**:
- users table - User data (id, name, email, password_hash)
- user_profiles table - Extended profile data (bio, avatar_url, preferences)
Design patterns to follow (from system-architecture.md):
Validation: Architecture aligns with tech-stack.md and system-architecture.md constraints
See resources/architecture-planning.md for complete component design workflow.
Design entities, relationships, and database migrations.
Entity design:
## Data Model (plan.md)
### Entities
**users** (existing table - reuse):
- id (UUID, PK)
- email (VARCHAR, UNIQUE, NOT NULL)
- password_hash (VARCHAR, NOT NULL)
- created_at (TIMESTAMP, NOT NULL)
**user_profiles** (new table):
- id (UUID, PK)
- user_id (UUID, FK → users.id, UNIQUE, NOT NULL)
- bio (TEXT, NULLABLE)
- avatar_url (VARCHAR, NULLABLE)
- preferences (JSONB, NULLABLE)
- updated_at (TIMESTAMP, NOT NULL)
ERD diagram (Mermaid):
erDiagram
users ||--o| user_profiles : has
users {
UUID id PK
VARCHAR email
VARCHAR password_hash
TIMESTAMP created_at
}
user_profiles {
UUID id PK
UUID user_id FK
TEXT bio
VARCHAR avatar_url
JSONB preferences
TIMESTAMP updated_at
}
Migrations:
-- Migration: 2025-11-19-create-user-profiles.sql
CREATE TABLE user_profiles (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID UNIQUE NOT NULL REFERENCES users(id) ON DELETE CASCADE,
bio TEXT,
avatar_url VARCHAR(500),
preferences JSONB DEFAULT '{}',
updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_user_profiles_user_id ON user_profiles(user_id);
Validation: ERD aligns with data-architecture.md naming conventions and storage strategy
See resources/data-model-planning.md for complete entity design and migration workflow.
Design API endpoints, request/response schemas, and validation rules.
API design (follows api-strategy.md patterns):
## API Endpoints (plan.md)
### GET /api/users/:id/profile
**Description**: Fetch user profile by user ID
**Auth**: Required (JWT token)
**Request**: None
**Response** (200 OK):
```json
{
"id": "uuid",
"user_id": "uuid",
"bio": "string",
"avatar_url": "string",
"preferences": {
"theme": "dark",
"notifications_enabled": true
},
"updated_at": "2025-11-19T10:00:00Z"
}
```
Errors: 401 Unauthorized, 404 Not Found
Description: Update user profile Auth: Required (JWT token, must own profile) Request:
{
"bio": "string (max 500 chars)",
"avatar_url": "string (valid URL)",
"preferences": {
"theme": "light|dark",
"notifications_enabled": boolean
}
}
Response (200 OK): Updated profile object Errors: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
**OpenAPI specification** (if applicable):
- Generate OpenAPI 3.0 spec for all endpoints
- Include request/response schemas, validation rules, error codes
- Save to docs/api/openapi.yaml
**Validation**: API design follows api-strategy.md REST patterns, error handling (RFC 7807), and auth requirements
See resources/api-contracts.md for OpenAPI generation and contract-first development.
</step>
<step number="6">
**Plan Testing Strategy**
Define test coverage plan with specific test types.
**Testing layers** (from development-workflow.md):
```markdown
## Testing Strategy (plan.md)
### Unit Tests (80% coverage target)
**Backend**:
- UserService.ts - Business logic validation
- test: updateProfile validates bio length (max 500 chars)
- test: updateProfile validates avatar URL format
- test: updateProfile preserves existing preferences when partial update
- UserRepository.ts - Database queries
- test: findByUserId returns profile or null
- test: updateProfile updates only provided fields
**Frontend**:
- ProfileForm.tsx - UI component behavior
- test: validates bio length before submission
- test: shows error message for invalid avatar URL
- test: preserves unsaved changes on navigation away
### Integration Tests
**API Endpoints**:
- PUT /api/users/:id/profile
- test: authenticated user can update own profile
- test: user cannot update other user's profile (403)
- test: invalid bio length returns 400 with error details
**Database**:
- User + UserProfile relationship
- test: deleting user cascades to user_profiles
- test: user can have only one profile (UNIQUE constraint)
### E2E Tests (Critical paths only)
- User updates profile bio and sees changes reflected
- User uploads avatar image and sees preview
- User changes theme preference and UI updates
Coverage targets:
Validation: Testing strategy aligns with development-workflow.md Definition of Done
See resources/testing-strategy.md for test type selection and coverage planning.
Predict task count based on feature scope (20-30 tasks expected).
Estimation formula:
Total Tasks = Frontend Tasks + Backend Tasks + Database Tasks + Testing Tasks + Documentation Tasks
Frontend Tasks = Components × 2 (implement + tests)
Backend Tasks = Endpoints × 3 (controller + service + tests)
Database Tasks = Tables × 2 (migration + tests)
Testing Tasks = Integration Tests + E2E Tests
Documentation Tasks = 1-2 (README, API docs)
Example calculation:
## Complexity Estimate (research.md)
**Frontend**:
- 2 components (ProfileForm, ProfilePage) × 2 = 4 tasks
**Backend**:
- 2 endpoints (GET, PUT) × 3 = 6 tasks
**Database**:
- 1 table (user_profiles) × 2 = 2 tasks
**Testing**:
- 3 integration tests = 3 tasks
- 2 E2E tests = 2 tasks
**Documentation**:
- Update README = 1 task
- Update API docs = 1 task
**Total**: 19 tasks (within 20-30 range ✅)
Complexity tiers:
Validation: Estimate aligns with feature scope from spec.md
See resources/complexity-estimation.md for detailed estimation formulas and calibration.
Generate plan.md and research.md with all findings.
plan.md structure:
# Implementation Plan: [Feature Name]
## Architecture
[Component structure, layers, design patterns from Step 3]
## Data Model
[Entities, ERD, migrations from Step 4]
## API Endpoints
[Endpoint design, schemas, validation from Step 5]
## Testing Strategy
[Unit, integration, E2E tests from Step 6]
## Implementation Sequence
1. Database migration (user_profiles table)
2. Backend API endpoints (GET, PUT /api/users/:id/profile)
3. Frontend components (ProfileForm, ProfilePage)
4. Integration tests (API + database)
5. E2E tests (user journeys)
6. Documentation (README, API docs)
research.md structure:
# Research Findings: [Feature Name]
## Project Context
[Constraints from 8 project docs - Step 1]
## Reuse Opportunities
[5-15 reusable components found - Step 2]
## Complexity Estimate
[Task count prediction - Step 7]
## Technical Decisions
- Database: PostgreSQL (from tech-stack.md)
- API: REST (from api-strategy.md)
- Auth: JWT (existing pattern from codebase)
- Frontend: Next.js + React (from tech-stack.md)
Validation: Both files created in specs/NNN-slug/ directory
See reference.md for complete artifact generation workflow.
Planning phase complete when all validation criteria met. Ready to proceed to /tasks phase.
Why: Wastes time rebuilding existing components. Creates code duplication.
Impact:
Example (bad):
/plan starts immediately with architecture design
Designs new AuthService from scratch
Reality: src/services/AuthService.ts already exists (reusable)
Result: Duplicate AuthService, 4 hours wasted
Example (good):
/plan starts with code reuse search (Step 2)
Finds: src/services/AuthService.ts (reusable)
Designs: Extend AuthService with new method (not rebuild)
Result: 30 minutes work (vs 4 hours)
Why: Hallucinate wrong technology choices. Violate project standards.
Impact:
Example (bad):
/plan skips project docs loading
Plans: GraphQL API with MongoDB
Reality: tech-stack.md specifies REST + PostgreSQL
Result: Entire plan must be redone (2-3 hours wasted)
Example (good):
/plan loads tech-stack.md first (Step 1)
Reads: Database = PostgreSQL, API = REST
Plans: REST API with PostgreSQL (aligned)
Result: Plan approved on first review
Why: No clear Definition of Done. Implementation phase lacks test guidance.
Impact:
Example (bad):
Testing Strategy: "Write unit tests for all components"
Implementation phase: Unclear what to test, how much coverage needed
Result: 45% coverage, missing integration tests
Example (good):
Testing Strategy:
- Unit: UserService.updateProfile validates bio length (80% coverage)
- Integration: PUT /api/users/:id/profile with auth
- E2E: User updates profile and sees changes
Implementation phase: Clear guidance, all tests implemented
Result: 85% coverage, all test types covered
Why: No velocity tracking. Can't detect scope creep.
Impact:
Example (bad):
/plan: No complexity estimate
/tasks: Generates 45 tasks
Question: "Is 45 tasks reasonable for this feature?"
Answer: Unknown (no baseline estimate)
Example (good):
/plan: Estimates 20-30 tasks (Step 7)
/tasks: Generates 45 tasks
Red flag: 45 > 30 (scope creep detected)
Action: Review tasks, remove unnecessary work
Result: 28 tasks (aligned with estimate)
Why: Frontend/backend integration bugs. No clear contract to test against.
Impact:
Example (bad):
API Endpoints: "GET /api/users/:id/profile - Returns user profile"
Implementation: Frontend expects { bio, avatar }, backend returns { description, image }
Result: Integration bug, 2 hours debugging
Example (good):
API Endpoints:
GET /api/users/:id/profile
Response: { "bio": string, "avatar_url": string, "preferences": object }
Validation: bio max 500 chars, avatar_url must be valid URL
Implementation: Frontend and backend aligned on contract
Result: Zero integration bugs
Result: Faster implementation, less duplication, consistent patterns
Result: No hallucinated tech choices, compliant architecture
Result: Clear Definition of Done, comprehensive test coverage
Result: Detect scope creep, track velocity, validate task breakdown
Result: Zero integration bugs, contract-first development
Ready to proceed to /tasks phase for task breakdown.
Bad planning:
Issue: Found <5 reuse opportunities (expected 5-15) Solution: Expand search - try broader keywords, search for design patterns (Repository, Service), check dependencies
Issue: Complexity estimate >50 tasks (expected 20-30) Solution: Feature too large - split into multiple features, remove nice-to-have requirements, simplify scope
Issue: API contract doesn't match existing patterns Solution: Review api-strategy.md and existing endpoints for consistent patterns, align with project standards
Issue: ERD too complex (>10 entities for single feature) Solution: Scope too large - split into multiple features, or some entities already exist (check data-architecture.md)
Planning artifacts:
Estimation & validation:
Examples:
Next phase: After planning completes → /tasks (break down into 20-30 concrete implementation tasks)
