Repository navigation
docs: restructure README for gradual adoption and current workflows - #313
Conversation
 |
|
Overall Grade |
Security Reliability Complexity Hygiene |
Code Review Summary
| Analyzer | Status | Updated (UTC) | Details |
|---|---|---|---|
| Secrets |  |
Oct 2, 2026 6:32a.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.
Coverage Report for packages/tbd
File CoverageNo changed files found. |
Record the landing-page restructure review: optionality as the spine, incremental adoption, and what not to duplicate from shortcuts or policy docs. Co-authored-by: Joshua Levy <joshua@cal.berkeley.edu>
The main-branch doc-reference test resolves tbd shortcut/guidelines names found in docs/. Point at #309 file paths for setup-tbd and agent-policy-grants instead of those commands. Co-authored-by: Joshua Levy <joshua@cal.berkeley.edu>
The IA review stays the rationale. The rewrite follows the user's positioning as the opening rather than the draft snippet in section 9. Co-authored-by: Joshua Levy <joshua@cal.berkeley.edu>
The user chose not to execute the medium IA pass. The addendum now says the #309 structure stays and only the opening/background framing changes. Co-authored-by: Joshua Levy <joshua@cal.berkeley.edu>
eedd1a5 to
2bfd7d9
Compare
jlevy
changed the title
There was a problem hiding this comment.
Review A (senior engineering review, round 1) · head 2bfd7d9d · base main at f08eeee9
Reviewer: coordinator session, GPT-6; exact model variant and reasoning setting are not exposed. This review includes fixes written by the coordinator and is not independent. A separate read-only sub-agent reviewed the full pinned diff and found no actionable issues. Channel: formal review.
Coverage: 7 of 7 changed files, including the README, revised review/implementation plan, design introduction, source skill, and all three generated skill copies. Nothing skipped. Same-repository owner-authored PR; execution trusted. Remote stack lookup returned no membership.
Tests run: 72 targeted documentation/routing/generated-skill contract tests; both doc-reference tests; 27 prime CLI golden checks; isolated setup fixtures; all 135 relative links/anchors; package and CLI README comparison. Full pre-push and final-head CI results are recorded below.
Summary and verdict
The README now gives a useful first-session path and makes gradual adoption and customization explicit while preserving the broader coding-quality, task-tracking, and workflow pitch. It is 486 lines instead of 677, with all generated catalogs retained in a collapsible appendix. The outdated proposal was replaced with the implemented plan.
Verdict: no outstanding actionable findings. This records review evidence; it does not merge the PR.
Findings
None at the reviewed head. The proposal review and implementation addressed minimal initialization versus default setup, per-run surface selection, policy defaults and stack handling, independent web/watch use, documentation customization, and stale or overstated claims. The final audit’s link-description correction and the suite’s missing template-example check are also resolved.
Suggestions
None requiring follow-up.
Design assessment
Progressive disclosure with links to maintained procedures fits this landing page better than duplicating policy schemas and merge checklists. Keeping the generated catalogs preserves discovery and existing drift protection without another hand-maintained list. The remaining request table intentionally preserves the exact review/fix/merge vocabulary covered by contract tests.
Documentation
Capability descriptions agree across README, design, source skill, and generated copies. The packaged README and tbd readme match the root source. The revised plan documents the decision, validation, and maintenance map; tbd-athj tracks delivery.
False positives / do not fix
- Surface selection intentionally neither uninstalls existing files nor persists the selection. Isolated CLI fixtures confirm both behaviors.
- Generated catalog counts and contents remain generated; they should not be manually rewritten.
- This PR changes documentation only. Model defaults and recorded policy grants are unchanged. Dedicated security, performance, or intricate-runtime-correctness reviews are not applicable to this diff.
CI status
All seven checks pass at the unchanged reviewed head 2bfd7d9db350cde3769e9392d35fc9bd0d794c04: macOS Node 24, Windows Node 24, Ubuntu Node 22.12.0 and Node 24, Coverage & Lint, Benchmark, and DeepSource Secrets. CI run.
Normal local pre-push gates also passed: formatting, lint, type checks, build, 3,017 tests (one existing skip), and package-age audit. The initial full run caught the omitted template example; its fix passed the targeted doc-reference check and the complete pre-push suite. One targeted fixture setup timed out once; its normal retry and the complete suite passed.
jlevy
left a comment
jlevy
left a comment
There was a problem hiding this comment.
Review B (follow-up review, round 2) · head 60e2dee573706c300b09ef67279736d05bdee19e · base f08eeee90b7f941a46cc070e0b95d5f820e7c224
Reviewer: Sol sub-agent /root/model_audit, requested gpt-6-sol; tier/reasoning inherited and not separately recorded. The reviewer authored none of the lower-layer follow-up. Channel: formal review, published by coordinator.
Coverage: All seven files changed since prior accepted head 2bfd7d9d: README, setup-tbd introduction, canonical skill, all three generated copies, and review checklist. No new delta skipped. The unchanged design file remains covered by Review A.
Summary and verdict
No remaining actionable findings in the follow-up scope. The README and reusable skill now match the actual first-install path, and prime renders a distinct initialization command before the policy-review handoff. The user-reported bootstrap failure is covered by a behavioral sequence regression.
Stack: README #313 remains the lower documentation layer; release #321 includes the prime guidance fix, regression coverage and release notes. The user has authorized merging and publishing v0.10.0 after the normal gates pass.
Findings and dispositions
None at the final head. During implementation, the reusable skill bootstrap path was corrected in 60e2dee5; source review and generated-skill drift tests verify initialization precedes shortcut lookup.
Suggestions
None requiring follow-up.
Design and scope
Both supported entry points are explicit: the user installs the CLI, or asks the agent to run npm install -g get-tbd@latest. Installation is followed by prime, user-chosen prefix, repository initialization, then the setup shortcut for policy review. Prime supplies instructions; the agent runs setup. Existing projects refresh without choosing another prefix. Repository-owned beads/plans support coordination across Claude Code and Codex sessions without prescribing platform roles or promising conversation-state synchronization.
False positives / do not fix
- Shortcut lookup before initialization still refuses intentionally; the fix supplies the available bootstrap path instead of silently initializing with a guessed prefix.
- The setup shortcut may refresh setup again after initialization; setup is idempotent.
- Prior security/correctness reviews remain pinned to their original commits and cover unchanged release-safety code. This follow-up does not reattribute them to the new head.
- The documented downstream development-audit exception remains disclosed; do not call its full verify gate all green.
Validation
Coordinator: 64 prime/setup tests passed across the initial run and the isolated rerun of one unrelated timeout; 29 documentation/generated-skill checks and 27 prime CLI golden checks passed. The sequence regression verifies shortcut refusal before init, actionable prime guidance, explicit-prefix setup, and successful shortcut lookup afterward. Reviewer performed source inspection only. The normal push gates then passed formatting, lint, types, build and all 192 test files (3,028 passed, one existing skip). Eighteen setup-hook tests passed after replacing a legacy fixture completion budget with the shared subprocess timeout helper; assertions and performance gates are unchanged.
Final candidate package, upgrade, compatibility, web and metadata proofs passed. An isolated npm global installation reports 0.10.0 and zero runtime advisories; the fresh prime/setup/shortcut flow succeeds. Downstream tryscript passes its functional gates, 252 unit tests and 108 compatibility assertions; repeat upgrade is byte-identical. Its full verify exits 1 only for the same six pre-existing development advisories as baseline, with identical advisory records.
CI status
All seven expected checks passed at this exact head. CI run 36974010985 concluded success for Ubuntu Node 22.12.0/24, macOS Node 24, Windows Node 24, Coverage and Lint, and Benchmark; DeepSource Secrets also passed. The user separately authorized the merge and release; this review is validation evidence, not that authorization.
1 participant
The README now introduces first use, gradual adoption, customization, and shared work across Claude Code and Codex sessions. Tasks, plans, specs, and progress live in the Git repository, independent of a particular agent account or app state.
The README is 505 lines, down from 677. No runtime behavior, model defaults, dependencies, or policy grants change in this layer. The prime runtime guidance and behavioral regression are in upper release PR #321, within formal stack #322.
Plan: README review and implementation. Tracking:
tbd-athj,tbd-aoe3,tbd-0ai1.Validation: 72 original documentation/routing checks, all 135 original relative links/anchors, isolated setup fixtures, and package/CLI README parity. Follow-up validation passed 29 documentation/generated-skill checks and 27 prime golden checks. The final stack passed normal push hooks, formatting, lint, types, build, and 3,028 tests (one existing skip). Final candidate package and installed bootstrap proofs are recorded on #321.
Exact lower head:
60e2dee573706c300b09ef67279736d05bdee19e. All seven checks passed in CI run 36974010985, including DeepSource Secrets. Pinned original review A and independent Sol follow-up B cover the full change. The user has authorized merging the ready stack and publishing v0.10.0.