Prd to tasks

PRD to Tasks

Convert a PRD into a machine-readable tasks.json file that drives implementation. Each user story and functional requirement becomes one or more concrete, dependency-ordered tasks.

When to Use

• A PRD has been created and the user wants to start implementation
• The user says: "create tasks," "break this down," "what should I work on first?"
• Before delegating implementation to agents (implement-tasks)
• To estimate effort or plan sprints

When NOT to Use

• No PRD exists (run create-prd first)
• The task is trivially small (just do it)
• The user wants a TODO.md instead (use project-files)
• For tracking in-progress tasks (use TODO.md from project-files)

Prerequisites

• A PRD exists (created by create-prd or manually)
• Access to the PRD file in the current workspace

tasks.json Format

{
  "$schema": "tasks/v1",
  "metadata": {
    "project": "Feature or project name",
    "prd": "PRD-feature-name.md",
    "created": "YYYY-MM-DD",
    "version": "1.0",
    "totalTasks": 12,
    "totalEstimatedHours": 40,
  },
  "phases": {
    "1-foundation": {
      "label": "Phase 1: Foundation",
      "description": "Core infrastructure and setup that everything depends on",
      "tasks": ["T001", "T002", "T003"],
    },
    "2-core": {
      "label": "Phase 2: Core Features",
      "description": "Must-have user stories (P0)",
      "tasks": ["T004", "T005", "T006", "T007"],
    },
    "3-polish": {
      "label": "Phase 3: Polish & Edge Cases",
      "description": "Should-have user stories (P1) and hardening",
      "tasks": ["T008", "T009", "T010"],
    },
    "4-nice-to-have": {
      "label": "Phase 4: Nice to Have",
      "description": "P2 stories, stretch goals",
      "tasks": ["T011", "T012"],
    },
  },
  "tasks": [
    {
      "id": "T001",
      "title": "Set up project structure and configuration",
      "description": "Create the module directory, configuration files, type definitions, and base interfaces needed by all subsequent tasks.",
      "phase": "1-foundation",
      "priority": "critical",
      "estimatedHours": 2,
      "dependencies": [],
      "userStory": null,
      "functionalReq": "FR-1",
      "planModel": "type-driven",
      "tags": ["setup", "types"],
      "acceptanceCriteria": [
        "Directory structure matches project conventions",
        "Type definitions compile without errors",
        "Configuration is loaded correctly",
      ],
    },
    {
      "id": "T002",
      "title": "Implement JWT token generation and validation",
      "description": "Create the core auth utilities: generate access tokens, verify tokens, extract user info from tokens, handle expiration.",
      "phase": "1-foundation",
      "priority": "critical",
      "estimatedHours": 4,
      "dependencies": ["T001"],
      "userStory": "As a user, I want to authenticate so that I can access protected resources.",
      "functionalReq": "FR-1",
      "planModel": "type-driven",
      "tags": ["auth", "security"],
      "acceptanceCriteria": [
        "Access tokens are generated with correct claims",
        "Expired tokens are rejected",
        "Tampered tokens are rejected",
        "Token validation completes in under 5ms",
      ],
    },
    {
      "id": "T003",
      "title": "Add auth middleware for protected routes",
      "description": "Create Hono middleware that checks for valid JWT on protected routes and injects user context.",
      "phase": "1-foundation",
      "priority": "critical",
      "estimatedHours": 3,
      "dependencies": ["T002"],
      "userStory": "As a user, I want protected routes to require authentication.",
      "functionalReq": "FR-2",
      "planModel": "review-first",
      "tags": ["auth", "middleware", "api"],
      "acceptanceCriteria": [
        "Protected routes return 401 without valid token",
        "Valid tokens pass through with user context injected",
        "Middleware doesn't affect public routes",
      ],
    },
  ],
}

Field Reference

Field	Type	Required	Description
id	string	Yes	Unique task ID, format T001, T002, etc.
title	string	Yes	Short, actionable task title
description	string	Yes	What needs to be done, context, approach hints
phase	string	Yes	Must match a key in phases
priority	string	Yes	critical, high, medium, low
estimatedHours	number	Yes	Rough estimate in hours
dependencies	string[]	Yes	IDs of tasks that must complete first (empty array if none)
agent	string	Yes	Squad agent responsible for implementation (see Agent Mapping)
moeExperts	string[]	Yes	MoE experts who review/analyze before implementation (see Expert Selection)
userStory	string|null	No	The user story this task satisfies
functionalReq	string	No	The FR this task maps to (e.g., "FR-1")
planModel	string	No	Opencode Go plan model to use for this task (see Plan Models below)
tags	string[]	No	Labels for filtering (auth, ui, api, db, test, docs, etc.)
acceptanceCriteria	string[]	Yes	Verifiable conditions that prove the task is done

Top-Level agents Key

The agents object maps each squad agent to their assigned tasks for quick reference during implementation:

"agents": {
  "frontend-engineer": {
    "role": "UI components, client-side functionality",
    "tasks": ["T003", "T004", "T006"]
  },
  "backend-engineer": {
    "role": "Business logic, APIs, data processing",
    "tasks": ["T001", "T002", "T005"]
  },
  "qa-engineer": {
    "role": "Automated tests, linting, integration checks",
    "tasks": ["T007", "T008"]
  }
}

Dependency Rules

1. Dependencies must reference valid task IDs — No forward references to non-existent tasks
2. No circular dependencies — The graph must be a DAG
3. Phase dependencies are implicit — All tasks in phase N may depend on tasks in phase < N
4. Keep dependencies minimal — Only list direct dependencies, not transitive ones

Workflow

1. Read the PRD

Parse the PRD and extract all important elements:

• User stories — Map each to one or more tasks
• Functional requirements — Each FR becomes at least one task
• Non-functional requirements — May generate cross-cutting tasks (performance, accessibility, security)
• Constraints — May create setup/configuration tasks
• Dependencies — External dependencies become initial tasks

2. Group into Phases

Default phase structure (adjust based on PRD content):

Phase	Contents	Priority Mapping
1-foundation	Project setup, types, config, database schema, shared utilities	critical
2-core	All P0 (Must Have) user stories and their FRs	critical / high
3-polish	P1 (Should Have) stories, error handling, edge cases, tests, docs	high / medium
4-nice-to-have	P2 (Nice to Have) stories, stretch goals	medium / low

Common additional phases: 0-prerequisites (for external dependencies), 5-deploy (CI/CD, monitoring).

3. Create Tasks

For each phase, create tasks following these rules:

• One task = one cohesive unit of work — Completabe in 2-8 hours
• Task title is a verb phrase — "Implement X", "Add Y", "Create Z", "Fix W"
• Description adds context — Why this task exists, what approach to take, files to touch
• Acceptance criteria are testable — Write them as if for an automated test

4. Wire Dependencies

Draw the dependency graph:

T001 (setup) ← no deps
  ├── T002 (auth utils) ← depends on T001
  │   ├── T003 (middleware) ← depends on T002
  │   └── T004 (login endpoint) ← depends on T002
  └── T005 (user model) ← depends on T001
      └── T006 (user API) ← depends on T005

Encode in the dependencies arrays.

5. Add Estimates and Tags

• estimatedHours: Be conservative. If unsure, round up.
• tags: Use consistent tags across the project. Common: setup, types, auth, api, ui, db, test, docs, security, performance, a11y, dx.

6. Assign Agent and MoE Experts

Every task must be assigned to a squad agent (who implements) and a set of MoE experts (who review/analyze before implementation). These go in the agent and moeExperts fields on each task, and are summarized in the top-level agents key.

Agent Mapping

Map each task to the squad agent whose domain matches:

Squad Agent	Domains	Task Tags
frontend-engineer	UI components, client-side JS, Astro pages, i18n, CSS, Alpine, htmx	ui, astro, alpine, htmx, i18n, form, css, responsive
backend-engineer	Libraries, APIs, Astro endpoints, business logic, data processing	lib, api, endpoint, pix, qr, server, svg
devops-sre	Dependency management, build tooling, CI/CD, configuration	setup, deps, config, ci, deploy
qa-engineer	Unit tests, integration tests, E2E tests, linting	test, unit, integration, e2e

If a task spans domains (e.g., an endpoint with UI), pick the primary agent. If unsure, default to backend-engineer for server-side work and frontend-engineer for client-side work.

MoE Expert Selection

Choose 2–4 MoE experts based on the task's concerns. Use the mixture-of-experts skill definitions:

Task Domain (tags)	Recommended MoE Experts	Why
setup, deps, config	maintainer, dx-specialist	Tooling and dev experience
lib, pix, qr	architect, security, maintainer	Core logic correctness
lib, svg, qr	architect, performance, maintainer	Rendering performance
api, endpoint, svg, caching	architect, api-designer, security, performance	API design + caching + security
api, endpoint, html, htmx, caching	architect, api-designer, maintainer, performance	API design + templates + caching
i18n, pt-br	maintainer, dx-specialist	Consistency and completeness
ui, alpine, form, validation	maintainer, minimalist, dx-specialist, performance	Interactive form quality
ui, htmx, clipboard, qr	maintainer, minimalist, dx-specialist, performance	Async UI quality
ui, astro, integration	maintainer, minimalist	Page structure simplicity
ui, edge-case	maintainer, minimalist, dx-specialist	Edge case UX clarity
ui, a11y, graceful-degradation	maintainer, dx-specialist	Accessibility and fallbacks
ui, responsive, dark-mode, a11y	maintainer, minimalist, dx-specialist	Visual quality across modes
alpine, htmx, integration	maintainer, dx-specialist, architect	Framework interop complexity
test, unit	maintainer, security	Test coverage + security edge cases
test, integration, api	maintainer, security, api-designer	API correctness + security
test, e2e	maintainer, dx-specialist	User-facing test quality

Override rule: If the task description or acceptance criteria suggest special concerns (e.g., unusual security risk, strict performance target), adjust the expert mix accordingly. Add security for auth/PII concerns, performance for latency-sensitive work, minimalist if the task risks over-engineering.

Build the agents Top-Level Key

After assigning every task's agent, build the agents summary:

"agents": {
  "frontend-engineer": {
    "role": "UI components, client-side functionality (Alpine, htmx, Astro pages, i18n, CSS)",
    "tasks": ["T006", "T007", "T008", "T009"]
  },
  "backend-engineer": {
    "role": "Libraries (pix, qrcode), Astro server endpoints",
    "tasks": ["T002", "T003", "T004", "T005"]
  },
  "devops-sre": {
    "role": "Dependency management",
    "tasks": ["T001"]
  },
  "qa-engineer": {
    "role": "Unit tests, integration tests, E2E tests",
    "tasks": ["T014", "T015", "T016", "T017"]
  }
}

The agents key must be validated: every task ID listed in agents.*.tasks must appear in the tasks array, and every task in tasks must have its agent field match exactly one agent entry.

7. Assign Plan Models

Each task may reference an opencode Go plan model — a structured approach for how the implementation subagent should plan and execute the task. This tells the subagent which planning strategy to use.

Available Plan Models

Plan Model	Description	Best For
explore-first	Research and understand before changing anything	Unfamiliar code, bug investigations, architecture review
test-driven	Write failing test first, then implement to pass	New features, algorithmic logic, well-specified behavior
refactor-safe	Preserve behavior, improve structure incrementally	Refactoring, cleanup, tech debt reduction
type-driven	Define types/interfaces first, then implement	New modules, API design, greenfield features
scout-then-build	Quick exploration pass, then implement in one go	Small features, single-file changes, config updates
review-first	Review existing code, propose changes, then implement	Legacy code, sensitive modules, high-risk changes

Assigning Plan Models to Tasks

Choose the plan model that best fits the task's nature and risk level:

Task Type	Recommended Plan Model	Why
New feature implementation	type-driven or test-driven	Clear interface/contract first
Bug fix	explore-first or scout-then-build	Understand before fixing
Refactoring	refactor-safe	Preserve existing behavior
Security-sensitive work	review-first	Extra caution required
Simple config/script	scout-then-build	Low risk, fast execution
Architecture change	explore-first + review-first	High impact, need thorough review

Example task with plan model:

{
  "id": "T003",
  "title": "Add auth middleware for protected routes",
  "planModel": "type-driven",
  // ... other fields
}

8. Validate the File

Run the shared DAG validator. It checks everything: valid JSON, missing dependencies, circular dependencies, phase keys, unique IDs, agent/moeExperts fields, and the agents summary.

# Run from the skill directory; validates the tasks.json in cwd
bun ../../scripts/validate-dag.ts tasks.json --summary

Flags:

• --summary — include topological order, phase breakdown, and hour estimates
• --quiet — exit code only (useful in scripts)

If validation fails, the script exits with code 1 and prints a specific error. Fix the issue before proceeding.

9. Present for Review

Summarize the task breakdown including agent assignments:

I've created tasks.json with [N] tasks across [M] phases:

Phase 1 - Foundation (3 tasks, 8h): Setup, types, base config
Phase 2 - Core (5 tasks, 22h): All P0 user stories
Phase 3 - Polish (3 tasks, 8h): Error handling, tests, docs
Phase 4 - Nice to Have (2 tasks, 6h): P2 stories

Total estimated: 44h
Critical path: T001 → T002 → T004 → T007 → T009

Agent assignments:
- frontend-engineer: 4 tasks (12h) — form, result pane, page integration
- backend-engineer: 3 tasks (10h) — libraries, endpoints
- devops-sre: 1 task (0.5h) — dependencies
- qa-engineer: 4 tasks (9h) — unit, integration, E2E tests

File: tasks.json — ready for implement-tasks

Want me to adjust any priorities, estimates, or agent assignments?

Complete Example

Given the Dark Mode PRD from create-prd:

{
  "$schema": "tasks/v1",
  "metadata": {
    "project": "Dark Mode",
    "prd": "PRD-dark-mode.md",
    "created": "2026-04-27",
    "version": "1.0",
    "totalTasks": 5,
    "totalEstimatedHours": 12,
    "totalTasks": 5
  },
  "agents": {
    "frontend-engineer": {
      "role": "UI components, CSS, state management",
      "tasks": ["T001", "T002", "T003", "T004", "T005"]
    }
  },
  "phases": {
    "1-foundation": {
      "label": "Phase 1: Foundation",
      "description": "Theme infrastructure",
      "tasks": ["T001", "T002"],
    },
    "2-core": {
      "label": "Phase 2: Core Feature",
      "description": "Theme toggle and system preference",
      "tasks": ["T003", "T004"],
    },
    "3-polish": {
      "label": "Phase 3: Polish",
      "description": "Persistence and transitions",
      "tasks": ["T005"],
    },
  },
  "tasks": [
    {
      "id": "T001",
      "title": "Define CSS custom properties for light and dark themes",
      "description": "Create CSS variables for all colors in both themes. Audit existing color usage and replace hardcoded colors with variables.",
      "phase": "1-foundation",
      "priority": "critical",
      "estimatedHours": 3,
      "dependencies": [],
      "agent": "frontend-engineer",
      "moeExperts": ["maintainer", "minimalist"],
      "userStory": null,
      "functionalReq": "FR-1",
      "planModel": "type-driven",
      "tags": ["ui", "css"],
      "acceptanceCriteria": [
        "All colors in the app are controlled by CSS custom properties",
        "Light theme looks identical to current app",
        "Dark theme colors meet WCAG AA contrast minimums",
        "No hardcoded colors remain outside of theme definitions",
      ],
    },
    {
      "id": "T002",
      "title": "Create ThemeProvider context and useTheme hook",
      "description": "SolidJS context provider that holds current theme state and provides toggle functionality. Expose via useTheme() hook.",
      "phase": "1-foundation",
      "priority": "critical",
      "estimatedHours": 2,
      "dependencies": ["T001"],
      "agent": "frontend-engineer",
      "moeExperts": ["maintainer", "dx-specialist", "architect"],
      "userStory": null,
      "functionalReq": "FR-1",
      "planModel": "type-driven",
      "tags": ["ui", "state"],
      "acceptanceCriteria": [
        "ThemeProvider wraps the app root",
        "useTheme() returns { theme, toggle, setTheme }",
        "Theme changes trigger re-render of dependent components",
        "Default theme is 'light'",
      ],
    },
    {
      "id": "T003",
      "title": "Add theme toggle to settings menu",
      "description": "Add a toggle switch or button in the existing settings/user menu. Use useTheme() to read/write state.",
      "phase": "2-core",
      "priority": "high",
      "estimatedHours": 2,
      "dependencies": ["T002"],
      "agent": "frontend-engineer",
      "moeExperts": ["maintainer", "minimalist", "dx-specialist"],
      "userStory": "As a user, I want to toggle between light and dark mode so that I can reduce eye strain in low-light environments.",
      "functionalReq": "FR-1",
      "planModel": "scout-then-build",
      "tags": ["ui"],
      "acceptanceCriteria": [
        "Toggle is visible in settings menu",
        "Clicking toggle switches theme immediately",
        "Toggle reflects current theme state",
        "Toggle is keyboard accessible",
      ],
    },
    {
      "id": "T004",
      "title": "Detect and respect OS color scheme preference",
      "description": "On first visit, check window.matchMedia('(prefers-color-scheme: dark)'). If user hasn't explicitly set a preference, use the OS value.",
      "phase": "2-core",
      "priority": "high",
      "estimatedHours": 1.5,
      "dependencies": ["T002"],
      "agent": "frontend-engineer",
      "moeExperts": ["maintainer", "dx-specialist"],
      "userStory": "As a user, I want the app to follow my OS color scheme by default so that I don't need to configure it manually.",
      "functionalReq": "FR-2",
      "planModel": "explore-first",
      "tags": ["ui", "a11y"],
      "acceptanceCriteria": [
        "First visit on dark-mode OS shows dark theme",
        "First visit on light-mode OS shows light theme",
        "OS theme change while app is open updates app theme",
        "User's explicit choice overrides OS preference",
      ],
    },
    {
      "id": "T005",
      "title": "Persist theme preference to localStorage",
      "description": "Save user's theme choice to localStorage. On load, check localStorage first, then fall back to OS preference, then light.",
      "phase": "3-polish",
      "priority": "medium",
      "estimatedHours": 1.5,
      "dependencies": ["T002", "T004"],
      "agent": "frontend-engineer",
      "moeExperts": ["maintainer", "minimalist"],
      "userStory": "As a user, I want my preference to persist across sessions so that I don't need to re-set it.",
      "functionalReq": "FR-1",
      "planModel": "scout-then-build",
      "tags": ["ui", "state"],
      "acceptanceCriteria": [
        "Theme choice survives page reload",
        "Theme choice survives browser restart",
        "Clearing localStorage resets to OS default",
        "No flash of wrong theme on page load (SSR-safe)",
      ],
    },
  ],
}

Edge Cases

Large PRDs (20+ User Stories)

Break into multiple task files or use phases aggressively:

"phases": {
  "1-mvp": { "label": "Phase 1: MVP", "tasks": ["T001".."T008"] },
  "2-enhance": { "label": "Phase 2: Enhancement", "tasks": ["T009".."T015"] },
  "3-scale": { "label": "Phase 3: Scale", "tasks": ["T016".."T020"] }
}

Tasks That Span Multiple FRs

A task may satisfy multiple functional requirements. List the primary one in functionalReq. Add secondary ones in the description or tags.

Unclear Dependencies

If the dependency order is unclear, annotate:

"description": "NOTE: May need to run before T007 if the API changes. Confirm during implementation."

External Dependencies

For dependencies on external systems or other teams:

{
  "id": "T000",
  "title": "[EXTERNAL] Obtain API key from third-party service",
  "description": "Blocked until we receive API credentials from vendor X.",
  "phase": "0-prerequisites",
  "priority": "critical",
  "estimatedHours": 0,
  "dependencies": [],
  "acceptanceCriteria": ["API key received and validated"],
  "tags": ["external", "blocker"],
}

Best Practices

• Tasks are leaf-level work — If a task is "Implement auth system," it's too big. Split it.
• Acceptance criteria are binary — Either passing or failing, no judgment calls.
• Keep estimates honest — Don't pad, don't optimistically undercount.
• Dependencies are minimal — Only list what must precede. Don't chain everything.
• Assign agent and MoE experts — Every task must have an agent and moeExperts. Validate with the checks in Step 7. Don't skip this — it's required for implement-tasks to delegate correctly.
• Tags enable filtering — Use consistent tags so agent assignment and MoE selection are predictable.
• One tasks.json per project — Not per feature within a project (use phases for that).
• Version the file — If the PRD changes, update tasks.json and bump the version.

Output

Write the tasks.json to the project root or alongside the PRD:

# Option A: Next to PRD
PRD-dark-mode.md
tasks.json

# Option B: In a docs/ or specs/ directory
docs/PRD-dark-mode.md
docs/tasks.json

The implement-tasks skill will look for tasks.json in the current working directory by default.