feat(0.24.0): scaffold Development Philosophy into AGENTS.md/CLAUDE.md on install (BRO-1406)

[broomva]

What

Every newly-bootstrapped workspace now inherits an explicit Development Philosophy section in its scaffolded AGENTS.md (+ a short anchor in CLAUDE.md), so downstream development follows the philosophy by default — cohesively with the user's own project. Previously the scaffold deployed the mechanism (the P1–P20 contract) without the intent.

Closes BRO-1406.

Why

The 20 primitives are the how; new repos got no why. The most-starred public CLAUDE.md (multica-ai/andrej-karpathy-skills, ~168k★) proves enormous demand for four guiding principles — Think Before Coding · Simplicity First · Surgical Changes · Goal-Driven Execution — but leaves them as prose ritual. bstack's edge is the Ritual-vs-Substance rule: each principle is bound to the primitive that makes it machine-checkable (Think→P14+P15, Simplicity→P20, Surgical→P10, Goal→P11+P19).

Changes

• assets/templates/AGENTS.md.template — new ## Development Philosophy section between Self-Meta Definition and the primitives table (the why frames the how): 4-principle → enforcing-primitive table + the binding Ritual-vs-Substance rule + an explicit "extend it with your own principles" invitation.
• assets/templates/CLAUDE.md.template — short philosophy anchor → AGENTS.md#development-philosophy.
• references/new-workspace-flow.md — deployed-files note updated.
• CHANGELOG.md + VERSION → 0.24.0.

Dep-chain

• Upstream: the four principles (Karpathy lineage + Ritual-vs-Substance rule), mapped to existing primitives. KG: research/entities/tool/karpathy-claude-md-guidelines.md.
• Downstream: scripts/bootstrap.sh Phase 2 (scaffold_governance_file) copies templates verbatim → no code change needed. Idempotent-never-overwrite → new installs get it; existing workspaces unaffected (backfill is a deferred bstack doctor/repair follow-up).
• Primitive count unchanged (20) — governance-substrate content, not a P-row (respects L3 stability budget λ₃≈0.006).

Verification (P11)

Ran the real scaffold into a temp git repo (BSTACK_SKIP_SKILLS/RCS=1): both AGENTS.md and CLAUDE.md contain the section, all 4 principle rows present, {{WORKSPACE_NAME}} substituted (# fresh-repo — Agent Guidelines).

Deferred (follow-ups, not in this PR)

1. bstack doctor lint for the section (makes it contract-enforced; lets repair backfill existing workspaces).
2. Dogfood into bstack's own root governance + ~/broomva.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Added Development Philosophy section to workspace templates introducing guiding principles for agent and development guidance.
  • Updated workspace deployment documentation to reflect philosophy integration.

• Chores

  • Version bumped to 0.24.0.

[linear]

BRO-1406

[coderabbitai]

Warning

Review limit reached

@broomva, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 50 minutes and 48 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

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 include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0907eca6-edc4-4d17-af7d-7e1c72c79648

📥 Commits

Reviewing files that changed from the base of the PR and between 78011c7 and f90a803.

📒 Files selected for processing (4)

• CHANGELOG.md
• assets/templates/AGENTS.md.template
• assets/templates/CLAUDE.md.template
• references/new-workspace-flow.md

📝 Walkthrough

Walkthrough

PR scaffolds a Development Philosophy section into agent and Claude workspace templates, mapping four guiding principles to enforcing primitives. Deployment documentation and release notes are updated accordingly, with VERSION bumped to 0.24.0.

Changes

Development Philosophy Template Scaffolding

Layer / File(s)	Summary
Development Philosophy Definitions in Agent Templates assets/templates/AGENTS.md.template, assets/templates/CLAUDE.md.template	Four principles—Think before coding, Simplicity first, Surgical changes, Goal-driven execution—are introduced and mapped to machine-checkable primitives, with guidance for extending principles while preserving the primitive enforcement layer.
Documentation and Version Release references/new-workspace-flow.md, CHANGELOG.md, VERSION	Deployment flow documentation enumerates the four principles and their primitive bindings; CHANGELOG.md records the 0.24.0 release (2026-06-05) with notes on non-changes to bootstrap behavior and primitive count; VERSION bumped from 0.23.2 to 0.24.0.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related issues

• bstack: scaffold Development Philosophy section into AGENTS.md/CLAUDE.md on install life#1627: Implements the same Development Philosophy scaffolding into workspace templates and deployment documentation.

Possibly related PRs

• broomva/bstack#50: Modifies references/new-workspace-flow.md to document Development Philosophy governance principles and their primitive mappings in deployed workspaces.
• broomva/bstack#4: Modifies assets/templates/AGENTS.md.template and assets/templates/CLAUDE.md.template to extend/restructure agent governance principles and primitives content.

Poem

🐰 A philosophy springs forth in green,
Four principles, machine-checkable, keen—
Think, simplify, cut surgical, win,
Documented in templates we spin. 📋
Version bumped, release notes shine bright! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: scaffolding a Development Philosophy section into AGENTS.md and CLAUDE.md templates as part of version 0.24.0, with relevant ticket reference.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/scaffold-development-philosophy

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[broomva]

P20 Cross-Review verdict: ✅ PASS (8/10)

Strata A — true cross-vendor (Codex gpt-5.4), 3 fix rounds.

Round	Score	Findings → resolution
1	4/10 BLOCK	undefined /simplify ref (dropped) · Surgical→P10 overclaim · Goal-driven→/goal inconsistency (→P11+P19) · changelog hype
2	6/10 BLOCK	Surgical→P10 still overclaimed → remapped to P14 (bounds surface) + P20 (flags tangential edits) · changelog still advocacy
3	8/10 PASS	changelog stripped to neutral fact; provenance kept in Notes. "keeps the philosophy as substrate text rather than inventing a 21st primitive, preserves the 20-primitive contract"

Net effect: the gate caught that the original diff overclaimed enforcement strength — mapping principles to primitives more tightly than the actual predicates support. Final version adds an explicit enforcement-strength-varies note (hard predicate vs judgment gate), which is both accurate and on-thesis.