tbd

Imported from jlevy/tbd (skills/tbd/SKILL.md). Install upstream with npx skills add jlevy/tbd --skill tbd. Copyright stays with the author.

tbd helps humans and agents ship code with greater speed, quality, and discipline.

1. Beads: Git-native issue tracking (tasks, bugs, features). Never lose work across sessions. Drop-in replacement for bd.
2. Spec-Driven Workflows: Plan features → break into beads → implement systematically.
3. Knowledge Injection: 40+ engineering guidelines (TypeScript, Python, Rust, TDD, testing, Convex, monorepos) available on demand.
4. Shortcuts: Reusable instruction templates for common workflows (code review, commits, PRs, cleanup, handoffs).

Installation

npm install -g get-tbd@latest      # Install or upgrade the CLI (same command for both)
tbd setup --auto --prefix=<name>   # Fresh project (--prefix is REQUIRED: 2-8 alphabetic chars recommended. ALWAYS ASK THE USER FOR THE PREFIX; do not guess it)
tbd setup --auto                   # Existing tbd project — also the upgrade step (applies any format migration; commit the diff it reports)
tbd setup --from-beads             # Migration from .beads/ if `bd` has been used

If tbd refuses with “This repository requires a newer version of tbd”, run the two install/upgrade commands above.

Routine Commands

tbd --help    # Command reference
tbd status    # Status
tbd doctor    # If there are problems

tbd setup --auto   # Run any time to refresh setup
tbd prime      # Restore full context on tbd after compaction
tbd web --open # Open the live, read-only bead viewer

CRITICAL: You Operate tbd, the User Doesn’t

You are the tbd operator: Users talk naturally; you translate their requests to tbd actions. DO NOT tell users to run tbd commands. That’s your job.

• WRONG: “Run tbd create to track this bug”

• RIGHT: (you run tbd create yourself and tell the user it’s tracked)

Live browser requests: When the user asks to see, show, open, or view beads in a browser, start tbd web --open yourself with the agent platform’s long-running process facility. Do not merely print the command. If the requested project is outside your current working directory, start tbd web <path> --open; the path may be its repository root or any subdirectory. Wait for the startup descriptor, give the user its loopback URL, and leave the process running until they ask you to stop it or the session environment requires cleanup.

The page is a live, read-only viewer, not an editor. You remain the tbd operator: make every requested bead change with ordinary tbd commands, and the running page observes the resulting local state automatically. Browser filters change only the presentation. Starting the viewer never justifies an implicit fetch, merge, or push; run tbd sync only when the user asks to exchange remote bead state, after which its local result also appears automatically.

Welcoming a user: When users ask “what is tbd?” or want help → run tbd shortcut welcome-user

User Request → Agent Action

Loading guidelines for engineering work: three layers, in this order.

1. Always, before writing or reviewing code, load the engineering core:

   tbd guidelines general-eng-agent-principles

2. The language documents that match the changed surface. Do not load an entire language group by default.

3. Cross-cutting topics, by what the change actually touches—errors, tests and goldens, code and comment policy, dependencies, published interfaces, commits, review, CI and gates, filesystem work, and releases. These are not always-load: read the group’s note in tbd guidelines --list and pull the ones that apply.

Load several selected documents in one call; guidelines, shortcut, template, and docs show all take several names.

Run tbd guidelines --list to see all available guidelines.

Where beads live: on the dedicated tbd-sync branch, not your working branch. Bead changes never appear in your feature branch’s commits or its PR diff. That is the design, not lost work: don’t hunt for them there, and don’t claim “everything is on this PR” about bead state.

Let tbd own that branch. tbd sync maintains it and tbd doctor --fix repairs it. Use tbd commands rather than raw git for anything touching tbd-sync; hand checkouts, merges, and pushes are how bead state gets tangled.

Note: .tbd/workspaces/ is the exception: never gitignore it; the outbox must be committed to your working branch. See tbd guidelines tbd-sync-troubleshooting for details.

CRITICAL: Session Closing Protocol

Before saying “done”, you MUST complete this checklist:

[ ] 1. git add + git commit
[ ] 2. git push
[ ] 3. gh pr checks <PR> --watch 2>&1 (IMPORTANT: WAIT for final summary, do NOT tell user it is done until you confirm it passes CI!)
[ ] 4. tbd close <id1> <id2> ... --reason "..." — one bulk call per group of beads sharing a reason (never a per-ID loop)
[ ] 5. tbd sync
[ ] 6. CONFIRM CI passed (if failed: fix, run tests, re-push, restart from step 3)

Work is not done until pushed, CI passes, and tbd is synced.

Remote/proxied session where GitHub seems blocked? If the environment has egress, gh works through a scoped NO_PROXY bypass. Three facts decide most of these:

• The git remote may sit behind a ref-scoped credential broker: pushes to refs/heads/* succeed, pushes to refs/tags/* fail with HTTP 403. Create the tag on the direct channel instead: gh api repos/OWNER/REPO/git/refs -f ref=refs/tags/vX.Y.Z -f sha=SHA.
• git push --dry-run passes for tags the broker then refuses at receive-pack, so a clean dry run proves nothing.
• A GitHub-host 403 carrying no x-github-request-id header is proxy-manufactured, not an organization egress denial.

Run tbd shortcut setup-github-cli and follow “Proxied Remote Sessions” before concluding gh is unavailable.

Bead Tracking Rules

• Track all task work not done immediately as beads (discovered work, TODOs, multi-session work)
• When in doubt, create a bead
• Check tbd ready when not given specific directions
• Always close/update beads and run tbd sync at session end

Commands

Finding Work

Creating & Updating

IMPORTANT: if you are about to shell-loop or pipe around tbd, stop; the bulk or filter form exists. show, close, reopen, and update take multiple IDs; guidelines/shortcut/template/docs show take multiple names; dep add takes multiple blockers; list/search/show have --limit/--count/--max-lines. NEVER for id in …; do tbd close $id; done (one call gives one lock, one summary, --json, and --ignore-missing), NEVER tbd show X | head (use --max-lines), NEVER tbd list | grep <id> (use tbd search <partial-id>). A bulk call shares one reason (and, for update, one set of field changes), so group the beads that share the same mutation and make one call per group.

Dependencies & Sync

Labels & Search

External Trackers (Linear)

Setting Linear up at all — including “add my key” — is tbd shortcut setup-linear. Run it rather than improvising; it detects which case applies and walks the user through only that case.

The mental model it encodes: config is shared, credentials are personal. The integrations block in .tbd/config.yml (team, project, policy) is committed, so a teammate who clones already has it; LINEAR_API_KEY lives in the environment or a gitignored .env and is never committed. So a user joining a repo whose team already syncs needs only a key—never a config edit, and never integration sync --push (their links arrived with the clone; after a dry-run preview, plain tbd sync first pulls the team’s current bead state and then reconciles Linear). Run tbd integration status --offline first in every case. Full details: the External Tracker Integrations section of tbd docs. Bulk runs over 20 creates / 40 updates refuse without --yes. Never echo credentials into output or commits. --pull never replays or performs provider writes; deferred claims and conflict notices remain journaled until the next full sync. Link/inbound creation refuse a remote tbd://bead/… claim unless --force is explicit and the old claim was verified stale. Configured project scopes both creates and automatic inbound scans; an explicit --external import bypasses that scan scope. Assignees sync only through user_map: beads retain aliases (including on initial import), runtime email/UUID targets never persist, unmapped local aliases are reported, and an unmapped provider identity leaves the local field and prior bridge base unchanged with a safe warning, preserving local divergence until mapping recovers. Linear sub-issues import parent-first and never flatten; max_nesting limits only new outbound creation. Comments are append-only and paginated; edits, deletions, reactions, and thread shape are not synchronized. Linear descriptions carry a tbd-owned ⟦tbd⟧ … ⟦/tbd⟧ region. Human prose outside it is preserved; legacy HTML-comment delimiters are upgraded on the next outbound sync. Never hand-edit the managed region—change the bead and sync instead.

Direction flags mean the same thing everywhere in tbd: bare = both directions, --push = outbound only, --pull = inbound only, --status = report only. Plain tbd sync at session end covers docs, issues, AND enabled trackers; surfaces run independently, so one failing (an expired key, a down remote) never stops the others, and every failure is reported at the end. Narrow with --docs, --issues, or --integrations for a single surface.

Documentation

Quick Reference

• Priority: P0=critical, P1=high, P2=medium (default), P3=low, P4=backlog
• Types: issues default to task; run tbd create --help for the valid types
• Status: open, in_progress, closed
• JSON output: Add --json to any command