coyote/assets/skills/task-tracking/SKILL.md at main

Files

T

Dark-Alex-17 e4c5f42a25 feat(TASK-001): add rigor/surfaces declaration layer to planning skills

design-session: Quality bar round in Step 2 (rigor/surfaces proposal,
per-surface confirm/drop, other:<label> lane, autonomous fallback),
rigor+surfaces frontmatter and Quality bar section in the Step 3 PLAN
template, poc-dodge anti-pattern.
task-tracking: optional per-task surfaces key (inherits the plan's list);
rigor stays run-level only.
plan-gatekeeping: manifest category 11 (Quality bar) with
FRICTION/BLOCKING severity guidance.

2026-08-28 14:47:57 -06:00

4.3 KiB

Raw Permalink Blame History

description, enabled_tools

description	enabled_tools
File-based task tracking for plan-driven runs on any project. Defines the TASK-NNN directory schema (index.md + append-only log.md), the frontmatter lifecycle (pending/in-progress/blocked/complete), numbering, the completion protocol, and follow-up task creation. The tasks directory on disk is the durable run state - it survives context compression. Grants filesystem access for managing task files.	fs_read, fs_grep, fs_glob, fs_ls, fs_cat, fs_write, fs_patch, fs_mkdir

description

enabled_tools

File-based task tracking for plan-driven runs on any project. Defines the TASK-NNN directory schema (index.md + append-only log.md), the frontmatter lifecycle (pending/in-progress/blocked/complete), numbering, the completion protocol, and follow-up task creation. The tasks directory on disk is the durable run state - it survives context compression. Grants filesystem access for managing task files.

fs_read, fs_grep, fs_glob, fs_ls, fs_cat, fs_write, fs_patch, fs_mkdir

You are tracking implementation tasks as files. The task directory is the durable source of truth for run state — anything that lives only in chat history is lost to context compression. Keep it current at every state change, not in batches.

Layout

<plans_dir>/
  PLAN-<slug>.md                  # the plan (see design-session / plan-authoring)
  tasks/
    TASK-001-<slug>/
      index.md                    # current state: frontmatter + What/Steps/Acceptance criteria
      log.md                      # append-only audit trail
    TASK-002-<slug>/
      ...

index.md schema

---
title: <short imperative title>
status: pending        # pending | in-progress | blocked | complete
type: feature          # feature | chore | followup
points: 1.0            # engineer-days; ~1.0 per the sizing rule
plan: PLAN-<slug>.md
blocked_by: []         # TASK ids that must be complete first
created: YYYY-MM-DD
surfaces: []           # this task's surfaces; omitted = inherit the plan's list
---

## What

One paragraph: what this task produces, named concretely (files, symbols, behaviors).

## Steps

- [ ] Concrete step — name the file, function, or migration
- [ ] ...

## Acceptance criteria

- [ ] Observable behavior, measurable ("returns 429 after 3 failed attempts")
- [ ] ...

Status lives in frontmatter — there are no lifecycle directories. status: complete plus all boxes checked IS done.

surfaces come from the plan's ## Quality bar; rigor is run-level only — there is no per-task rigor.

log.md conventions

Append-only. Each entry is an H2: ## YYYY-MM-DD — <short label> (created, started, implemented, diverged, completed, ...). Body is 1-3 sentences of prose; structured data lives in markdown links (branch URLs, commit SHAs, PR links). Never rewrite an old entry — add a new one.

Numbering

Scan tasks/TASK-* for the highest NNN and increment (zero-padded to 3). This assumes a single writer per plans directory; if multiple agents or people share one, serialize task creation.

Lifecycle protocol

Transition	Do
Create	`fs_mkdir` the dir; write `index.md` (status: pending) + `log.md` with a `created` entry
Claim	frontmatter `status: in-progress`; log `started` (note the branch + base SHA)
Blocked	`status: blocked`; log why and what unblocks it
Complete	Check off every Step and Acceptance criterion (verified, not aspirational); log `completed` with commit SHAs AND any follow-ups reported by the implementer, VERBATIM; set `status: complete`

Never mark a criterion checked without evidence. Never batch state changes — update at the moment of transition.

Follow-up tasks

When implementation surfaces manual/out-of-scope actions (secrets to create, cloud roles to provision, console steps, cross-repo changes): create a task per item (group small related ones) with type: followup, status: pending, the WHAT/WHERE/WHY/WHEN in its What section, and a note of which TASK surfaced it. Follow-ups are deliverables to hand to the user — never implement them in the current run.

Consistency checks (run at the end of a run)

Every task dir has both index.md and log.md.
Every blocked_by reference resolves to an existing task.
No task is complete with unchecked Steps/Acceptance criteria.
Every complete task's log has a completed entry with commit references.
The PLAN's breakdown table rows all map to task dirs (and vice versa).

Anti-patterns

Run state that exists only in chat — session ids, decisions, and follow-ups belong in task files.
status: complete with unchecked boxes, or checked boxes without evidence.
Rewriting log history instead of appending.
Hand-picking a task number without scanning (collisions).
Follow-ups mentioned in a summary but never materialized as task files.

4.3 KiB Raw Permalink Blame History