Commandtypescript

/plan-feature Command

Create comprehensive feature implementation plan with codebase analysis and research

View Source
<objective> Transform "$ARGUMENTS" into a battle-tested implementation plan through systematic codebase exploration, pattern extraction, and strategic research.

Core Principle: PLAN ONLY - no code written. Create a context-rich document that enables one-pass implementation success.

Execution Order: CODEBASE FIRST, RESEARCH SECOND. Solutions must fit existing patterns before introducing new ones.

Agent Strategy: Use Task tool with subagent_type="Explore" for codebase intelligence gathering. This ensures thorough pattern discovery before any external research. </objective>

<context> Project structure: !`ls -la src/` Package info: !`cat package.json | head -30` Existing features: !`ls src/features/ 2>/dev/null || echo "No features directory"` CLAUDE.md rules: @CLAUDE.md </context> <process>

Phase 1: PARSE - Feature Understanding

EXTRACT from input:

  • Core problem being solved
  • User value and business impact
  • Feature type: NEW_CAPABILITY | ENHANCEMENT | REFACTOR | BUG_FIX
  • Complexity: LOW | MEDIUM | HIGH
  • Affected systems list

FORMULATE user story:

As a <user type>
I want to <action/goal>
So that <benefit/value>

PHASE_1_CHECKPOINT:

  • [ ] Problem statement is specific and testable
  • [ ] User story follows correct format
  • [ ] Complexity assessment has rationale
  • [ ] Affected systems identified

GATE: If requirements are AMBIGUOUS → STOP and ASK user for clarification before proceeding.

Phase 2: EXPLORE - Codebase Intelligence

CRITICAL: Use Task tool with subagent_type="Explore" and prompt for thoroughness="very thorough"

Example Task invocation:

Explore the codebase to find patterns, conventions, and integration points
relevant to implementing: [feature description].

DISCOVER:
1. Similar implementations - find analogous features with file:line references
2. Naming conventions - extract actual examples of function/class/file naming
3. Error handling patterns - how errors are created, thrown, caught
4. Logging patterns - logger usage, message formats
5. Type definitions - relevant interfaces and types
6. Test patterns - test file structure, assertion styles
7. Integration points - where new code connects to existing
8. Dependencies - relevant libraries already in use

Return ACTUAL code snippets from codebase, not generic examples.

DOCUMENT discoveries in table format:

| Category | File:Lines | Pattern Description | Code Snippet | |----------|-----------|---------------------|--------------| | NAMING | src/features/X/service.ts:10-15 | camelCase functions | export function createThing() | | ERRORS | src/features/X/errors.ts:5-20 | Custom error classes | class ThingNotFoundError | | LOGGING | src/core/logging/index.ts:1-10 | getLogger pattern | const logger = getLogger("domain") | | TESTS | src/features/X/tests/service.test.ts:1-30 | describe/it blocks | describe("service", () => { | | TYPES | src/features/X/models.ts:1-20 | Drizzle inference | type Thing = typeof things.$inferSelect |

PHASE_2_CHECKPOINT:

  • [ ] Explore agent launched and completed successfully
  • [ ] At least 3 similar implementations found with file:line refs
  • [ ] Code snippets are ACTUAL (copy-pasted from codebase, not invented)
  • [ ] Integration points mapped with specific file paths
  • [ ] Dependencies cataloged with versions from package.json

Phase 3: RESEARCH - External Documentation

ONLY AFTER Phase 2 is complete - solutions must fit existing codebase patterns first.

SEARCH for (use WebSearch tool):

  • Official documentation for involved libraries (match versions from package.json)
  • Known gotchas, breaking changes, deprecations
  • Security considerations and best practices
  • Performance optimization patterns

FORMAT references with specificity:

- [Library Docs v{version}](https://url#specific-section)
  - KEY_INSIGHT: {what we learned that affects implementation}
  - APPLIES_TO: {which task/file this affects}
  - GOTCHA: {potential pitfall and how to avoid}

PHASE_3_CHECKPOINT:

  • [ ] Documentation versions match package.json
  • [ ] URLs include specific section anchors (not just homepage)
  • [ ] Gotchas documented with mitigation strategies
  • [ ] No conflicting patterns between external docs and existing codebase

Phase 4: DESIGN - UX Transformation

CREATE ASCII diagrams showing user experience before and after:

╔═══════════════════════════════════════════════════════════════════════════════╗
║                              BEFORE STATE                                      ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║                                                                               ║
║   ┌─────────────┐         ┌─────────────┐         ┌─────────────┐            ║
║   │   Screen/   │ ──────► │   Action    │ ──────► │   Result    │            ║
║   │  Component  │         │   Current   │         │   Current   │            ║
║   └─────────────┘         └─────────────┘         └─────────────┘            ║
║                                                                               ║
║   USER_FLOW: [describe current step-by-step experience]                       ║
║   PAIN_POINT: [what's missing, broken, or inefficient]                        ║
║   DATA_FLOW: [how data moves through the system currently]                    ║
║                                                                               ║
╚═══════════════════════════════════════════════════════════════════════════════╝

╔═══════════════════════════════════════════════════════════════════════════════╗
║                               AFTER STATE                                      ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║                                                                               ║
║   ┌─────────────┐         ┌─────────────┐         ┌─────────────┐            ║
║   │   Screen/   │ ──────► │   Action    │ ──────► │   Result    │            ║
║   │  Component  │         │    NEW      │         │    NEW      │            ║
║   └─────────────┘         └─────────────┘         └─────────────┘            ║
║                                   │                                           ║
║                                   ▼                                           ║
║                          ┌─────────────┐                                      ║
║                          │ NEW_FEATURE │  ◄── [new capability added]          ║
║                          └─────────────┘                                      ║
║                                                                               ║
║   USER_FLOW: [describe new step-by-step experience]                           ║
║   VALUE_ADD: [what user gains from this change]                               ║
║   DATA_FLOW: [how data moves through the system after]                        ║
║                                                                               ║
╚═══════════════════════════════════════════════════════════════════════════════╝

DOCUMENT interaction changes:

| Location | Before | After | User_Action | Impact | |----------|--------|-------|-------------|--------| | /route | State A | State B | Click X | Can now Y | | Component.tsx | Missing feature | Has feature | Input Z | Gets result W |

PHASE_4_CHECKPOINT:

  • [ ] Before state accurately reflects current system behavior
  • [ ] After state shows ALL new capabilities
  • [ ] Data flows are traceable from input to output
  • [ ] User value is explicit and measurable

Phase 5: ARCHITECT - Strategic Design

ANALYZE deeply (use extended thinking if needed):

  • ARCHITECTURE_FIT: How does this integrate with vertical slice structure?
  • EXECUTION_ORDER: What must happen first → second → third?
  • FAILURE_MODES: Edge cases, race conditions, error scenarios?
  • PERFORMANCE: Will this scale? Database queries optimized?
  • SECURITY: Attack vectors? Data exposure risks? Auth/authz?
  • MAINTAINABILITY: Will future devs understand this code?

DECIDE and document:

APPROACH_CHOSEN: [description]
RATIONALE: [why this over alternatives - reference codebase patterns]

ALTERNATIVES_REJECTED:
- [Alternative 1]: Rejected because [specific reason]
- [Alternative 2]: Rejected because [specific reason]

NOT_BUILDING (explicit scope limits):
- [Item 1 - explicitly out of scope and why]
- [Item 2 - explicitly out of scope and why]

PHASE_5_CHECKPOINT:

  • [ ] Approach aligns with existing vertical slice architecture
  • [ ] Dependencies ordered correctly (types → repository → service → routes)
  • [ ] Edge cases identified with specific mitigation strategies
  • [ ] Scope boundaries are explicit and justified

Phase 6: GENERATE - Implementation Plan File

OUTPUT_PATH: .agents/plans/{kebab-case-feature-name}.plan.md

Create directory if needed: mkdir -p .agents/plans

PLAN_STRUCTURE (the template to fill and save):

# Feature: {Feature Name}

## Summary
{One paragraph: What we're building and high-level approach}

## User Story
As a {user type}
I want to {action}
So that {benefit}

## Problem Statement
{Specific problem this solves - must be testable}

## Solution Statement
{How we're solving it - architecture overview}

## Metadata
| Field | Value |
|-------|-------|
| Type | NEW_CAPABILITY / ENHANCEMENT / REFACTOR / BUG_FIX |
| Complexity | LOW / MEDIUM / HIGH |
| Systems Affected | {comma-separated list} |
| Dependencies | {external libs/services with versions} |
| Estimated Tasks | {count} |

---

## UX Design

### Before State

{ASCII diagram - current user experience with data flows}


### After State

{ASCII diagram - new user experience with data flows}


### Interaction Changes
| Location | Before | After | User Impact |
|----------|--------|-------|-------------|
| {path/component} | {old behavior} | {new behavior} | {what changes for user} |

---

## Mandatory Reading

**CRITICAL: Implementation agent MUST read these files before starting any task:**

| Priority | File | Lines | Why Read This |
|----------|------|-------|---------------|
| P0 | `path/to/critical.ts` | 10-50 | Pattern to MIRROR exactly |
| P1 | `path/to/types.ts` | 1-30 | Types to IMPORT |
| P2 | `path/to/test.ts` | all | Test pattern to FOLLOW |

**External Documentation:**
| Source | Section | Why Needed |
|--------|---------|------------|
| [Lib Docs v{version}](url#anchor) | {section name} | {specific reason} |

---

## Patterns to Mirror

**NAMING_CONVENTION:**
```typescript
// SOURCE: src/features/example/service.ts:10-15
// COPY THIS PATTERN:
{actual code snippet from codebase}

ERROR_HANDLING:

// SOURCE: src/features/example/errors.ts:5-20
// COPY THIS PATTERN:
{actual code snippet from codebase}

LOGGING_PATTERN:

// SOURCE: src/features/example/service.ts:25-30
// COPY THIS PATTERN:
{actual code snippet from codebase}

REPOSITORY_PATTERN:

// SOURCE: src/features/example/repository.ts:10-40
// COPY THIS PATTERN:
{actual code snippet from codebase}

SERVICE_PATTERN:

// SOURCE: src/features/example/service.ts:40-80
// COPY THIS PATTERN:
{actual code snippet from codebase}

TEST_STRUCTURE:

// SOURCE: src/features/example/tests/service.test.ts:1-25
// COPY THIS PATTERN:
{actual code snippet from codebase}

Files to Change

| File | Action | Justification | |------|--------|---------------| | src/features/new/models.ts | CREATE | Type definitions - re-export from schema | | src/features/new/schemas.ts | CREATE | Zod validation schemas | | src/features/new/errors.ts | CREATE | Feature-specific errors | | src/features/new/repository.ts | CREATE | Database operations | | src/features/new/service.ts | CREATE | Business logic | | src/features/new/index.ts | CREATE | Public API exports | | src/core/database/schema.ts | UPDATE | Add table definition |

NOT Building (Scope Limits)

Explicit exclusions to prevent scope creep:

  • {Item 1 - explicitly out of scope and why}
  • {Item 2 - explicitly out of scope and why}

Step-by-Step Tasks

Execute in order. Each task is atomic and independently verifiable.

Task 1: CREATE src/core/database/schema.ts (update)

  • ACTION: ADD table definition to schema
  • IMPLEMENT: {specific columns, types, constraints}
  • MIRROR: src/core/database/schema.ts:XX-YY - follow existing table pattern
  • IMPORTS: import { pgTable, text, timestamp } from "drizzle-orm/pg-core"
  • GOTCHA: {known issue to avoid, e.g., "use uuid for id, not serial"}
  • VALIDATE: npx tsc --noEmit - types must compile

Task 2: CREATE src/features/new/models.ts

  • ACTION: CREATE type definitions file
  • IMPLEMENT: Re-export table, define inferred types
  • MIRROR: src/features/projects/models.ts:1-10
  • IMPORTS: import { things } from "@/core/database/schema"
  • TYPES: type Thing = typeof things.$inferSelect
  • GOTCHA: Use $inferSelect for read types, $inferInsert for write
  • VALIDATE: npx tsc --noEmit

Task 3: CREATE src/features/new/schemas.ts

  • ACTION: CREATE Zod validation schemas
  • IMPLEMENT: CreateThingSchema, UpdateThingSchema
  • MIRROR: src/features/projects/schemas.ts:1-30
  • IMPORTS: import { z } from "zod/v4" (note: zod/v4 not zod)
  • GOTCHA: z.record requires two args in v4
  • VALIDATE: npx tsc --noEmit

Task 4: CREATE src/features/new/errors.ts

  • ACTION: CREATE feature-specific error classes
  • IMPLEMENT: ThingNotFoundError, ThingAccessDeniedError
  • MIRROR: src/features/projects/errors.ts:1-40
  • PATTERN: Extend base Error, include code and statusCode
  • VALIDATE: npx tsc --noEmit

Task 5: CREATE src/features/new/repository.ts

  • ACTION: CREATE database operations
  • IMPLEMENT: findById, findByUserId, create, update, delete
  • MIRROR: src/features/projects/repository.ts:1-60
  • IMPORTS: import { db } from "@/core/database/client"
  • GOTCHA: Use results[0] pattern, not .first() - check noUncheckedIndexedAccess
  • VALIDATE: npx tsc --noEmit

Task 6: CREATE src/features/new/service.ts

  • ACTION: CREATE business logic layer
  • IMPLEMENT: createThing, getThing, updateThing, deleteThing
  • MIRROR: src/features/projects/service.ts:1-80
  • PATTERN: Use repository, add logging, throw custom errors
  • IMPORTS: import { getLogger } from "@/core/logging"
  • VALIDATE: npx tsc --noEmit && bun run lint

Task 7: CREATE src/features/new/index.ts

  • ACTION: CREATE public API exports
  • IMPLEMENT: Export types, schemas, errors, service functions
  • MIRROR: src/features/projects/index.ts:1-20
  • PATTERN: Named exports only, hide repository (internal)
  • VALIDATE: npx tsc --noEmit

Task 8: CREATE src/features/new/tests/service.test.ts

  • ACTION: CREATE unit tests for service
  • IMPLEMENT: Test each service function, happy path + error cases
  • MIRROR: src/features/projects/tests/service.test.ts:1-100
  • PATTERN: Use describe/it from bun:test, mock repository
  • VALIDATE: bun test src/features/new/tests/

Testing Strategy

Unit Tests to Write

| Test File | Test Cases | Validates | |-----------|-----------|-----------| | src/features/new/tests/schemas.test.ts | valid input, invalid input | Zod schemas | | src/features/new/tests/errors.test.ts | error properties | Error classes | | src/features/new/tests/service.test.ts | CRUD ops, access control | Business logic |

Edge Cases Checklist

  • [ ] Empty string inputs
  • [ ] Missing required fields
  • [ ] Unauthorized access attempts
  • [ ] Not found scenarios
  • [ ] Duplicate creation attempts
  • [ ] {feature-specific edge case}

Validation Commands

Level 1: STATIC_ANALYSIS

bun run lint && npx tsc --noEmit

EXPECT: Exit 0, no errors or warnings

Level 2: UNIT_TESTS

bun test src/features/{feature}/tests/

EXPECT: All tests pass, coverage >= 80%

Level 3: FULL_SUITE

bun test && bun run build

EXPECT: All tests pass, build succeeds, dist/ created

Level 4: DATABASE_VALIDATION (if schema changes)

Use Supabase MCP to verify:

  • [ ] Table created with correct columns
  • [ ] RLS policies applied
  • [ ] Indexes created

Level 5: BROWSER_VALIDATION (if UI changes)

Use Browser MCP to verify:

  • [ ] UI renders correctly
  • [ ] User flows work end-to-end
  • [ ] Error states display properly

Level 6: MANUAL_VALIDATION

{Step-by-step manual testing specific to this feature}

Acceptance Criteria

  • [ ] All specified functionality implemented per user story
  • [ ] Level 1-3 validation commands pass with exit 0
  • [ ] Unit tests cover >= 80% of new code
  • [ ] Code mirrors existing patterns exactly (naming, structure, logging)
  • [ ] No regressions in existing tests
  • [ ] UX matches "After State" diagram

Completion Checklist

  • [ ] All tasks completed in dependency order
  • [ ] Each task validated immediately after completion
  • [ ] Level 1: bun run lint && npx tsc --noEmit passes
  • [ ] Level 2: bun test {pattern} passes
  • [ ] Level 3: bun test && bun run build succeeds
  • [ ] Level 4: Database validation passes (if applicable)
  • [ ] Level 5: Browser validation passes (if applicable)
  • [ ] All acceptance criteria met

Risks and Mitigations

| Risk | Likelihood | Impact | Mitigation | |------|------------|--------|------------| | {Risk description} | LOW/MED/HIGH | LOW/MED/HIGH | {Specific prevention/handling strategy} |

Notes

{Additional context, design decisions, trade-offs, future considerations}


</process>

<output>
**OUTPUT_FILE**: `.agents/plans/{kebab-case-feature-name}.plan.md`

**REPORT_TO_USER** (display after creating plan):

```markdown
## Plan Created

**File**: `.agents/plans/{feature-name}.plan.md`

**Summary**: {2-3 sentence feature overview}

**Complexity**: {LOW/MEDIUM/HIGH} - {brief rationale}

**Scope**:
- {N} files to CREATE
- {M} files to UPDATE
- {K} total tasks

**Key Patterns Discovered**:
- {Pattern 1 from Explore agent with file:line}
- {Pattern 2 from Explore agent with file:line}

**External Research**:
- {Key doc 1 with version}
- {Key doc 2 with version}

**UX Transformation**:
- BEFORE: {one-line current state}
- AFTER: {one-line new state}

**Risks**:
- {Primary risk}: {mitigation}

**Confidence Score**: {1-10}/10 for one-pass implementation success
- {Rationale for score}

**Next Step**: To execute, run: `/execute-plan .agents/plans/{feature-name}.plan.md`
</output> <verification> **FINAL_VALIDATION before saving plan:**

CONTEXT_COMPLETENESS:

  • [ ] All patterns from Explore agent documented with file:line references
  • [ ] External docs versioned to match package.json
  • [ ] Integration points mapped with specific file paths
  • [ ] Gotchas captured with mitigation strategies
  • [ ] Every task has at least one executable validation command

IMPLEMENTATION_READINESS:

  • [ ] Tasks ordered by dependency (can execute top-to-bottom)
  • [ ] Each task is atomic and independently testable
  • [ ] No placeholders - all content is specific and actionable
  • [ ] Pattern references include actual code snippets (copy-pasted, not invented)

PATTERN_FAITHFULNESS:

  • [ ] Every new file mirrors existing codebase style exactly
  • [ ] No unnecessary abstractions introduced
  • [ ] Naming follows discovered conventions
  • [ ] Error/logging patterns match existing
  • [ ] Test structure matches existing tests

VALIDATION_COVERAGE:

  • [ ] Every task has executable validation command
  • [ ] All 6 validation levels defined where applicable
  • [ ] Edge cases enumerated with test plans

UX_CLARITY:

  • [ ] Before/After ASCII diagrams are detailed and accurate
  • [ ] Data flows are traceable
  • [ ] User value is explicit and measurable

NO_PRIOR_KNOWLEDGE_TEST: Could an agent unfamiliar with this codebase implement using ONLY the plan? </verification>

<success_criteria> CONTEXT_COMPLETE: All patterns, gotchas, integration points documented from actual codebase via Explore agent IMPLEMENTATION_READY: Tasks executable top-to-bottom without questions, research, or clarification PATTERN_FAITHFUL: Every new file mirrors existing codebase style exactly VALIDATION_DEFINED: Every task has executable verification command UX_DOCUMENTED: Before/After transformation is visually clear with data flows ONE_PASS_TARGET: Confidence score 8+ indicates high likelihood of first-attempt success </success_criteria>