vitya
a71ed9bf07
Public reference for the on-disk .tasks/STATUS.md block format the autonomous poller parses: header regex, status emoji, and the **Weight:** / **Notify:** / **Requirements:** fields. Ships with factory where the internal wiki and MCP source can't reach. Distinct from delegate-task (MCP-tool delegation) and using-tasks (board mechanics). Authored via superpowers:writing-skills TDD: - RED: 3 baseline subagents w/o skill — 2/3 used ###/bullet headers the parser cannot recognize as a task, 2/3 omitted **Weight:** (invented risk/tier/ claimable-by), 2/3 put notify in prose, 1/3 used 🟢 for a ready task. - GREEN: 2 fresh subagents w/ skill — both parser-valid, incl. correct **Weight:** needs-human for the critical-infra scenario. - REFACTOR: no new format loopholes. Ground truth verified vs live source (status-md.ts parser, claim.ts gate, fleet-router.js routing): missing Weight finds no backend tier -> poller parks to blocked, so Weight is operatively required for pickup. Closes [create-task-format-for-poller-skill]. Install to ~/.claude/skills + hermes mapping deferred as follow-up. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
46 lines
4.1 KiB
Markdown
46 lines
4.1 KiB
Markdown
---
|
||
title: task-format skill — design
|
||
type: concept
|
||
updated: 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.
|