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

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

# 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
```sql
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
```typescript
// 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

2. **Parallel Tasks**
   - Can be worked on simultaneously
   - Usually: independent components, tests

3. **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.