task-list-runner

task-list-runner

Drive a harness task list (JSON file matching the task-list-schema.md schema) to completion by dispatching each task to a foreground Agent tool call, one at a time. Pairs with task-list-builder, which produces the JSON.

The schema this skill consumes is defined in ${CLAUDE_PLUGIN_ROOT}/task-list-schema.md. Re-read that file rather than relying on memory.

Arguments: $ARGUMENTS

CLI reference — task_list_cli.py

The bundled CLI at ${CLAUDE_PLUGIN_ROOT}/skills/task-list-runner/task_list_cli.py is the canonical interface to the task file.

Invocation form (always): python3 "${CLAUDE_PLUGIN_ROOT}/skills/task-list-runner/task_list_cli.py" <subcommand> --file <path>. Never run the bare script path (.../task_list_cli.py <subcommand>): the file ships without an executable bit, so a bare-path invocation dies with exit 126 (permission denied) and forces a wasted retry. It also won't be auto-approved — the PreToolUse allow-list hook only matches commands that start with python3, so the bare path additionally eats a permission prompt. Every bare task_list_cli.py ... reference below is shorthand for this full python3 "<path>" ... form — expand it when you build the actual Bash call.

Subcommands: next, start, set-status, draft, publish, get, list, status, remaining, verify. All take --file <task-file-path>. Don't invent verbs like show, inspect, info, or view — argparse rejects anything outside the list above and prints the full subcommand help on rejection, so a wrong guess costs one wasted call but the right verb is always one of the ten names just enumerated.

• next — atomically claim and print the next task. Resumes in-progress, else flips first pending → in-progress. Exits 14 if no tasks remain. Exits 11 if any task is currently drafted — resolve via publish or set-status failed first. Output omits agentValidations by design: the implementation agent calls next to claim its task and must not pre-read the validator's checklist (get and list return the full object — they're for the runner's validator-dispatch and status-display callers). Redaction is at print time only; the on-disk file is unchanged.
• start --id <N> — flip task N from pending → in-progress.
• draft --id <N> --commit-msg "<subject>" --log-file <path|-> — flip in-progress task N to drafted; writes the log into the task and parks the commit subject in a per-task /tmp staging file. Does NOT touch git. This is the implementation agent's terminal step within an iteration — the runner takes over and dispatches the validation agent before either publish or set-status failed resolves the draft. Same --log-file - + quoted-heredoc convention as set-status (use stdin to keep it one Bash call).
• publish --id <N> — flip drafted task N to complete by running git commit against the already-staged git index using the staged subject. Verifies the index is non-empty before committing. On success, removes the staging file. On commit failure (e.g., a pre-commit hook rejects), the task stays drafted and the staging file stays put — the runner can fix the underlying cause and re-run publish --id N. Only the runner calls this (post-validation), never the implementation agent.
• set-status --id <N> --status complete|failed --log-file <path|-> — flip task N to a terminal status without touching git. Allowed transitions: in-progress → complete (no-code completion, e.g., investigation tasks), in-progress → failed (implementation gave up), drafted → failed (validation rejected the draft after retries). drafted → complete is forbidden — force the happy path through publish so a task cannot reach complete without a commit. Same --log-file - + quoted-heredoc convention as draft (the stdin path is preferred in the dispatched-agent flow because it's one Bash call, not two tool calls each gated separately by the auto-mode classifier).
• get --id <N> — print one task as pretty JSON. Unlike next, returns the full object including agentValidations — called by the runner during Phase 4 step 7 to source the validation agent's checklist. The implementation agent must not call get for its own task (use next to claim it instead); doing so would surface the validator-only field the redaction is structurally preventing.
• list [--status <s>] — print all tasks (or filtered) as a JSON array.
• status — print task counts (including a drafted count) + a precomputed remaining integer (pending + in_progress + drafted, the halt-gate's one number) + plan path. Use this for Phase 5 summary displays AND as the between-iteration halt-gate (it runs load_and_validate like every other command, so a non-zero exit means the file is corrupt). Drafted is non-terminal and counts toward remaining — a draft awaiting publish-or-fail still owes the runner work.
• remaining — print non-terminal tasks (pending + in-progress + drafted) as a compact JSON array — each entry has just id, title, effort, status. Use for Phase 3's user-facing summary table. The hot-path halt-gate uses status.remaining (the integer) instead so a 30–50-task file doesn't pay an O(N) array on every iteration.
• verify --id <N> — execute the resolved verifySteps for task N in order, capturing each step's stdout+stderr to /tmp/verify-<id>-step<i>-<slug>.log, stopping on the first failure with that step's exit code, and printing one verify[i/n] <slug> exit=<EX> log=<path> line per executed step. Resolution rule: if task N declares its own verifySteps array, those run (total replacement, not a merge); otherwise the top-level verifySteps runs. So --id selects both the log-file slug and the resolved-steps source — different tasks may run different steps. Auto-approved through the harness PreToolUse hook, so per-task verification runs without per-call prompts; trust for verifySteps content is upstream (task-list-builder).