marcusgoll This skill orchestrates the /plan phase, which runs after /spec (or /clarify) and before /tasks in the feature workflow.
Core responsibilities:
- Load all 8 project documentation files from docs/project/ for constraint extraction
- Search codebase for similar features and reusable components (expect 5-15 opportunities)
- Design architecture with components, layers, and design patterns
- Plan data model with entities, relationships, and migrations
- Define API contracts in OpenAPI format (if applicable)
- Plan testing strategy (unit, integration, E2E)
- Estimate complexity (20-30 tasks predicted)
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
- Load Project Documentation - Read all 8 docs/project/*.md files for constraints (tech stack, architecture, data model, API patterns)
- Research Code Reuse - Search codebase before designing (expect 5-15 reuse opportunities)
- Design Architecture - Components, layers, design patterns (MVC, Repository, etc.)
- Plan Data Model - Entities, relationships, ERD diagram, migrations
- Define API Contracts - Endpoints, schemas, validation (OpenAPI format if applicable)
- Plan Testing Strategy - Unit, integration, E2E coverage with specific test types
- Estimate Complexity - Predict 20-30 tasks based on feature scope
Key principle: Research before designing. Maximize code reuse. Align with project documentation.
See resources/ directory for detailed workflows on each step.
Before beginning planning phase:
- Specification phase completed (spec.md exists in specs/NNN-slug/)
- Feature requirements understood (success criteria, user stories, edge cases)
- Project documentation available (docs/project/*.md) OR brownfield codebase exists
- Git working tree clean (no uncommitted changes)
If specification incomplete, return to /spec or /clarify phase.
Read all 8 project documentation files for constraint extraction.
Files to load (from docs/project/):
- overview.md - Vision, users, scope, success metrics
- system-architecture.md - C4 diagrams, components, data flows
- tech-stack.md - Database, frontend, backend, deployment platform
- data-architecture.md - ERD, entity schemas, storage strategy
- api-strategy.md - REST/GraphQL patterns, auth, versioning
- capacity-planning.md - Scaling tier, cost model
- deployment-strategy.md - CI/CD pipeline, environments
- development-workflow.md - Git flow, PR process, testing strategy
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):
- Scan package.json, requirements.txt for tech stack
- Analyze existing database migrations for data model
- Review existing API routes for patterns
- Infer architecture from directory structure
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:
- Services: Authentication, validation, data transformation
- Components: Forms, tables, modals, buttons (UI)
- Utilities: Date formatting, error handling, logging
- Schemas: Database models, API contracts, validation rules
- Patterns: Repository pattern, middleware, hooks
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):
- Presentation Layer: UI components, pages, forms
- Business Logic Layer: Services, domain logic, validation
- Data Access Layer: Repositories, database queries, ORM models
- Integration Layer: External APIs, third-party services
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):
- Repository pattern for data access
- Service layer for business logic
- Dependency injection for testability
- Middleware for cross-cutting concerns (auth, logging, error handling)
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
PUT /api/users/:id/profile
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:
- Unit tests: 80% coverage (business logic + UI components)
- Integration tests: All API endpoints + critical database operations
- E2E tests: 3-5 critical user journeys
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:
- Simple: 10-15 tasks (single component, 1-2 endpoints)
- Medium: 20-30 tasks (multiple components, 3-5 endpoints) ← Most features
- Complex: 40-60 tasks (multiple pages, 10+ endpoints, complex business logic)
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.
- plan.md created with architecture, components, API contracts, testing strategy
- research.md created with project context, reuse findings (5-15 opportunities), complexity estimate
- All 8 project docs read (or brownfield research complete if docs missing)
- Code reuse opportunities identified and documented
- Testing strategy defined (unit, integration, E2E with specific tests)
- Complexity estimated (20-30 tasks predicted)
- API contracts specified in OpenAPI format (if applicable)
- Data model ERD created with Mermaid diagram (if database changes)
Planning phase complete when all validation criteria met. Ready to proceed to /tasks phase.
Why: Wastes time rebuilding existing components. Creates code duplication.
Impact:
- Duplicate code (DRY violations)
- Longer implementation time (build what exists)
- Inconsistent patterns (different auth flows, different validation)
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:
- Wrong database choice (plan PostgreSQL, project uses MongoDB)
- Wrong API style (plan GraphQL, project uses REST)
- Wrong architecture (plan microservices, project is monolith)
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:
- Low test coverage (<50% vs 80% target)
- Missing integration tests (only unit tests)
- No E2E tests for critical user journeys
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:
- Scope creep undetected (planned 20 tasks, actual 60 tasks)
- Can't validate /tasks output (is 45 tasks reasonable?)
- No burndown tracking (unknown if on schedule)
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:
- Integration bugs (frontend expects field A, backend returns field B)
- Ambiguous validation (is bio max 500 or 1000 chars?)
- No contract tests (can't validate API compliance)
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
- Search codebase for similar features (Step 2)
- Identify 5-15 reuse opportunities
- Design with reuse in mind (extend, not rebuild)
Result: Faster implementation, less duplication, consistent patterns
- Read docs/project/*.md for constraints (Step 1)
- Extract tech stack, architecture, API patterns
- Align plan with documented standards
Result: No hallucinated tech choices, compliant architecture
- Unit tests: 80% coverage with specific test cases
- Integration tests: All API endpoints + critical database operations
- E2E tests: 3-5 critical user journeys
Result: Clear Definition of Done, comprehensive test coverage
- Calculate: Frontend + Backend + Database + Testing + Documentation
- Expect: 20-30 tasks for medium features
- Use estimate to validate /tasks output
Result: Detect scope creep, track velocity, validate task breakdown
- Request/response schemas in JSON format
- Validation rules (max length, regex, required fields)
- Error codes (400, 401, 403, 404)
- OpenAPI spec if applicable
Result: Zero integration bugs, contract-first development
- plan.md created with architecture, components, API contracts, testing strategy, implementation sequence
- research.md created with project context (8 docs), reuse findings (5-15 opportunities), complexity estimate (20-30 tasks)
- All 8 project docs read (overview, architecture, tech-stack, data, API, capacity, deployment, workflow)
- Code reuse opportunities identified and documented (5-15 expected)
- Testing strategy defined (unit 80% coverage, integration all endpoints, E2E 3-5 journeys)
- Complexity estimated (20-30 tasks predicted)
- API contracts specified with request/response schemas, validation, errors
- Data model ERD created with Mermaid diagram (if database changes)
- state.yaml updated (planning.status = completed)
Ready to proceed to /tasks phase for task breakdown.
- Research-first (5-15 reuse opportunities identified)
- Project-aligned (reads all 8 docs, follows constraints)
- Specific testing strategy (named test cases, 80% coverage target)
- Complexity estimated (20-30 tasks predicted)
- Complete API contracts (schemas, validation, errors)
- ERD diagram for data model (Mermaid format)
Bad planning:
- Design-first (skips reuse search, duplicates code)
- Hallucinated tech (ignores project docs, wrong database)
- Vague testing ("write tests" with no specifics)
- No complexity estimate (scope creep undetected)
- Incomplete API contracts (no schemas, no validation)
- No ERD (entity relationships unclear)
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)
- Project Docs Integration (resources/project-docs-integration.md) - Load 8 project docs workflow
- Code Reuse Analysis (resources/code-reuse-analysis.md) - Anti-duplication search patterns
- Architecture Planning (resources/architecture-planning.md) - Component design, layers, patterns
Planning artifacts:
- Data Model Planning (resources/data-model-planning.md) - Entity design, ERD, migrations
- API Contracts (resources/api-contracts.md) - OpenAPI specs, endpoint design
- Testing Strategy (resources/testing-strategy.md) - Coverage plan, test types
Estimation & validation:
- Complexity Estimation (resources/complexity-estimation.md) - Task count prediction formulas
- Common Mistakes (resources/common-mistakes.md) - Anti-patterns to avoid
Examples:
- Good vs Bad Planning (examples.md) - Real examples from actual planning sessions
Next phase: After planning completes → /tasks (break down into 20-30 concrete implementation tasks)