Write Tasks

Write Tasks

Turn docs/specs/<slug>/_prd.md (and _techspec.md when present) into the executable task graph: one task_NN.md per task plus _tasks.md, the manifest that implement-task, implement-spec, and any future daemon schedule from. The artifacts are the contract — a fresh agent session must be able to pick up one task file and build it with no other context than the spec folder.

Preconditions

$ARGUMENTS names the spec. _prd.md must exist. If _techspec.md is missing on a feature with real architectural surface, run write-techspec first and then decompose — authoring the missing artifact is the resolution, never a reason to stop for permission. Under autonomous work this needs no confirmation: directing autonomous work authorizes the whole authoring chain for every Spec already in the approved queue, per docs/agents/autonomous-work.md. Ask for acceptance only when explicitly told to decompose without a tech spec, and then compensate with deeper codebase exploration before decomposing.

Project Constraint preflight

Run this preflight before deriving or approving a breakdown:

1. Classify the Spec. A Spec under the resolved archive directory (docs/history/specs/ for the built-in docs/specs root, or <spec-root>/_archived/ for an external or non-default root), or one proven to have completed before this contract applied, is a completed or archived legacy Spec. Leave every legacy artifact byte-identical: do not backfill, reformat, regenerate, or otherwise rewrite it.
2. For every active, non-archived, and not already completed Spec, require the PRD and every present TechSpec to contain complete Project Constraints sections. Each section must record Identifier strategy, Authentication and HTTP, Active ADR obligations, and Tooling authority as applicable or not applicable with a reason, and each row must cite its operative docs/agents/ source path.
3. If either active artifact is absent or incomplete, refuse to create or update _tasks.md or any Task file. Name every missing row, reason, or source path and send the Spec back through the owning authorial skill.
4. Inspect the proposed slices for any creation, edit, rename, move, or deletion of repository-tooling configuration, scripts, ignore files, plugin declarations, or version pins. Such work is authorized only when the PRD and present TechSpec record express maintainer authorization and the exact bounded repository-relative files it covers. A generic implementation request, setup approval, or Task assignment is not authorization. Without both the authorization and bounded files, refuse decomposition.
5. Copy the bounded file list into each authorized tooling Task's scope and acceptance criteria. The Task may change only those paths plus its own Task file; split any work that needs a different boundary.

Dependencies remain owned only by _tasks.md; Task status remains owned only by each Task file. The preflight never moves either responsibility.

Ownership rules (what lives where, and why)

• Dependencies live only in the _tasks.md graph. Never in task files. Two copies of an edge is how graphs drift.
• Status lives only in each task file's frontmatter. _tasks.md owns topology, not progress — schedulers re-read task files for state.
• Task Type is required in every task file. Use exactly one of backend, frontend, data, infra, docs, test, chore, or qa. Reserve qa for the unique authored terminal gate named by the manifest's qa: field. The Implement Command consumes this value for routing and rejects missing or unknown values; never leave a placeholder or infer the type later.
• Content references, never duplicates. Task files point at PRD/TechSpec sections by name; a task that restates the spec goes stale the first time the spec is amended. Link an adopted source at its post-adoption path in the owning Spec with a destination relative to that Task file, never at its pre-adoption provenance path. A secondary Spec links the primary owner's copy and adopts nothing.
• Context entries are labeled paths. Add ## Context only when the Task needs specific instruction or interface paths beyond the standard Spec bundle. Use bullets shaped as - instruction: <path> or - interface: <path>. Paths must be clean, repository-relative, and unique; a Task may declare at most 50 unique entries. The Daemon reserves those paths before filling the 200-path Spec Context Bundle with prior changed files.

Decomposition rules

• Vertical slices. Each task delivers a narrow but complete path through every layer it touches, demoable or verifiable on its own — a tracer bullet, not a layer ("all the schemas" is a wrong task; "expired imports retry and surface their status" is a right one).

• Prefactoring first. When a slice needs the ground prepared, make that its own leading task: make the change easy, then make the easy change.

• Characterize external surfaces during authoring. When a Spec crosses an external surface such as an adapter, contract, or database, author a characterization Task that records what the real boundary does, not what a fake does, so an unsupported premise fails while the Spec is still being authored rather than at the QA gate.

  List it in needs, not merely earlier in the file. Every Task whose premise depends on the characterization names that Task in its needs entry in _tasks.md. Execution waves are built from needs alone, so a Task that merely appears later in the manifest can run in the same wave as the characterization it depends on, and read a boundary nobody has characterized yet. File order is not a dependency.

  A characterization Task touches a real boundary, so bound it explicitly. Its file states the target it will reach, by name. It reads rather than writes, or runs against an isolated instance the Task itself creates and removes; it never characterizes against shared or production state by default. It uses credentials scoped to that target and no wider, honours cancellation, and cleans up what it created even when it fails. A characterization that must write requires that write to be authorized in the Task the way any other irreversible action is — recording what a boundary does is not authority to change it.

  Its Verification asserts the record, never the boundary. The Daemon runs a Task's declared ## Verification commands verbatim through the shell, once against the unchanged tree before the Agent turn exists and again at settlement. Nothing in that path reads the bounds above: they constrain the Agent, and the Daemon is not the Agent. A Verification that reaches the real surface therefore reaches it unbounded, twice, including before any work has been done. Verify the characterization the Task recorded — its shape, its presence, what downstream Tasks will read — and leave the boundary call in the Agent turn, where the Task's declared target, isolation, credentials, and write authorization apply. This is the hermeticity rule these commands already carry, stated where the temptation to break it is strongest: a live external surface is ambient state, and a command that depends on one is not hermetic.

• Sized for one fresh session. A task an agent can complete in a single sitting with a fresh context. More than ~7 subtasks or files means split it.

• Tests embedded, never separated. Every task's acceptance criteria include its own tests; a trailing "write the tests" task means the earlier tasks were never done.

• Independently implementable. Once its needs are completed, a task must require no other unfinished work — that's what allows parallel execution across worktrees later.

• Verification must be hermetic, portable, effect-proving, and Daemon-owned. Every task's ## Verification commands must be satisfiable in a fresh worktree using only repository state, declared config, and task-owned setup. Do not depend on untracked local files, prior Runs, interactive prompts, pushed branches, or ambient machine state unless the task explicitly creates that state. Use portable shell forms: prefer grep over rg in task gates, avoid wc-pipeline assertions that vary across platforms, and use repository build flags such as go build -buildvcs=false ./... when a build is required. A Task must prove its own effect with executable checks; the Run-level gate proves nothing else regressed. Do not add a whole-package suite command to each Task for regression coverage. Every Verification command must be able to fail when no work was done: a command that names a missing test or selects no cases is vacuous if it still exits zero. A Verification command passes only by exiting zero. For an assertion whose success is an empty result or an absent string, use a form that turns that condition into exit zero: matches="$(find path -name '*.tmp' -print)" || exit 1; test -z "$matches", test -d path && ! grep -rq 'forbidden' path, or find path -name '*.tmp' -print > /tmp/matches.txt 2>&1 || { cat /tmp/matches.txt; exit 1; }; test ! -s /tmp/matches.txt || { cat /tmp/matches.txt; exit 1; } when failure must print the matches. Refuse the work-independent shape composed only of repository-wide gates plus working-tree cleanliness checks; those checks pass most easily when no Task work occurred. The Daemon runs these commands after the Agent turn and may send one failure-only Verification Feedback prompt; do not tell the Agent to run the authoritative gate itself.

• Requirements must be mutually satisfiable. Refuse a Task when its declared MUST and MUST NOT clauses require and forbid the same named state. Do not send work that cannot satisfy its own written contract to an Agent Session.

• Gate rehearsals declare their evidence. A Task whose title states that it rehearses or proves a gate must include ## Rehearsal Cases with one - Case: <case>; Observation: <observation> entry for every case it must exercise. Refuse the Task when the section is absent or any entry lacks its case or observation.

• One acceptance row rests on evidence the Spec did not author. At least one named acceptance row in the graph must rest on evidence originating outside the Spec's own artifacts — a repository the Spec did not build, a measurement it did not design, or published literature — and must record where that evidence came from. A rehearsal shows that the code matches the requirement; only an outside source can show that the requirement was right. When that source cannot be obtained during task authoring, decomposition proceeds without human interaction and records the row as blocked with its reason. The blocked row is carried into the QA gate, where it triggers a rows_blocked_environment entry on the report and blocks PR preparation.

• Commit and push stay out of task criteria. The Daemon owns Task commits, Run integration, and any configured push. Never put commit, push, PR creation, or branch-publishing requirements in task Requirements, Subtasks, Acceptance Criteria, or Verification commands.

Author the QA gate decision

Follow one order per Spec: implement the graph including its authored gate, archive, open the Pull Request, watch until Clean, and merge.

ADR-0091 keeps the authored QA gate before any Pull Request exists, while ADR-0080 lets environment-blocked rows pass with equivalent evidence. Spec 0078 proved that path: eleven of eighteen rows were blocked, nine of those eleven on no open Pull Request and each of those nine backed by recorded payload, command-runner, and event-stream evidence.

Every active Spec authored under the QA Task contract must choose exactly one of these shapes during decomposition:

• Include the gate. Add qa: task_NN to _tasks.md frontmatter, naming one task_NN.md whose type is qa. Make that node terminal and make its needs list cover every non-QA leaf so the gate cannot run before any branch of the graph settles.
• Decline the gate. Add qa: declined and a non-empty qa_reason to _tasks.md frontmatter. Do not emit a qa Task when the gate is declined.

A post-contract graph with neither declaration, both shapes, an unnamed qa Task, or a gate that is not terminal is a defect. Refuse to produce it. An absent declaration remains valid only for a legacy graph proven to predate the contract; leave that graph byte-identical.

Whichever shape the graph takes, its closing node also carries the glossary check — the authored qa Task when the gate is included, otherwise the last Task in topological order. Give the check that home so a term the Spec coined, changed, or dropped is noticed while the work is still open rather than after it closes. The domain guide (docs/agents/domain.md) owns what the check looks for and when the domain context is updated in response; the graph owns only where it happens, and nothing in it waits for a human.

Corrective-Task ceiling

The corrective-work ceiling remains two Tasks. When QA findings would require more than two corrective Tasks, do not author a third patch or stop for a policy decision. Choose one sanctioned exit:

• Amend the TechSpec and recut the Task Graph from it.
• Promote the excess corrective work to its own Spec and leave the gate failing the discovered story explicitly.

Reaching the ceiling is a decision inside the loop's authority. The loop chooses an exit and continues without stopping for a human.

Task Type selection

Choose the type from the Task's dominant delivered outcome, not from who will implement it, the tool used, or configuration choices:

• backend — CLI, daemon, service, API, domain, or core application behavior;
• frontend — browser UI, TUI, visual, interaction, accessibility, or UX behavior;
• data — persistence schema, query, migration, import, or data-pipeline behavior;
• infra — build, CI/CD, packaging, deployment, environment, or operational infrastructure;
• docs — documentation-only behavior or durable knowledge artifacts;
• test — test harness, fixture, evaluation, or coverage work without a product behavior change;
• chore — bounded maintenance that changes none of the preceding product surfaces;
• qa — the unique authored terminal gate that executes qa-gate after every non-QA leaf settles; never use it for implementation tests or an intermediate checkpoint.

When a vertical slice crosses types, use the type of its primary user-visible or operational outcome. If two outcomes are independently valuable or the dominant outcome remains ambiguous, split the Task so each slice has one dominant outcome; do not encode multiple values and do not defer the classification.

Process

1. Derive the breakdown

Start from the TechSpec's Build Order (its dependency statements become graph edges). Map every PRD user story and core feature onto at least one task; an uncovered story is a hole to fix now. Decide the QA gate once from the authored Spec and add either its terminal node or the reasoned decline to the breakdown.

2. Escalation check — decide autonomously, escalate by exception

Derive the breakdown and write it. The Spec is the authorization: a PRD and TechSpec that passed their own gates already carry the product and architecture decisions, so granularity, dependency order, and Task Type classification are derivations from those artifacts — not decisions to confirm. Report the finished breakdown so a change to any slice can be requested afterwards; do not block on approval.

Stop and ask only when the next decision would change authority, architecture, or blast radius:

• Missing authority. A slice would create, edit, rename, move, or delete protected tooling that the PRD and present TechSpec do not authorize with exact bounded files. Name the paths and why they are needed; never widen the boundary yourself.
• Unverifiable without a human. A Task's acceptance genuinely needs a person or a credential the repository cannot hold — a live external account, a physical device, a subjective judgement. Verification must stay hermetic, so a Task that cannot be is a Spec problem, not a graph problem.
• The Spec is wrong, not just thin. The decomposition only works by contradicting or extending the TechSpec's Build Order, architecture, or contracts. Route back to write-techspec rather than silently redesigning.
• Irreversible blast radius inside one slice. A Task would run a data migration, a destructive deletion, a release or publication, or a credential rotation. Confirm the boundary before that Task exists.
• Irreducible complexity. A slice cannot be sized to one fresh session and cannot be split without breaking the vertical-slice rule. That signals an under-specified Spec; say which slice and why.

Escalate with the specific blocking fact and a proposed resolution, never with an open "is this ok?". Anything outside those five is a derivation: granularity preference, naming, ordering the Build Order already implies, and dominant-outcome classification are decided here. Every type cell must carry exactly one allowed Task Type before writing — a blank, placeholder, or combined value is a defect to resolve, not a question to ask.

3. Write the files

From the templates in references/task-template.md, write _tasks.md and every task_NN.md (numbered from 01 in topological order). Copy the derived Task Type into each task's type frontmatter and the _tasks.md projection table. For an included gate, name the qa Task with qa: in manifest frontmatter, place it last in topological order, and give it every non-QA leaf in needs; for a decline, write qa: declined with qa_reason and emit no qa Task. Acceptance criteria must be independently verifiable — a criterion nobody can check is a wish, not a criterion. Include a ## Verification section with exact, hermetic, portable commands that prove the task's effect in a fresh worktree; the Daemon runs them verbatim after Agent work. Add ## Context only for task-specific instruction or interface paths that the standard Spec Context Bundle would not make obvious.

Durability applies here too: describe behavior and interfaces, not repo file paths (relative references within the spec folder are fine — the folder moves as a unit).

4. Validate the graph

Before reporting, verify mechanically — parse, don't eyeball.

Start by running the repository's own checker on the Spec you just decomposed:

roundfix spec check <slug> --run-verification

This form reads the PRD, the TechSpec, the ADRs they cite, and the graph together — which is the first moment all four exist — and executes authored Verification commands in a disposable checkout at HEAD. A clean verdict from roundfix spec check <slug> without --run-verification does not cover Vacuous Verification: it does not execute those commands against the unchanged tree, so a command that already exits zero can remain undiscovered. Do not prefer the non-probing form for its speed; that speed is a consequence of omitting command execution.

Treat every reported error as blocking: fix the artifact and re-run until it is clean, and do not report the breakdown while a finding stands. A [gap] is blocking too; account for the named ADR or record why it does not apply. Skipped checks are informational.

This is not a substitute for the list below, which covers what the checker does not: it catches unlisted and unaccounted ADRs, incomplete Project Constraints, unmapped coverage, contradictory requirements, undeclared rehearsals, work-independent Verification, and an undocumented Vocabulary Contract. It does not yet verify that a cited ADR says what the artifact claims it says.

Then confirm by reading:

• Every graph.nodes[].file exists and every task file has parseable frontmatter with status: pending.
• Every task file has exactly one type value from backend, frontend, data, infra, docs, test, chore, or qa; the _tasks.md projection row for that task contains the identical value.
• Every needs entry names an existing node id; no cycles (a topological order can be printed).
• Every post-contract graph declares exactly one QA decision. An included gate is the unique qa Task, has no dependents, and depends directly or transitively on every non-QA leaf; a declined gate has a non-empty qa_reason and no qa Task.
• Every PRD user story appears in some task's References.

Print the wave plan (wave 1 = no needs; wave N = needs met by earlier waves) as the execution preview.

5. Report

Reply with the breakdown table (id | title | type | complexity | needs), the authored QA decision and its reason when declined, a one-line rationale for the slicing, the file list, and the wave plan — and say that a change to any slice can be requested now. Name any escalation trigger you hit and how it was resolved.

Anti-patterns

• Horizontal slicing (a schema task, an API task, a UI task) — every task should cut through the stack.
• Mega-tasks that "do the feature" — if it can't be verified alone, it isn't a task yet.
• Vague criteria ("works correctly", "handles errors") — name the observable behavior.
• Non-hermetic Verification that relies on local-only files, prior Run state, manual prompts, or remote branch state.
• Non-portable Verification such as wc pipeline shape checks, rg dependency checks where grep works, or Go build commands missing the repository's -buildvcs=false flag.
• Verification that only exercises broad suites without proving the Task's specific effect.
• Commit, push, PR, or branch-publishing acceptance criteria — those are Daemon and delivery responsibilities, not task success criteria.
• Editing the graph and the task files out of sync — regenerate both from the same breakdown.
• Blocking on approval for a breakdown the Spec already authorizes — invocation is the authorization, and granularity is a derivation, not a decision.
• Proceeding past a real escalation trigger because the loop is running — a missing tooling authorization or a Task that cannot be verified hermetically is a stop, not a judgement call.
• Missing, placeholder, combined, or invented Task Types — classification is a required routing contract, not descriptive free text.
• Leaving a post-contract graph without either an authored terminal qa Task or qa: declined plus qa_reason — omission is a defect, not a per-run QA choice.

References

• references/task-template.md — templates for _tasks.md and task_NN.md. Read it before writing any file.