AI工作流

Dependencies and Labels

tbd dep add proj-b3m9 proj-a7k2        # b3m9 depends on a7k2
tbd blocked                            # Show blocked beads
tbd label add proj-a7k2 urgent backend
tbd label remove proj-a7k2 urgent
tbd label list                         # All labels in use
tbd search "authentication"            # Search beads

Installation and Setup

Requirements: - Node.js 20+ - Git 2.42+ (for orphan worktree support)

npm install -g get-tbd@latest

Setup

```bash

Team Setup

tbd is designed for teams where one person sets up the project and others join later.

First contributor:

npm install -g get-tbd@latest
tbd setup --auto --prefix=proj   # Short alphabetic prefix for issue IDs
git add .tbd/ .claude/ && git commit -m "Initialize tbd"
git push

Joining contributors:

git clone <repo>
npm install -g get-tbd@latest
tbd setup --auto                    # No --prefix needed—reads existing config

Quick Start

[!TIP] If running on your own machine, install the tbd CLI yourself: npm install -g get-tbd@latest Then tell your agent: “run tbd for instructions to set up this project” If running on a fresh cloud instance (like Claude Code Cloud), tell the agent: “install tbd (npm install -g get-tbd@latest) and run tbd prime for instructions to set up this project”

That’s it. Running tbd prime gives agents full workflow context on how to use tbd and how to help you. It will then bootstrap a SKILL.md into your project by running tbd setup --auto (which will add a .tbd directory and add itself to your .claude skills and hooks). And then it will use shortcuts to welcome you and get you started.

Running tbd with no arguments shows help with a prominent reminder for agents to run tbd prime.

You can then always ask questions like: “what can I do with tbd?”

How to Use `tbd`

You talk to your agent in natural language. The agent translates your requests into tbd commands.

The tbd CLI blends task tracking and context injection. Some tbd commands do things, like create or update beads, and some help the agent get status or context or knowledge and know what to do next:

Under the hood, your agent runs these tbd commands automatically. You just talk naturally.

Shortcuts, Guidelines, and Templates

tbd bundles three types of documentation your agent can invoke on demand:

```bash

Guidelines—coding rules and best practices

tbd guidelines --list # List all guidelines tbd guidelines typescript-rules # Get TypeScript rules

Can I add my own guidelines?

Yes. tbd comes with 20+ bundled guidelines, but you can add your own team’s docs from any URL:

tbd guidelines --add=<url> --name=my-team-rules
tbd shortcut --add=<url> --name=my-team-workflow
tbd template --add=<url> --name=my-team-template

You can also configure which docs are available in .tbd/config.yml. I put my favorite guidelines and shortcuts in by default, but you’re not locked into using them.

Joining an existing tbd project (no prefix needed—reads existing config)

tbd setup --auto

Claude Code Integration

tbd setup --auto configures SessionStart hooks that run at the beginning of each Claude Code session:

• tbd prime—injects workflow context so the agent knows how to use tbd
• ensure-gh-cli.sh—installs the GitHub CLI (gh) if not already available

GitHub authentication: For gh to work, set these environment variables before starting your agent session:

GH_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GH_PROMPT_DISABLED=1

Create a Personal Access Token (fine-grained recommended) with Contents and Pull requests read/write permissions. For Claude Code Cloud, set these in your project’s environment variables. For local CLI usage, add them to your shell profile (~/.zshrc or ~/.bashrc). See the setup-github-cli shortcut for details.

To disable automatic gh installation, pass --no-gh-cli during setup or set use_gh_cli: false in .tbd/config.yml under settings:.

Shortcuts—workflow instructions

tbd shortcut --list # List all shortcuts tbd shortcut new-plan-spec # Get the plan spec workflow

How does `tbd` compare to Beads?

tbd was inspired by Beads by Steve Yegge, and I’m grateful for the idea—it genuinely changed how I work with agents. If you’re not familiar with Beads, the core insight is that git-native issue tracking raises an agent’s capacity for structured work from ~5-10 to-do items to hundreds of beads.

tbd builds on that foundation with a simpler architecture: plain Markdown files instead of JSONL, no daemon, no SQLite, no 4-way sync. This avoids the edge cases I ran into with network filesystems (Claude Code Cloud), merge conflicts, and multi-agent workflows.

If you already use Beads, tbd setup --from-beads migrates you to tbd. This imports and sets up your .tbd directory and preserves the IDs of all issues.

Scope: tbd focuses on the durable layer—issue tracking, specs, and knowledge that persist across sessions and live in git. It does not aim to solve real-time multi-agent coordination, which is a separate problem requiring sub-second messaging and atomic claims. Tools like Agent Mail and Gas Town address that space and are complementary to tbd—you could layer real-time coordination on top of tbd’s durable tracking. See the design doc for a detailed comparison.

FAQ