feat(templates): refresh CLAUDE.md + AGENTS.md to P1–P19 + lockstep test#15
Closed
broomva wants to merge 3 commits into
Closed
feat(templates): refresh CLAUDE.md + AGENTS.md to P1–P19 + lockstep test#15broomva wants to merge 3 commits into
broomva wants to merge 3 commits into
Conversation
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (5)
📝 WalkthroughWalkthroughThis PR expands the bstack governance model from 13 to 20 primitives, updates documentation templates with full discipline definitions and short-name index conventions, introduces Plugin Skill Precedence rules, and adds a lockstep test to validate cross-file consistency. ChangesGovernance Primitive Expansion
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
…1–P19
Templates were stuck at "thirteen primitives" (P1–P13) while bstack
SKILL.md, scripts/doctor.sh, and references/primitives.md had moved to
nineteen (P1–P19). This scaffolded every new workspace into permanent
disagreement with the catalog — `bstack bootstrap` produced governance
files that `bstack doctor` then reported as having six missing primitive
sections.
Changes:
1. **CLAUDE.md.template** (+58/-22): rewritten to nineteen primitives
with the full table (P1–P19), short-name convention + index, Plugin
Skill Precedence section (bstack > superpowers hierarchy), updated
governance/hooks/conventions sections, Self-Documenting Standards
block.
2. **AGENTS.md.template** (+220/-14): bumped intro to nineteen, every
### P# heading renamed to "### P# — Name: …" form, short-name
convention + index added, full bodies for P14 (Dep-Chain), P15
(Snapshot), P16 (Crystallize), P17 (Lens), P18 (Audience), P19
(Orchestrate) — each with What/How/Invariant/Reflexive Trigger Rule.
Composition-loop diagram rewritten in short-name form with P14–P19
threaded at pre-flight + boundary crossings. Plugin Skill Precedence
section after composition loop documents the bstack > plugin hierarchy
and the "what this kills / what this keeps" partition.
3. **SKILL.md** (+1/-1): tiny drift fix — body said "16 primitives"
while frontmatter said "nineteen". Now consistent.
4. **tests/template_lockstep.test.sh** (new, 188 lines): asserts
primitive-count and structural consistency across the four
governance surfaces that must agree:
- SKILL.md frontmatter description (canonical count word + P19
reference + P1–P19 trigger span)
- scripts/doctor.sh EXPECTED_COUNT (the validator)
- assets/templates/CLAUDE.md.template (intro count, table rows,
short-name index entry count, Plugin Skill Precedence presence)
- assets/templates/AGENTS.md.template (intro count, composition-loop
intro, ### Pn section count, Plugin Skill Precedence presence)
- Short-name index payload identity between the two templates
13 assertions, all green at canonical count = 19. Designed to be the
guardrail that makes this kind of drift CI-visible — when the next
primitive is added (P20 in flight), this test catches any template
that didn't get updated.
Numbering uses **bstack canonical ordering**: P7=Freshness, P8=Janitor,
P9=Wait. This matches the prior template state and bstack catalog
(SKILL.md, doctor.sh, references/primitives.md). The ~/broomva workspace
itself uses P7=Wait, P8=Freshness, P9=Janitor because of historical
script + config-dir naming (BROOMVA_P8_HOME, ~/.config/broomva/p9-
janitor/); that's a workspace-specific deviation documented in
workspace#54 and is NOT a template concern — new bstack installs get
clean canonical numbering.
Companion to broomva/workspace#54 (precedence + short names + P19 in
workspace governance). Independent of bstack#14 (P20 sync) — that PR
adds P20 to the catalog; once it merges, a follow-up updates these
templates + lockstep test to canonical=20.
Follow-ups (separate PRs):
- bootstrap.sh + revamp.sh ORDERED_SKILLS divergence from SKILL.md
ROSTER (bootstrap installs persist + wealth-management + investment-
management; ROSTER instead has autonomous + role-x).
- P20 propagation to templates after bstack#14 merges.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Companion to #14 (Cross-Model Adversarial Review Gate). bstack catalog moved to twenty primitives via #14 (SKILL.md / doctor.sh / references/ primitives.md updated) but #14 did not touch templates. That's exactly the drift this PR was created to close, and exactly what the new template_lockstep.test.sh caught immediately after rebase: --- before this commit --- CLAUDE.md.template intro says 'twenty irreducible primitives (P1–P20)' → FAIL (says nineteen / P19) AGENTS.md.template intro says 'twenty irreducible building blocks' → FAIL AGENTS.md.template composition-loop intro says 'twenty primitives' → FAIL AGENTS.md.template ### Pn section count → FAIL (19, expected 20) CLAUDE.md.template primitive table row count → FAIL (19, expected 20) CLAUDE.md.template short-name index entry count → FAIL (19, expected 20) AGENTS.md.template + CLAUDE.md.template references P20 → FAIL --- after this commit --- All 13 lockstep checks passed at canonical count = 20 (twenty) Changes: - **assets/templates/CLAUDE.md.template**: count phrase "nineteen → twenty", "P1–P19 → P1–P20", short-name index appends "Cross-Review (P20)", primitive table gets P20 row (mechanism: 3 strata A/B/C, anti-slop ≥7/10, ≤3 fix rounds, broomva/cross-review skill; invariant: substantive PRs require ≥7/10 verdict before Pipeline P4 auto-merge). - **assets/templates/AGENTS.md.template**: count phrase nineteen→twenty in intro + composition-loop, short-name index appends Cross-Review (P20), new `### P20 — Cross-Review` section with full What/How (3-strata table) / Invariant / Reflexive Trigger Rule (5 triggers). Composition-loop diagram threads Cross-Review (P20) between Empirical (P11) deploy verification and Pipeline (P4) auto-merge — the exact insertion point per P20 spec ("gate fires before P4 auto-merge"). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
broomva
force-pushed
the
feat/template-refresh-precedence-short-names
branch
from
e740820 to
c633f5c
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@assets/templates/CLAUDE.md.template`:
- Line 42: Update the stale range "Bstack primitives (P1–P19)" in the
CLAUDE.md.template to "P1–P20" so Cross-Review (P20) is included; locate the
phrase "Bstack primitives (P1–P19)" in the template and replace the numeric
range to match the canonical P1–P20 used elsewhere (intro, summary, index, and
table). Optionally, add or adjust the lockstep test to assert any "P1–P\d+"
range expression in CLAUDE.md.template matches the canonical primitive count to
prevent future drift.
In `@SKILL.md`:
- Around line 60-61: Update the stale counts in the Substrate vs Mode section:
replace "19 primitives + 29 skills" with "20 primitives + 30 skills" in the
Substrate (/bstack) description, and change "19-reflex pipeline" to "20-reflex
pipeline" in the Mode (broomva/autonomous, /autonomous) description so the
document matches the canonical P1–P20 and 30 skills contract.
In `@tests/template_lockstep.test.sh`:
- Around line 13-14: Update the misleading header comments that claim the script
"Exits non-zero on first mismatch" to accurately state that the script
aggregates all failures and exits with a non-zero status at the end; change both
the top-of-file header comment near the descriptive block and the later comment
block (the one around the failure-aggregation logic and summary output) so they
describe aggregated reporting and final exit-on-summary behavior instead of
immediate exit-on-first-mismatch.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 31c40fb5-c813-49cf-8fff-bd2421f908c8
📒 Files selected for processing (4)
SKILL.mdassets/templates/AGENTS.md.templateassets/templates/CLAUDE.md.templatetests/template_lockstep.test.sh
|
|
||
| ## Plugin Skill Precedence | ||
|
|
||
| Bstack primitives (P1–P19) and bstack-native skills (`/autonomous`, `/shape`, `/persist`, `/ship`, `/bookkeeping`, `/p9`, etc.) **supersede** plugin skills (`superpowers:*`, `pr-review-toolkit:*`, `codex:*`) wherever they conflict. Plugin skills carry no weight when they collide with workspace governance — the `superpowers:using-superpowers` skill itself encodes this priority: *"User's explicit instructions … highest priority. … If CLAUDE.md says X and a skill says Y, follow the user's instructions."* |
There was a problem hiding this comment.
Stale primitive range in Plugin Skill Precedence — should be P1–P20.
This sentence still reads "Bstack primitives (P1–P19)" while the rest of the file (intro at Line 5, summary at Line 9, short-name index at Line 13, and table at Lines 15–36) was bumped to P1–P20. Readers parsing this clause as authoritative could conclude that Cross-Review (P20) is excluded from the plugin-skill precedence rule. The lockstep test in this PR validates count fields and (Pn) entries but won't catch prose range expressions like this.
📝 Proposed fix
-Bstack primitives (P1–P19) and bstack-native skills (`/autonomous`, `/shape`, `/persist`, `/ship`, `/bookkeeping`, `/p9`, etc.) **supersede** plugin skills (`superpowers:*`, `pr-review-toolkit:*`, `codex:*`) wherever they conflict.
+Bstack primitives (P1–P20) and bstack-native skills (`/autonomous`, `/shape`, `/persist`, `/ship`, `/bookkeeping`, `/p9`, etc.) **supersede** plugin skills (`superpowers:*`, `pr-review-toolkit:*`, `codex:*`) wherever they conflict.You may also want to extend the lockstep test with an assertion that any P1–P\d+ range expression in either template equals the canonical count, so future bumps don't re-introduce this drift.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Bstack primitives (P1–P19) and bstack-native skills (`/autonomous`, `/shape`, `/persist`, `/ship`, `/bookkeeping`, `/p9`, etc.) **supersede** plugin skills (`superpowers:*`, `pr-review-toolkit:*`, `codex:*`) wherever they conflict. Plugin skills carry no weight when they collide with workspace governance — the `superpowers:using-superpowers` skill itself encodes this priority: *"User's explicit instructions … highest priority. … If CLAUDE.md says X and a skill says Y, follow the user's instructions."* | |
| Bstack primitives (P1–P20) and bstack-native skills (`/autonomous`, `/shape`, `/persist`, `/ship`, `/bookkeeping`, `/p9`, etc.) **supersede** plugin skills (`superpowers:*`, `pr-review-toolkit:*`, `codex:*`) wherever they conflict. Plugin skills carry no weight when they collide with workspace governance — the `superpowers:using-superpowers` skill itself encodes this priority: *"User's explicit instructions … highest priority. … If CLAUDE.md says X and a skill says Y, follow the user's instructions."* |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@assets/templates/CLAUDE.md.template` at line 42, Update the stale range
"Bstack primitives (P1–P19)" in the CLAUDE.md.template to "P1–P20" so
Cross-Review (P20) is included; locate the phrase "Bstack primitives (P1–P19)"
in the template and replace the numeric range to match the canonical P1–P20 used
elsewhere (intro, summary, index, and table). Optionally, add or adjust the
lockstep test to assert any "P1–P\d+" range expression in CLAUDE.md.template
matches the canonical primitive count to prevent future drift.
Comment on lines
+13
to
+14
| # Exits non-zero on first mismatch. No external test framework. | ||
| # |
There was a problem hiding this comment.
Correct the script behavior comment (“first mismatch”).
The header says it exits on the first mismatch, but implementation intentionally aggregates all failures and exits at the end. Please update the comment to match actual behavior.
Also applies to: 177-184
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@tests/template_lockstep.test.sh` around lines 13 - 14, Update the misleading
header comments that claim the script "Exits non-zero on first mismatch" to
accurately state that the script aggregates all failures and exits with a
non-zero status at the end; change both the top-of-file header comment near the
descriptive block and the later comment block (the one around the
failure-aggregation logic and summary output) so they describe aggregated
reporting and final exit-on-summary behavior instead of immediate
exit-on-first-mismatch.
P20 Cross-Review (Strata B fresh-context subagent) on this PR's prior HEAD scored 4/10 NEEDS-FIX. This commit addresses all blockers and high-severity findings; round 1 of max 3 per the P20 reflexive rule. ## Cross-review findings + fixes ### [BLOCKING] doctor.sh regex mismatch with new heading format Previous PR head changed AGENTS.md.template headings from `### P1: Conversation Bridge (Episodic Memory)` to `### P1 — Bridge: Conversation Bridge (Episodic Memory)`. But scripts/doctor.sh line 138 was `grep -qE "^### $prefix:"` — required colon directly after primitive number. Cross-review scaffolded a workspace from the prior templates + ran doctor.sh and got `28/70 passed, 42 gaps` — 20 missing primitive sections + 13 missing reflexive trigger rules, all caused by heading-format regression. The lockstep test (added by prior commit `c633f5c`) gave false-green because it checked `^### P[0-9]+ — ` (the NEW format the PR introduces), not what doctor.sh actually validates. Lockstep was checking the templates were consistent *with themselves* instead of with the validator. Textbook P16 substance-vs-ritual failure. Fix: scripts/doctor.sh:138 regex now `^### $prefix[: ]` — accepts both `### Pn:` (legacy) and `### Pn — Short: Long` (new short-name format). The `[: ]` character class is one char (colon OR space); for prefix=P1, matches "### P1:" and "### P1 — " but not "### P11:" (next char after P1 is '1', neither colon nor space). Same fix on doctor.sh:155 in the awk reflexive-trigger locator. Verified: scaffolded workspace now passes doctor with 0 primitive gaps + 0 reflexive gaps. ### [HIGH] SKILL.md body drift — partial fix in prior commit was misleading Prior commit `22bf59d` fixed line 60 (16→19) and claimed "now consistent" in the message. Cross-review found SKILL.md body STILL said: - L60 "the 19 primitives + 29 skills" (should be 20/30 post-#14) - L61 "19-reflex pipeline" (should be 20) - L84 "The sixteen primitives" (should be twenty) - L267-269 "P1–P16 rows" + "### P1: through ### P16:" + reflexive list ending at P16 - L319 "Primitive contract | 13/13" (should be 20/20) - L393 "full P1–P13 reference" (should be P1–P20) All six lines now corrected. Note L267 doctor-section description now explicitly documents both heading formats supported. ### [HIGH] Lockstep test missed the bug it was supposed to catch Added Section 7 to tests/template_lockstep.test.sh: "Scaffold-and-doctor compliance". The REAL guardrail: scaffold a temp workspace from the templates (mirror bootstrap.sh's scaffold_governance_file flow), run doctor.sh --quiet against it, assert 0 primitive-section gaps + 0 reflexive-trigger gaps. This is lockstep-vs-validator, not just lockstep-vs-self. Auto-discovers canonical count from doctor.sh and runs the full validation pipeline against scaffolded output. Test now has 15 assertions (was 13). All pass at canonical=20. ### [MEDIUM] P20 paraphrase dropped "Linear ticket" Per `references/primitives.md` §P20, the verdict is "logged in PR comments + Linear ticket". Templates said "logged in PR" only. Both CLAUDE.md.template and AGENTS.md.template P20 entries now say "logged in PR comments + Linear ticket (if workspace uses Linear)" — preserves spec fidelity while acknowledging workspace-optional Linear. ## Test plan - [x] `bash tests/template_lockstep.test.sh` — 15/15 PASS at canonical=20 - [x] Scaffold-and-doctor section confirms 0 primitive gaps + 0 reflexive gaps when templates are instantiated into a fresh workspace + doctor runs against it - [x] Cross-review's specific verification command reproduced locally (scaffold + doctor with BROOMVA_WORKSPACE override) — passes ## Re-fire cross-review post-push This is round 1 of 3 per P20 rule. After CI green, re-fire P20 gate (Strata B fresh subagent) to rescore. Target ≥7/10 for merge. Cross-review verdict log: stored in this PR's comments after re-run. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
6 tasks
Owner
Author
|
Closing — bulk content absorbed via #16. When this PR's branch (
While this PR was in P20 cross-review, #16 ("align P7/P8/P9 numbering to workspace canonical") merged. #16 contains substantively the same content as #15 (same author pattern, parallel agent session). Diff of this branch vs current main: mostly redundant. The unique residual value from this PR's b80fac9 commit (round-1 P20-cross-review-driven polish):
These three items have been cherry-picked onto a fresh branch off current main and submitted as #17. The doctor.sh regex change from b80fac9 was dropped (redundant with #16's identical fix using slightly different regex syntax). PR #15 closed in favor of #17. See #17 for the cleanly-rebased version. |
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
1 participant
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
Templates were stuck at "thirteen primitives" (P1–P13) while bstack's own SKILL.md /
scripts/doctor.sh/references/primitives.mdhad moved to nineteen. Everybstack bootstrapagainst a new workspace scaffolded governance files thatbstack doctorthen reported as having six missing primitive sections. This PR closes the drift and adds a lockstep test so it can't recur silently.Changes
assets/templates/CLAUDE.md.template(+58/-22): rewritten to nineteen primitives. Full table P1–P19, short-name convention (Name (Pn)form) + index, Plugin Skill Precedence section (bstack > superpowers hierarchy), Self-Documenting Standards.assets/templates/AGENTS.md.template(+220/-14): bumped intro to nineteen, every### P#heading renamed to### P# — Name: …, short-name convention + index, full bodies for P14 Dep-Chain, P15 Snapshot, P16 Crystallize, P17 Lens, P18 Audience, P19 Orchestrate (each with What/How/Invariant/Reflexive Trigger Rule). Composition-loop diagram rewritten in short-name form with P14–P19 threaded. Plugin Skill Precedence section documents what the hierarchy kills (form-fill ritual) and what it keeps (TDD, requesting-code-review, subagent-driven-development, etc.).SKILL.md(+1/-1): tiny drift fix — body said "16 primitives" while frontmatter said "nineteen".tests/template_lockstep.test.sh(new, 188 lines): 13 assertions across the four governance surfaces that must agree (SKILL.md frontmatter,doctor.shEXPECTED_COUNT, CLAUDE.md.template, AGENTS.md.template). Auto-discovers the canonical count fromdoctor.shso it stays valid as the count grows. All green at canonical=19.Numbering
Templates use bstack canonical ordering: P7=Freshness, P8=Janitor, P9=Wait. Matches the prior template state and the bstack catalog (SKILL.md, doctor.sh, references/primitives.md). The
~/broomvaworkspace itself uses P7=Wait, P8=Freshness, P9=Janitor because of historical script + config-dir naming (BROOMVA_P8_HOME,~/.config/broomva/p9-janitor/) — that's a workspace-specific deviation documented in workspace#54, NOT a template concern. New bstack installs get clean canonical numbering.Test plan
bash tests/template_lockstep.test.sh— 13/13 pass.bash scripts/doctor.shagainst a workspace scaffolded from these templates should now report 0 primitive-section gaps (vs 6 before).bash tests/onboard.test.shshould remain green.bootstrap.sh/revamp.sh/doctor.sh— scope kept to template refresh + lockstep guardrail.Coordination with in-flight PRs
Follow-ups (separate PRs)
bootstrap.sh/revamp.shskill list reconciliation — bootstrap'sORDERED_SKILLSincludespersist + wealth-management + investment-managementbut is missingautonomous + role-x; SKILL.md'sROSTERhas the opposite. Pick a canonical (probably SKILL.md), align the installer.~/broomva's scripts/config dirs to canonical, or havedoctor.shvalidate against an explicit per-workspace numbering map. Out of scope for templates; affects only the~/broomvainstall.🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Tests