Command: plan-feature
CRITICAL: PLANS ARE SPECIFICATIONS ONLY
NO CODE, NO SQL, NO HARDCODED SCHEMAS
No SQL migration code | No TypeScript/JavaScript | No hardcoded schema fields
Fetch database schema dynamically (when needed) | Describe conceptually | Reference patterns
Purpose: Transform user ideas or audit reports into structured implementation plans
When to use: User provides feature idea, brain dump, or audit file
Output: MULTIPLE planning documents in docs/plans/ - one per phase step (1.1, 1.2, 2.1, etc.)
Execution Contract
| Aspect |
Value |
| Scope |
Specification-only, no executable code or SQL |
| Primary tools |
read_file, grep, codebase_search, list_dir, glob_file_search, mcp_supabase_execute_sql (SELECT only), docker exec psql (SELECT only) |
| Forbidden |
Schema migrations, seed files, code edits, .env* changes, browser tools |
| Effort budget |
≤15 tool calls, ≤15 minutes (unless deep multi-module plan requested) |
| Mode |
Targeted discovery (tables/pages/components), avoid full-repo sweeps unless broad |
Tool Usage
| Use |
Avoid |
src/types/database.types.ts as primary schema reference |
Creating code/SQL in plan files |
read_file / grep / codebase_search for components/pages/patterns |
Heavy repo-wide searches when user specified files/routes |
| Database queries (SELECT only) for live schema/data examples |
|
Scope of Schema & Discovery
| Scenario |
Action |
| Feature involves tables/columns/relationships/migrations/RLS/seeds |
Fetch schema |
| Pure UI/routing, user confirms “no database changes” |
Schema fetch optional |
| No obvious existing pattern/component fits |
Run full discovery |
| User provided similar pages/components |
Keep discovery minimal, start from those |
Why multiple docs: Each doc = one agent task | Enable true parallel execution | Clear dependencies
Note: Audit files are deleted only if they were read and used as input, and only after plan files are created successfully.
Command Trigger
Activates when: User calls @plan-feature
Workflow
Fetch Schema → Discover → Clarify → Confirm → Create Plan → Delete Audit → Ready
Key Principles: Always fetch fresh schema | Plans define WHAT and WHY, not HOW | No code/SQL in plans | Reference patterns | Decisions only
Communication
Output: Questions in structured format (table/bullets) | Concise confirmations | No explanations of process
Phase 0: Fetch Database Schema
ALWAYS RUN - Required for all features (API routes, components, database changes)
| Step |
Action |
Details |
| 0 |
Check types file |
Read src/types/database.types.ts (auto-generated, current schema) |
| 1 |
Get schema |
docker exec supabase_db_anomaly psql -U postgres -d postgres -c "\dt" (list tables), \d+ table_name (table details), \d+ public.* (all public tables) |
| 2 |
Analyze structure |
Naming conventions, relationship patterns, field types, enums/options tables, RLS patterns |
| Capture |
Analyze For |
| Table names, columns/types, PKs, FKs, indexes, constraints |
Naming conventions, relationship patterns, common field types, enums/options tables, RLS patterns |
Phase 1: Codebase Discovery
| Step |
Action |
Search For |
| 1 |
Read docs |
docs/quick-reference.md (components), docs/guides/*.md (patterns), docs/database/*.md (schema), docs/architecture.md (tech stack) |
| 2 |
Search components |
src/components/ - Form patterns (TextInput, EmailInput, selectors), Table/list (ListPageCard, tables), Data display (cards, detail pages), Interactive (modals, sheets, dialogs), Navigation (tabs, filters) |
| 3 |
Search pages |
src/app/ - Similar entity pages, list pages (filters/search), detail pages (tabs), form submission patterns, API route patterns |
| 4 |
Identify patterns |
List page (filter/search/table), detail page tabs, slide-in form, delete confirmation, searchable selector, table pattern |
| 5 |
Note reusable |
Document: Existing components, similar pages/patterns, relevant guides |
| Database Patterns |
|
| Soft delete |
is_deleted |
| Timestamps |
created_at, updated_at |
| User relationships |
created_by, user_id |
| RLS policies |
|
Phase 2: Clarification
| Step |
Action |
Details |
| 1 |
Read input |
User brain dump, audit report (docs/reports/*-report-*.md), existing plan |
| 1 |
Identify report |
Track *-report-*.md files for deletion after plan creation |
| 1 |
Analyze |
Clear/unclear requirements, missing info, ambiguous logic, assumptions |
| 2 |
Match patterns |
Can reuse components? Similar pages? DB conventions? API structure? |
| 2 |
Reduce questions |
Default to discovered patterns, use existing components, follow conventions, ask only about unique requirements |
| 3 |
Generate questions |
Requirements not covered by patterns, business logic, unique data, different user flows |
| Input Type |
Description |
| Reports (audits) |
List problems/fixes, no implementation, INPUT to planning |
| Plans (this command) |
Implementation roadmap with phases, command keywords, OUTPUT |
| Category |
Questions |
| User Roles |
Who accesses? Roles? Permissions? |
| Data Model |
Tables/fields? Relationships? New/existing? |
| UI Flow |
Pages? Actions? Navigation? |
| Business Logic |
Rules? Calculations? Validations? |
| Edge Cases |
No data? Errors? Duplicates? |
| Dependencies |
Other features? New tables required? |
| Permissions |
Who can view? Edit? Delete? |
Step 4: Ask Questions
Show discovery context:
## Feature Planning: [Name]
### Discovered Patterns
**Components to reuse:** - ComponentA, ComponentB, ComponentC
**Similar pages:** - `/existing/page` - Uses list-page pattern
**Database conventions:** - Soft delete, timestamps, user tracking, RLS
### Clarification Questions
(Only asking about unique aspects)
### Data Model
1. Should [entity] have [field] for [purpose]?
2. Can [entity] relate to multiple [others]?
### Logic
3. What if [condition]?
4. Should [calc] update auto when [trigger]?
Step 5: Multiple Rounds
Continue until: All critical decisions made | No ambiguity | Edge cases understood | Data model clear | User flows defined
Phase 3: Confirmation
Step 1: Write Summary
CRITICAL: Wait for explicit approval
## Feature Confirmation: [Name]
### Summary: [2-3 sentence overview]
### Reusing Existing Patterns
**Components:** - `ExistingComponent1` - For [purpose] | - `ExistingComponent2` - For [purpose]
**Patterns:** - List page pattern (from `/similar/page`) | - Slide-in form pattern | - Soft delete pattern
**Database:** - Following standard: soft delete, timestamps, RLS
### Critical Decisions
**Decision 1: [Topic]**
- Decided: [What] | - Rationale: [Why]
### Implementation Scope
**Database:** - New table: `table_name` (purpose) | - Modify: `existing_table` (add columns)
**API Routes:** - `GET /api/endpoint` - Purpose
**Pages:** - `/route` - Purpose (using [pattern] from [similar page])
**New Components:** - `ComponentName` - Purpose (if any new ones needed)
### User Confirmation
**Does this match your vision? Any changes?**
Step 2: Wait for Approval
User may: Approve → Proceed to Phase 4 | 
Request changes → Update, re-confirm | 
Add requirements → Back to Phase 2
Phase 4: Plan Creation
Step 1: Determine Structure & Phase Strategy
Split by execution pattern:
IF feature has NO database changes
└─ Single plan: Phase 2 (Implementation)
IF feature has database changes (any size)
├─ Always separate Phase 1: Foundation (database-change, database-rls, seed-apply)
└─ Phase 2+: Implementation
IF feature is large (>400 lines) OR has independent modules
├─ Split into multiple plan files by module/layer
├─ Each file = separate @implement-feature task
└─ Use phase numbering to show parallel vs sequential execution
Split criteria:
├─ Independent API route groups → Separate plans (can run parallel)
├─ Shared vs feature-specific components → Separate plans (can run parallel)
├─ Role-specific pages (admin/member/staff) → Separate plans (can run parallel)
└─ Integration work → Separate plan (sequential after modules)
Target: Plans 200-400 lines | Clear phase numbering | Maximum parallelization
Step 2: File Naming - One Document Per Phase Step
CRITICAL: Create SEPARATE plan documents for EACH phase step (1.1, 1.2, 2.1, etc.)
Why: Each document = one agent task | Enable true parallel execution | Clear dependencies
Naming Convention:
[feature-name]-[phase-number]-[command-keyword]-[phase-name].md
Phase Numbering:
├─ 1.1, 1.2, 1.3 = Sequential foundation phases (must run in order)
├─ 2.1, 2.1, 2.1 = Parallel implementation phases (can run simultaneously)
└─ 3.1, 3.1 = Parallel page/integration phases
Command Keywords:
├─ implement = @implement-feature (new features, APIs, components, pages)
├─ fix = @fix-bug (bug fixes, corrections, patches)
└─ refactor = @refactor-pilot then @refactor-rollout (code improvements, optimizations, restructuring)
Examples:
| Phase |
Filename |
Command |
| 1.1 |
notifications-1.1-implement-database.md |
@database-change |
| 1.2 |
notifications-1.2-implement-rls.md |
@database-rls |
| 2.1 |
notifications-2.1-implement-api-routes.md |
@implement-feature |
| 2.1 |
notifications-2.1-implement-components.md |
@implement-feature |
| 3.1 |
notifications-3.1-implement-admin-pages.md |
@implement-feature |
| Bug fix |
fk-ambiguity-fix-services.md |
@fix-bug |
| Refactor |
server-components-refactor.md |
@refactor-pilot |
Location: docs/plans/
Rule: ALWAYS include phase number (1.1, 2.1, etc.) in filename AND phase name for clarity
Step 3: Create Files - One Per Phase Step
| Step |
Action |
| 1 |
Check docs/plans/ exists (create if missing) |
| 2 |
Create individual plan document for each phase step (1.1, 1.2, 2.1, etc.) |
| 3 |
Write files to docs/plans/[feature]-[phase]-[command]-[name].md |
| 4 |
Confirm creation with full paths and phase numbers |
| 5 |
Delete audit file if used (tracked from Phase 2, Step 1) |
| Report File Deletion |
|
| Delete if |
File matches docs/reports/*-report-*.md AND was used as input |
| Examples |
performance-report-2025-11-13.md, database-report-2025-11-13.md, codebase-report-2025-11-13.md |
| Do NOT delete |
Plan files, guides, other documentation |
| Confirm |
Show deleted file path to user |
Step 4: Individual Phase Document Structure
CRITICAL: Each phase gets its OWN document using the unified template below
Unified Plan Template
# Phase [X.X]: [Phase Name] - [Feature Name]
**Phase:** [X.X] | **Created:** [Date] | **Status:** Ready | **Estimated:** [X-Y min]
---
## Phase Info
**Phase Number:** [X.X]
**Phase Name:** [Database Schema / RLS Policies / Seed Data / API Routes / Components / Services / Pages]
**Command:** [@database-change / @database-rls / @seed-apply / @implement-feature]
**Feature:** [Overall feature name]
---
## This Phase
**What:** [2-3 sentences - what this phase accomplishes]
**Why:** [Why this phase is needed]
---
## Dependencies
**Depends on:** [None / Phase X.X complete]
**Blocks:** [Phase X.X, Phase X.X, all Phase X+]
**Can run with:** [None - sequential / List phases that can run in parallel]
---
## Context: Overall Feature
**Feature Goal:** [1-2 sentences about overall feature]
**This Phase Role:** [How this phase fits into the bigger picture]
---
## Prerequisites
**Read before implementing:**
- `docs/quick-reference.md`
- `docs/database/[relevant].md` (if database-related)
- `docs/guides/[relevant-pattern].md` (if implementation-related)
- Fetched schema: See Phase 0 (if database-related)
- Similar code: [paths] (if implementation-related)
---
## Reusing Existing
**Components:** [List existing components to use - if applicable]
**Patterns:** [List patterns from docs/guides - if applicable]
**Similar Code:** [Reference similar implementations - if applicable]
---
## Implementation Details
[FOR DATABASE PHASE 1.1:]
### Database Changes
**Schema Source:** Fetched from local Docker database
**New Tables:**
#### `table_name`
- Purpose: [What it stores]
- Pattern: Follow existing conventions (soft delete, timestamps, user tracking)
- Relationships: Links to [existing tables]
- Indexes: [Columns to index for performance]
**Modified Tables:**
#### `existing_table`
- Add fields: [Conceptual field purposes]
- Add relationships: [FK targets]
**Implementation Note:** AI fetches exact schema before implementation
[FOR RLS PHASE 1.2:]
### RLS Policies Required
**Tables:** [List tables needing RLS]
**Access Patterns:**
#### `table_name`
- SELECT: [user-scoped / role-based / public]
- INSERT: [authenticated / role-based]
- UPDATE: [owner-only / role-based]
- DELETE: [owner-only / role-based]
**Policy Specifications:**
- [Describe policy logic conceptually]
- [Reference existing similar policies]
[FOR SEED PHASE 1.3:]
### Seed Data Required
**Purpose:** [Enable local development of feature]
**Data Types:**
- [Entity type]: [N records with these characteristics]
- [Entity type]: [N records with these characteristics]
**Relationships:** [How seed data should link together]
[FOR API ROUTES:]
### API Endpoints
**GET `/api/endpoint`**
- Purpose: [Description]
- Query params: [List]
- Returns: [Data structure]
- Auth: Required/Optional
- Filter: [Logic]
- **CRITICAL:** Use slug-based references (not IDs)
**POST `/api/endpoint`**
- Purpose: [Description]
- Body: [Fields]
- Validation: [Rules]
- Auth: Required
**🔑 SLUG-BASED REFERENCES:**
- Reference options by slug: `status_slug: 'active'`
- NEVER hardcode IDs or names
- Slugs are consistent across environments
[FOR COMPONENTS:]
### Components to Create
**`ComponentName`**
- Purpose: [What it does]
- File: `src/components/[path].tsx`
- Props: [List with types]
- State: [Client/Server component]
- Pattern: [Reference similar component]
[FOR SERVICES:]
### Service Functions
**`functionName`**
- Purpose: [What it does]
- File: `src/lib/[path].ts`
- Params: [List]
- Returns: [Type]
- Pattern: [Reference similar function]
[FOR PAGES:]
### Pages to Create
**`/route/path`**
- Purpose: [What user does here]
- Pattern: [list-page / detail-page / etc.]
- Features: [Filter, search, create, edit, delete]
- Components: [List components used]
- Data: [API endpoints to fetch from]
- Auth: [Required roles]
**`/route/[id]`**
- Purpose: [Detail page function]
- Pattern: [detail-page-tabs / etc.]
- Tabs: [List tabs]
- Components: [List components]
- Data: [API endpoints]
### User Flow
1. [User action 1]
2. [System response 1]
3. [User action 2]
4. [System response 2]
---
## Security
- [ ] Auth required for protected endpoints/routes
- [ ] Input validation
- [ ] SQL injection prevention (use Supabase client)
- [ ] XSS prevention
- [ ] Role-based access (if applicable)
---
## Performance
- [ ] Efficient queries (no N+1)
- [ ] Pagination if needed
- [ ] Debounce for search
- [ ] Optimistic updates where applicable
- [ ] Code splitting if needed (pages)
- [ ] Lazy loading (pages)
---
## Accessibility
- [ ] Keyboard navigation (pages)
- [ ] Screen reader support (pages)
- [ ] Proper heading hierarchy (pages)
- [ ] Focus indicators (pages)
- [ ] Color contrast (pages)
---
## Acceptance Criteria
**Complete when:**
- [ ] [Phase-specific criterion 1]
- [ ] [Phase-specific criterion 2]
- [ ] All files created/modified
- [ ] No errors in migration/policy/seed/code
- [ ] No console errors
- [ ] No linter errors
- [ ] Functions work as specified
- [ ] Security checks pass
- [ ] Can proceed to next phase (if applicable)
*Phase Plan - Generated by @plan-feature*
Document Rules:
- Each phase = separate file
- Include phase number in filename AND header
- Keep <300 lines per document
- Make each document self-contained
- Include dependencies/blocks clearly
- Specify command to run
- Use only sections relevant to phase type
Plan Quality Checklist
Before finalizing:
- Database schema fetched (Phase 0 - ALWAYS, even if no db changes)
- Codebase discovery completed
- Existing components/patterns/similar pages referenced
- NO code/SQL/hardcoded schemas included
- SEPARATE document created for EACH phase step (1.1, 1.2, 2.1, etc.)
- Phase number included in filename ([feature]-[phase]-[command]-[name].md)
- Each document is self-contained (agent can work from single doc)
- Dependencies/blocks clearly specified (in each document)
- Each document <300 lines
- Scannable format (tables/bullets, 1-2 sentences max)
- Conceptual descriptions only (AI fetches implementation details)
- All files created in
docs/plans/
- Report file deleted if used as input (from docs/reports/)
- Optimistic update strategy specified (for list/table operations)
Best Practices
| DO |
DON’T |
| Fetch database schema first (Phase 0) |
Hardcode field types/names in plans |
| Discover existing components/patterns first |
Skip codebase discovery |
| Reference similar pages/guides |
Duplicate existing pattern docs |
| Default to established patterns |
Include any code/SQL |
| Create SEPARATE document for EACH phase step |
Create one large document with all phases |
| Include phase number in filename (1.1, 2.1, etc.) |
Use generic filenames without phase numbers |
| Make each document self-contained |
Assume agent reads multiple documents |
| Clearly specify dependencies/blocks |
Leave phase relationships unclear |
| Ask specific structured questions |
Create prose-heavy docs |
| Use tables/bullets (AI-scannable) |
Exceed 300 lines per document |
| Make all decisions in plan |
Leave decisions ambiguous |
Create files in docs/plans/ |
Skip acceptance criteria |
| Delete report file after using it |
Leave report files (from audits) |
| Include command keyword in filename (-implement, -fix, -refactor) |
Use generic plan names without keywords |
| Keep descriptions 1-2 sentences max |
Add verbose examples |
| Specify optimistic updates for lists/tables |
Plan to refetch entire lists |
| Use phase numbering: 1.1, 1.2 (sequential), 2.1, 2.1 (parallel) |
Use generic Phase 1, Phase 2 without numbers |
| Map phases to specific commands (@database-change, @database-rls, @implement-feature) |
Leave execution strategy ambiguous |
| Separate database/RLS/seed into individual docs |
Combine foundation phases in one document |
| Identify parallel work explicitly (same phase numbers = parallel) |
Assume user knows what can run in parallel |
| Enable multi-agent execution (one doc = one task) |
Create documents requiring coordination |
Success Metrics
Plan successful when:
- Database schema fetched (Phase 0 - ALWAYS)
- Codebase discovery completed
- Existing components/patterns/similar pages identified
- Questions focused on unique requirements
- User confirmed matches vision
- All requirements clear
- NO code/SQL/hardcoded schemas in plan
- SEPARATE document created for EACH phase step (1.1, 1.2, 2.1, etc.)
- Each document is self-contained (agent needs only that one doc)
- Phase number in filename ([feature]-[phase]-[command]-[name].md)
- Dependencies/blocks clearly specified (in each document)
- Plans are AI-optimized (tables/bullets, 1-2 sentences)
- Each document <300 lines
- Agent can start from single document without questions
- Decisions documented
- Multiple files created in
docs/plans/ (one per phase)
- Report file deleted if one was used as input (from docs/reports/)
- Optimistic update strategy defined (for features with list/table updates)
- Multi-agent execution enabled (parallel phases identified)
Related Commands
After Planning:
- @database-change (Phase 1.1: database schema changes)
- @database-rls (Phase 1.2: RLS policies)
- @seed-apply (Phase 1.3: test data)
- @implement-feature (Phase 2+: implements plan modules)
Note: User decides when to commit/deploy changes
Global Cursor Command - Works across all projects