Agent Prompt Generation

Create structured task prompts that coding agents can execute effectively.

Output Files

Task generation produces two files:

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

TASKS.json Structure

{
  "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

TASKS.md Structure

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

# 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:

## 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

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

Task Categories

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:

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.