j4flmao/agent-skills/agent-task-checklist

Agent Task Checklist

Purpose

Make long agent tasks observable and resumable. A checklist file (task.md, or the host's built-in task-list tool when one exists) lists atomic steps and their state, and is updated the moment a step starts or finishes — so a user, a reviewer or a resumed session can tell exactly what is done, in progress and left.

Agent Protocol

Trigger

"task.md", "checklist", "track progress", "break it down", "what's left", long tasks (>5 steps or multiple sessions).

Input Context

• The approved plan or the user's request.
• Whether the host provides a native task/plan tool (prefer it over a file).

Output Artifact

task.md at the repo root or scratch location agreed with the user (never committed unless asked).

Response Format

# Task: {title}
 
## Steps
-[x] Read existing auth middleware and tests
-[/] Add refresh-token rotation to `src/auth/tokens.ts`
-[ ] Update `tests/auth/tokens.test.ts` for rotation and reuse detection
-[ ] Run `npm test -- auth` and fix failures
-[ ] Update CHANGELOG
 
## Blocked / Questions
-{item} — waiting on {who/what}
 
## Notes
-{decision or discovery worth keeping}

State Notation

[/] is a convention of this workflow, not standard Markdown task-list syntax; GitHub renders only [ ] and [x] as checkboxes.

Granularity Rules

• One step = one verifiable outcome, typically minutes, not hours.
• Start each step with a verb and name the file or command: "Add X to path", "Run cmd".
• Split any step that touches more than one component or has its own verification.
• Put verification as its own step ("Run tests", "Check build") so it cannot be skipped implicitly.

Update Discipline

1. Write the full list before starting work.
2. Mark [/] when beginning a step; [x] immediately when it is verified.
3. When new work is discovered, insert it in order — do not silently expand an existing step.
4. When the plan changes, rewrite the list so it never shows abandoned steps as pending.
5. On interruption or handoff, the checklist plus Notes must be enough to resume.

Anti-Patterns

Checklist

• [ ] All steps written before execution
• [ ] Exactly one in-progress item
• [ ] Verification steps explicit
• [ ] Blockers recorded with owner
• [ ] Final state shows no stale [ ] items