Skip to main content
This guide shows you how to use the Requirements → Plan → Task workflow in practice, from initial idea to implementation-ready tasks.

​
Basic Flow

The typical workflow progression:
1

Start with Requirements Agent

Invoke the 📋 Requirements agent with your feature idea or user request.
@requirements Add ability to export user data in multiple formats
The agent will:
  • Research your codebase for similar features
  • Ask clarifying questions
  • Draft a requirements document
  • Iterate until you approve
2

Hand Off to Plan Agent

Once requirements are approved, invoke the 📝 Plan agent with the requirements document.
@plan Design technical solution for requirements in specs/features/042-data-export/
The agent will:
  • Research architectural patterns
  • Design component structure
  • Create implementation sequencing
  • Iterate until you approve
3

Generate Tasks

With approved requirements and plan, invoke the ✅ Task agent.
@task Create implementation tasks for specs/features/042-data-export/
The agent will:
  • Break design into coding tasks
  • Identify dependencies
  • Create verification criteria
  • Produce actionable checklist
4

Execute Tasks

Use the task checklist to guide implementation, either manually or with AI assistance.

​
Agent Invocation Patterns

Each agent accepts different input formats:

​
Requirements Agent

@requirements Add user authentication with OAuth providers

​
Plan Agent

@plan Design solution for specs/features/042-data-export/requirements.md

​
Task Agent

@task Create tasks for specs/features/042-data-export/

​
Internal Agent Workflow

Each agent follows the same internal cycle:

​
1. Discovery

The agent uses a research subagent to autonomously explore:
  • Existing features and patterns
  • Project conventions and skills
  • Technical constraints
  • Analogous implementations
Agents MUST use #tool:agent/runSubagent for research — they don’t explore directly. This keeps the main agent focused on synthesis and decision-making.

​
2. Alignment

If research reveals ambiguities:
  • Agent uses #tool:vscode/askQuestions to clarify
  • Surfaces technical constraints and tradeoffs
  • Validates assumptions before drafting
  • May loop back to Discovery if scope changes significantly
Agents should not make large assumptions. If context is unclear, they ask questions rather than guessing.

​
3. Drafting

Once context is clear:
  • Agent drafts the spec document (requirements/plan/tasks)
  • Follows the phase-specific style guide
  • Includes traceability identifiers (REQ-, DES-, etc.)
  • Persists to specs/features/{NNN}-{feature-name}/
  • Shows scannable summary to user

​
4. Refinement

User can request:
  • Changes → Agent revises and syncs the file
  • Alternatives → Loops back to Discovery
  • Clarifications → Agent explains or asks follow-ups
  • Approval → Enables handoff to next phase

​
Decision Trees

​
Requirements Agent Decisions

​
Plan Agent Decisions

​
Task Agent Decisions

​
File Structure

The workflow produces this structure: 
specs/
└── features/
    └── {NNN}-{feature-name}/
        ├── requirements.md  # Phase 1 output
        ├── plan.md          # Phase 2 output
        └── tasks.md         # Phase 3 output

​
Naming Convention

  • {NNN}: Zero-padded sequential number (e.g., 042)
  • {feature-name}: Kebab-case description (e.g., data-export)
Examples:
  • specs/features/001-oauth-integration/
  • specs/features/042-data-export/
  • specs/features/137-workspace-sharing/

​
Practical Examples

​
Example 1: Simple Feature

Phase 1: Requirements
## Requirements: CSV Data Export

Allow users to export their workspace data in CSV format.

**Requirements**

1. REQ-1 (Must): User can trigger export from workspace settings
2. REQ-2 (Must): System generates CSV with all workspace data
3. REQ-3 (Should): Export includes timestamp in filename
4. REQ-4 (Must): System validates data before export

**Acceptance Criteria**

1. REQ-1 — When user clicks "Export CSV" button, the system shall initiate download
2. REQ-2 — The system shall include all workspace records in exported CSV
3. REQ-3 — Where export is successful, the filename shall include ISO timestamp
4. REQ-4 — If data validation fails, then the system shall show error message
Phase 2: Plan
## Technical Design: CSV Export Service

**Steps**

1. DES-1: Create CSV export service (REQ-1, REQ-2)
2. DES-2: Add validation layer (REQ-4)
3. DES-3: Implement filename generation with timestamp (REQ-3)
4. DES-4: Wire up UI button to service (REQ-1)

**Relevant files**

- `web/app/api/export/csv/route.ts` — New API route handler
- `web/lib/services/export.service.ts` — CSV generation logic
- `web/app/workspace/settings/page.tsx` — Add export button
Phase 3: Tasks
## Implementation Tasks: CSV Export

- [ ] 1. Create export service
  - [ ] 1.1 Implement CSV generation function
    - Create `web/lib/services/export.service.ts`
    - Requirements: REQ-2, REQ-3
    - Design: DES-1, DES-3
  - [ ] 1.2 Add data validation
    - Add validation to export service
    - Requirements: REQ-4
    - Design: DES-2

- [ ] 2. Create API route
  - [ ] 2.1 Implement route handler
    - Create `web/app/api/export/csv/route.ts`
    - Requirements: REQ-1
    - Design: DES-1

- [ ] 3. Add UI integration  
  - [ ] 3.1 Add export button to settings
    - Modify `web/app/workspace/settings/page.tsx`
    - Requirements: REQ-1
    - Design: DES-4

​
Example 2: Complex Feature

Phase 1 focuses on:
  • User personas (editors vs viewers)
  • Conflict resolution requirements
  • Performance constraints
  • Security and permissions
Phase 2 explores:
  • WebSocket vs Server-Sent Events
  • Operational Transform vs CRDT
  • State synchronization strategy
  • Rollback and recovery
Phase 3 breaks into phases:
  • Phase A: Core infrastructure (WebSocket, connection management)
  • Phase B: Document sync (conflict resolution, state management)
  • Phase C: UI integration (presence indicators, live cursors)

​
Best Practices

Start with Why

Begin requirements with the problem and user value, not the solution

Question Early

Use askQuestions liberally in Discovery and Alignment — don’t guess

Research First

Always run research subagent before drafting specs

Sync Files

Keep spec files in sync with every revision — don’t just update in-chat

Trace Everything

Maintain REQ → DES → Task mappings throughout all phases

Verify Incrementally

Add verification steps at task boundaries, not just at the end

​
Common Pitfalls

Skipping Research: Don’t draft requirements or design without running a research subagent first. You’ll miss existing patterns and constraints.
Phase Bleeding: Don’t include technical architecture in requirements, or coding tasks in design. Respect phase boundaries.
Assumption Debt: Don’t make large assumptions when context is unclear. Ask questions during Alignment.
Forgetting Traceability: Every design decision should map to requirements. Every task should map to design. Don’t lose the thread.

​
Next Steps

Requirements Phase

Learn how to gather and document requirements

Plan Phase

Explore technical design and planning

Task Phase

Master implementation task breakdown

Build docs developers (and LLMs) love

Get started for freeTalk to us