task-specs

name

task-specs

description

Flesh out the skeleton task files from a task DAG into full self-contained task specifications that stateless coding agents can execute. Use this skill whenever the user asks to "spec out the tasks", "flesh out the task specs", "write the task specs for the DAG", "make the tasks executable", "expand the task skeletons", or "finalize the tasks for the coding agents". Trigger on phrases like "spec out the tasks in plans/<slug>/", "write specs for the DAG at …", "fill in the tasks", "make the tasks ready for execution", "task-spec the DAG". This is the step *after* `task-dag` — it reads each skeleton task file and replaces the 1-line body with a complete spec (files to touch, interface contracts, acceptance criteria, test plan, patterns to reuse), so a coding agent picking up a single task file has everything it needs without reading siblings.

Task Specs Generator

Replace the skeleton bodies in plans/<slug>/tasks/T-NNN-*.md with full self-contained specifications. The bar to clear: a coding agent picking up one task file can complete the work without reading the design doc, the PRD, or any sibling task file. Anything the agent needs must be inline or named by an exact file path.

When this skill triggers

Use this skill for any request that boils down to "make the DAG executable" or "fill in the task specs." Common phrasings:

• "Spec out the tasks in plans/<slug>/tasks/"
• "Flesh out the task specs for the DAG at plans/<slug>/"
• "Write the task specs"
• "Make the tasks ready for execution"
• "Fill in the skeleton task files"

If the user passes specific task IDs (e.g., T-001,T-003), only spec those — leave the rest as skeletons. If they don't, spec every task with a skeleton (one-line) body.

If the user is asking to create the DAG, use task-dag first. If they're asking to design the system (architecture, contracts), use tech-design.

Workflow

1. Read the inputs

Locate the tasks directory. Default: plans/<slug>/tasks/. Read everything in that directory and the siblings:

• tasks/index.md — the DAG view (Mermaid + table + notes on shape). Pay attention to "Notes on shape" — that's where the task-dag skill flagged decomposition judgment calls.
• Every existing tasks/T-NNN-*.md skeleton — you need their frontmatter (id, title, depends_on, status, estimated_size) and their current body to know whether they're skeletons (1 line) or already specced.
• Sibling plans/<slug>/design.md — the technical design. This is your primary reference for what each task is actually building. Architecture, components, data model, contracts, patterns-to-reuse — all live here.
• Sibling plans/<slug>/prd.md if it exists — useful for the why behind a task when the design is silent.

2. Recall from Hindsight memory (best-effort)

If Hindsight tools are available, query per task before speccing. Examples of useful queries:

• agent_knowledge_recall with "previous task specs in this repo for " — to surface patterns from successful prior tasks
• Or "common gotchas when speccing tasks" — to surface things prior runs learned the hard way

If a relevant page comes back, use it as context. Recall is best-effort — proceed without it if unavailable.

3. Determine which tasks to spec

By default, spec every task whose body is a skeleton (one or two sentences, often containing a "Full spec to be written by task-specs" deferral). Leave tasks that already have a multi-section body alone unless the user explicitly says to re-spec.

If the user passed a specific task ID list, restrict to those.

4. Spec in topological order

Process tasks in dependency order — leaves (no deps) first, then their dependents. This matters because a downstream task's spec may need to reference a contract (function signature, type, file path) established by an upstream task you're about to spec. Doing them in order means by the time you reach T-005, you already know exactly what T-003 exports, so you can spec the import side with confidence.

If two tasks have no dependency between them, order doesn't matter — pick any sensible order (e.g., ascending ID).

5. Explore the codebase per task

For each task, do focused exploration before writing the spec. Search for:

• Existing files the task will modify — read them first; you can't write a spec for "modify src/models/user.ts" without knowing what's in there today.
• Sibling files that demonstrate the convention — if you're adding a new model, find an existing model and note its layout.
• Utilities to reuse — functions or helpers in src/lib/, src/utils/, or wherever the project keeps shared code, that this task should call rather than re-implement.
• Test patterns — how other features test similar work; what fixtures or helpers exist.
• Naming conventions — kebab-case files? snake_case symbols? Check before inventing names.

Use Grep for symbol lookups and Read for files. The exploration burden is per-task, not per-repo — you're answering "what does this specific task need from the codebase," not "what's in this repo."

For greenfield projects with no existing patterns to anchor to, name files based on the design doc's proposed structure and flag any uncertainty in the task's "Notes" section.

6. Write the full task body

Preserve the existing frontmatter exactly — id, title, depends_on, status: pending, estimated_size. Do not change dependency edges or task identity; those are the DAG's contract and downstream tools rely on them. Only replace the body (everything after the closing --- of the frontmatter).

Default task spec structure

---
id: T-001
title: "User model + migration"
depends_on: []
status: pending
estimated_size: medium
---

# T-001: User model + migration

## Context
Two sentences max. What this task does and why, linking to the relevant section of `../design.md` if helpful.

## Files to create/modify
A bulleted list. For each file:
- `path/to/file.ext` (create | modify | delete) — one-line description of what changes

Be exact — these paths land on a stateless coding agent's tool calls.

## Interface contracts
Concrete code blocks for any function, type, schema, or API surface this task introduces or modifies. Use the language the file is in (TypeScript, Python, SQL, etc.). Show signatures, not implementations. Downstream tasks may import these — they need to be unambiguous.

If the task is purely modifying internals with no new public surface, say "No new public surface" and move on.

## Existing patterns to reuse
A bulleted list. For each:
- `path/to/existing/file.ext` — one-sentence "why this fits"

Examples: the model layout to copy, the test helper to import, the middleware to wrap. Coding agents read these so they don't reinvent.

## Acceptance criteria
A checkbox list. Each item must be objectively verifiable — a command to run, a file that must exist, a test that must pass, an exit code. Avoid "the feature works" — say "`npm test src/models/user.test.ts` exits 0".

## Test plan
A paragraph or short list describing how this task gets tested. Name the test file(s), the kind of tests (unit, integration), and any fixtures needed. The coding agent ships these tests as part of the task.

## Out of scope
What this task explicitly does *not* do, with task IDs for where the excluded work lives (e.g., "Auth is handled in T-003; API endpoints in T-005").

## Notes / open questions
Anything genuinely unresolved that the coding agent should know — naming choices left to the agent, ambiguities in the design, decisions to escalate. If there's nothing, omit this section.

Sizing guidance

Per-task spec length varies with task size:

• fine tasks: 30–80 lines is typical
• medium tasks: 60–150 lines is typical
• coarse tasks: 100–250 lines is typical

If a spec is much shorter, you probably skipped exploration. If it's much longer, you may be over-specifying — coding agents are smart, you don't need to dictate every implementation detail. The spec defines interfaces and acceptance; the coding agent decides implementation.

7. Idempotency

If a task file already has a multi-section body (i.e., it's been specced before), leave it alone unless the user explicitly says to re-spec. Safe to re-run after a partial completion — the skill should skip already-specced tasks rather than overwrite them.

If you do skip a task, mention it in the final report so the user knows.

8. Persist learnings to Hindsight (best-effort)

If exploration uncovered repeatable patterns — "in this repo, model tasks always need a migration sibling and a <model>.test.ts next to them" — write or update a Hindsight page via agent_knowledge_create_page or _update_page. Keep pages tight: one pattern per page, concrete examples, file paths.

Don't dump feature-specific spec details into Hindsight. Only patterns that will help future task-spec runs in this repo.

9. Surface what changed

Tell the user, in two sentences:

• How many tasks were specced (and how many skipped because already specced)
• Anything notable you flagged (e.g., "T-004 has an open question about which auth middleware to call — the design doc was silent")

If you couldn't anchor a task to real files (because the design's structure is greenfield), say so explicitly so the user can verify before coding agents pick the tasks up.

Quality bar

A task spec is read by a stateless coding agent that has no other context. The bar:

• The agent can complete the task by reading only this file
• Every file path is real (or, for greenfield, named consistently with the design)
• Every interface contract is concrete enough that another task importing from it can be specced in advance
• Every acceptance criterion is objectively verifiable
• Existing patterns to reuse are cited with paths, not described abstractly

Things to avoid:

• Vague file paths ("the model file") — name it
• Pseudo-code in interface contracts ("// handle the request") — write the signature
• Acceptance criteria that aren't testable ("works correctly") — write a command or a file check
• Re-stating the design doc instead of applying it to this specific task — the task spec earns its keep by being concrete where the design is general
• Implementation details the coding agent doesn't need — leave room for the agent to decide how; you specify what and interfaces
• Changing the frontmatter — id, title, depends_on, estimated_size are the DAG's contract; preserve them exactly

When you write each spec, picture a stateless agent opening this one file in a fresh session. If anything they need isn't in the file, dig harder.