docket — a to-do queue for your skills

You build a repo full of skills. The docket is how work gets queued across them: a passive store of agent-actionable items, each naming the subject it acts on and the skill that runs it, with an append-only log so a session that starts with no memory of yesterday can pick up where the last one stopped.

• Zero dependencies. One stdlib Python file (3.9+). No packages, no network, no services.
• Nothing runs itself. Something external invokes the agent — a loop, a cron, or you.
• Two yeses, both human. An agent proposes work and drafts output; a person approves the work and accepts the draft. That is the whole safety model.

Install

Copy this directory into your repo as a skill, then initialise the store:

cp -r docket-skill /path/to/your-repo/.claude/skills/docket
cd /path/to/your-repo
python3 .claude/skills/docket/scripts/docket.py init

init creates docket/items/ and docket/config.json, seeding the stage vocabulary from the skills already in .claude/skills/. Edit the ranks, set owner_names, and — if your subjects are directories — set subject_root so the tool refuses items pointing at work that does not exist.

An alias makes the rest readable:

alias docket='python3 .claude/skills/docket/scripts/docket.py'

Five minutes end to end

docket add login-rework --stage write-spec \
  --action "Draft the spec for the new login screen into work/login-rework/SPEC.md" \
  --name "Login spec"

docket next --claim              # the agent takes one item; exit 2 = docket clear
docket log login-rework/001 "Read the existing flow." --next "Write the SSO section."
docket stage login-rework/001 --path work/login-rework/SPEC.md
docket accept login-rework/001 --note "Reads right — go ahead and file the tickets."
docket done login-rework/001 --resolution "Spec written, tickets filed."

What is in here

• SKILL.md — the skill itself: the agent loop, the human walk, the non-negotiable rules.
• scripts/docket.py — the whole tool. Validates and refuses; never ranks, never chooses.
• reference/data-contract.md — every field, every state, and the two rules with teeth.
• reference/designing-stages.md — mapping your skills to stages, and ranking them so that finishing beats starting.
• reference/walk.md — the human review pass, and how to run the loop unattended afterwards.

The design in one paragraph

The tool is deliberately dumb: it validates the data contract and refuses writes that break it, and it does nothing else. It will not rank by age, infer priority from state, repair a broken item, or decide what matters. All judgement lives in the skill that drives it and in the person who walks the board — which is what makes the store readable by hand, portable between agents, and safe to leave running.

License

MIT — see LICENSE.