task-ledger

Manages task and inbox file formats, ID reservation, and ledger validation for docs/tasks_manager.

Updated Apr 6, 2026
One-click install
npx skills add https://github.com/toderian/project_template --skill task-ledger-toderian
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: task-ledger
Source: https://github.com/toderian/project_template/tree/main/plugins/agents-tasks/skills/task-ledger
Command: npx skills add https://github.com/toderian/project_template --skill task-ledger-toderian

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Keeping a Markdown-based task system consistent is hard: task IDs collide between parallel agents, ledgers drift out of sync with task files, and malformed metadata slips into commits. This Skill defines the canonical task and inbox file formats and provides the tooling that reserves IDs atomically, regenerates derived ledgers, and validates the whole docs/tasks_manager/ tree. ## Core Features & Use Cases - Atomic ID reservation: at reserve inbox <slug> and at reserve task <PREFIX> <TYPE> <slug> create placeholder files under a lock so concurrent agents never claim the same ID. - Ledger sync and validation: at ledger sync regenerates _active.md, _done.md, and generated area pages; at ledger check fails on duplicate IDs, malformed metadata, status-directory mismatches, and stale generated files. - Execution support: at task brief <TASK-ID> --phase N writes a self-contained implementer brief per phase, and at task run-state init|check manages the resume map for phased execution. - Use Case: After triaging an inbox idea into task AUTH-001, you implement it phase by phase, then run at ledger check to confirm every task file, roadmap reference, and generated ledger is consistent before committing. ## Quick Start Ask the agent to reserve a new task ID for the auth area and validate the task ledger with at ledger check after editing any task file.

Frequently Asked Questions about task-ledger

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a new task file without ID collisions?

Run `at reserve task <PREFIX> <TYPE> <slug>`, which atomically creates a placeholder file under a lock and prints its path. The prefix must be registered in docs/tasks_manager/_areas.md and the type must be F, D, C, or R. Fill the placeholder immediately with the task template.

How do I validate task files and ledgers after editing?

Run `at ledger check`, a read-only validator that fails on duplicate or ambiguous IDs, malformed required metadata, status-directory mismatches, unregistered areas or prefixes, bad roadmap references, and stale generated files. Follow with `at repos-check` when edits touched Repos or Autonomy metadata.

What is the difference between the inbox and task layers?

The inbox holds raw, low-commitment ideas as I-NNN files with minimal fields for fast capture. Triage promotes good ideas into full task files with typed IDs, phases, acceptance criteria, and tests, recording Source ref: I-NNN for traceability.

Does the ledger tooling require third-party Python packages?

No. All scripts use only the Python standard library plus bash, so they run before any package installation. The shared mdtables.py module handles escape-aware Markdown table parsing for both the ledger generator and the repo config validator.

What happens when a task file grows too large?

The validator warns when a task exceeds 400 lines or its Execution log section exceeds 200 lines. Run `at ledger rotate-log <TASK-ID>` to move the log body into docs/tasks_manager/_logs/<TASK-ID>.md, leaving a short pointer in the task file.

When should I use at task brief and run-state?

Use them when executing a multi-phase task with an implementer subagent. `at task brief <TASK-ID> --phase N` writes a self-contained brief for one phase, and `at task run-state init|check` creates and validates the resume map tracking each phase's status and commit.