anthropic-task-ledger-workflow

name	anthropic-task-ledger-workflow
description	Use when delivery should be ledger-driven with resumable state: task files like tasks.json/agent-progress.txt, exactly one active task, explicit validation evidence, one commit per implementable task, an independent code-review gate before QA, and an independent QA pass before completion. Also use for review-only or QA-only passes tied to a ledger task.

Anthropic Task Ledger Workflow

Overview

Use this skill when you want durable, resumable delivery instead of ad hoc edits.

Drive work from a machine-readable task ledger, keep one task in progress, validate every deliverable, require an independent review gate before QA, and keep evidence so another session can resume safely.

Trigger Checklist

Use this skill when one or more are true:

• the repo uses tasks.json, agent-progress.txt, or a similar ledger
• the user asks for one task per commit with explicit validation
• work must survive restarts, handoffs, or long-running delivery
• the request is an independent review pass or QA pass for a named task
• public behavior/docs must ship in lockstep with implementation

Do not use this skill for throwaway edits or brainstorming without implementation.

Progressive Disclosure

Keep this file focused on workflow and load details on demand:

• use references/session-start-template.md for startup sequencing
• use references/task-ledger-template.json for ledger shape
• use references/review-qa-checklists.md for detailed review/QA prompts
• use references/gotchas.md when a known failure mode appears

Session Start

Before implementation, run this sequence:

1. Run pwd.
2. Read repository instructions (for example AGENTS.md).
3. Read agent-progress.txt if present.
4. Read tasks.json (or repo-specific ledger file) if present.
5. Read recent history, for example git log --oneline --decorate -10.
6. Run repo bootstrap only if required (for example ./init.sh).
7. Confirm task ownership and status: exactly one in_progress task for implementation work.

If there is no active task, create or reopen one before coding.

Availability And Setup

If this skill is unavailable in the current session:

• follow the same workflow manually
• record the fallback in ledger notes
• do not silently skip review/QA gates

Optional setup for repos that use this workflow repeatedly:

• keep a small config file (for example .codex/task-ledger-config.json) with ledger paths, default validation command, and gate defaults
• store long-lived workflow memory outside the skill folder (for example ${CODEX_HOME:-$HOME/.codex}/memories/task-ledger-workflow/) so upgrades do not erase history
• keep all repo-specific behavior in that config, not in this generic skill

Optional On-Demand Guardrails

If your environment supports session hooks, enable them only when needed:

• block destructive shell operations unless explicitly required by the active task
• block edits outside task scope during review-only or QA-only work

Keep these guardrails opt-in and session-scoped so they do not burden normal coding sessions.

Ledger Rules

Use a machine-readable ledger. Apply these rules:

• only one task may be in_progress for implementation work
• each implementable task maps to one commit
• each task must define validation before coding
• capture validation results in structured fields
• require independent review before QA whenever possible
• require independent QA before closure whenever possible
• keep files_expected, dependencies, and notes current
• record exceptions explicitly (waivers, accepted risks, unavailable subagents)

Recommended statuses:

• pending
• in_progress
• implemented
• review_passed
• qa_passed
• done

Recommended task types:

• implement
• review
• qa
• docs

Delivery Modes

Implement Task (default)

1. Restate scope and declared validation command.
2. Set task to in_progress.
3. Gather only task-specific context.
4. Implement the smallest coherent change.
5. Run declared validation.
6. Record validation output in the ledger.
7. Run independent review gate.
8. Address blockers and run one bounded re-review.
9. Run independent QA gate.
10. Address QA blockers or record QA pass.
11. Commit only scoped files.

Review-Only Task

Use when the user asks for independent code review without new implementation.

• do not create unrelated implementation commits
• record findings with severity and file references
• set status to review_passed only when no blockers remain or accepted-risk disposition is documented

QA-Only Task

Use when the user asks for independent QA verification of an existing diff.

• confirm review gate state first
• verify validation evidence and scope hygiene
• set status to qa_passed only when blockers are cleared or explicitly waived

Review Gate

Run an independent code review before QA whenever possible.

Preferred order:

1. Codex /review when available
2. independent review subagent
3. clearly separated self-review fallback (must be recorded)

Review must verify:

• diff matches task scope
• implementation is technically sound
• validation command ran and passed
• no unexpected files changed
• ledger state and evidence are accurate
• public docs were updated when public interfaces changed

Bounded loop rules:

• allow one implementation pass and one re-review after initial review
• if disagreement remains, record common-ground disposition per finding: fixed, accepted_risk, or declined_with_rationale
• only unresolved blocking defects stop progression to QA

If independent review is impossible, require an explicit waiver before QA:

• why independent review was unavailable
• who accepted the exception
• why moving forward is still safe

QA Rules

Run an independent QA pass whenever possible.

QA must verify:

• review gate completed and disputed findings are resolved or documented
• diff matches task scope
• declared validation ran successfully
• no unexpected file changes
• ledger reflects actual state
• public docs match current behavior

If independent QA is impossible, record the exception with the same waiver rigor as review.

Commit Rules

Use one commit per implementable task.

Message format:

<task-id>: <short description>

Examples:

T014: add html report output
T015: document reusable workflow inputs
T016: finalize ledger after release handoff

For review-only and QA-only tasks, commit is typically n/a unless the task explicitly includes documentation updates.

Documentation Rules

When public behavior changes, update docs in the same delivery sequence:

• installation and setup steps
• CLI options and workflow inputs/outputs
• release tags and distribution artifacts
• report formats and troubleshooting notes

Keep examples aligned with shipped behavior.

Subagent Usage

Prefer subagents for bounded, independent gates:

• independent review
• independent QA
• narrow context gathering in parallel

Avoid delegating critical-path implementation that immediately blocks your next action.

Gotchas

Common failure modes and mitigations live in references/gotchas.md.

If one appears, record:

• symptom
• mitigation used
• whether the template or instructions should be updated

Finalization

Before ending the session:

1. Ensure active task has validation evidence and final status.
2. Ensure review/QA outcomes and waiver decisions are recorded.
3. Leave repo in resumable state.
4. Record key follow-up context in agent-progress.txt.
5. Confirm ledger consistency for the next session.

If the project uses a final ledger task, complete it before considering delivery finished.