Feature Tasks Work

Execute planned work as an orchestrator with deterministic delegation and status tracking.

Mandatory interface

Use the bundled CLI for orchestration state and prompt assembly.

• Do not hand-edit planning/<title-slug>/task.status.json during normal execution.
• Use taskctl commands for queue reads, task lifecycle transitions, and delegation prompts.
• Hand edits are recovery-only when the status file is corrupted.

Set a command alias before orchestration:

TASKCTL="<path-to-skill>/scripts/taskctl"

Protocol

1. Start orchestration with minimal prior context. If your agent supports session reset, use it.
2. Resolve title-slug (for example add-new-payment-method) under planning/.
3. Run "$TASKCTL" init <title-slug>.
   • Loads or creates task.status.json.
   • Resets stale in_progress entries to todo.
   • Re-evaluates blocked tasks whose blockers are now done.
4. Discover dispatchable work with "$TASKCTL" ready <title-slug> --json.
5. For each task, prefer atomic dispatch:
   • "$TASKCTL" dispatch <title-slug> [task-id] --owner <orchestrator-or-subagent-id> --json
6. If dispatch is not used, do split mode:
   • Build delegation payload/prompt with "$TASKCTL" prompt <title-slug> <task-id> --json.
   • Mark dispatched with "$TASKCTL" start <title-slug> <task-id> --owner <orchestrator-or-subagent-id>.
7. Delegate using the generated prompt.
8. After each attempt, persist result with:
   • "$TASKCTL" complete <title-slug> <task-id> --result <done|blocked|failed> --summary "..." --files ... --tests ... --blockers ... --next ...
9. Retry policy:
   • Protocol failure (missing response fields): retry once with a format reminder.
   • Transient failure (timeout/rate limit): retry once after a pause.
   • Task failure (result=failed): mark blocked and continue.
   • Persistent failure (second attempt fails): mark blocked and continue.
10. Repeat dispatch -> complete until no todo tasks remain.
11. Emit final summary with done/blocked counts and unresolved blockers.

CLI commands

The script supports these commands:

• init [title-slug]
• ready [title-slug]
• prompt [title-slug] [task-id]
• dispatch [title-slug] [task-id] --owner <owner-name>
• start [title-slug] <task-id> --owner <owner-name>
• complete [title-slug] <task-id> --result <done|blocked|failed> --summary <text> [--files a,b] [--tests a,b] [--blockers a,b] [--next a,b]
• status [title-slug]

Notes:

• If title-slug is omitted, it is derived from the current branch.
• prompt returns both structured payload and formatted prompt when --json is used.
• For prompt or dispatch, if title-slug is omitted and task ID is explicit, pass --task <task-id>.

Delegation payload contract (outbound)

Use the payload from taskctl prompt. Required fields:

• task_id
• title
• acceptance
• deliverables
• project
• dependency_results (for each done blocker: { task_id, result_summary, files_changed })
• response_format list

Optional fields:

• context
• spec_excerpt

spec_excerpt rules

taskctl prompt follows these rules:

• If SPEC.md exists and is under 200 lines, include all of it.
• If SPEC.md is over 200 lines, include only sections referenced by context entries containing SPEC.md#<section>.
• If SPEC.md is missing, omit spec_excerpt.

Delegation response contract (required)

Every delegated task must return:

• task_id
• result (done|blocked|failed)
• result_summary
• files_changed (array)
• tests_run (array)
• blockers (array)
• next_unblocked_tasks (array of task IDs)

Treat missing required fields as protocol failure and apply retry policy.

Context management

• Keep per completed task: task_id, one-line result_summary, files_changed.
• Discard after completion: full delegation prompt, full response body, acceptance, deliverables, context hints.
• Always retain: dispatch queue and task.status.json summary counts.
• When context pressure is high (>60% tasks done): summarize completed tasks into one block and discard individual details.
• Never discard blocked task details and blockers.

task.status.json schema

Default path: planning/<title-slug>/task.status.json.

{
  "project": "my-project",
  "schema_version": 2,
  "updated_at": "2026-02-11T12:00:00.000Z",
  "summary": {
    "todo": 2,
    "in_progress": 1,
    "done": 3,
    "blocked": 1
  },
  "tasks": {
    "TASK-001": {
      "state": "done",
      "owner": "subagent-backend-1",
      "attempts": 1,
      "started_at": "2026-02-11T11:40:00.000Z",
      "finished_at": "2026-02-11T11:55:00.000Z",
      "blockers": [],
      "files_changed": ["src/api/orders.ts"],
      "tests_run": ["npm test -- orders"],
      "result_summary": "Implemented order endpoint and tests.",
      "next_unblocked_tasks": ["TASK-002"]
    }
  }
}

State semantics

• todo: not started.
• in_progress: delegated and awaiting result.
• done: completed and accepted.
• blocked: cannot proceed after retry policy or hard dependency blockage.

Only dispatch tasks in todo state that are currently unblocked.