diff --git a/.agents/skills/tbd/SKILL.md b/.agents/skills/tbd/SKILL.md index e4cf32096..2fecf4581 100644 --- a/.agents/skills/tbd/SKILL.md +++ b/.agents/skills/tbd/SKILL.md @@ -12,22 +12,34 @@ Run 'tbd setup' to update. **`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 +1. **Beads**: Git-native issue tracking for tasks, bugs, and features, shared across + sessions and machines. +2. **Spec-Driven Workflows**: Plan features, break them into beads, and implement them 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). +3. **Knowledge Injection**: Engineering guidelines for languages, testing, architecture, + and other topics, loaded on demand. +4. **Shortcuts**: Reusable instructions for code review, commits, PRs, cleanup, and + handoffs. + +Use the capabilities the user wants; they can adopt beads alone or choose individual +guidelines and workflows. +The bundled docs are customizable defaults. +Load relevant guidelines as needed and preserve the user’s task-specific instructions. ## Installation -**For a new project, and again after every tbd upgrade, run `tbd shortcut setup-tbd` and -follow it.** It installs or upgrades the CLI, runs setup, and asks the user about any -unanswered policy grants. -The setup commands it runs: +Check `tbd --version` first. +Install the CLI if missing, or install/upgrade it when the user explicitly requests it. +Then run `tbd prime` in the project’s Git repository. +For a fresh project, ask the user for the issue-ID prefix and run +`tbd setup --auto --prefix=`; never guess the prefix. + +**Once the project is initialized, run `tbd shortcut setup-tbd` and follow it.** The +shortcut is unavailable before initialization. +It reviews setup and unanswered policy grants; run it again after every tbd upgrade. +With an existing working CLI, ask before upgrading unless the user already requested the +upgrade or tbd requires a newer version. +The installation and setup commands are: ```bash npm install -g get-tbd@latest # Install or upgrade the CLI (same command for both) @@ -138,7 +150,7 @@ or want help → run `tbd shortcut welcome-user` | “Update the guidelines to the latest” | `tbd docs update`; on conflicts ask the user, then `--merge` or `--keep-ours` | | “I deleted a forked doc file” | `tbd docs status` shows it `missing`; restore with `tbd docs fork --force` or finalize with `tbd docs unfork ` | | **Setup** | | -| “Set up tbd” / *(after upgrading tbd)* | `tbd shortcut setup-tbd` | +| “Set up tbd” / *(after upgrading tbd)* | Follow Installation above; initialize a fresh project before `tbd shortcut setup-tbd` | | **External Trackers** | | | “Set up Linear” / “Connect this repo to Linear” | `tbd shortcut setup-linear` | | “My Linear sync isn’t working” / “Add my Linear key” | `tbd shortcut setup-linear` | diff --git a/.claude/skills/tbd/SKILL.md b/.claude/skills/tbd/SKILL.md index e4cf32096..2fecf4581 100644 --- a/.claude/skills/tbd/SKILL.md +++ b/.claude/skills/tbd/SKILL.md @@ -12,22 +12,34 @@ Run 'tbd setup' to update. **`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 +1. **Beads**: Git-native issue tracking for tasks, bugs, and features, shared across + sessions and machines. +2. **Spec-Driven Workflows**: Plan features, break them into beads, and implement them 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). +3. **Knowledge Injection**: Engineering guidelines for languages, testing, architecture, + and other topics, loaded on demand. +4. **Shortcuts**: Reusable instructions for code review, commits, PRs, cleanup, and + handoffs. + +Use the capabilities the user wants; they can adopt beads alone or choose individual +guidelines and workflows. +The bundled docs are customizable defaults. +Load relevant guidelines as needed and preserve the user’s task-specific instructions. ## Installation -**For a new project, and again after every tbd upgrade, run `tbd shortcut setup-tbd` and -follow it.** It installs or upgrades the CLI, runs setup, and asks the user about any -unanswered policy grants. -The setup commands it runs: +Check `tbd --version` first. +Install the CLI if missing, or install/upgrade it when the user explicitly requests it. +Then run `tbd prime` in the project’s Git repository. +For a fresh project, ask the user for the issue-ID prefix and run +`tbd setup --auto --prefix=`; never guess the prefix. + +**Once the project is initialized, run `tbd shortcut setup-tbd` and follow it.** The +shortcut is unavailable before initialization. +It reviews setup and unanswered policy grants; run it again after every tbd upgrade. +With an existing working CLI, ask before upgrading unless the user already requested the +upgrade or tbd requires a newer version. +The installation and setup commands are: ```bash npm install -g get-tbd@latest # Install or upgrade the CLI (same command for both) @@ -138,7 +150,7 @@ or want help → run `tbd shortcut welcome-user` | “Update the guidelines to the latest” | `tbd docs update`; on conflicts ask the user, then `--merge` or `--keep-ours` | | “I deleted a forked doc file” | `tbd docs status` shows it `missing`; restore with `tbd docs fork --force` or finalize with `tbd docs unfork ` | | **Setup** | | -| “Set up tbd” / *(after upgrading tbd)* | `tbd shortcut setup-tbd` | +| “Set up tbd” / *(after upgrading tbd)* | Follow Installation above; initialize a fresh project before `tbd shortcut setup-tbd` | | **External Trackers** | | | “Set up Linear” / “Connect this repo to Linear” | `tbd shortcut setup-linear` | | “My Linear sync isn’t working” / “Add my Linear key” | `tbd shortcut setup-linear` | diff --git a/README.md b/README.md index 6acdb7bbc..6b6816f32 100644 --- a/README.md +++ b/README.md @@ -7,445 +7,376 @@ **tbd is a skill and CLI that upgrades coding quality, task tracking, and workflows for any coding agent.** -It gives agents git-native task tracking for longer unattended work (beads), reusable -engineering guidelines, and reusable workflows (code reviews, PR workflows, shortcuts). -Adoption is gradual (use only what you want), customizable (override or replace skills -and guidelines), and batteries included (the defaults encode hard-learned practices). - -`tbd` (short for “To Be Done,” or “TypeScript beads” if you prefer) started in January -2026 as a better [Beads](https://github.com/steveyegge/beads) (`bd`) and has since added -workflows of many kinds. -Beads are Markdown files on a dedicated sync branch, so agents and humans share one -durable task layer across sessions and machines, with no daemon and no database. -It installs as a skill for Claude Code and Codex, works through the CLI in any other -agent environment, and is a drop-in replacement for `bd`. - -## What You Get - -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 +Give your agent durable task memory, engineering guidelines it can load when needed, and +repeatable workflows for planning, reviewing, and shipping changes. +Start with the parts you need. +The defaults are ready to use, and you can customize or replace them with your team’s +practices. + +1. **Beads**: Git-native issue tracking for tasks, bugs, and features, shared across + agents, sessions, and machines. +2. **Spec-Driven Workflows**: Plan features, break them into beads, and implement them 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). - -On top of that, `tbd web` shows beads live in a browser, `tbd watch` wakes agents when -bead state changes, `tbd integration` syncs beads with Linear, and policy grants record -which actions agents may take in the project (see -[Features at a Glance](#features-at-a-glance)). +3. **Knowledge Injection**: Engineering guidelines for languages, testing, architecture, + and other topics, loaded on demand. +4. **Shortcuts**: Reusable instructions for code review, commits, PRs, cleanup, and + handoffs. + +These capabilities work together, but you can use beads alone or choose individual +guidelines and workflows. +`tbd` stores beads as Markdown files on a dedicated Git branch, with no required daemon +or database. It installs project skills and hooks for Claude Code and Codex and works +through the CLI in other agent environments. + +**Coordinate across agents and sessions.** Tasks, plans, specs, and progress are +recorded in the Git repository, not tied to a Claude Code or Codex account or to local +or cloud app state. +Sessions from either tool can use the shared repository to coordinate +on the same beads and plans or hand off ongoing work, following the project’s workflow +instructions. + +[Quick Start](#quick-start) · [Adoption Choices](#adopt-only-what-you-want) · +[Setup](#installation-and-setup) · [CLI Reference](packages/tbd/docs/tbd-docs.md) · +[Bundled Library](#bundled-library) ## Quick Start +Requires Node.js 22.12.0 or newer and Git 2.42 or newer. Install the CLI: ```bash npm install -g get-tbd@latest ``` -Then tell your agent: - -***“Run tbd prime, then set up tbd in this project.”*** - -The agent asks you for a short issue-ID prefix, runs `tbd setup --auto --prefix=`, -and follows -[`tbd shortcut setup-tbd`](packages/tbd/docs/shortcuts/standard/setup-tbd.md), which -asks you once, for the project as a whole, which policy grants agents have here (GitHub -editing and merging, stacked PRs, sub-agents, PR review requirements, and Linear sync) -and records the answers in `AGENTS.md`. Unanswered grants stay ask-first; **“not now”** -is a valid answer. Merge, stacks, sub-agents, and Linear can be granted later. -Say **“Set up tbd”** again after any upgrade: it asks only about policies that are still -unanswered. From then on you talk to your agent in natural language; “what can I do with -tbd?” runs the welcome shortcut. -For cloud instances and upgrades, see [Installation and Setup](#installation-and-setup). +Then, with your agent working in your project’s Git repository, tell it: + +**“Run tbd prime, then set up tbd in this project.”** + +Or ask the agent to handle both steps: + +**“Run `npm install -g get-tbd@latest`, then run `tbd prime` and set up tbd in this +project.”** + +Installing the CLI does not initialize the project. +`tbd prime` gives the agent instructions. +For a new project, the agent asks you for a short issue-ID prefix and runs +`tbd setup --auto --prefix=`. For an existing tbd project, the agent runs +`tbd setup --auto` without a new prefix. +After initialization, the agent can run +[`tbd shortcut setup-tbd`](packages/tbd/docs/shortcuts/standard/setup-tbd.md) to review +policy choices and verify setup. +The shortcut is available only inside an initialized tbd repository. +Default setup writes the project’s tbd configuration, agent skills, hooks, and sub-agent +definitions. Review and commit those files so teammates share the setup. +See [Agent Surfaces](#agent-surfaces) to select which integrations are installed. + +Setup also offers project-wide policy choices for GitHub actions, delegation, reviews, +and Linear. You can say **“not now”** and decide when a task needs them; setting up tbd +does not require granting merge authority or connecting an external tracker. + +Start with a request such as **“Track the bug where login fails after a password +reset.”** Your agent creates a bead that the next session can find. +Ask **“What can I do with tbd?”** for an introduction tailored to your project. + +## Adopt Only What You Want + +Choose the parts that help your work; these are not required stages. + +- **Beads without agent integrations.** In a Git repository, `tbd init --prefix=myapp` + initializes task tracking without installing agent skills or hooks. + Choose your own short prefix; `myapp` is an example. + Commit the generated `.tbd/` configuration and use the CLI directly or through your + agent. `tbd sync` exchanges bead state through your Git remote. + You can add agent integrations later with `tbd setup --auto`. +- **Selected agent integrations.** Use `--surfaces` to choose which files a setup run + installs or refreshes. + For example, `tbd setup --auto --surfaces=portable,agents-md` installs the portable + skill and `AGENTS.md` guidance. + This does not uninstall existing surfaces or save a preference: repeat the selection + on later runs; unrestricted setup installs all surfaces. +- **Your team’s knowledge.** Load the bundled guidelines you need, fork them into your + repository to edit, or add your own docs. + See [Guidelines, Shortcuts, and Templates](#shortcuts-guidelines-and-templates). +- **Workflows when they help.** Use a planning, review, or release shortcut for the task + at hand. You can adjust its instructions and record standing project permissions later. + A workflow shortcut supplies instructions to the agent; it is not an autonomous + scheduler or an enforcement boundary. + +The web viewer and bead watcher work with beads alone. +Linear, formal PR stacks, and sub-agent delegation are additional choices, not +prerequisites. ## Talking to Your Agent -The agent translates your requests into `tbd` commands: some do things, like creating -beads, and others give the agent context, knowledge, or a workflow to follow. -These are the requests the installed skill routes; say them in your own words. +Your agent operates tbd on your behalf. +These examples show both small tasks and fuller workflows; the installed skill and +[request vocabulary](packages/tbd/docs/shortcuts/standard/pr-review-workflows.md#request-vocabulary) +provide the complete routing. | What you say | What happens | What runs | | --- | --- | --- | -| “There’s a bug where …” | Agent creates and tracks a bead | `tbd create "..." --type=bug` | -| “Let’s work on issues/beads” | Agent finds ready beads and starts working | `tbd ready` | -| “Show my beads in a browser” | Agent starts the live, read-only viewer, gives you its URL, and keeps it running | `tbd web --open` | -| “Plan a new feature” / “Create a spec” | Agent creates a spec from a template | [`tbd shortcut new-plan-spec`](packages/tbd/docs/shortcuts/standard/new-plan-spec.md) | -| “Break spec into beads” | Agent creates implementation beads from the spec | [`tbd shortcut plan-implementation-with-beads`](packages/tbd/docs/shortcuts/standard/plan-implementation-with-beads.md) | -| “Implement these beads” | Agent works through the beads systematically | [`tbd shortcut implement-beads`](packages/tbd/docs/shortcuts/standard/implement-beads.md) | -| “Review this code” / “Code review” | Agent reviews uncommitted, branch, or PR changes with all guidelines | [`tbd shortcut review-code`](packages/tbd/docs/shortcuts/standard/review-code.md) | -| “Review PR #N” | Agent publishes one senior engineering review at a pinned head | [`tbd shortcut review-github-pr`](packages/tbd/docs/shortcuts/standard/review-github-pr.md) | -| “Address the reviews on PR #N” | Agent gives every finding a disposition (fixed, rebutted, declined, or deferred), pushes confirmed fixes, and replies | [`tbd shortcut address-pr-review`](packages/tbd/docs/shortcuts/standard/address-pr-review.md) | -| “Review and fix PR #N” | One review round and its addressing; the agent asks before another round | [`tbd shortcut review-and-merge-prs`](packages/tbd/docs/shortcuts/standard/review-and-merge-prs.md) (fix mode) | -| “Get PR #N merge-ready” | As above, and the merge gate passes at the current head; no merge | [`tbd shortcut review-and-merge-prs`](packages/tbd/docs/shortcuts/standard/review-and-merge-prs.md) (merge-ready mode) | -| “Make sure PR #N is reviewed and merged” | As above, and the agent merges the PR | [`tbd shortcut review-and-merge-prs`](packages/tbd/docs/shortcuts/standard/review-and-merge-prs.md) (merge mode) | -| “Commit this” / “Use the commit shortcut” | Agent runs pre-commit checks, reviews, and commits | [`tbd shortcut code-review-and-commit`](packages/tbd/docs/shortcuts/standard/code-review-and-commit.md) | -| “Create a PR” / “File a PR” | Agent creates or updates the pull request | [`tbd shortcut create-or-update-pr-simple`](packages/tbd/docs/shortcuts/standard/create-or-update-pr-simple.md) | -| “Create a stacked PR” / “Stack this” | Agent splits the work into a formal stack of dependent PRs | [`tbd shortcut stacked-prs`](packages/tbd/docs/shortcuts/standard/stacked-prs.md) | -| “Merge main into my branch” | Agent merges `origin/main`, resolves conflicts, and watches CI | [`tbd shortcut merge-upstream`](packages/tbd/docs/shortcuts/standard/merge-upstream.md) | -| “Use TypeScript best practices” | Agent loads the TypeScript rules | [`tbd guidelines typescript-rules`](packages/tbd/docs/guidelines/typescript-rules.md) | -| “Use TDD” / “Test-driven development” | Agent loads the TDD guidelines | [`tbd guidelines general-tdd-guidelines`](packages/tbd/docs/guidelines/general-tdd-guidelines.md) | -| “Add golden/e2e testing” | Agent loads the golden testing guidelines | [`tbd guidelines golden-testing-guidelines`](packages/tbd/docs/guidelines/golden-testing-guidelines.md) | -| “Research this topic” | Agent creates a research brief from a template | [`tbd shortcut new-research-brief`](packages/tbd/docs/shortcuts/standard/new-research-brief.md) | -| “Document architecture” | Agent creates an architecture doc | [`tbd shortcut new-architecture-doc`](packages/tbd/docs/shortcuts/standard/new-architecture-doc.md) | -| “Make the guidelines visible / customize doc X” | Agent forks the docs into `docs/tbd/` | `tbd docs fork --category=general --category=` (or `--all`) | -| “Clean up this code” / “Remove dead code” | Agent removes duplicates and dead code | [`tbd shortcut code-cleanup-all`](packages/tbd/docs/shortcuts/standard/code-cleanup-all.md) | -| “Set up tbd” / *(after upgrading tbd)* | Agent reviews setup and asks about unanswered policy grants | [`tbd shortcut setup-tbd`](packages/tbd/docs/shortcuts/standard/setup-tbd.md) | -| “Set up Linear” / “Add my Linear key” | Agent configures the repository or adds your personal key, whichever applies | [`tbd shortcut setup-linear`](packages/tbd/docs/shortcuts/standard/setup-linear.md) | -| “You can use sub-agents” / *(delegating any work)* | Agent checks the grant, splits the work, and briefs sub-agents by tier | [`tbd shortcut delegate-to-subagents`](packages/tbd/docs/shortcuts/standard/delegate-to-subagents.md) | - -Every default in a shortcut yields to your specific guidance: “post the review as a PR -comment”, “also do a security review”, “two rounds”, or “don’t merge anything today”. - -## Features at a Glance - -- **Git-native beads:** one Markdown file with YAML frontmatter per bead, on a dedicated - `tbd-sync` branch, so parallel creation never conflicts and your code history stays - clean; JSON output, bulk commands, and self-documenting help keep it agent-operated. -- **Spec-driven workflows:** shortcuts for the full cycle: plan spec, beads, - implementation, validation plan, and PR. -- **PR review lifecycle:** reviews published at a pinned head under one review-state - contract, addressed finding by finding, with a merge gate before any merge (see - [`pr-review-workflows`](packages/tbd/docs/shortcuts/standard/pr-review-workflows.md)). -- **Policy grants and delegation:** standing, project-wide consent for classes of agent - actions, recorded in `AGENTS.md` and managed with `tbd policy`, plus one delegation - procedure for any platform with provider-neutral model tiers (see - [Agent Policies and Delegation](#agent-policies-and-delegation)). -- **Live web view and watching:** `tbd web --open` serves a loopback-only, read-only - board that updates as beads change, and `tbd watch` blocks until selected bead state - changes on the remote, with no daemon (see [Commands](#commands)). -- **Linear sync:** `tbd integration` mirrors or synchronizes selected beads with Linear, - and plain `tbd sync` covers it (see [Optional Linear Setup](#optional-linear-setup)). -- **Guidelines, shortcuts, and templates:** bundled docs the agent loads by name, - forkable into `docs/tbd/` and extensible from any URL (see - [Shortcuts, Guidelines, and Templates](#shortcuts-guidelines-and-templates)). -- **Beads compatible:** largely compatible with `bd` at the CLI level, with - `tbd setup --from-beads` to migrate (see [Why tbd](#why-tbd)). +| “There’s a bug where …” | Creates a durable task | `tbd create "..." --type=bug` | +| “Show my beads in a browser” | Starts the live, read-only viewer and keeps it running | `tbd web --open` | +| “Plan a new feature” | Writes a spec before implementation | [`tbd shortcut new-plan-spec`](packages/tbd/docs/shortcuts/standard/new-plan-spec.md) | +| “Review PR #N” | Publishes a review | [`tbd shortcut review-github-pr`](packages/tbd/docs/shortcuts/standard/review-github-pr.md) | +| “Address the reviews on PR #N” | Fixes or dispositions the findings and verifies the result | [`tbd shortcut address-pr-review`](packages/tbd/docs/shortcuts/standard/address-pr-review.md) | +| “Review and fix PR #N” | Reviews and addresses findings | [`tbd shortcut review-and-merge-prs`](packages/tbd/docs/shortcuts/standard/review-and-merge-prs.md) (fix mode) | +| “Get PR #N merge-ready” | Completes review and validation without merging | [`tbd shortcut review-and-merge-prs`](packages/tbd/docs/shortcuts/standard/review-and-merge-prs.md) (merge-ready mode) | +| “Make sure PR #N is reviewed and merged” | Reviews, addresses findings, and merges when the requirements are met | [`tbd shortcut review-and-merge-prs`](packages/tbd/docs/shortcuts/standard/review-and-merge-prs.md) (merge mode) | +| “Set up tbd” | Checks project setup and unanswered policy choices | [`tbd shortcut setup-tbd`](packages/tbd/docs/shortcuts/standard/setup-tbd.md) | +| “You can use sub-agents” | Delegates with scoped briefs and verifies the results | [`tbd shortcut delegate-to-subagents`](packages/tbd/docs/shortcuts/standard/delegate-to-subagents.md) | +| “Hand this off to another agent” | Prepares a handoff with the spec, beads, branch, and current context | [`tbd shortcut agent-handoff`](packages/tbd/docs/shortcuts/standard/agent-handoff.md) | + +Your specific instructions take precedence over shortcut defaults: for example, “also do +a security review,” “post it as a PR comment,” or “don’t merge anything today.” + +## Optional Capabilities + +### Live viewing and watching + +Ask your agent to **“Show my beads in a browser.”** It starts `tbd web --open`, gives +you the loopback URL, and keeps the process running. +The page updates as local beads change. +It is read-only: ask the agent to edit beads through ordinary commands. +Opening it never fetches or synchronizes remote data. + +`tbd watch` observes changes on the remote sync branch; `tbd changes` reports changes +since a sync-branch commit. +For an unattended worker, the +[`watch-beads` shortcut](packages/tbd/docs/shortcuts/standard/watch-beads.md) combines +watching with checks for work already ready. +The [CLI reference](packages/tbd/docs/tbd-docs.md) has selectors, timing, and JSON +output. + +### Agent policies and delegation + +Project policy grants record standing consent in `AGENTS.md`; effective grants come from +the repository’s default branch. +`tbd policy show` explains the current settings. +Without a grant, the agent asks when an action needs authorization. +Unanswered merge policy means `confirm-every`; unanswered review requirements mean +`standard`. + +Merge authorization and review requirements are separate: permission to merge does not +waive review or validation. +Your instructions can narrow or authorize actions for the current task, and no policy +bypasses a tool permission or sandbox. +The [policy guidelines](packages/tbd/docs/guidelines/agent-policy-grants.md) define the +values; the +[review workflow](packages/tbd/docs/shortcuts/standard/pr-review-workflows.md) defines +review and merge requirements. + +For delegated work, the +[delegation shortcut](packages/tbd/docs/shortcuts/standard/delegate-to-subagents.md) +covers task boundaries, model tiers, evidence, and follow-up. +Default setup provides project-local tier definitions; the current model suggestions +live in [Agent Model Tiers](packages/tbd/docs/guidelines/agent-model-tiers.md). -## Installation and Setup +### Optional Linear Setup -**Requirements:** +Say **“Set up Linear.”** The agent follows +[`tbd shortcut setup-linear`](packages/tbd/docs/shortcuts/standard/setup-linear.md), +whether it is configuring a repository for the first time or helping a teammate join. +The team, project, and sync policy are shared in `.tbd/config.yml`; each contributor’s +`LINEAR_API_KEY` stays in their environment or a gitignored `.env`, never in a commit or +chat message. + +Once enabled, plain `tbd sync` includes Linear according to the integration +configuration. Teammates can view and update selected work in Linear without using the +CLI. See +[External Tracker Integrations](packages/tbd/docs/tbd-docs.md#external-tracker-integrations) +for selection, linking, and synchronization behavior. -- Node.js 22.12.0 or newer -- Git 2.42 or newer (orphan worktree support) -- GitHub CLI (`gh`) 2.97.0 or newer, optional: the generated session hook installs it - when missing or too old; pass `--no-gh-cli` to setup, or set `use_gh_cli: false` under - `settings:` in `.tbd/config.yml`, to leave `gh` alone. +## Installation and Setup -```bash -npm install -g get-tbd@latest # Install or upgrade (same command for both) -``` +### Existing projects and upgrades -On a fresh cloud instance (such as Claude Code Cloud) where the CLI is not installed, -tell the agent: ***“install tbd (npm install -g get-tbd@latest), run tbd prime, and set -up tbd in this project.”*** +Install or upgrade with `npm install -g get-tbd@latest`, then ask your agent to **“Set +up tbd.”** The setup shortcut checks the installed CLI, refreshes the project, and asks +about unanswered policies. +It installs a missing or incompatible CLI and asks before an optional upgrade of a +working installation. -### Setup and Upgrading +The underlying commands are: ```bash -tbd setup --auto --prefix=myapp # Fresh project (--prefix is REQUIRED: a short alphabetic name used in issue IDs, e.g. myapp → myapp-a1b2) -tbd setup --auto # Existing tbd project; also the upgrade step after npm install -g -tbd setup --from-beads # Migrate from Beads (see Migrating from Beads) +tbd setup --auto --prefix=myapp # New project with default agent integrations +tbd setup --auto # Existing project; refresh after upgrading the CLI +tbd setup --from-beads # Import an uninitialized Beads project (see below) ``` -`tbd setup --auto` is idempotent and safe to run at any time: it initializes `.tbd/`, -refreshes the cached docs and every agent surface, applies any repository format -migration, and writes the policy block in `AGENTS.md` back unchanged. -Commit the diff it reports. -Bare `tbd setup` displays help. -The [`setup-tbd`](packages/tbd/docs/shortcuts/standard/setup-tbd.md) shortcut wraps -these commands: it installs or upgrades the CLI, runs setup, asks about unanswered -policy grants and records the answers, sets up `gh` authentication, stack tooling, and -Linear as the grants require, and verifies with `tbd doctor`. The output of a fresh -setup points to it; run it (say “Set up tbd”) for a new project and after every upgrade. - -Upgrading is the same two commands, `npm install -g get-tbd@latest` and -`tbd setup --auto`. If the new version bumps the repository format (`tbd_format` in -`.tbd/config.yml`), setup migrates it and prints a notice; commit the diff, and -teammates on an older tbd see “This repository requires a newer version of tbd” until -they upgrade too. Issue data is never touched, and the migration is revertible (see -“Aborting a Format Upgrade” in the CLI manual, `tbd docs manual`). +A prefix is required for a new project; choose a short alphabetic name for issue IDs +such as `myapp-a1b2`. Bare `tbd setup` displays help. +Setup refreshes cached docs and selected managed agent files, preserves recorded policy +grants, and applies any repository format migration. +Review and commit the diff it reports. +If a format upgrade requires teammates to upgrade too, setup tells you; the +[manual](packages/tbd/docs/tbd-docs.md) documents compatibility and rollback. -### Team Setup +For a fresh cloud environment, ask the agent to install `get-tbd`, run `tbd prime`, and +set up the project. The same project configuration can be committed and shared across +local and cloud sessions. -**First contributor:** +### Team setup -```bash -npm install -g get-tbd@latest -tbd setup --auto --prefix=proj # Short alphabetic prefix for issue IDs -git add .tbd/ .agents/ .claude/ .codex/ AGENTS.md -git commit -m "Initialize tbd" -git push -``` +The first contributor chooses the prefix and commits `.tbd/config.yml` and the generated +agent files. Joining contributors install the CLI and run `tbd setup --auto` in the +cloned repository; they use the existing prefix and recorded project policies. -**Joining contributors:** - -```bash -git clone -npm install -g get-tbd@latest -tbd setup --auto # No --prefix needed: reads the committed config -``` - -Policy grants are committed with `AGENTS.md`, so joiners inherit them. +`tbd sync` exchanges beads on the dedicated sync branch. +Code and setup files still use your ordinary Git commits and pushes. +People who only need task tracking can use the CLI without installing every agent +integration. ### Agent Surfaces -Setup installs six project-local surfaces by default. -`--surfaces=` (or `all`) narrows the generated files; it does not skip -initialization, migration, or the docs refresh. +Default setup installs all six project-local surfaces. +Select them with `--surfaces=`; selection does not skip initialization, +migrations, or docs refresh, and does not remove files installed earlier. -| Surface | Files | What it gives the agent | +| Surface | Project files | Purpose | | --- | --- | --- | -| `portable` | `.agents/skills/tbd/SKILL.md` | The tbd skill, for any agent that reads portable skills | -| `agents-md` | A managed block in `AGENTS.md` | Orientation for any agent that reads `AGENTS.md`, plus the policy block | -| `claude` | `.claude/skills/tbd/SKILL.md`, hooks in `.claude/settings.json`, and scripts | The Claude Code skill mirror and hooks | -| `claude-agents` | `.claude/agents/tbd-*.md` | Tier agent definitions for sub-agents | -| `codex` | `.codex/hooks.json` and scripts | The Codex hooks | -| `codex-agents` | `.codex/agents/tbd-*.toml` | Tier agent definitions for sub-agents | - -Claude Code and Codex get the same hooks: at session start, `tbd whoami --ensure-id` -sets a stable, machine-local agent identity, `tbd prime` injects workflow context and -the effective policy grants, and `ensure-gh-cli.sh` installs `gh` unless disabled; a -brief `tbd prime` runs before context compaction and the closing reminder after tool -use. Codex also reads `AGENTS.md`; other agents (Cursor, for example) use the portable -skill, `AGENTS.md`, or just the CLI, since `tbd prime` gives any agent the full -workflow. - -The four tier agent definitions (`tbd-strong-max`, `tbd-strong`, `tbd-moderate`, and -`tbd-fast`) each set a model and a reasoning level from the dated suggestions in -[`agent-model-tiers`](packages/tbd/docs/guidelines/agent-model-tiers.md); setup -refreshes them on every run, so upgrading tbd updates them, and removing a file’s -`DO NOT EDIT` marker takes it over. -To leave them out, list the other surfaces: -`--surfaces=portable,agents-md,claude,codex`. - -`tbd status` lists the installed skill, hooks, and `AGENTS.md` block, though not the -tier agent definitions, which `tbd doctor` reports once they exist. -`tbd uninstall --confirm` removes `.tbd/`, the hidden worktree, the local sync branch -(unless `--keep-branch`), and the generated tier agent definitions; the skills, hooks, -and the `AGENTS.md` block stay in place. - -### GitHub Authentication and Stack Tooling - -The PR shortcuts use `gh`. Authenticate with `gh auth login`, or set `GH_TOKEN` (a -[Personal Access Token](https://github.com/settings/tokens?type=beta), fine-grained -recommended, with **Contents** and **Pull requests** read/write permissions) and -`GH_PROMPT_DISABLED=1` before starting the session: in the project’s environment -variables on Claude Code Cloud, or in your shell profile locally. -The session hook enforces the `gh` 2.97.0 floor. -Stack tooling (the pinned `gh-stack` extension and its agent skill) is installed only -when the `github-stacked-prs` policy is granted, through `ensure-gh-cli.sh --with-stack` -as the +| `portable` | `.agents/skills/tbd/SKILL.md` | Portable skill | +| `agents-md` | Managed block in `AGENTS.md` | Orientation and project policies | +| `claude` | `.claude/skills/tbd/SKILL.md`, settings, and scripts | Claude Code skill and hooks | +| `claude-agents` | `.claude/agents/tbd-*.md` | Claude Code tier definitions | +| `codex` | `.codex/hooks.json` and scripts | Codex hooks | +| `codex-agents` | `.codex/agents/tbd-*.toml` | Codex tier definitions | + +Hooks restore context and session identity and remind agents to complete their work. +Other agents can use the portable skill, `AGENTS.md`, or `tbd prime` through the CLI. +See [setup-tbd](packages/tbd/docs/shortcuts/standard/setup-tbd.md) for installation +checks. + +### GitHub tooling + +GitHub CLI (`gh`) is optional for core beads. +The generated session hook can install it when missing or below the required version. +To leave it alone, pass `--no-gh-cli` to setup or set `settings.use_gh_cli: false` in +`.tbd/config.yml`. + +For GitHub workflows, the [setup-github-cli shortcut](packages/tbd/docs/shortcuts/standard/setup-github-cli.md) -describes; without the grant, agents propose separate PRs instead. -Authentication is separate from authorization: a working `gh` login is not a grant, and -a grant never bypasses a tool permission. - -### Optional Linear Setup - -tbd works without an external tracker. -To add Linear, say **“Set up Linear.”** The agent runs -[`tbd shortcut setup-linear`](packages/tbd/docs/shortcuts/standard/setup-linear.md), -which tells first-time repository configuration apart from a teammate joining a -repository whose configuration is already committed: `.tbd/config.yml` holds the shared -Linear team, project, and policy, while each contributor supplies a personal -`LINEAR_API_KEY` through the environment or a gitignored `.env`, never in chat or in a -commit. When the `linear` policy is granted, the default selection is `epics`: open epic -beads, synchronized in both directions. -`tbd integration status` verifies the connection, plain `tbd sync` then covers Linear, -and -[External Tracker Integrations](packages/tbd/docs/tbd-docs.md#external-tracker-integrations) -in the CLI reference has the policies, selectors, and bulk-change safety. +covers authentication, token permissions, and stack tooling. +A GitHub login is separate from permission to act. +Formal stacks can be authorized for a task or through the project’s standing policy; +existing stacks retain their stack handling. ### Migrating from Beads +Import before initializing tbd, while the source `.beads/` directory still exists: + ```bash -tbd --dry-run setup --from-beads # Preview; writes nothing -tbd setup --from-beads # Initialize, import, install surfaces, archive .beads/ -tbd stats # Verify +tbd --dry-run setup --from-beads # Preview without writing +tbd setup --from-beads # Import and install agent integrations +tbd stats # Check imported totals tbd list --all ``` -Run this before initializing tbd, while `.beads/` still exists. -Setup imports `.beads/issues.jsonl` when present and renames the directory to -`.beads-disabled/`, the rollback source; it can continue after a missing JSONL file or -import warning, so verify the totals. -It does not remove `.beads-hooks/`, Cursor rules, Claude settings, or Beads text in -`AGENTS.md`. Issue IDs are preserved: `proj-123` in Beads is `proj-123` in tbd. +Setup reads `.beads/issues.jsonl` when present, preserves issue IDs, and renames +`.beads/` to `.beads-disabled/`. Keep that directory as a recovery source and verify the +import: setup can continue after a missing JSONL file or an import warning. +It does not remove unrelated hooks, Cursor rules, Claude settings, or Beads +instructions. See the +[migration guide](packages/tbd/docs/tbd-docs.md#migration-from-beads) for details. -## Agent Policies and Delegation +## Shortcuts, Guidelines, and Templates -A **policy grant** records your explicit consent for a class of agent actions, for the -project as a whole, so agents neither ask in every session nor act without consent. -Grants live in a policy block inside the tbd block in `AGENTS.md`, are committed like -any other change, and take effect from the default branch. -The seven policies: - -| Policy | Recommended | Covers | -| --- | --- | --- | -| `github-workflows` | `granted` | Issues, labels, and re-running or cancelling CI runs | -| `github-editing` | `granted` | Branches and PRs short of merging: pushing, creating and editing PRs, posting reviews and replies, watching CI | -| `github-merge` | `confirm-session` | Who authorizes merging a PR whose review requirements are met: `never` (an agent does not merge), `confirm-every` (every merge needs its own authorization; what an unanswered policy means), `confirm-session` (a session confirmation covers the task it was given for: the PRs of the task the user confirmed, including every layer of a stack those merges include, and a PR outside that task needs its own confirmation), or `autonomous` (no asking) | -| `github-stacked-prs` | `granted` | Installing the `gh stack` tooling and creating, submitting, syncing, and merging formal stacks | -| `subagents` | `granted` | Delegating to sub-agents following `delegate-to-subagents` | -| `pr-review-requirements` | `standard` | The reviews a PR needs before it merges: one senior engineering review and one addressing pass, plus a dedicated security, performance, or correctness review where the PR is sensitive; `standard + security` or `standard + 2 rounds` adds kinds or rounds | -| `linear` | Asked separately | Syncing beads with Linear; `epics` syncs open epic beads in both directions | - -The block, with its fixed prose omitted: - -```markdown - - -- `github-workflows`: granted -- `github-editing`: granted -- `github-merge`: confirm-session -- `github-stacked-prs`: granted -- `subagents`: granted -- `pr-review-requirements`: standard -- `linear`: not-granted - -Recorded 2026-09-17. - -``` +The bundled library gives your agent instructions and references on demand. +A shortcut is a workflow to follow, a guideline is knowledge to apply, and a template is +a starting point for a document. +You can use them independently of bead tracking. ```bash -tbd policy show # Answered and unanswered policies, with effective values -tbd policy grant subagents # Record the recommended value -tbd policy revoke github-merge # Record the revoke value, what an unanswered policy takes -tbd policy set pr-review-requirements standard + 2 rounds # Record any valid value -tbd policy refresh # Rewrite generated guidance only (grants, date, notes untouched) -tbd setup --auto --policies=recommended # Record the recommended set for every unanswered policy (Linear is asked separately) +tbd shortcut --list +tbd guidelines --list +tbd template --list +tbd guidelines typescript-rules +tbd shortcut new-plan-spec +tbd template plan-spec ``` -An unanswered policy is treated as `not-granted`, with two exceptions (`confirm-every` -for `github-merge` and `standard` for review requirements), and the agent asks when a -task needs it. Your instructions in the conversation override recorded grants for that -task, in either direction, and a grant never bypasses a tool permission or sandbox. -The block interior is fully managed: `grant`, `revoke`, and `set` rebuild everything -between the markers from the recorded grants and the date, so text you add by hand in -there is lost the next time one of them runs. -Only `refresh` leaves it alone, so keep notes about your grants outside the markers. -`tbd prime` prints the effective grants, `tbd doctor` validates the block, and -[`agent-policy-grants`](packages/tbd/docs/guidelines/agent-policy-grants.md) is the full -definition. - -**Delegation.** With `subagents` granted, agents follow -[`delegate-to-subagents`](packages/tbd/docs/shortcuts/standard/delegate-to-subagents.md): -your session is the coordinator; it splits the work by role (reviewer, addressing agent, -administrator), assigns each task a tier from -[`agent-model-tiers`](packages/tbd/docs/guidelines/agent-model-tiers.md) (strong, -moderate, or fast, defined by model rank and reasoning level within your own provider), -spawns fresh, named sub-agents through the generated `tbd-*` definitions, writes -self-contained briefs, and verifies every claim that comes back. -[`review-and-merge-prs`](packages/tbd/docs/shortcuts/standard/review-and-merge-prs.md) -runs the reviews, the addressing pass, the round decision, and the merge gate this way; -without sub-agents, one session performs the same steps in order. -The vendor guidance behind the procedure is in the -[sub-agent research brief](docs/project/research/current/research-2026-09-16-subagent-guidance-anthropic-openai.md). +To customize the library, ask your agent to: -## Commands +- **Load only what the task needs.** Select relevant topics instead of putting the whole + library into every prompt. +- **Fork a bundled doc.** `tbd docs fork typescript-rules` creates a tracked, editable + copy in `docs/tbd/`. tbd serves that copy; `tbd docs update` merges upstream changes + after upgrades. +- **Add team docs.** `tbd guidelines --add= --name=my-team-rules` registers a URL; + shortcuts and templates support the same flags. + Repository-local docs and overrides can also be configured in `.tbd/config.yml`. -### Beads +The `.tbd/docs/` cache is disposable; edit a fork or your own source file instead. +The [managed-docs guide](packages/tbd/docs/tbd-docs.md#managing-docs-two-modes) explains +precedence and update conflicts. +The [Bundled Library](#bundled-library) below is generated from the shipped docs, so its +names, links, and counts stay checked in CI. -```bash -tbd ready # Open work with no delegate, hold, deferral, or blocker -tbd list # List open beads (--all includes closed; --specs groups by spec) -tbd show proj-a7k2 # View bead details (several IDs in one call) -tbd create "Title" --type=bug # Create bead (bug/feature/task/epic/chore) -tbd start proj-a7k2 # Claim under the resolved agent identity -tbd close proj-a7k2 --reason="Fixed in commit abc123" -tbd close proj-a7k2 proj-b3m9 --reason="Sprint done" # Bulk close (one call, no loops) -tbd dep add proj-b3m9 proj-a7k2 # b3m9 depends on a7k2 -tbd label add proj-a7k2 urgent backend -tbd search "authentication" # Search beads by text or partial ID -tbd sync # Sync with remote (auto-commits and pushes) -tbd web --open # Open the live, read-only browser viewer -tbd watch --ready --json # Block until a bead newly becomes ready -tbd changes --since # What changed since a sync-branch commit -``` +## Commands -`tbd start` writes the acting agent to `delegate` and preserves the accountable -`assignee`; `tbd whoami` shows the identity it records. -Pull and re-read shared state before claiming, then sync the accepted claim; the -collision check is local and advisory. - -`tbd web` stays in the foreground, binds loopback only, has no write route, and serves -the same queries and hierarchy as the CLI. It is a viewer, not an editor: ask the agent -to change beads with ordinary commands, and the open page updates automatically; it -never fetches from the remote on its own, and `tbd web ../another-repo --open` serves -any initialized repository. -`tbd watch` polls the remote sync-branch tip, fetches only once it moves, reports one -matching change, and exits; a `--ready` watch is edge-triggered, so the -[watch-beads shortcut](packages/tbd/docs/shortcuts/standard/watch-beads.md) adds startup -and periodic `tbd ready` scans for an unattended worker loop. -The [CLI reference](packages/tbd/docs/tbd-docs.md) has ports, selectors, and the JSON -and dry-run options. - -### External Trackers (Linear) +Most users ask their agent to operate tbd. +For direct CLI use: ```bash -tbd integration status # Verify config, credential, and connectivity -tbd --dry-run integration sync # Preview the full reconciliation, write nothing -tbd integration sync # Both directions: reconcile every linked pair -tbd integration sync --push # Outbound only: project beads to the tracker -tbd integration link proj-a7k2 FIN-123 # Bind a bead to an existing issue -tbd integration unlink proj-a7k2 # Sever the link; nothing is deleted anywhere +tbd ready # Find unclaimed, unblocked work +tbd create "Fix login" --type=bug +tbd show myapp-a1b2 +tbd start myapp-a1b2 # Claim work under the current agent identity +tbd close myapp-a1b2 --reason="Fixed and verified" +tbd sync # Exchange bead state with the remote +tbd web --open # Live local viewer +tbd status # Repository and installation status +tbd doctor # Diagnose configuration or storage problems +tbd docs # Managed-docs overview +tbd docs show tbd-docs # Full CLI manual +tbd --help ``` -Once an integration is enabled, plain `tbd sync` includes it, so most sessions never -need these directly. - -### Documentation and Maintenance +Before claiming shared work, pull and re-read state, then sync your claim. +Claims are advisory, not atomic assignments across machines. +Data-oriented commands support `--json`; supported mutations accept `--dry-run`. The +[CLI reference](packages/tbd/docs/tbd-docs.md) has the full commands and flags. -```bash -tbd # Command help -tbd prime # Full orientation and workflow guidance -tbd readme # This file -tbd docs # Managed-docs overview (cached, forked, and local docs) -tbd docs show tbd-docs # Full CLI reference (the manual; alias: tbd docs manual) -tbd design # Design doc -tbd status # Repository status and installed surfaces (works before init too) -tbd stats # Bead statistics -tbd doctor # Check for problems (--fix repairs them) -tbd policy show # Agent policy grants (see Agent Policies and Delegation) -``` +## Why tbd -Online: the [CLI Reference](packages/tbd/docs/tbd-docs.md) and the -[Design Doc](packages/tbd/docs/tbd-design.md). +Task state and engineering context solve different problems. +Beads preserve tasks, dependencies, and decisions across sessions; guidelines make +conventions available when an agent needs them; shortcuts make practices such as +planning and review repeatable. +You can adopt each without requiring the others. +They help an agent work systematically, while tests, review, and human judgment still +determine whether a change is good. + +For a larger feature, one useful path is spec → implementation beads → implementation → +validation → PR review. +For a small fix, a bead and a focused review may be enough. +Choose the process to fit the work. + +`tbd` (“To Be Done,” or “TypeScript beads”) began in January 2026 as an alternative to +Steve Yegge’s [Beads](https://github.com/steveyegge/beads). +It keeps core `bd` commands and workflows familiar, with Markdown/YAML issue files and +Git-based synchronization. +Compatibility is broad, not an implementation of every `bd` feature; see the +[design comparison](packages/tbd/docs/tbd-design.md#12-when-to-use-tbd-vs-beads). +Capitalized *Beads* names the original tool; lowercase “beads” means the issues. -### Agent-Friendly Flags +## Contributing -These global flags are accepted by every command, but commands apply only the behavior -they implement: +See [docs/development.md](docs/development.md) for build and test instructions, and +[docs/docs-overview.md](docs/docs-overview.md) for the documentation map. -| Flag | Purpose | -| --- | --- | -| `--json` | Structured output for data-oriented commands; raw document commands remain text | -| `--dry-run` | Preview supported mutations; read-only commands may ignore it | -| `--quiet` | Minimal output | +## License -## Shortcuts, Guidelines, and Templates +MIT -`tbd` bundles three kinds of documentation your agent loads on demand: +## Bundled Library -```bash -tbd shortcut --list # List all shortcuts -tbd shortcut new-plan-spec # Get the plan spec workflow -tbd guidelines --list # List all guidelines -tbd guidelines typescript-rules # Get TypeScript rules (several names in one call) -tbd template --list # List all templates -tbd template plan-spec # Get a plan spec template -tbd guidelines --add= --name=my-team-rules # Add your own from any URL (shortcut and template take --add too) -``` +These catalogs are optional reference material. +Ask your agent to load a named document, or browse with `tbd shortcut --list`, +`tbd guidelines --list`, and `tbd template --list`. -These docs are cached in `.tbd/docs/` (gitignored) during setup and refreshed by every -`tbd setup --auto`. Fork any of them into `docs/tbd/` with `tbd docs fork ` (or -`--category=` or `--all`) and they become visible on GitHub, reviewable in PRs, -and editable in place: tbd serves your copy instead, and `tbd docs update` merges -upstream improvements into it after an upgrade. -`.tbd/config.yml` configures which docs are available. +
Browse all bundled shortcuts, guidelines, and templates @@ -567,110 +498,7 @@ upstream improvements into it after an upgrade. -## Why tbd - -Agents can be excellent or poor depending on what they are given: without structure and -knowledge they forget conventions between sessions, skip testing, and drift from a -team’s patterns, and neither pasting rules into prompts nor piling every rule into -`CLAUDE.md` or `AGENTS.md` scales. -Beads (git-native, CLI-based issue tracking) solve the task management part, raising an -agent’s capacity for structured work from a handful of ad-hoc to-do items to hundreds of -tracked beads with dependencies that persist in git. -Task tracking alone does not help with planning or quality, so tbd adds spec-driven -workflows to think through what to build before building it, and curated engineering -guidelines the agent loads when it needs them. -You can then hand an agent a well-defined spec with clear beads and expert knowledge and -get back careful, well-structured code, across sessions. - -**Spec-driven development.** For non-trivial features: - -1. **Plan**: write a planning spec (`tbd shortcut new-plan-spec`) -2. **Break down**: convert the spec into implementation beads - (`tbd shortcut plan-implementation-with-beads`) -3. **Implement**: work through the beads (`tbd shortcut implement-beads`) -4. **Validate**: write a validation plan and run the tests - (`tbd shortcut new-validation-plan`) -5. **Ship**: commit and create the PR - (`tbd shortcut create-or-update-pr-with-validation-plan`), then have it reviewed and - merged (`tbd shortcut review-and-merge-prs`) - -Iterating on the spec is the hard part; with a good spec, writing the code is often -almost automatic. These workflows come from -[heavy spec-driven agentic coding](https://github.com/jlevy/speculate/blob/main/about/lessons_in_spec_coding.md), -and shortcuts make them repeatable, including by voice: “use the shortcut to create a -new plan spec that …”. - -**Compared to Beads.** tbd was inspired by [Beads](https://github.com/steveyegge/beads) -by Steve Yegge and keeps the idea with a simpler architecture: plain Markdown files -instead of JSONL, no daemon modifying the working tree, no SQLite, no 4-way sync. -That avoids merge conflicts, sync confusion across branches and the database, and file -locking on network filesystems such as Claude Code Cloud; beads stay in git on the -`tbd-sync` branch, and `tbd watch`, `tbd web`, and `tbd integration sync` build on that -layer. The [design doc](packages/tbd/docs/tbd-design.md) has the detailed comparison. - -> [!NOTE] -> *Beads* (capitalized) refers to Steve Yegge’s original -> [`bd` tool](https://github.com/steveyegge/beads). -> Lowercase “beads” refers to the issues stored in `tbd` or `bd`. - -## FAQ - -### How does `tbd` compare to Beads? - -See [Why tbd](#why-tbd): the same idea with a simpler architecture. -If you already use Beads, `tbd setup --from-beads` migrates you, preserving every issue -ID (see [Migrating from Beads](#migrating-from-beads)). - -### Can my team see beads without using the CLI? - -Yes, two ways: `tbd web --open` serves a live, read-only board in a local browser, and -the Linear integration mirrors or synchronizes selected beads with your team’s tracker, -so people who never clone the repo still see, and can update, the work (see -[Optional Linear Setup](#optional-linear-setup)). - -### Can agents merge my PRs? - -Only as far as the project allows, and the `github-merge` policy has four settings -rather than yes or no. -`never` means an agent does not merge at all; `confirm-every`, which is what an -unanswered policy means, needs your authorization for each merge, so “Make sure PR #N is -reviewed and merged” authorizes that PR and nothing else; `confirm-session` -(recommended) lets it merge once a session confirmation covers the task it was given -for: the PRs of the task the user confirmed, including every layer of a stack those -merges include, and a PR outside that task needs its own confirmation; `autonomous` lets -it merge without asking. -None of them lowers the review bar: `pr-review-requirements` decides whether a PR is -ready, and the merge gate checks it separately in every case. -Before merging, `review-and-merge-prs` checks the merge gate: the review requirements -are met (under `standard`, a senior engineering review at a pinned head, a pass -addressing all its findings, and a dedicated review for each area the PR is sensitive -in), every finding has a disposition and every deferral an open bead, no newer review -content is unaddressed, any question about another round has been answered, CI is green -at the unchanged head, GitHub reports the PR mergeable, and every layer below a stack -layer has merged. The merge uses the repository’s merge method at the gated head, never -`--admin`, and a branch-protection block is reported, not bypassed. - -### Can I add my own guidelines? - -Yes. Add your team’s docs from any URL with `tbd guidelines --add` (and -`tbd shortcut --add` or `tbd template --add`), fork the bundled ones into `docs/tbd/` to -edit them in place, and configure which docs are available in `.tbd/config.yml` (see -[Shortcuts, Guidelines, and Templates](#shortcuts-guidelines-and-templates)). - -### Was `tbd` built with `tbd`? - -Yes. -It was bootstrapped with the original `bd`, imported its own issues, and has tracked -its own specs and beads and loaded its own guidelines since; all of its code and specs -are agent-written. - -## Contributing - -See [docs/development.md](docs/development.md) for build and test instructions. - -## License - -MIT +
diff --git a/packages/tbd/docs/shortcuts/standard/setup-tbd.md b/packages/tbd/docs/shortcuts/standard/setup-tbd.md index 841661d44..a73eb8406 100644 --- a/packages/tbd/docs/shortcuts/standard/setup-tbd.md +++ b/packages/tbd/docs/shortcuts/standard/setup-tbd.md @@ -10,6 +10,11 @@ The output of `tbd setup` ends by pointing here, and “Set up tbd” is the req runs it. Re-running it is safe: setup is idempotent, and each run asks only about policies that are still unanswered. +The CLI shortcut requires an initialized tbd repository. +For a fresh project, run `tbd prime` first: it tells you to ask for an issue prefix and +run `tbd setup --auto --prefix=`. Then load this shortcut to review policies and +finish setup. + Operate tbd for the user throughout: run the commands yourself, and ask the user only for decisions (the prefix and the policy answers) and for authentication that must come from them (a `gh` login or token, a personal Linear key). diff --git a/packages/tbd/docs/shortcuts/system/skill-baseline.md b/packages/tbd/docs/shortcuts/system/skill-baseline.md index 289372226..7d1e311d4 100644 --- a/packages/tbd/docs/shortcuts/system/skill-baseline.md +++ b/packages/tbd/docs/shortcuts/system/skill-baseline.md @@ -4,22 +4,34 @@ description: Full tbd workflow guide for agents --- **`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 +1. **Beads**: Git-native issue tracking for tasks, bugs, and features, shared across + sessions and machines. +2. **Spec-Driven Workflows**: Plan features, break them into beads, and implement them 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). +3. **Knowledge Injection**: Engineering guidelines for languages, testing, architecture, + and other topics, loaded on demand. +4. **Shortcuts**: Reusable instructions for code review, commits, PRs, cleanup, and + handoffs. + +Use the capabilities the user wants; they can adopt beads alone or choose individual +guidelines and workflows. +The bundled docs are customizable defaults. +Load relevant guidelines as needed and preserve the user’s task-specific instructions. ## Installation -**For a new project, and again after every tbd upgrade, run `tbd shortcut setup-tbd` and -follow it.** It installs or upgrades the CLI, runs setup, and asks the user about any -unanswered policy grants. -The setup commands it runs: +Check `tbd --version` first. +Install the CLI if missing, or install/upgrade it when the user explicitly requests it. +Then run `tbd prime` in the project’s Git repository. +For a fresh project, ask the user for the issue-ID prefix and run +`tbd setup --auto --prefix=`; never guess the prefix. + +**Once the project is initialized, run `tbd shortcut setup-tbd` and follow it.** The +shortcut is unavailable before initialization. +It reviews setup and unanswered policy grants; run it again after every tbd upgrade. +With an existing working CLI, ask before upgrading unless the user already requested the +upgrade or tbd requires a newer version. +The installation and setup commands are: ```bash npm install -g get-tbd@latest # Install or upgrade the CLI (same command for both) @@ -130,7 +142,7 @@ or want help → run `tbd shortcut welcome-user` | “Update the guidelines to the latest” | `tbd docs update`; on conflicts ask the user, then `--merge` or `--keep-ours` | | “I deleted a forked doc file” | `tbd docs status` shows it `missing`; restore with `tbd docs fork --force` or finalize with `tbd docs unfork ` | | **Setup** | | -| “Set up tbd” / *(after upgrading tbd)* | `tbd shortcut setup-tbd` | +| “Set up tbd” / *(after upgrading tbd)* | Follow Installation above; initialize a fresh project before `tbd shortcut setup-tbd` | | **External Trackers** | | | “Set up Linear” / “Connect this repo to Linear” | `tbd shortcut setup-linear` | | “My Linear sync isn’t working” / “Add my Linear key” | `tbd shortcut setup-linear` | diff --git a/packages/tbd/docs/tbd-design.md b/packages/tbd/docs/tbd-design.md index 8cdf3f1cf..735e88726 100644 --- a/packages/tbd/docs/tbd-design.md +++ b/packages/tbd/docs/tbd-design.md @@ -9,7 +9,7 @@ agents. **First drafted**: January 2025 -**Last updated**: 2026-09-19 +**Last updated**: 2026-09-30 * * * @@ -248,24 +248,29 @@ agents. for AI coding agents.** tbd ("To Be Done" or “TypeScript Beads”) is a git-native issue tracker that stores -issues as Markdown files with YAML frontmatter on a dedicated sync branch, enabling -conflict-free collaboration without daemons or databases. +issues as Markdown files with YAML frontmatter on a dedicated sync branch. +Agents share task state through Git without a required daemon or database. It also bundles spec-driven workflows, reusable workflow shortcuts, and a curated knowledge base of engineering best practices that agents can inject into their context on demand. -tbd provides **four integrated capabilities**, listed identically in the README and the -installed skill: +tbd provides **four capabilities** that can be adopted gradually. +Their names and descriptions are shared with the README and installed skill: -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 +1. **Beads**: Git-native issue tracking for tasks, bugs, and features, shared across + sessions and machines. +2. **Spec-Driven Workflows**: Plan features, break them into beads, and implement them 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). +3. **Knowledge Injection**: Engineering guidelines for languages, testing, architecture, + and other topics, loaded on demand. +4. **Shortcuts**: Reusable instructions for code review, commits, PRs, cleanup, and + handoffs. + +Beads work independently of the agent integrations. +Guidelines, shortcuts, and templates can be selected by task, forked, or replaced with +project documentation. +Bundled defaults provide a starting point without requiring every workflow or external +integration. On top of these, `tbd web` shows beads live in a browser (§4.15), `tbd watch` wakes agents when bead state changes (§4.14), `tbd integration` syncs beads with Linear diff --git a/skills/tbd/SKILL.md b/skills/tbd/SKILL.md index f6d5b8bce..97dbf1abc 100644 --- a/skills/tbd/SKILL.md +++ b/skills/tbd/SKILL.md @@ -23,22 +23,34 @@ allowed-tools: Bash(tbd:*) Read Write --- **`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 +1. **Beads**: Git-native issue tracking for tasks, bugs, and features, shared across + sessions and machines. +2. **Spec-Driven Workflows**: Plan features, break them into beads, and implement them 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). +3. **Knowledge Injection**: Engineering guidelines for languages, testing, architecture, + and other topics, loaded on demand. +4. **Shortcuts**: Reusable instructions for code review, commits, PRs, cleanup, and + handoffs. + +Use the capabilities the user wants; they can adopt beads alone or choose individual +guidelines and workflows. +The bundled docs are customizable defaults. +Load relevant guidelines as needed and preserve the user’s task-specific instructions. ## Installation -**For a new project, and again after every tbd upgrade, run `tbd shortcut setup-tbd` and -follow it.** It installs or upgrades the CLI, runs setup, and asks the user about any -unanswered policy grants. -The setup commands it runs: +Check `tbd --version` first. +Install the CLI if missing, or install/upgrade it when the user explicitly requests it. +Then run `tbd prime` in the project’s Git repository. +For a fresh project, ask the user for the issue-ID prefix and run +`tbd setup --auto --prefix=`; never guess the prefix. + +**Once the project is initialized, run `tbd shortcut setup-tbd` and follow it.** The +shortcut is unavailable before initialization. +It reviews setup and unanswered policy grants; run it again after every tbd upgrade. +With an existing working CLI, ask before upgrading unless the user already requested the +upgrade or tbd requires a newer version. +The installation and setup commands are: ```bash npm install -g get-tbd@latest # Install or upgrade the CLI (same command for both) @@ -149,7 +161,7 @@ or want help → run `tbd shortcut welcome-user` | “Update the guidelines to the latest” | `tbd docs update`; on conflicts ask the user, then `--merge` or `--keep-ours` | | “I deleted a forked doc file” | `tbd docs status` shows it `missing`; restore with `tbd docs fork --force` or finalize with `tbd docs unfork ` | | **Setup** | | -| “Set up tbd” / *(after upgrading tbd)* | `tbd shortcut setup-tbd` | +| “Set up tbd” / *(after upgrading tbd)* | Follow Installation above; initialize a fresh project before `tbd shortcut setup-tbd` | | **External Trackers** | | | “Set up Linear” / “Connect this repo to Linear” | `tbd shortcut setup-linear` | | “My Linear sync isn’t working” / “Add my Linear key” | `tbd shortcut setup-linear` |