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:

Run pwd.
Read repository instructions (for example AGENTS.md).
Read agent-progress.txt if present.
Read tasks.json (or repo-specific ledger file) if present.
Read recent history, for example git log --oneline --decorate -10.
Run repo bootstrap only if required (for example ./init.sh).
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)

Restate scope and declared validation command.
Set task to in_progress.
Gather only task-specific context.
Implement the smallest coherent change.
Run declared validation.
Record validation output in the ledger.
Run independent review gate.
Address blockers and run one bounded re-review.
Run independent QA gate.
Address QA blockers or record QA pass.
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:

Codex /review when available
independent review subagent
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:

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

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

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.