Skill v1.0.1

version: "1.0.1" description: 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. enabled_tools: 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

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.