Task Phase

The Task phase is the final step in the 3-phase workflow. The ✅ Task agent converts approved requirements and technical design into a detailed, dependency-aware implementation plan consisting of discrete coding tasks.

Agent Configuration

name: ✅ Task
description: Transforms approved requirements and design into structured implementation tasks
argument-hint: Provide approved requirements and design context to produce actionable tasks
target: vscode
disable-model-invocation: true
tools:
  [
    "search",
    "read",
    "edit",
    "web",
    "execute/getTerminalOutput",
    "execute/testFailure",
    "agent",
    "vscode/askQuestions",
  ]
agents: []

Phase Responsibility

Phase 3 of 3: Task PlanningYour SOLE responsibility is task planning. NEVER start implementation.

What This Phase Does

Converts design into specific coding activities
Sequences tasks for optimal development flow
Creates clear, actionable tasks for implementation
Establishes dependencies and build order
Enables incremental progress with testable milestones

What This Phase Does NOT Do

Redefine requirements (belongs in Phase 1)
Redesign architecture (belongs in Phase 2)
Implement product code

Purpose and Goals

As the bridge between planning and execution, the Task phase ensures:

Convert design into specific coding activities
Sequence tasks for optimal development flow
Clarify each task with clear completion criteria
Establish dependencies and build order
Enable incremental progress with testable milestones
Provide roadmap for systematic feature development

The Four-Stage Workflow

The Task agent cycles through these stages iteratively:

Discovery

Research implementation details and technical constraints.Use #tool:agent/runSubagent for research:

- 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 as implementation templates
- Identify missing information, technical unknowns, design constraints
- DO NOT draft full task plan yet — focus on discovery and feasibility

Note: For simple, known-file lookups, direct read is acceptable.

Alignment

Confirm requirements and design are approved and stable.Use #tool:vscode/askQuestions to:

Confirm Phase 1 and Phase 2 artifacts are approved
Clarify task breakdown granularity preferences
Surface technical constraints or blockers
Validate sequencing approach

Loop back to Discovery if answers significantly change scope.

Task Planning

Create comprehensive implementation task plan.Must include:

Concrete coding tasks mapped to REQ-* and DES-*
Clear task sequencing with dependencies
Task granularity suitable for incremental execution
Files/components/symbols to create, modify, or verify
Test and validation expectations per task or group
Clear objective and done criteria per task
Scope boundaries

Persist immediately to specs/features/{NNN}-{feature-name}/tasks.mdOutput contract:

Include full, scannable task plan in-chat
Confirm exact file path written
Include dependency summary (critical path + parallelizable groups)

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 → Ready for implementation

Task Plan Structure

The Task agent follows this style guide:

## Implementation Tasks: {Title (2-10 words)}

{TL;DR - what will be implemented, why this sequencing is recommended, and how execution will proceed safely and incrementally.}

**Steps**

- [ ] 1. {Major component or phase}
  - [ ] 1.1 {Specific coding task}
    - Objective: {What this task accomplishes}
    - Files: `{full/path/to/file}` — {what to modify/create}
    - Components/symbols: {specific functions, types, classes}
    - Expected outcome: {what evidence marks it done}
    - Requirements: REQ-1, REQ-2
    - Design: DES-1.1
  - [ ] 1.2 {Next specific task}
    - Objective: {What this task accomplishes}
    - Dependencies: Depends on 1.1
    - Requirements: REQ-3
    - Design: DES-1.2

**Task Sequencing Strategy**

- Feature-Slice Approach: Organize into end-to-end vertical slices
- Dependency-First Order: data model → repository → business logic → API → UI → validation

**Relevant files**

- `{full/path/to/file}` — {what to modify/create, specific patterns}

**Verification**

1. {Specific verification: tests, commands, MCP tools}
2. Baseline checks: `bun run lint`, `bun run format`, relevant tests

Task Sequencing Strategies

The Task phase uses two primary sequencing approaches:

Feature-Slice Approach

Organize tasks into end-to-end vertical slices that deliver user-visible value early:

**Feature Slices**

Slice 1: Basic CSV Export (Minimal Viable Feature)
- [ ] 1.1 Create basic CSV formatter
- [ ] 1.2 Add API route for CSV export
- [ ] 1.3 Add export button to UI
- [ ] 1.4 Verify end-to-end CSV download

Slice 2: JSON Export Support
- [ ] 2.1 Create JSON formatter
- [ ] 2.2 Extend API route for format parameter
- [ ] 2.3 Add format selector to UI
- [ ] 2.4 Verify JSON export works

Slice 3: Advanced Features
- [ ] 3.1 Add data validation layer
- [ ] 3.2 Implement category selection
- [ ] 3.3 Add metadata headers

Dependency-First Baseline Order

Unless justified otherwise, sequence in this default order:

Data model/database changes
Repository/data access layer
Business logic/services
API/contracts
UI integration
End-to-end validation

Traceability Mapping

Every task references both requirements and design:

# From Requirements (Phase 1)
REQ-1: User can trigger export from settings
REQ-2: System generates CSV with all data
REQ-4: System validates data before export

# From Design (Phase 2)
DES-1: CSV Export Service (REQ-2, REQ-4)
DES-2: API Route Handler (REQ-1)
DES-3: UI Integration (REQ-1)

# Tasks (Phase 3)
- [ ] 1.1 Implement CSV export service
  - Requirements: REQ-2, REQ-4
  - Design: DES-1
  
- [ ] 2.1 Create API route handler
  - Requirements: REQ-1
  - Design: DES-2
  
- [ ] 3.1 Add export button to settings page
  - Requirements: REQ-1
  - Design: DES-3

This ensures every task has clear justification and scope.

Real Example

From the agent’s task planning process:

Example: Data Export Feature Implementation Tasks

## Implementation Tasks: Multi-Format Data Export

Implement CSV and JSON export functionality incrementally, starting with core export service, then API integration, and finally UI. Each major phase is independently verifiable.

**Steps**

- [ ] 1. Create export service layer
  - [ ] 1.1 Implement base export service
    - Objective: Create `ExportService` class with format-agnostic interface
    - Files: `web/lib/services/export.service.ts` (NEW)
    - Components: `ExportService` class, `ExportFormat` type, `ExportOptions` interface
    - Pattern: Follow dependency injection pattern from `WorkspaceService`
    - Expected outcome: Service can accept workspace data and format parameter
    - Requirements: REQ-2
    - Design: DES-1
    
  - [ ] 1.2 Implement CSV formatter
    - Objective: Create CSV formatting strategy with headers and proper escaping
    - Files: `web/lib/formatters/csv.formatter.ts` (NEW)
    - Components: `CsvFormatter` class implementing `IFormatter` interface
    - Expected outcome: Formatter converts workspace objects to valid CSV string
    - Requirements: REQ-2, REQ-3
    - Design: DES-1.2
    - Dependencies: None (parallel with 1.3)
    
  - [ ] 1.3 Implement JSON formatter
    - Objective: Create JSON formatting strategy with flat structure
    - Files: `web/lib/formatters/json.formatter.ts` (NEW)
    - Components: `JsonFormatter` class implementing `IFormatter` interface
    - Expected outcome: Formatter converts workspace objects to valid JSON
    - Requirements: REQ-2
    - Design: DES-1.2
    - Dependencies: None (parallel with 1.2)
    
  - [ ] 1.4 Add data validation
    - Objective: Validate workspace data integrity before export
    - Files: `web/lib/services/export.service.ts` (MODIFY)
    - Components: `validateExportData()` method
    - Expected outcome: Service throws error if data is corrupted
    - Requirements: REQ-4
    - Design: DES-1.1
    - Dependencies: Depends on 1.1
    
  - [ ] 1.5 Add filename generation with timestamp
    - Objective: Generate filename in format `workspace-{name}-{timestamp}.{ext}`
    - Files: `web/lib/services/export.service.ts` (MODIFY)
    - Components: `generateFilename()` method using ISO 8601 format
    - Expected outcome: Filenames include workspace name and ISO timestamp
    - Requirements: REQ-3
    - Design: DES-1.2
    - Dependencies: Depends on 1.1
    
  - [ ] 1.6 Add metadata header generation
    - Objective: Include schema version and export metadata in files
    - Files: `web/lib/services/export.service.ts` (MODIFY)
    - Components: `generateMetadata()` method
    - Expected outcome: Exports include metadata header with schema version
    - Requirements: REQ-5
    - Design: DES-5
    - Dependencies: Depends on 1.1

- [ ] 2. Create API route handler
  - [ ] 2.1 Implement export API route
    - Objective: Create streaming endpoint for export downloads
    - Files: `web/app/api/workspace/[id]/export/route.ts` (NEW)
    - Components: `POST` handler, streaming response
    - Pattern: Follow streaming pattern from `download/route.ts`
    - Expected outcome: Route accepts format param and returns file download
    - Requirements: REQ-1, REQ-2
    - Design: DES-2
    - Dependencies: Depends on 1.1-1.6
    
  - [ ] 2.2 Add permission checks
    - Objective: Verify user has owner/admin role before allowing export
    - Files: `web/app/api/workspace/[id]/export/route.ts` (MODIFY)
    - Components: Use `requireWorkspaceRole(['owner', 'admin'])`
    - Pattern: Reuse from `web/lib/auth/permissions.ts`
    - Expected outcome: Non-admin users receive 403 error
    - Requirements: REQ-1 (security)
    - Design: DES-3
    - Dependencies: Depends on 2.1

- [ ] 3. Build UI integration
  - [ ] 3.1 Add export section to settings page
    - Objective: Create "Data Export" section in workspace settings
    - Files: `web/app/workspace/[id]/settings/page.tsx` (MODIFY)
    - Components: New section after "Danger Zone" with description
    - Pattern: Follow existing settings section layout
    - Expected outcome: UI shows export section with format selector
    - Requirements: REQ-1
    - Design: DES-4
    - Dependencies: Depends on 2.1, 2.2
    
  - [ ] 3.2 Add format selection dropdown
    - Objective: Allow user to choose between CSV and JSON
    - Files: `web/app/workspace/[id]/settings/page.tsx` (MODIFY)
    - Components: `Select` component with format options
    - Pattern: Reuse existing `Select` from shadcn/ui
    - Expected outcome: Dropdown shows "CSV" and "JSON" options
    - Requirements: REQ-2
    - Design: DES-4
    - Dependencies: Depends on 3.1
    
  - [ ] 3.3 Add category selection (optional)
    - Objective: Allow user to select specific data categories to export
    - Files: `web/app/workspace/[id]/settings/page.tsx` (MODIFY)
    - Components: Multi-select for data categories
    - Expected outcome: User can choose specific categories or "All"
    - Requirements: REQ-6 (Could priority)
    - Design: DES-4
    - Dependencies: Depends on 3.2 (defer if time-constrained)
    
  - [ ] 3.4 Wire up export button
    - Objective: Trigger API call and download on button click
    - Files: `web/app/workspace/[id]/settings/page.tsx` (MODIFY)
    - Components: `handleExport` function, loading state
    - Expected outcome: Button click initiates file download
    - Requirements: REQ-1
    - Design: DES-4
    - Dependencies: Depends on 3.2

- [ ] 4. Add tests and verification
  - [ ] 4.1 Unit test formatters
    - Objective: Test CSV and JSON formatters with sample data
    - Files: `web/lib/formatters/*.test.ts` (NEW)
    - Tests: Valid formatting, edge cases, escaping, schema compliance
    - Command: `bun test web/lib/formatters`
    - Dependencies: Depends on 1.2, 1.3
    
  - [ ] 4.2 Integration test API route
    - Objective: Test export endpoint with authenticated requests
    - Files: `web/app/api/workspace/[id]/export/route.test.ts` (NEW)
    - Tests: Successful export, permission denial, invalid format
    - Command: `bun test web/app/api/workspace`
    - Dependencies: Depends on 2.1, 2.2
    
  - [ ] 4.3 Manual verification
    - Objective: Verify end-to-end export flow in browser
    - Steps:
      1. Export CSV as owner → verify file downloads and opens in Excel
      2. Export JSON as owner → verify file structure
      3. Attempt export as viewer → verify 403 error
      4. Verify filename includes timestamp
      5. Verify metadata header present
    - Dependencies: Depends on 3.4

**Task Sequencing Strategy**

- **Feature-Slice Approach**: Organized into service → API → UI slices
- **Dependency-First Order**: Following data layer → service → API → UI pattern
- **Parallelizable Tasks**: 1.2 and 1.3 (formatters) can run in parallel
- **Optional Task**: 3.3 (category selection) can be deferred if time-constrained

**Relevant files**

- `web/lib/services/export.service.ts` — NEW: Core export service
- `web/lib/formatters/csv.formatter.ts` — NEW: CSV formatting
- `web/lib/formatters/json.formatter.ts` — NEW: JSON formatting
- `web/app/api/workspace/[id]/export/route.ts` — NEW: Export API endpoint
- `web/app/workspace/[id]/settings/page.tsx` — MODIFY: Add export UI
- `web/lib/db/schema.ts` — REFERENCE: Workspace data structure
- `web/lib/auth/permissions.ts` — REUSE: Permission patterns

**Verification**

1. Run unit tests: `bun test web/lib/formatters`
2. Run integration tests: `bun test web/app/api/workspace`
3. Manual export test as owner (CSV and JSON)
4. Manual permission test as non-owner (verify 403)
5. Verify filename timestamp format
6. Verify CSV opens in Excel without errors
7. Verify JSON validates against schema
8. Baseline checks: `bun run lint && bun run format`

**Decisions**

- Category selection (task 3.3) marked as optional — can defer to v2 if needed
- CSV formatter uses flat structure for maximum compatibility
- API route uses streaming to handle large exports without timeout

**Dependency Summary**

**Critical Path**:
1.1 → 1.4 → 1.5 → 2.1 → 2.2 → 3.1 → 3.2 → 3.4 → 4.3

**Parallel Groups**:
- Group 1: 1.2, 1.3 (formatters — independent)
- Group 2: 1.5, 1.6 (both depend on 1.1, independent of each other)
- Group 3: 4.1, 4.2 (tests — can run in parallel)

Task Hierarchy Pattern

Tasks use checkbox hierarchy with numbered labels:

- [ ] 1. Major component (e.g., "Create export service layer")
  - [ ] 1.1 Specific task (e.g., "Implement CSV formatter")
    - Objective: What this accomplishes
    - Files: What to modify/create
    - Components: Specific symbols
    - Expected outcome: Done criteria
    - Requirements: REQ-*
    - Design: DES-*
  - [ ] 1.2 Next specific task
    - ...

Completion Criteria

Every task must have clear “done” criteria:

Good Completion Criteria

✅ Objective: Formatter converts workspace objects to valid CSV string
✅ Expected outcome: CSV file opens correctly in Excel without errors
✅ Expected outcome: Non-admin users receive 403 error when attempting export

Bad Completion Criteria (Too Vague)

❌ Task is complete
❌ Feature works
❌ Tests pass

Key Rules

Naming Required: If {NNN} or {feature-name} is missing, ask one concise naming question before writing tasks.md.

Traceability Required: Every task must include explicit REQ-* and DES-* identifiers. Don’t lose the thread.

No Architecture Changes: Don’t redesign architecture in tasks. Raise change feedback to Phase 2 instead.

Dual Output: Always provide (1) scannable task plan in-chat and (2) persisted file path confirmation.

Phase Boundary Contract

Allowed Artifact

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

Required Inputs from Earlier Phases

✅ Approved requirements (requirements.md) with REQ-*
✅ Approved technical design (plan.md) with DES-*

Required Output Guarantees

✅ Every implementation task references at least one REQ-* and one DES-*
✅ Dependency chain and parallelizable groups explicitly called out
✅ Each task has verifiable completion signal

Forbidden Outputs

❌ New requirement scope definition (belongs to Phase 1)
❌ New technical architecture decisions (belongs to Phase 2)
❌ Product code implementation

Verification Baseline

Every task plan should include these baseline checks:

**Verification**

1. {Feature-specific tests and validation}
2. Baseline checks:
   - `bun run lint` — No linting errors
   - `bun run format` — Code formatted correctly
   - Relevant tests pass

Quality Checklist

Before finalizing task plan, verify:

Next Steps

Start Implementation

Use the task checklist to guide development, checking off tasks as you complete them

Review Workflow

See how all three phases work together in practice

Plan Phase

⌘I

Overview

Phases

Agent Configuration

Phase Responsibility

What This Phase Does

What This Phase Does NOT Do

Purpose and Goals

The Four-Stage Workflow

Task Plan Structure

Task Sequencing Strategies

Feature-Slice Approach

Dependency-First Baseline Order

Traceability Mapping

Real Example

Task Hierarchy Pattern

Completion Criteria

Good Completion Criteria

Bad Completion Criteria (Too Vague)

Key Rules

Phase Boundary Contract

Allowed Artifact

Required Inputs from Earlier Phases

Required Output Guarantees

Forbidden Outputs

Verification Baseline

Quality Checklist

Next Steps

Start Implementation

Review Workflow

Build docs developers (and LLMs) love

Overview

Phases

​Agent Configuration

​Phase Responsibility

​What This Phase Does

​What This Phase Does NOT Do

​Purpose and Goals

​The Four-Stage Workflow

​Task Plan Structure

​Task Sequencing Strategies

​Feature-Slice Approach

​Dependency-First Baseline Order

​Traceability Mapping

​Real Example

​Task Hierarchy Pattern

​Completion Criteria

​Good Completion Criteria

​Bad Completion Criteria (Too Vague)

​Key Rules

​Phase Boundary Contract

​Allowed Artifact

​Required Inputs from Earlier Phases

​Required Output Guarantees

​Forbidden Outputs

​Verification Baseline

​Quality Checklist

​Next Steps

Start Implementation

Review Workflow

Build docs developers (and LLMs) love

Agent Configuration

Phase Responsibility

What This Phase Does

What This Phase Does NOT Do

Purpose and Goals

The Four-Stage Workflow

Task Plan Structure

Task Sequencing Strategies

Feature-Slice Approach

Dependency-First Baseline Order

Traceability Mapping

Real Example

Task Hierarchy Pattern

Completion Criteria

Good Completion Criteria

Bad Completion Criteria (Too Vague)

Key Rules

Phase Boundary Contract

Allowed Artifact

Required Inputs from Earlier Phases

Required Output Guarantees

Forbidden Outputs

Verification Baseline

Quality Checklist

Next Steps