Repository navigation
Task: Describe loopwright by its principles, not its stack #13
Description
Goal
Make loopwright describe itself by its principles first and its stack second, in
the four places where its identity is currently written through the stack. The
most consequential of the four is .loopwright/claude-md-section.md: it is the
block install.sh injects into every host repo's CLAUDE.md, so it is how
loopwright introduces itself to everyone who adopts it. Leaving it as is would
mean the source repo talks about principles while every adopter still reads a
description by directory and test runner.
What "nothing is removed" means here, precisely, because one line is an
exception: every requirement fact survives — Node ≥ 20.11, the need for a
package.json, npm/pnpm/yarn support. They stop being the identity, but they stay
stated. The one line whose truth value changes, not just its framing, is the
merge-authority sentence at README.md:142-143: "always the human's decision"
becomes the human's decision by default. That is P8, and it is a real change,
not a reframing.
The checkable test for "principles first", so this is not a matter of taste:
in each rewritten lead, the first sentence must name a concrete opinion — the
tone to match is docs/loopwright/quality-gate.md:3-5 — and must not contain
"JS/TS" or "vendor" before that opinion has been stated. Any coder and any
reviewer can run that test without judgement.
Acceptance criteria
-
README.md:3-6leads with a named opinion and the "vendor it into any
JS/TS repo" clause follows rather than defines — per the textual test above. -
README.md:89("Your stack, not loopwright's") andREADME.md:173(the
parenthetical "loopwright targets JS/TS repos") no longer frame identity as
the stack, while remaining factually accurate about what is required.
README.md:174(package managers) carries no identity framing and needs no
edit. -
README.md:158-169("How it's wired") gains a row for
docs/loopwright/principles.md. -
README.md:142-143— "Two rules hold the whole thing together: the gate
is the only source of truth for "done", and merging is always the
human's decision." — is reconciled with P8: merge is the human's by
default, automating it is an explicit opt-in. This is the second site of the
absolute rule, andREADME.mdhas only this draft as its owner. -
CLAUDE.mdand.loopwright/claude-md-section.mdboth point at three docs
with principles first, and both describe loopwright by what it is
opinionated about before naming.loopwright/. This includes
CLAUDE.md:1-6, the preamble above the<!-- loopwright:start -->
marker — it is unique to this repo, is not shared with
claude-md-section.md, and is the single worst identity-by-mechanism site
in the repo ("the engine lives in.loopwright/scripts/, its tests in
.loopwright/tests/"). -
package.json:4describes loopwright by its process opinions rather than
as a "quality layer for AI-assisted JS/TS repos". - No factual requirement is lost in the rewrite: Node ≥ 20.11, the need for a
package.json, and npm/pnpm/yarn support remain stated somewhere in
README.md.
Pointers into the RFC
- Context → the exact sentences that currently carry the stack framing, with
their locations. - Scope, third bullet → the four files, why
claude-md-section.mdis the most
important of them, and theREADME.md:142-143reconciliation. - "Why the contested branches settled where they did" → the P2/P8 split, which
is whatREADME.md:142-143has to be rewritten against: the gate half of that
sentence survives as P2, the merge half becomes P8's default. docs/loopwright/quality-gate.md:3-5is the one place in the repo that already
states purpose process-first; it is the tone to match.
Blocked by
#11 — these files link to the doc and summarise it, so it has
to exist first.
Activity
SamuelDenani commentedon Oct 7, 2026
Spec and implementation plan committed:
docs/specs/issue-13.md(ontask/13-principles-first-identity, based onfeat/rfc-5-core-principles).Six steps. Notes worth surfacing from planning:
CLAUDE.md:8-62is verified byte-identical to.loopwright/claude-md-section.md, andinstall.sh:53-63splices the latter into every host repo'sCLAUDE.md. Those two edits are one edit applied twice, propagated with the installer's own awk splice and guarded by a byte-identity sync check.CLAUDE.md:1-6(above the<!-- loopwright:start -->marker, shared with nothing) gets its own step, since editing the shared block does not touch it and the sync check cannot see it..loopwright/config.jsonscopessources.rootsto.mjsunder.loopwright/scriptsand.loopwright/tests, so markdown and one JSON string move no metric. Each step substitutes a runnable check with recorded before-output.README.md:142-143is the one line whose truth value changes rather than its framing, per P8.SamuelDenani commentedon Oct 7, 2026
done in #17, merged into feat/rfc-5-core-principles