Forkable docs (f05): spec and implementation — fork/unfork/status/update/diff/list

.agents/skills/tbd/SKILL.md

@@ -6,7 +6,7 @@ description: |-
   Invoke when user mentions: tbd, beads, bd, shortcuts, issues, bugs, tasks, features, epics, todo, tracking, specs, planning, implementation, validation, guidelines, templates, commit, PR, pull request, code review, testing, TDD, test-driven, golden testing, snapshot testing, TypeScript, Python, Convex, monorepo, cleanup, dead code, refactor, handoff, research, architecture, labels, search, checkout library, source code review, or any workflow shortcut.
 name: tbd
 ---
-<!-- DO NOT EDIT: Generated by tbd setup (format=f04).
+<!-- DO NOT EDIT: Generated by tbd setup (format=f05).
 Run 'tbd setup' to update.
 -->
 
@@ -25,12 +25,15 @@ Run 'tbd setup' to update.
 ## Installation
 
 ```bash
-npm install -g get-tbd@latest
+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 (prefix already set)
+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
 
 ```bash
@@ -90,6 +93,10 @@ or want help → run `tbd shortcut welcome-user`
 | **Documentation** |  |
 | “Research this topic” | `tbd shortcut new-research-brief` |
 | “Document architecture” | `tbd shortcut new-architecture-doc` |
+| “What guidelines/docs are there?” | `tbd docs list` |
+| “Make the guidelines visible / customize doc X” | `tbd docs fork <name>` (or `--all`), then edit in `docs/tbd/` |
+| “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>` |
 | **Cleanup & Maintenance** |  |
 | “Clean up this code” / “Remove dead code” | `tbd shortcut code-cleanup-all` |
 | “Fix repository problems” | `tbd doctor --fix` |
@@ -179,6 +186,8 @@ working branch. See `tbd guidelines tbd-sync-troubleshooting` for details.
 | `tbd guidelines <name>` | Load coding guidelines |
 | `tbd guidelines --list` | List guidelines |
 | `tbd template <name>` | Output a template |
+| `tbd docs` / `tbd docs list` | Managed-docs overview / cross-kind list with state markers |
+| `tbd docs fork/unfork/update <name>` | Fork docs into `docs/tbd/`, return to upstream, pull upstream updates |
 
 ## Quick Reference
 
@@ -221,6 +230,7 @@ Run `tbd shortcut <name>` to use any of these shortcuts:
 | revise-all-architecture-docs | Comprehensive revision of all current architecture documents |
 | revise-architecture-doc | Update an architecture document to reflect current codebase state |
 | setup-github-cli | Ensure GitHub CLI (gh) is installed and working |
+| suggest-upstream-improvements | Review local doc-fork customizations and contribute the generally useful changes back upstream |
 | sync-failure-recovery | Handle tbd sync failures by saving to workspace and recovering later |
 | update-specs-status | Review active specs and sync their status with tbd issues |
 | welcome-user | Welcome message for users after tbd installation or setup |

.claude/skills/tbd/SKILL.md

@@ -6,7 +6,7 @@ description: |-
   Invoke when user mentions: tbd, beads, bd, shortcuts, issues, bugs, tasks, features, epics, todo, tracking, specs, planning, implementation, validation, guidelines, templates, commit, PR, pull request, code review, testing, TDD, test-driven, golden testing, snapshot testing, TypeScript, Python, Convex, monorepo, cleanup, dead code, refactor, handoff, research, architecture, labels, search, checkout library, source code review, or any workflow shortcut.
 name: tbd
 ---
-<!-- DO NOT EDIT: Generated by tbd setup (format=f04).
+<!-- DO NOT EDIT: Generated by tbd setup (format=f05).
 Run 'tbd setup' to update.
 -->
 
@@ -25,12 +25,15 @@ Run 'tbd setup' to update.
 ## Installation
 
 ```bash
-npm install -g get-tbd@latest
+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 (prefix already set)
+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
 
 ```bash
@@ -90,6 +93,10 @@ or want help → run `tbd shortcut welcome-user`
 | **Documentation** |  |
 | “Research this topic” | `tbd shortcut new-research-brief` |
 | “Document architecture” | `tbd shortcut new-architecture-doc` |
+| “What guidelines/docs are there?” | `tbd docs list` |
+| “Make the guidelines visible / customize doc X” | `tbd docs fork <name>` (or `--all`), then edit in `docs/tbd/` |
+| “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>` |
 | **Cleanup & Maintenance** |  |
 | “Clean up this code” / “Remove dead code” | `tbd shortcut code-cleanup-all` |
 | “Fix repository problems” | `tbd doctor --fix` |
@@ -179,6 +186,8 @@ working branch. See `tbd guidelines tbd-sync-troubleshooting` for details.
 | `tbd guidelines <name>` | Load coding guidelines |
 | `tbd guidelines --list` | List guidelines |
 | `tbd template <name>` | Output a template |
+| `tbd docs` / `tbd docs list` | Managed-docs overview / cross-kind list with state markers |
+| `tbd docs fork/unfork/update <name>` | Fork docs into `docs/tbd/`, return to upstream, pull upstream updates |
 
 ## Quick Reference
 
@@ -221,6 +230,7 @@ Run `tbd shortcut <name>` to use any of these shortcuts:
 | revise-all-architecture-docs | Comprehensive revision of all current architecture documents |
 | revise-architecture-doc | Update an architecture document to reflect current codebase state |
 | setup-github-cli | Ensure GitHub CLI (gh) is installed and working |
+| suggest-upstream-improvements | Review local doc-fork customizations and contribute the generally useful changes back upstream |
 | sync-failure-recovery | Handle tbd sync failures by saving to workspace and recovering later |
 | update-specs-status | Review active specs and sync their status with tbd issues |
 | welcome-user | Welcome message for users after tbd installation or setup |

.tbd/config.yml

@@ -1,4 +1,4 @@
-tbd_format: f04
+tbd_format: f05
 tbd_version: development
 display:
   id_prefix: tbd
@@ -23,10 +23,9 @@ settings:
 # Auto-sync: Docs are automatically synced when stale (default: every 24 hours).
 # Configure with settings.doc_auto_sync_hours (0 = disabled).
 docs_cache:
-  lookup_path:
-    - .tbd/docs/shortcuts/system
-    - .tbd/docs/shortcuts/standard
   files:
+    references/tbd-docs.md: internal:tbd-docs.md
+    references/tbd-design.md: internal:tbd-design.md
     shortcuts/system/shortcut-explanation.md: internal:shortcuts/system/shortcut-explanation.md
     shortcuts/system/skill-baseline.md: internal:shortcuts/system/skill-baseline.md
     shortcuts/system/skill-brief.md: internal:shortcuts/system/skill-brief.md
@@ -58,6 +57,7 @@ docs_cache:
     shortcuts/standard/revise-all-architecture-docs.md: internal:shortcuts/standard/revise-all-architecture-docs.md
     shortcuts/standard/revise-architecture-doc.md: internal:shortcuts/standard/revise-architecture-doc.md
     shortcuts/standard/setup-github-cli.md: internal:shortcuts/standard/setup-github-cli.md
+    shortcuts/standard/suggest-upstream-improvements.md: internal:shortcuts/standard/suggest-upstream-improvements.md
     shortcuts/standard/sync-failure-recovery.md: internal:shortcuts/standard/sync-failure-recovery.md
     shortcuts/standard/update-specs-status.md: internal:shortcuts/standard/update-specs-status.md
     shortcuts/standard/welcome-user.md: internal:shortcuts/standard/welcome-user.md
@@ -92,3 +92,8 @@ docs_cache:
     templates/plan-spec.md: internal:templates/plan-spec.md
     templates/qa-playbook.md: internal:templates/qa-playbook.md
     templates/research-brief.md: internal:templates/research-brief.md
+    references/docmap-format.md: internal:references/docmap-format.md
+    references/docref-format.md: internal:references/docref-format.md
+  lookup_path:
+    - .tbd/docs/shortcuts/system
+    - .tbd/docs/shortcuts/standard

AGENTS.md

@@ -33,7 +33,7 @@ Work is NOT complete until `git push` succeeds.
 - NEVER say “ready to push when you are” - YOU must push
 - If push fails, resolve and retry until it succeeds
 
-<!-- BEGIN TBD INTEGRATION format=f04 surface=agents-md -->
+<!-- BEGIN TBD INTEGRATION format=f05 surface=agents-md -->
 ## tbd
 
 This repository uses **tbd** for git-native issue tracking (beads), spec-driven

README.md

@@ -37,7 +37,6 @@ will work in Cursor, Codex, or any agent environment that can use the `tbd` CLI.
 ## Quick Start
 
 > [!TIP]
-> 
 > If running on your own machine, install the `tbd` CLI yourself:
 > 
 > **`npm install -g get-tbd@latest`**
@@ -50,6 +49,11 @@ will work in Cursor, Codex, or any agent environment that can use the `tbd` CLI.
 > 
 > ***“install tbd (npm install -g get-tbd@latest) and run tbd prime for instructions to
 > set up this project”***
+> 
+> If tbd is already set up in the repo and you want the latest version, tell the agent:
+> 
+> ***“upgrade tbd (npm install -g get-tbd@latest), run tbd setup --auto, and commit the
+> changes”***
 
 That’s it.
 Running `tbd prime` gives agents full workflow context on how to use `tbd` and
@@ -122,7 +126,6 @@ agents handling different aspects that I manage) is slower, because it forces yo
 design, but it gives higher quality results.
 
 > [!NOTE]
-> 
 > We use *Beads* (capitalized) to refer to Steve Yegge’s original
 > [`bd` tool](https://github.com/steveyegge/beads).
 > Lowercase “beads” refers generically to the issues stored in `tbd` or `bd`.
@@ -160,8 +163,8 @@ You just talk naturally.
 
 > [!NOTE]
 > For full technical details, see the [reference docs](packages/tbd/docs/tbd-docs.md)
-> (run `tbd docs`) or the full [design doc](packages/tbd/docs/tbd-design.md)
-> (`tbd design`).
+> (run `tbd docs show tbd-docs`) or the full
+> [design doc](packages/tbd/docs/tbd-design.md) (`tbd design`).
 
 - **Git-native:** Beads live in your repo, synced to a separate, dedicated `tbd-sync`
   branch. Your code history stays clean—no bead churn polluting your logs.
@@ -225,7 +228,6 @@ practices. These aren’t generic tips; they’re mostly my own detailed and som
 opinionated rules with concrete examples, built from months of heavy agentic coding.
 
 > [!TIP]
-> 
 > An example: I *strongly* believe there are much better ways to do testing
 > proliferating hundreds of unit and integration tests.
 > So (with help from some Opus 4.5 and GPT-5 Pro) I wrote a multi-page brief about
@@ -292,6 +294,25 @@ tbd setup --from-beads
 > **Tip:** Run `tbd setup --auto` anytime to refresh skill files, hooks, and configs
 > with the latest shortcuts, guidelines, and templates.
 
+### Upgrading
+
+Upgrading an existing installation is the same two commands, run by you or your agent:
+
+```bash
+npm install -g get-tbd@latest   # Upgrade the CLI
+tbd setup --auto                # Refresh skills/hooks and apply any format migration
+```
+
+If the new version bumps the repository format (`tbd_format` in `.tbd/config.yml`),
+setup migrates it automatically and prints a notice — **commit the resulting diff** to
+publish the upgrade to your team.
+Teammates still on an older tbd then see “This repository requires a newer version of
+tbd” until they run the same two commands.
+Issue data is never touched by an upgrade, and the migration is revertible: see
+“Aborting a Format Upgrade” under Troubleshooting in the CLI manual (`tbd docs manual`).
+If you have forked docs in `docs/tbd/`, `tbd sync` prints a notice when their upstream
+versions moved — run `tbd docs update` to merge the changes in.
+
 ### Team Setup
 
 `tbd` is designed for teams where one person sets up the project and others join later.
@@ -394,11 +415,21 @@ tbd template --list              # List all templates
 tbd template plan-spec           # Get a plan spec template
 
 # Add your own from any URL
+# (per-kind aliases for `tbd docs add <docref>`)
 tbd guidelines --add=<url> --name=<name>
 tbd shortcut --add=<url> --name=<name>
 tbd template --add=<url> --name=<name>
 ```
 
+**Forkable: see them in your repo.** By default these docs are served from a hidden,
+gitignored cache. Fork any of them into `docs/tbd/` 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:
+
+```bash
+tbd docs fork --all              # Or fork by name: tbd docs fork <name> [<name>...]
+```
+
 **Available shortcuts:**
 
 | Category | Shortcut | Purpose |
@@ -480,7 +511,8 @@ Every command supports these flags for automation:
 ```bash
 tbd                          # Full orientation and workflow guidance
 tbd readme                   # This file
-tbd docs                     # Full CLI reference
+tbd docs                     # Managed-docs overview (cached, forked, and local docs)
+tbd docs show tbd-docs       # Full CLI reference (the manual; alias: tbd docs manual)
 ```
 
 Or read online:

docs/development.md

@@ -345,6 +345,7 @@ the full specification.
 │ Committed to the repo:
 ├── config.yml                      # Project configuration
 ├── .gitignore                      # Controls what's gitignored below
+├── doc-forks/                      # Fork manifest + base snapshots (f05; tbd-design.md §2.9)
 ├── workspaces/                     # Persistent state (outbox, named workspaces)
 │   └── outbox/                     # Sync failure recovery data
 │
@@ -354,7 +355,7 @@ the full specification.
 └── backups/                        # Legacy local backups
 
 $GIT_COMMON_DIR/tbd/                # Shared by all linked worktrees of this repo
-├── layout.yml                      # Common-dir layout metadata (same f04 format ID)
+├── layout.yml                      # Common-dir layout metadata (mirrors config's tbd_format)
 ├── locks/
 │   └── data-sync.lock/             # mkdir-based repo-scoped lock
 ├── backups/                        # Shared migration/repair backups
@@ -366,11 +367,28 @@ $GIT_COMMON_DIR/tbd/                # Shared by all linked worktrees of this rep
         └── meta.yml
 ```
 
+`.tbd/doc-forks/` is committed and holds only fork *tracking state*: the `forks.yml`
+manifest plus `base/` snapshots that `tbd docs update` three-way merges against.
+The doc **fork dir** itself lives deliberately *outside* `.tbd/` — default `docs/tbd/`,
+tracked in git like any other docs.
+
 **CRITICAL**: Issues must be written to the **worktree path**
 (`$GIT_COMMON_DIR/tbd/data-sync-worktree/.tbd/data-sync/issues/`), NOT the direct path
 (`.tbd/data-sync/issues/`). The direct path is gitignored and exists only as a legacy
 diagnostic/migration location.
 
+### Format Upgrades and Rollback
+
+A `tbd_format` bump writes exactly two stamps: the tracked `.tbd/config.yml` and the
+machine-local `$GIT_COMMON_DIR/tbd/layout.yml` (plus, only when `tbd setup --auto` is
+run, the tracked agent-surface markers).
+It never touches issue data, so any upgrade can be aborted: restore the tracked files
+from git and delete `layout.yml` (it regenerates from the config).
+The full state inventory and abort recipe are user-facing in `tbd-docs.md`
+§Troubleshooting → “Aborting a Format Upgrade”; the migrate → revert → repeat loop and
+both interrupted-upgrade partial states are pinned by tests in
+`tests/common-dir-layout-doctor.test.ts` (“f04 → f05 upgrade”).
+
 ### Key Source Files
 
 - `packages/tbd/src/lib/paths.ts` - Path constants and `resolveDataSyncDir()`
@@ -440,6 +458,12 @@ Run the e2e worktree scenarios:
 npx tryscript run tests/cli-sync-worktree-scenarios.tryscript.md
 ```
 
+### Testing Forkable Docs
+
+Forkable-docs behavior (fork/unfork/update/diff/status) is covered by
+`tests/cli-docs-fork.tryscript.md`, `tests/cli-docs-update.tryscript.md`, and
+`tests/fork-cross-platform-e2e.test.ts` (run from `packages/tbd/`).
+
 <!-- This document follows common-doc-guidelines.md.
 See github.com/jlevy/practical-prose and review guidelines before editing.
 -->

docs/docs-overview.md

@@ -50,17 +50,24 @@ Project-specific specifications, architecture, and research docs:
 
 ### tbd CLI Documentation Commands
 
-In addition to these repository docs, tbd provides built-in documentation via CLI:
+In addition to these repository docs, tbd provides managed documentation via the
+`tbd docs` group and per-kind readers:
 
-- `tbd shortcut --list` / `tbd shortcut <name>`—Workflow shortcuts (new-plan-spec,
-  code-review-and-commit, review-code-typescript, etc.)
-- `tbd guidelines --list` / `tbd guidelines <name>`—Coding guidelines (typescript-rules,
-  python-rules, general-tdd-guidelines, etc.)
-- `tbd template --list` / `tbd template <name>`—Document templates (plan-spec,
-  research-brief, architecture)
+- `tbd docs`—Status overview of managed docs; `tbd docs list` shows every doc across
+  kinds with `[forked]`/`[customized]`/`[local]` markers
+- `tbd docs show <name>`—Read any doc by name; `tbd docs show tbd-docs` is the CLI
+  manual (alias `tbd docs manual`)
+- `tbd shortcut <name>` / `tbd guidelines <name>` / `tbd template <name>`—Per-kind
+  readers (with `--list`)
+- `tbd docs sync`—Refresh the gitignored `.tbd/docs/` cache (also run by setup)
 
-These CLI-provided docs are installed locally in `.tbd/docs/` during `tbd setup --auto`
-and can be refreshed anytime by re-running setup.
+#### Forking docs into the repo
+
+`tbd docs fork <name>` (or `--all`) copies managed docs into a visible, git-tracked
+`docs/tbd/` folder; tbd then serves your copies everywhere it served the upstream ones.
+`tbd docs update` three-way merges upstream changes into forked copies after an upgrade;
+`tbd docs status` shows each doc’s state.
+See “Managing Docs” in `tbd docs show tbd-docs` for the full model.
 
 #### Adding external docs by URL
 
@@ -76,7 +83,8 @@ GitHub blob URLs are automatically converted to raw URLs.
 If direct fetch returns HTTP 403, the system falls back to `gh api` for authenticated
 access.
 User-added shortcuts are stored in `shortcuts/custom/` to keep them separate from
-bundled docs.
+bundled docs. The unified form is `tbd docs add <docref>` (the per-kind flags remain as
+aliases), and `docs_cache.local_dirs` can serve additional in-repo doc directories.
 
 <!-- This document follows common-doc-guidelines.md.
 See github.com/jlevy/practical-prose and review guidelines before editing.