process: Add forkable docs workflow plan spec#167
Merged
Conversation
Plan spec for a minimal shadcn-style eject/uneject workflow: copy bundled guidelines/shortcuts/templates into a visible, git-tracked docs/tbd/ folder, shadow the bundled copies via existing DocCache precedence, track provenance in a committed .tbd/ejected.yml manifest, add setup opt-ins and an upstream-contribution playbook. Deliberately the forward-compatible kernel of the larger PR #117 docs-config redesign, with no f04 format break. https://claude.ai/code/session_017S2YnirprCMG8ihkGdRBsS
 |
|
Overall Grade |
Security Reliability Complexity Hygiene |
Code Review Summary
| Analyzer | Status | Updated (UTC) | Details |
|---|---|---|---|
| Secrets |  |
Jun 11, 2026 11:30p.m. | Review ↗ |
Important
AI Review is run only on demand for your team. We're only showing results of static analysis review right now. To trigger AI Review, comment @deepsourcebot review on this thread.
Generated by tbd setup at session start; the v0.2.3 release did not regenerate these pinned fallback scripts. https://claude.ai/code/session_017S2YnirprCMG8ihkGdRBsS
Coverage Report for packages/tbd
File CoverageNo changed files found. |
Fills the gap around upgrading tbd after ejecting: tbd eject --update refreshes unmodified copies and applies clean git three-way merges by default; conflicting docs are listed and only merged (with standard conflict markers) via opt-in --merge. Requires storing committed merge bases (.tbd/eject-base/) since a hash alone cannot drive a three-way merge; adds --rebase, conflicted-state tracking with marker auto-clear, and updates goals, states, CLI surface, phases, and tests accordingly. https://claude.ai/code/session_017S2YnirprCMG8ihkGdRBsS
Replaces the top-level eject/uneject commands and verb-flags (--update, --status, --rebase) with a noun-scoped tbd docs group per design review: docs eject/uneject/update/rebase/status/diff plus docs sync (absorbing tbd sync --docs as a deprecated alias) and kind-agnostic docs list/show. tbd self-docs join the system under a reserved tbd- name prefix as reference-kind docs (manual becomes tbd docs show tbd-docs; bare tbd docs is now the status overview). Records resolved decisions, renumbers open questions, and updates plan phases and tests to match. https://claude.ai/code/session_017S2YnirprCMG8ihkGdRBsS
…y flags Records resolutions from design review: docs/tbd default eject dir (setup-editable, persisted to config), README index with npx get-tbd pointer, .tbd/eject-base placement, tbd docs manual alias with no compat for the old bare-docs viewer, and eject/uneject verbs. Folds the standalone rebase subcommand into mutually exclusive update strategy flags (--merge combines with conflict markers; --rebase keeps local content and advances the fork point). Adopts a proper f04->f05 format bump with metadata-only migration, following the f04 precedent; notes PR #117's draft format id shifts to f06+. Two questions remain open (--relevant as setup default; packs in code vs frontmatter tags). https://claude.ai/code/session_017S2YnirprCMG8ihkGdRBsS
Generalizes beyond bundled/ejected locations by adopting two conventions from the PR #117 branch: docref becomes the universal source-address grammar now (parser ported as-is; internal: and URLs already conform; replaces ad-hoc blob-URL conversion), and docmap's generated-map schema becomes the --json output contract for docs list/status (the read side), while its manifest/lockfile/sync write side stays in the f06 framework. Adds docs_cache.local_dirs for serving docs from other in-repo directories and tbd docs add <docref> consolidating per-kind --add. Both format docs ship as bundled reference-kind docs with status banners. https://claude.ai/code/session_017S2YnirprCMG8ihkGdRBsS
Per design review: docref-everywhere is recorded as a hard rule (every document reference in config, manifests, CLI args, JSON output, and docs is a docref string). docmap is redefined as just the essential concept - a machine-readable inventory of a doc collection (identity, location, provenance docref, metadata per entry) - producer-agnostic and hand-authorable, with an inline v0.1 schema example. The shipped docmap-format reference doc will be authored fresh rather than adapted, citing the speculative PR #117 draft only as exploratory background; manifests/lockfiles/sync are deferred as future operations over docmaps. Drops the provisional bundle field from v1 JSON output. https://claude.ai/code/session_017S2YnirprCMG8ihkGdRBsS
Foreign docref sources sharpen three areas: the eject manifest now records source_revision (and source_tag when applicable) for git-hosted sources at every base advance, with stored base snapshots remaining the universal fallback for revision-less sources; docs sync groups files entries by source root (one fetch per git repo+ref, internal: as one group, standalone URLs individually) with per-group failure isolation so a vanished source or bad doc never aborts the rest and cache is never pruned on fetch failure; update stays offline against the cache so unreachable sources only affect staleness freshness, surfaced in status and doctor. Adds the eject-vs-fork terminology question (with a recommendation to adopt fork/unfork + upstream) as open question 1. https://claude.ai/code/session_017S2YnirprCMG8ihkGdRBsS
…st design Adds a 'three kinds of sync' design section with a scope table: tbd sync (issues), tbd setup (installation/integrations, may invoke a docs-cache sync), tbd docs sync (cache, grouped + failure-isolated), and tbd docs update (the only doc command that writes tracked files; offline). A universal sync command is explicitly rejected since doc updates can involve merges. Removes the interactive setup plan: the never-prompting --interactive flag is dropped, and setup --auto becomes self-documenting (eject options as copy-paste commands with a read-only --relevant detection preview), with agent-led conversational onboarding as the choice mechanism. Recorded as decisions 12-13. https://claude.ai/code/session_017S2YnirprCMG8ihkGdRBsS
Adopts the fork vocabulary throughout (the eject terms fit the all-inside-tbd world; with docref sources docs are multi-origin and the fork lifecycle - fork point, merge, rebase, unfork, contribute - is the accurate model): verbs fork/unfork, state forked, docs_cache.fork_dir, and the former bundled state renamed upstream, with bundled/built-in reserved for tbd-shipped internal: docs. Eject remains a skill routing synonym. All fork state consolidates under one committed .tbd/doc-forks/ directory (forks.yml manifest + base/ snapshots), and a new layout- contract section plus a generated .tbd/README.md document the exact contract of every .tbd entry: docs/ keeps its f04 cache mechanics verbatim (gitignored, regenerated, disposable) while doc-forks/ is the committed, precious fork state. Records that the f05 upgrade gate is what makes the reorganization and CLI-semantics changes safe to ship together. Resolved decisions 14-15; open questions down to two. https://claude.ai/code/session_017S2YnirprCMG8ihkGdRBsS
jlevy
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
docs/project/specs/active/plan-2026-06-11-eject-forkable-docs.md: a plan spec for a minimal, shadcn-style fork/unfork/update workflow that makes built-in and external guidelines, shortcuts, and templates visible, forkable, git-tracked files in the user's repo — the lightweight alternative to the full docs-config redesign explored in #117. (Terminology evolved during review from eject/uneject to fork/unfork, matching the multi-origin reality once docref sources arrived; "eject" remains a skill-routing synonym.)Core design (deliberately the smallest forward-compatible slice of #117):
tbd docscommand group (matching tbd'sdep/label/atticnoun-verb convention) owns the doc layer:fork,unfork,update,status,diff,sync(absorbingtbd sync --docs),add <docref>, kind-agnosticlist/show,manual. Baretbd docs= status overview. A "three kinds of sync" table fixes the taxonomy:tbd sync= issues;tbd setup= integrations;tbd docs sync/update= doc layer — a universal sync was explicitly rejected (doc updates can involve merges).tbd docs fork <name> | --pack=<lang> | --relevant | --allcopies docs verbatim into a git-trackeddocs/tbd/folder (setup-editable, persisted todocs_cache.fork_dir), shadowing upstream copies via the existingDocCachelookup. A generated README index explains the folder.tbd docs updatereconciles forks after upgrades viagit merge-file: unmodified copies refresh, clean three-way merges apply automatically; conflicting docs are listed until you choose a strategy —--merge(combine with conflict markers) or--rebase(keep yours, advance the fork point). Sync is grouped by source root (one fetch per git repo+ref, per-group failure isolation; a vanished source never aborts the rest and never prunes cache)..tbd/doc-forks/—forks.yml(manifest: source docref, hashes, andsource_revision/source_tagfor git-hosted sources) plusbase/(verbatim merge-base snapshots, the universal fallback for revision-less sources). A new layout-contract section plus a generated.tbd/README.mddocument every.tbd/entry;.tbd/docs/keeps its f04 gitignored-cache mechanics verbatim.--jsoncontract; both ship asreference-kind docs (docmap's spec authored fresh, citing process: Add docs config redesign plan spec #117 only as exploratory).docs_cache.local_dirsserves docs from other in-repo directories.--interactiveflag is removed;setup --autoprints a self-documenting menu with a read-only--relevantdetection preview; agents offer the choice conversationally.docs status --json→docs diff→ filing a GitHub issue on jlevy/tbd; convergence after upstream adoption makes unfork a plaintbd docs unfork.The spec includes the doc-state model (upstream/forked/customized/stale/conflicted/local/missing/orphaned), the update decision table (default/
--merge/--rebase), full CLI surface, backward-compatibility requirements, alternatives considered, 15 resolved decisions, 2 remaining open questions, a 5-phase 20-bead implementation plan, and a testing strategy.Relationship to #117
Positioned as the implementable kernel: docref adopted wholesale, docmap redefined and reduced to its inventory essence, manifest+bases map to the framework's override edges, and the passive-cache/explicit-update split maps to its
sync/source updatecontract. Nothing constrains its open questions Q15–Q19.Test plan
--relevantas fresh-setup default; pack definitions in code vs frontmatter tags)https://claude.ai/code/session_017S2YnirprCMG8ihkGdRBsS