Skip to main content
The Plan phase converts approved requirements into actionable technical designs. The 📝 Plan agent pairs with you to create architecture, sequencing, and validation strategies before implementation begins.

​
Agent Configuration

name: 📝 Plan
description: Transforms approved requirements into a comprehensive technical design blueprint
argument-hint: Provide approved requirements or feature context to produce technical design
target: vscode
disable-model-invocation: true
tools:
  [
    "search",
    "read",
    "edit",
    "web",
    "execute/getTerminalOutput",
    "execute/testFailure",
    "agent",
    "vscode/askQuestions",
  ]
agents: []

​
Phase Responsibility

Phase 2 of 3: Technical DesignYour SOLE responsibility is planning. NEVER start implementation.

​
What This Phase Does

  • Translates approved requirements into technical architecture
  • Defines component responsibilities and interactions
  • Creates implementation sequencing with dependencies
  • Establishes validation strategy
  • Identifies critical files and patterns to reuse

​
What This Phase Does NOT Do

  • Redefine requirements (must loop back to Phase 1)
  • Create executable coding task checklists (belongs in Phase 3)
  • Implement product code

​
The Four-Stage Workflow

The Plan agent cycles through these stages iteratively:
1

Discovery

Research codebase for architectural patterns and constraints.Mandatory: Run #tool:agent/runSubagent with research instructions:
- Research the user's task comprehensively using read-only tools
- Start with high-level code searches before reading specific files
- Pay special attention to skills in .github/skills for best practices
- Look for analogous existing features that can serve as implementation templates
- Identify missing information, conflicting requirements, technical unknowns
- DO NOT draft a full plan yet — focus on discovery, feasibility, and architecture signals
2

Alignment

Validate assumptions and confirm requirements stability.Use #tool:vscode/askQuestions to:
  • Confirm requirements are approved and stable
  • Surface discovered technical constraints and tradeoffs
  • Validate architectural approach
  • Present alternative approaches if applicable
Loop back to Discovery if answers significantly change scope.
3

Design

Create comprehensive technical design blueprint.Must include:
  • System architecture and component responsibilities
  • Technical decisions and tradeoffs
  • Data model and interface contracts
  • Step-by-step implementation plan with dependencies
  • Verification strategy (automated and manual)
  • Critical architecture to reuse
  • Files to modify or create (full paths)
  • Traceability map linking DES-* to REQ-*
Persist immediately to specs/features/{NNN}-{feature-name}/plan.md
4

Refinement

Iterate based on user feedback until approval.User responses:
  • Changes requested → Revise and sync file
  • Questions asked → Clarify or loop to Alignment
  • Alternatives wanted → Loop back to Discovery
  • Approval given → Enable handoff to Phase 3

​
Technical Design Structure

The Plan agent follows this style guide: 
## Technical Design: {Title (2-10 words)}

{TL;DR - what will be built, why this architecture is recommended, and how implementation will proceed.}

**Steps**

1. DES-1: {Implementation step} (REQ-1, REQ-2)
   - {Architecture-first ordering}
   - {Note dependency: "depends on N" or "parallel with N"}
2. DES-2: {Next step} (REQ-3)
3. DES-3: {For 5+ steps, group into named phases}

**Relevant files**

- `{full/path/to/file}` — {what to modify/create/reuse}
  - {Reference specific functions/patterns and why}

**Verification**

1. {Specific verification steps: tests, commands, MCP tools}
2. {Not generic statements — actionable validation}

**Decisions**

- {Decision, assumptions, and included/excluded scope}

**Traceability**

- DES-1 ↔ REQ-1, REQ-2
- DES-2 ↔ REQ-3

**Further Considerations**

1. {Clarifying question with recommendation}

​
Design Identifiers

The Plan phase introduces DES-* identifiers that map to REQ-* from Phase 1: 
# From Requirements (Phase 1)
REQ-1: User can trigger export from workspace settings
REQ-2: System generates CSV with all workspace data
REQ-3: Export includes timestamp in filename
REQ-4: System validates data before export

# Design Mapping (Phase 2)
DES-1: CSV Export Service (REQ-2, REQ-3, REQ-4)
  DES-1.1: Data validation layer (REQ-4)
  DES-1.2: CSV generation with timestamp (REQ-2, REQ-3)
DES-2: API Route Handler (REQ-1)
DES-3: UI Integration (REQ-1)
This traceability ensures every design decision maps back to requirements.

​
Implementation Sequencing

The Plan phase defines execution order with explicit dependencies:

​
Dependency Notation

**Steps**

1. DES-1: Create data model changes
2. DES-2: Implement repository layer (depends on DES-1)
3. DES-3: Build API endpoints (depends on DES-2)
4. DES-4.1: Add UI components (depends on DES-3)
   DES-4.2: Add state management (parallel with DES-4.1)
5. DES-5: End-to-end validation (depends on DES-4.1, DES-4.2)

​
Parallelizable Work

Identify steps that can run simultaneously: 
**Parallel Execution Groups**

- Group A (parallel): DES-2.1, DES-2.2, DES-2.3 (independent services)
- Group B (depends on Group A): DES-3 (API integration)
- Group C (parallel): DES-4.1 (UI), DES-4.2 (docs)

​
Real Example

From the agent’s planning process: 
## Technical Design: Multi-Format Data Export

Implement CSV and JSON export functionality using existing workspace data model, following repo patterns for API routes and file downloads.

**Steps**

1. DES-1: Create export service layer (REQ-2, REQ-3, REQ-4, REQ-5)
   - Build `ExportService` class with format-agnostic interface
   - Implement CSV and JSON formatters as separate strategies
   - Add data validation before formatting
   - Generate timestamp-based filenames
   - Depends on: Existing workspace schema

2. DES-2: Implement API route handler (REQ-1, REQ-2)
   - Create `/api/workspace/[id]/export` route
   - Accept format parameter (csv or json)
   - Stream response for large exports
   - Depends on: DES-1

3. DES-3: Add permission checks (REQ-1, NFR-Security)
   - Reuse existing permission middleware
   - Verify owner/admin role before export
   - Parallel with: DES-2 (integrate during implementation)

4. DES-4: Build UI integration (REQ-1, REQ-6)
   - Add "Export Data" section to workspace settings page
   - Create format selection dropdown
   - Implement category selection (optional, REQ-6)
   - Wire up download trigger
   - Depends on: DES-2, DES-3

5. DES-5: Add metadata header generation (REQ-5)
   - Include schema version in exported files
   - Add export timestamp and workspace info
   - Integrate with: DES-1

**Relevant files**

- `web/lib/services/export.service.ts` — NEW: Core export service
  - Follow pattern from `web/lib/services/workspace.service.ts`
  - Use dependency injection for formatters
  
- `web/lib/formatters/csv.formatter.ts` — NEW: CSV formatting logic
  - Reference `web/lib/utils/csv.ts` if it exists for helpers
  
- `web/lib/formatters/json.formatter.ts` — NEW: JSON formatting logic
  
- `web/app/api/workspace/[id]/export/route.ts` — NEW: API route
  - Follow streaming pattern from `web/app/api/workspace/[id]/download/route.ts`
  
- `web/app/workspace/[id]/settings/page.tsx` — MODIFY: Add export UI
  - Add new section after "Danger Zone"
  - Reuse existing `Button` and `Select` components
  
- `web/lib/db/schema.ts` — READ: Reference workspace data structure
  - Use existing `workspace` table schema
  
- `web/lib/auth/permissions.ts` — REUSE: Permission checking
  - Use `requireWorkspaceRole(['owner', 'admin'])` pattern

**Verification**

1. Unit tests: Test formatters with sample workspace data
   - `bun test web/lib/formatters/*.test.ts`
2. Integration test: Test API route with authenticated request
   - Verify CSV headers and content structure
   - Verify JSON schema validity
3. Manual test: Export from UI as owner (should succeed)
4. Manual test: Attempt export as viewer (should fail with 403)
5. Manual test: Verify filename includes timestamp
6. Performance test: Export workspace with 1000 records (should complete < 5s)
7. Baseline checks: `bun run lint && bun run format`

**Decisions**

- Decision: Use streaming response for exports
  - Rationale: Prevents timeout on large workspaces
  - Tradeoff: Slightly more complex error handling
  
- Decision: CSV format uses flat structure (no nested objects)
  - Rationale: Maximum compatibility with Excel/Numbers
  - Limitation: Complex nested data may lose structure
  
- Decision: Defer import functionality to v2
  - Rationale: Export-only satisfies core user need
  - Out of scope: Import validation and conflict resolution

**Traceability**

- DES-1 ↔ REQ-2, REQ-3, REQ-4, REQ-5
- DES-2 ↔ REQ-1, REQ-2
- DES-3 ↔ REQ-1, NFR-Security
- DES-4 ↔ REQ-1, REQ-6
- DES-5 ↔ REQ-5

**Further Considerations**

1. For workspaces >10k records, should we add progress indicator?
   - Option A: Add WebSocket-based progress (adds complexity)
   - Option B: Show indeterminate spinner (simpler, acceptable for v1)
   - Recommendation: Option B for v1

​
Architecture Patterns

The Plan phase references existing patterns from the codebase: 
// Reference from web/lib/services/workspace.service.ts
export class WorkspaceService {
  constructor(private db: Database) {}
  
  async getWorkspace(id: string) {
    // Implementation
  }
}
When to use: Business logic that doesn’t belong in API routes
// Reference from web/app/api/*/route.ts
export async function GET(request: Request) {
  // Permission check
  // Service call
  // Response formatting
}
When to use: All HTTP endpoints
// Reference from web/lib/auth/permissions.ts
await requireWorkspaceRole(['owner', 'admin'])
When to use: Any workspace-scoped operation

​
Key Rules

Require Approved Requirements: If Phase 1 requirements aren’t approved, create provisional design and flag blockers.
Use Research Subagents: Don’t do direct research yourself. Use #tool:agent/runSubagent for all exploration.
No Task Checklists: Don’t output - [ ] style implementation tasks. That belongs in Phase 3.
Reference Specifics: Don’t just list file paths. Reference specific functions, types, or patterns to reuse.

​
Phase Boundary Contract

​
Allowed Artifact

✅ specs/features/{NNN}-{feature-name}/plan.md only

​
Required Inputs from Phase 1

  • ✅ Approved requirements document
  • ✅ Requirement identifiers and acceptance criteria (REQ-*)
  • ✅ Scope boundaries and key constraints

​
Required Handoff to Phase 3

To hand off to the Task phase, plan must include:
  • ✅ Design identifiers for traceability (DES-1, DES-2.1, etc.)
  • ✅ Sequenced design-level implementation strategy
  • ✅ Validation strategy and risk controls

​
Forbidden Outputs

❌ Requirement redefinition (unless marked as change request to Phase 1)
❌ Executable coding task checklist and implementation assignments
❌ Product code implementation

​
Research Instructions

When running the research subagent: 
- Research the user's task comprehensively using read-only tools.
- Start with high-level code searches before reading specific files.
- Pay special attention to instructions and skills made available by the developers to understand best practices and intended usage.
- Look for analogous existing features that can serve as implementation templates — study how similar functionality already works end-to-end.
- Identify missing information, conflicting requirements, technical unknowns, and design constraints.
- DO NOT draft a full plan yet — focus on discovery, feasibility, and architecture signals.

​
Verification Strategy

Every plan must include specific verification steps:

​
Good Verification Steps

✅ Run bun test web/lib/services/export.service.test.ts
✅ Test API with curl -X POST http://localhost:3000/api/export
✅ Verify CSV opens correctly in Excel
✅ Check permission denied for non-admin users

​
Bad Verification Steps (Too Generic)

❌ Test the feature
❌ Verify it works
❌ Run all tests

​
Common Patterns

​
Grouping Large Plans

For plans with 5+ steps, group into phases: 
**Implementation Phases**

Phase A: Core Infrastructure (DES-1, DES-2, DES-3)
- Foundation for feature
- Independently testable

Phase B: Business Logic (DES-4, DES-5)
- Depends on Phase A
- Includes validation and processing

Phase C: UI Integration (DES-6, DES-7)
- Depends on Phase B
- User-facing components

​
Alternative Approaches

Document architectural alternatives: 
**Architectural Alternatives Considered**

1. Approach A: Server-side generation (chosen)
   - Pros: No client resource limits, easier permission checks
   - Cons: Server load for large exports
   
2. Approach B: Client-side generation
   - Pros: Offload processing to client
   - Cons: Data transfer overhead, permission complexity
   
**Decision**: Approach A for v1; reconsider for v2 if server load becomes issue

​
Quality Checklist

Before finalizing plan, verify:
  • Every design step has DES- identifier
  • Every DES- maps to at least one REQ-
  • Dependencies between steps are explicit
  • Parallelizable work is identified
  • Files to modify/create have full paths
  • Specific functions/patterns to reuse are named
  • Verification steps are actionable and specific
  • Architectural decisions include tradeoffs
  • No implementation task checkboxes (those go in Phase 3)

​
Next Steps

Task Phase

Convert approved design into implementation tasks

Requirements Phase

Review how requirements feed into planning

Build docs developers (and LLMs) love

Get started for freeTalk to us