td: Instructions file for Claude Code

CLAUDE.md

Working with td

td keeps task context durable across sessions. In a new context, run td usage --new-session -q to see current work.

Use your judgment about how much tracking a task needs. For substantive work: td start <id>, record progress with td log, hand off with td handoff <id>, then td review <id>.

Closing needs a review. Say who did it (default trusted mode; delegated/strict allow only the first):

• independent session: td approve <id> --reason "..."
• a sub-agent: td approve <id> --reviewed-by "<who>"
• you: td approve <id> --self-review --reason "..."

Prefer a reviewer with its own TD_CONTEXT_ID; never name one who did not review.

Run td usage or td <command> --help.

Review Model (Trusted Review)

Work still needs a review before it closes. What changed is that td now asks you to say who reviewed it, rather than assuming the reviewing agent and the recording session are the same thing.

In the default trusted mode:

• An independent session reviews and closes: td approve <id> --reason "..."
• A reviewer attests without closing and anyone closes after: td approve <id> --record-only --reason "...", then td approve <id> --reason "..."
• You implemented it and a sub-agent reviewed it: td approve <id> --reviewed-by "<who>"
• You implemented it and reviewed it yourself: td approve <id> --self-review --reason "..."

Prefer the first two. When a reviewing sub-agent has its own TD_CONTEXT_ID its independence is mechanically verified rather than asserted — see docs/multi-agent-sessions.md.

--reviewed-by is an attestation td cannot verify. It exists so an orchestrator recording a sub-agent's review writes a true record instead of claiming a self-review it did not perform. Do not use it to launder an unreviewed change: naming a reviewer who did not review is worse than --self-review, because it reads as independent in the audit trail. Do not create a throwaway session to make a review appear independent either.