This README exists so the state of this system is legible on its own, without re-deriving it from conversation history. It documents what's built, what's explicitly deferred and why, and what's genuinely still open. Update it whenever a file here is added, restructured, or a deferred decision gets made.
The rules here don't do anything sitting in this repo by themselves — this
repo is the source of truth for the rule content, not something that runs on
its own PRs. To actually get PR reviews from it, copy the two workflow files
in install/.github/workflows/ into your own
repo, add an ANTHROPIC_API_KEY secret, and open a PR. Full setup and how
the feedback/scoring loop works: install/README.md.
No contributions yet — see install/scripts/contribute-stats.py (in the audit-action
kit installed alongside this repo in a target project) to report your own
audit's anonymized numbers.
Files are organized dimension-first, then tier, per 00-method/BELIEF_SYSTEM_METHOD.md
Section 8 (the Three-Tier Operating Structure: Belief System → Protocols → Skills).
00-method/ The construction method itself — domain-agnostic, applies to any institution.
00-founding/ The one founding belief system for this practice, and the
protocol that adjudicates between the functional systems below it.
performance/
01-belief-system/ BELIEF_SYSTEM_react-performance.md
02-protocols/ Rule authoring, prioritization, audit & verify
03-skills/ Client-interaction-audit and verify-escalation skills, plus:
rules/ 70 individual rule files (async-, bundle-, server-, client-,
rerender-, rendering-, js-, advanced-) — the actual
Incorrect/Correct content, vendor-independent.
composability/
01-belief-system/ BELIEF_SYSTEM_react-composability.md
02-protocols/ PROTOCOL_react-composability-rules.md
03-skills/
rules/ 8 rule files (architecture-, state-, patterns-), plus
react19-no-forwardref.md tagged `status: candidate` —
it doesn't yet cleanly map to the belief system's 5
load-bearing distinctions (see that protocol's Ad Hoc
Application mechanism); flagged for a human promotion
decision, not asserted as a settled rule.
motion/
01-belief-system/ BELIEF_SYSTEM_react-motion.md
02-protocols/ PROTOCOL_react-motion-authoring.md
03-skills/
rules/ 5 pattern files (shared-element, suspense-reveal,
list-identity, state-change, route-change) — one per
row of the source material's implementation-order
table, each tagged with which of the protocol's 4
mechanisms it instantiates.
Each rules/*.md file's front matter carries id, title, category, tier
(the abstract Impact/Risk tier from that dimension's tiering mechanism),
source_section, dimension, and status (rule or candidate).
00-method/BELIEF_SYSTEM_METHOD.md founding-of-founding
00-founding/BELIEF_SYSTEM_react-codebase.md founding
00-founding/PROTOCOL_cross-functional-adjudication.md founding-level
performance/01-belief-system/BELIEF_SYSTEM_react-performance.md
performance/02-protocols/PROTOCOL_react-performance-rules.md author rules
performance/02-protocols/PROTOCOL_react-performance-prioritize.md weight findings by real usage
performance/02-protocols/PROTOCOL_react-performance-audit-verify.md scan real code, measure, apply ad hoc
performance/03-skills/SKILL_react-client-interaction-audit.md client-side metric gap
performance/03-skills/SKILL_react-performance-verify-escalation.md human intervention on repeated non-moves
performance/03-skills/rules/*.md (70) the actual rule content — NEW
composability/01-belief-system/BELIEF_SYSTEM_react-composability.md
composability/02-protocols/PROTOCOL_react-composability-rules.md author rules + ad hoc application
composability/03-skills/rules/*.md (8, incl. 1 candidate) the actual rule content — NEW
motion/01-belief-system/BELIEF_SYSTEM_react-motion.md
motion/02-protocols/PROTOCOL_react-motion-authoring.md meaning gate, trigger, directionality, degradation checks
motion/03-skills/rules/*.md (5) the actual pattern content — NEW
Each functional belief system (performance, composability, motion) has a
## Version and Commitments Log seeded at 0.1. Each is traced explicitly to
the founding document, and cross-domain conflicts route through
00-founding/PROTOCOL_cross-functional-adjudication.md rather than being
resolved unilaterally inside any one functional protocol.
The system is platform-independent by design:
performance/02-protocols/PROTOCOL_react-performance-audit-verify.md defines
a generic Observability Source interface (route timing, server duration,
build-time bundle size, optional request volume) rather than naming a vendor.
Any tool satisfying that interface — a platform's built-in analytics, a
self-hosted APM, a third-party RUM vendor, a CI bundle check — can be wired in
at the skill layer. The rule content in rules/*.md was sourced from
vercel-labs/agent-skills and edited for vendor-independence: self-promotional
references (a specific vendor's product names, that vendor's own case-study
blog posts) were generalized to the underlying platform-agnostic capability
they illustrate (e.g., "warm/reused serverless function instances" instead of
one vendor's branded compute product); genuinely framework-specific APIs
(Next.js, React) were kept as-is, since the practice's scope is React/Next.js,
not vendor-neutral-to-the-point-of-framework-agnostic.
Both performance/02-protocols/PROTOCOL_react-performance-audit-verify.md and
composability/02-protocols/PROTOCOL_react-composability-rules.md include an
Ad Hoc Application mechanism: an audit checks the existing rule set first,
and anything that violates the belief system's claim but matches no existing
rule becomes a labeled candidate finding (same Incorrect/Correct shape as
a real rule, tagged as unreviewed) rather than a bare assertion or a silent
miss. A candidate that recurs is the signal to promote it into a real rule.
SKILL_react-performance-verify-escalation.md's ledger has no persistence mechanism specified. The skill assumes a ledger exists to log qualifying non-moves and count toward the threshold of three, but nothing says where that ledger actually lives (a file in the repo, an external store). Needs a concrete location before the skill can run for real, not just be reasoned about in a single session.- No functional belief system has produced a real Version and Commitments
Log entry yet — all three are still at
0.1, seeded but untested. The escalation skill and the Ad Hoc Application promotion path are both designed to eventually write real entries here; neither has been exercised against an actual codebase yet. SKILL_react-client-interaction-audit.mdhas an acknowledged coverage ceiling: local profiling is a proxy, not production ground truth, and the skill explicitly declines to resolve that gap itself (it asks before adding real user monitoring rather than assuming it). This is a live gap, not a solved one with a caveat attached.- Composability's Ad Hoc Application boundary condition is structurally looser than Performance's. Performance's ambiguous cases resolve with more data (traffic). Composability's often don't — a config-object pattern can be a real violation in one codebase and a reasonable tradeoff in another as a matter of values, not missing information. Expect more candidates to stay candidates permanently here than in Performance; that's a predicted property of the belief system, not a defect to fix.
- The founding document has no Version and Commitments Log, unlike its three children — left out deliberately since it's the document that adjudicates the others, and revising it is more consequential. Whether it needs one is itself one of the open decisions below.
composability/03-skills/rules/react19-no-forwardref.mdis a candidate, not a promoted rule. It covers two React 19 API changes (forwardRefremoval,use()overuseContext()) that don't cleanly trace to any of the 5 existing load-bearing distinctions yet — a human promotion decision (perPROTOCOL_react-composability-rules.md's Mechanism 3, the Generative Test) is needed before it counts as a settled rule.
- Operations (cost/reliability). Real functional wound, but scoped out of
00-founding/BELIEF_SYSTEM_react-codebase.mdon purpose — its evidence type (production spend/incident data) doesn't match the founding claim's evidence type (code-level legibility), and folding it in would blunt the claim's falsifiability. If built, it belongs under a different founding scoped to deployed-application health, not this one.
Testing candidate axes — Security, Data Integrity, Resilience, Accessibility,
Privacy — against the founding claim surfaced a structural question, not just
a scope question: none of them can be adjudicated by
00-founding/BELIEF_SYSTEM_react-codebase.md at all, because its claim only
has vocabulary for legibility (can this be reasoned about), not for
exploitability, durability, dependency stability, usability by someone
unlike the builder, or consent. Per the Method (exactly one founding belief
per institution, able to adjudicate every functional system beneath it), that
suggests react-codebase may itself be one functional domain — Legibility
— sitting under a higher founding belief, provisionally stated as:
Every category of harm a system can do — to its maintainers, its data, its users, its dependents, people who use it differently than its builder does, whoever's data it touches, whoever pays for it — traces back to the same mechanism: an assumption that felt safe to leave unchecked. The axes differ only in who or what would have caught the assumption failing.
This has not been decided. Two live paths:
- Keep it simple. Leave
react-codebaseas founding. Treat any of Security / Data Integrity / Resilience / Accessibility / Privacy as unrelated sibling founding systems with no shared adjudicator between them and Legibility. Faster; loses the ability to resolve conflicts across these axes (e.g., a caching decision with both a performance upside and a staleness/security risk). - Promote properly. Add the higher founding belief, relabel
BELIEF_SYSTEM_react-codebase.mdas a functional Legibility document (light edit — reframe its wound as one instance of the higher claim), build any needed siblings underneath the new founding, all adjudicated by one document the way Performance/Composability/Motion already are. Under this path, each new sibling would get its own{dimension}/01-belief-system/ 02-protocols/03-skillsfolder, the same shape as the three built so far.
Everything already built survives either path unchanged — Performance, Composability, and Motion don't move, they just nest one level deeper under path 2. This is a naming/scoping decision, not rework, but it determines where any future axis gets built, so it's worth deciding before adding one rather than after.
Tested and judged genuinely distinct — real wound, real evidence type, not reducible to something already built:
- Security — assumption: this path doesn't need its own check. Caught by: an attacker.
- Data integrity — assumption: this write/migration can't corrupt or lose data. Caught by: an audit or incident.
- Resilience — assumption: this vendor/dependency stays up and compatible. Caught by: an outage or breaking change. (Also absorbs API-contract-stability — same wound, producer side instead of consumer side.)
- Accessibility — assumption: everyone navigates this the way I do. Caught by: assistive tech, a user who can't complete the flow.
- Privacy — assumption: this data is harmless to collect/log/forward. Caught by: a compliance audit or a user asking why. Kept separate from Security deliberately — Security asks "can this be stolen," Privacy asks "should this exist at all."
Tested and folded into an existing axis rather than kept standalone:
- Internationalization → sub-case of Accessibility (same wound: an assumption about who's on the other end).
- Testability → not a new axis at all; the sharpest possible evidence for Legibility's own claim, not a separate one.
- API contract stability → folds into Resilience (same wound, viewed from the producer's side).
None of the five distinct candidates are built. None should be built reactively just because they're named here — build one when there's an actual reason (a real codebase need), the same way Motion only got built once its buried claim was actually surfaced from real material, not speculatively ahead of need.