Skip to content

docs: restructure README for gradual adoption and current workflows #313

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jlevy merged 8 commits into from
Oct 2, 2026
Merged

docs: restructure README for gradual adoption and current workflows #313

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
941edd2
docs: Add README information-architecture review
Sep 19, 2026
caa7263
docs: Avoid #309-only tbd doc commands in the review
Sep 19, 2026
e8fb1f0
docs: Record the user-supplied README pitch in the review
Sep 19, 2026
a479b38
docs: Record that the README change is a light framing edit
Sep 19, 2026
2bfd7d9
docs: restructure README for gradual adoption and current workflows
jlevy Sep 30, 2026
2e57933
docs: explain shared workflows across coding agents
jlevy Oct 2, 2026
90b8f37
docs: clarify installation and repository setup order
jlevy Oct 2, 2026
60e2dee
docs: bootstrap fresh projects before loading setup shortcut
jlevy Oct 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 25 additions & 13 deletions .agents/skills/tbd/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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=<name>`; 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)
Expand Down Expand Up @@ -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 <name> --force` or finalize with `tbd docs unfork <name>` |
| **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` |
Expand Down
38 changes: 25 additions & 13 deletions .claude/skills/tbd/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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=<name>`; 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)
Expand Down Expand Up @@ -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 <name> --force` or finalize with `tbd docs unfork <name>` |
| **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` |
Expand Down
Loading
Loading