Agent Prompt Generation

Create structured task prompts that coding agents can execute effectively.

Output Files

Task generation produces two files:

| File | Purpose | Used By | |------|---------|---------| | TASKS.json | Machine-parseable metadata | Plugin agents, hooks, commands | | TASKS.md | Human-readable task prompts | Developers, code review |

Source of Truth: TASKS.json is authoritative. TASKS.md is a derived human-readable view.

TASKS.json Structure

json
{
  "version": "1.0",
  "feature": "feature-name",
  "summary": {
    "total_tasks": 5,
    "total_points": 18,
    "critical_path": ["TASK-001", "TASK-003", "TASK-005"]
  },
  "phases": [
    { "id": 1, "name": "Foundation" },
    { "id": 2, "name": "Core Implementation" },
    { "id": 3, "name": "Polish" }
  ],
  "tasks": {
    "TASK-001": {
      "title": "Setup Database Schema",
      "status": "not_started",
      "phase": 1,
      "points": 3,
      "depends_on": [],
      "blocks": ["TASK-002", "TASK-003"],
      "prd_refs": ["REQ-001", "REQ-002"],
      "sdd_refs": ["Section 5.1"],
      "acceptance_criteria": [
        "Schema file exists at db/schema.sql",
        "All tables have primary keys",
        "Foreign key relationships match SDD",
        "Migration runs without errors"
      ],
      "testing": [
        "Run migration: npm run db:migrate",
        "Verify tables: npm run db:verify"
      ],
      "prompt": "## Context\nThis task establishes the data layer...\n\n## Requirements\n- Create users table with id, email, created_at\n..."
    }
  }
}

Task Fields

| Field | Type | Description | |-------|------|-------------| | title | string | Clear, action-oriented task title | | status | enum | "not_started" \| "in_progress" \| "completed" | | phase | integer | Phase number (1-indexed) | | points | integer | Fibonacci story points: 1, 2, 3, 5, 8 | | depends_on | array | Task IDs that must complete first | | blocks | array | Task IDs that depend on this task | | prd_refs | array | Requirement IDs (REQ-XXX) this task addresses | | sdd_refs | array | SDD section references | | acceptance_criteria | array | Verifiable criteria for completion | | testing | array | Test commands or verification steps | | prompt | string | Full markdown prompt for implementation |

TASKS.md Structure

The markdown file contains human-readable content only. No status markers, dependencies, or acceptance criteria (those live in JSON).

markdown
# Implementation Tasks: [Feature Name]

## Summary

- Total Tasks: 5
- Total Story Points: 18
- Critical Path: TASK-001 → TASK-003 → TASK-005

## Requirement Coverage

| Requirement | Task(s) |
|-------------|---------|
| REQ-001 | TASK-001, TASK-003 |
| REQ-002 | TASK-002, TASK-004 |

---

## Phase 1: Foundation

### TASK-001: Setup Database Schema

#### Context
This task establishes the data layer for the feature. The schema must support
all entities defined in the SDD and enable the API operations in Phase 2.

#### Requirements
- Create users table with id, email, created_at
- Create sessions table with foreign key to users
- Add indexes for common query patterns

#### Technical Approach
Follow the existing migration pattern in `db/migrations/`. Use the same
column naming conventions as existing tables.

#### Files to Create/Modify
- `db/migrations/002_add_users.sql` - New migration file
- `db/schema.sql` - Update schema documentation

#### Key Interfaces

CREATE TABLE users ( id SERIAL PRIMARY KEY, email VARCHAR(255) UNIQUE NOT NULL, created_at TIMESTAMP DEFAULT NOW() );

#### Constraints
- Follow existing naming conventions (snake_case)
- Use SERIAL for auto-increment IDs
- All timestamps must include timezone

---

## Phase 2: Core Implementation

### TASK-002: Create API Endpoints
...

Task Prompt Template

Each task's prompt field should follow this structure:

markdown
## Context
[2-3 sentences explaining where this task fits in the larger system and why it matters]

## Requirements
- [Specific, verifiable requirement 1]
- [Specific, verifiable requirement 2]
- [Specific, verifiable requirement 3]

## Technical Approach

### Suggested Implementation
[Step-by-step guidance based on codebase patterns]

### Files to Create/Modify
- `path/to/new-file.ts` - [Purpose]
- `path/to/existing-file.ts` - [What changes]

### Key Interfaces

// Define expected interfaces interface ExpectedInput { field: string; }

interface ExpectedOutput { result: boolean; }

## Constraints
- Follow existing patterns in `[reference file]`
- Use `[specific library]` for `[purpose]`
- Do not modify `[protected area]`
- Maintain backward compatibility with `[existing API]`

Task Sizing Guidelines

| Points | Description | Example | |--------|-------------|---------| | 1 | Trivial change | Config update, copy change | | 2 | Small task | Single function, simple component | | 3 | Medium task | Multiple functions, moderate complexity | | 5 | Large task | Significant feature piece | | 8 | Complex task | Cross-cutting, multiple systems |

Rule: Tasks >5 points trigger auto-refinement. Tasks >8 points must be broken down.

Task Categories

| Category | Description | Examples | |----------|-------------|----------| | feature | New user-facing functionality | New UI component, API endpoint | | infrastructure | Backend systems, tooling | Database migration, CI setup | | testing | Test coverage | Unit tests, E2E tests | | documentation | Docs and comments | API docs, README updates | | security | Auth, permissions | Input validation, auth flow | | performance | Optimization | Caching, query optimization |

Dependency Mapping

When generating tasks, identify:

1. Hard Dependencies (depends_on/blocks)

• Task X must complete before Task Y can start
• Usually: schema → API → UI

1. Parallel Tasks

• Can be worked on simultaneously
• Usually: independent components, tests

1. Critical Path

• The longest chain of dependent tasks
• Store in summary.critical_path

Execution Phases

Group tasks into logical phases:

| Phase | Purpose | Typical Tasks | |-------|---------|---------------| | 1: Foundation | Setup and infrastructure | Schema, types, config | | 2: Core | Main implementation | APIs, services, core logic | | 3: UI | User interface | Components, pages, forms | | 4: Polish | Quality and docs | Tests, documentation, cleanup |

Quality Checklist

Before finalizing tasks:

• ] Every task has clear acceptance criteria in JSON
• ] Dependencies form a valid DAG (no cycles)
• ] No task exceeds 8 story points
• ] Every requirement (REQ-XXX) maps to at least one task
• ] Tests are included as explicit tasks
• ] File paths reference actual codebase structure
• ] prompt field contains full implementation guidance

Typical Decomposition Pattern

Feature X
├── TASK-001: Database schema/migrations (infrastructure, 3pts)
├── TASK-002: Type definitions and interfaces (infrastructure, 2pts)
├── TASK-003: API endpoint - create (feature, 3pts)
├── TASK-004: API endpoint - read (feature, 2pts)
├── TASK-005: API endpoint - update (feature, 3pts)
├── TASK-006: API endpoint - delete (feature, 2pts)
├── TASK-007: UI component - form (feature, 3pts)
├── TASK-008: UI component - list (feature, 3pts)
├── TASK-009: Unit tests (testing, 3pts)
├── TASK-010: Integration tests (testing, 3pts)
└── TASK-011: Documentation (documentation, 2pts)

Schema Reference

See references/tasks-schema.json for the full JSON Schema specification. See references/state-schemas.json for loop state file schemas.