claude-skills/.wiki/concepts/task-format-design.md

title, type, updated

title	type	updated
task-format skill — design	concept	2026-06-11

task-format skill — design

Why it exists

The autonomous poller (agents-task-runner) reads each project's .tasks/STATUS.md and decides what to claim, how to route it, and whom to notify. Those decisions hang on a handful of fields — most critically **Weight:** and **Notify:**. The formatting rules for those fields lived only in internal sources: the parser (projects-meta-mcp/src/lib/status-md.ts), the writer (status-md-writer.ts), and the ops runbook (.common/.wiki/concepts/agents-task-runner-ops.md).

The wiki is internal; skills ship with factory to external users. An external operator pointing the poller at their own board has no access to the wiki or the MCP source — so the on-disk task-block format had no public, copy-pasteable reference. task-format is that reference.

Scope — and why it's a separate skill

Three adjacent skills, deliberately not merged:

• delegate-task — workflow for creating a task for another project/agent via mcp__projects-meta__tasks_create. The tool emits the field format for you; the skill is the pre-flight gate + body template.
• using-tasks — policy for working an existing board (claim / switch / close / per-task files).
• task-format (this skill) — the byte-level field format the poller parses, for hand-edited STATUS.md blocks and for understanding what tasks_create produces.

A hand-edit scenario triggers none of the other two: delegate-task is about the MCP tool, using-tasks is about board mechanics, neither documents the exact header regex / Weight vocabulary / Notify line. Hence a focused reference skill.

Ground truth (sources of record)

• Header regex TASK_HEADER = /^##\s+(\S+)\s+\[([^\]]+)\]\s+—\s+(.+)$/u and all **Field:** regexes — status-md.ts.
• Canonical field order and the writer — status-md-writer.ts (formatTaskBlock).
• Claim gate: only weight === 'needs-human' is excluded at claim; capability/runtime gates — claim.ts selectClaimableTask.
• Missing-Weight behavior: the claim gate does not reject a weightless task, but the fleet router (fleet-router.js resolveBackend) finds no backend for an undefined tier, so the poller parks it to 🔵 blocked (no backend for weight_tier: unknown) and inboxes Notify. Net effect — confirmed by source, not folklore — a task without Weight does not run. The skill states this as the operative rule.
• Notify resolution + inbox write — crossProjectAgentPoller.js makeInboxWriter.

TDD record (per superpowers:writing-skills)

RED — 3 baseline subagents, no skill, asked to author a poller-claimable STATUS.md block (ordinary work ×2, critical-infra ×1). Failures: 2/3 used ### /bullet-list headers the parser cannot recognize as a task at all; 2/3 omitted **Weight:** entirely (invented risk: low, tier: L, claimable-by); 2/3 put the notification in prose instead of a **Notify:** field; 1/3 used 🟢 (done) for a ready task. The one partial success only got Weight/Notify right because it read the board and found the spec — a crib an external user lacks.

GREEN — 2 fresh subagents with the skill loaded, same scenarios. Both produced parser-valid blocks: correct ## ⚪ [slug] — header, **Field:** lines, **Weight:** + **Notify:**. The critical-infra agent correctly chose **Weight:** needs-human in canonical vocabulary (baseline had invented tier: L / auto: ❌).

REFACTOR — no new format loopholes surfaced; the skill maps every documented RED failure to a Common-mistakes row.

Decisions

• Version 0.1.0 — new skill; project-discipline Rule 3 first-version clause (matches delegate-task starting at 0.x).
• Reference skill, ~900 words — exceeds the <500 word target for frequently-loaded skills, justified: it loads only when authoring/editing a task block, and a field reference needs the full table to be useful.
• The needs-human critical-infra list mirrors delegate-task pre-flight Q0 and the ops runbook's "Critical-infra защита" — kept consistent on purpose.