.repo-tooling.json
.repo-tooling.json — two documents sharing one file: `record` is written by @rtorcato/repo-tooling (`setup` and `fix`) and stamped with provenance; `rules` is written by humans, reviewed in PRs, and never stamped. Both are read by `doctor`.
The file is two documents sharing one name, split by who writes them:
record— the tool-written half.setupcreates it,fixkeeps it current, and itswrittenBy/writtenAtstamps are provenance claims about exactly this subtree.rules— the human-written half: the repo's stated intent (mcp,exceptions,dependabot,github), edited by hand and reviewed in PRs. The tool carries it forward verbatim on every write and never stamps it.
doctor reads both. Commit the file — it is the repo's memory of its own tooling choices
and its standing rules.
Do you need it?
No. Nothing reads it at build, lint or test time. It exists only so doctor can tell an
intentional opt-out from drift, which is why doctor reports a missing one as
not configured, not an error. setup writes it; on an existing repo, generate or refresh it
from what's on disk:
npx @rtorcato/repo-tooling fix lockfile
It's the only config file you need. record.config already holds the full ProjectConfig,
and setup --config accepts the lockfile directly, so you can re-run a non-interactive setup
from it:
npx @rtorcato/repo-tooling setup --config .repo-tooling.json
How opt-outs work. When the lockfile records that you declined an optional tool (say
securityAutomation: false), doctor reports that check as ok — intentionally declined
instead of not configured. It does not silence drift: if a config you adopted diverges
from the shared base (your tsconfig.json extends a different preset, for example), doctor
still flags it. To declare a deliberate deviation, use rules.exceptions.
Adoption vs. standalone. fix lockfile infers adoption from what's on disk, so on a repo
that deliberately runs standalone configs (no @rtorcato/repo-tooling dependency) it can record
typescript.config: "base" and friends, claiming you extend the shared bases when you don't.
If you're not adopting repo-tooling's configs, skip the lockfile.
Editor validation
Every written file carries a $schema pointer, so editors that understand JSON Schema
(VS Code out of the box) validate, autocomplete, and show these descriptions inline:
{
"$schema": "https://docs.torcato.dev/repo-tooling/schemas/lockfile.json",
"version": 4,
...
}
The schema itself is published at https://docs.torcato.dev/repo-tooling/schemas/lockfile.json. It is
generated from the Lockfile TypeScript interface (pnpm schema:generate), and CI fails when the
published copy drifts from the type — this page renders from the same file, so what you read here
is what your editor enforces.
Top-level fields
| Field | Type | Required | Description |
|---|---|---|---|
$schema | string | no | URL of this schema; stamped on every write so editors validate the file. |
extends | string | no | A shared base of `rules` this repo inherits: a relative path (./base.json), an npm package path (@scope/pkg/base.json) or github:<owner>/<repo>/<path>[#<ref>]. The base is a JSON file with a `rules` object; this repo's own `rules` are deep-merged on top and always win. doctor reports when the base cannot be read; fix never writes into it. |
version | integer | yes | Lockfile format version (current: 4). v2 added config.language, v3 added assets, v4 split the file into record/rules subtrees; older files are migrated on read. |
record | object | yes | The tool-written record of what setup/fix last did. Only the tool writes here — the writtenBy/writtenAt stamps are provenance claims about exactly this subtree. |
rules | object | no | The human-written ruleset: the repo's stated intent, edited by hand and reviewed in PRs. The tool carries it forward verbatim on every write and never stamps it. |
Unknown fields are rejected (additionalProperties: false): the CLI rewrites the file from
scratch on every save, so any key it doesn't know is a key it would silently drop — except
rules and extends, which are carried forward verbatim.
record — what the tool wrote
| Field | Type | Required | Description |
|---|---|---|---|
config | object | yes | The resolved setup configuration this repo was scaffolded or audited with. |
assets | object | no | Preset name → sha256 of the asset's pristine content at copy time. Lets doctor tell a deliberate local fork (file differs from this hash) from a copy the package has since moved past (file still matches, shipped asset doesn't). A preset with no entry is untracked, never drifted. |
writtenBy | string | yes | Package name and version that last wrote the record subtree. |
writtenAt | string (date-time) | yes | ISO 8601 timestamp of the last record write. |
record.config — the ProjectConfig
The full setup configuration, identical to what setup --config accepts
(its standalone schema is published at
/schemas/project-config.json,
printable with setup --config-schema):
| Field | Type | Required | Description |
|---|---|---|---|
projectName | string | yes | |
language | js | swift | perl | python | no | |
projectType | library | web-app | node-api | nextjs-app | react-app | yes | |
typescript | object | yes | |
linting | object | yes | |
formatting | object | yes | |
testing | object | yes | |
gitHooks | boolean | yes | |
commitLint | boolean | yes | |
semanticRelease | boolean | yes | |
changesets | boolean | no | |
releasePlease | boolean | no | |
oxlint | boolean | no | |
vitePlus | boolean | no | |
securityAutomation | boolean | yes | |
bundler | tsup | esbuild | rollup | rolldown | vite | none | yes | |
treeshakeCheck | boolean | no | |
publint | boolean | no | |
badges | boolean | no | |
aiSetup | boolean | no | |
turborepo | boolean | no | |
nx | boolean | no | |
tailwind | boolean | no | |
docsSite | boolean | no | |
brand | boolean | no | |
bun | boolean | no | |
docs | object | no |
The object-typed fields above (typescript, linting, formatting, testing) are small
enum-valued records — see the schema for their exact shapes. docs (url, deploy) records
where the docs site lives and how it deploys; see
Docs site.
rules — what the humans wrote
Everything under rules is edited by hand and reviewed in PRs. It is deliberately outside
the writtenBy/writtenAt stamps: the tool never writes a rule here, so it never claims
authorship of one — a hand edit to rules leaves the record's provenance true.
rules lives inside a full lockfile. The examples on this page show only the rules key.
A file that holds rules alone, with no version and record, is not a lockfile doctor can
read, so none of its rules apply. doctor reports it as lockfile drift, and
npx @rtorcato/repo-tooling fix lockfile writes the record around the rules you already have.
Start from fix lockfile (or setup) and add rules to the file it writes, so it has this shape:
{
"version": 4,
"record": { "config": { /* written by fix lockfile */ } },
"rules": { "github": { "autoMerge": true } }
}
setup does write the empty containers, so a new repo has the shape in front of it rather
than a blank page — and doctor --rules-from has something local to compare:
"rules": { "mcp": { "recommended": [] }, "exceptions": {} }
Every value is empty on purpose. A default here would be this tool asserting a rule on a repo
whose humans have not stated one. An existing rules is carried forward untouched.
rules.mcp — recommended MCP servers
Advisory metadata about the MCP servers the repo's workflow assumes. Never an install directive: an entry may say what and why, and may not say how.
"rules": {
"mcp": {
"recommended": [
{ "name": "some-server", "importance": "important", "why": "edits the design files under design/" }
]
}
}
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | The server name as it would appear in .mcp.json. |
importance | nice-to-have | important | critical | yes | How much of the repo's workflow assumes the server. |
why | string | yes | One line on what the server is for — the thing .mcp.json structurally cannot say. |
importance is one of nice-to-have, important, critical — it signals how much of the
workflow assumes the server, and nothing more. why is the one line that .mcp.json
structurally cannot carry.
doctor reports, informationally, which recommended names the repo-scoped .mcp.json does not
declare. It never installs or enables a server, and there is deliberately no command, args
or env here: MCP servers execute code, so the real config belongs in .mcp.json, which
carries Claude Code's own first-use consent prompt. The lockfile says what and why,
.mcp.json says how, and you say whether. User-scoped MCP config is machine-private and
is not probed at all.
rules.dependabot — what the workflow does with a safe PR
Sets what the generated dependabot-automerge.yml does with a patch or minor PR it would
otherwise auto-merge. Absent means automerge, so a repo that never sets it sees no change.
"rules": { "dependabot": { "onPr": "label", "label": "needs-review" } }
onPr: "automerge"(default) merges on green.onPr: "label"addslabel(defaultneeds-review) and never merges, so a reviewer or a review bot can pick the PR up by label. Its workflow token getscontents: read, since only merging needscontents: write.
Majors and consumer-facing bumps go to a human in both modes. doctor reports a workflow that
does not match the configured mode and fix dependabot regenerates it from the config.
rules.github — the GitHub settings this repo should have
Without it, doctor compares live branch protection, merge and security settings against the
standard built into the tool. With it, the file records what the repo is supposed to have, so
a change made in the GitHub dashboard or with gh api shows up as drift until someone commits
it here.
"rules": {
"github": {
"requiredChecks": ["ci"],
"strict": false,
"autoMerge": true,
"deleteOnMerge": true,
"vulnerabilityAlerts": true,
"automatedSecurityFixes": true,
"privateVulnerabilityReporting": true,
"releaseReviewers": ["octocat"]
}
}
| Field | Type | Required | Description |
|---|---|---|---|
requiredChecks | array | no | Required status checks on the default branch, exhaustive: a live check not listed here is drift too. Names match exactly, so `test` does not cover matrix legs like `test (node 22)`: require the `ci` gate job instead. Standard: ci (a floor, extras allowed). |
strict | boolean | no | Require branches to be up to date before merging. Standard: false. |
autoMerge | boolean | no | Allow auto-merge. Standard: true. |
deleteOnMerge | boolean | no | Delete head branches on merge. Standard: true. |
vulnerabilityAlerts | boolean | no | Dependabot vulnerability alerts. Standard: true. |
automatedSecurityFixes | boolean | no | Dependabot automated security fixes. Standard: true. |
privateVulnerabilityReporting | boolean | no | Private vulnerability reporting (the "Report a vulnerability" button). Standard: true. |
actionsCanCreatePullRequests | boolean | no | Allow GitHub Actions to create and approve pull requests. Standard: on for a Changesets repo (its Version Packages PR needs it), off otherwise. |
releaseReviewers | array | no | GitHub user logins required to approve the `release` environment. Unchecked when absent. |
releaseBranches | array | no | Branches the `release` environment's deployment branch policy must allow. Standard: the default branch. |
Every field is optional, and an absent one falls back to the standard, so {} means "the
standard". A declared field differs from the standard in three ways:
- Drift names the field. For example,
auto-merge enabled (rules.github.autoMerge: false). requiredChecksis exhaustive. The standard list is a floor and extra live checks pass. A declared list is the whole set, so a required check added in the dashboard is drift too. Names match exactly, sotestdoes not cover a matrix leg liketest (node 22). Require thecigate job instead of the legs.falseis applied as off.fix github-settingsturns a feature off when the rules sayfalse, and does not only turn missing ones on.
fix github-settings applies everything except releaseReviewers and releaseBranches, which
fix release-environment applies. releaseReviewers replaces any existing reviewer rule.
releaseBranches (default: the default branch) gives a release environment with no deployment
branch policy a custom one, and adds any missing branch to an existing custom policy without removing
one; a protected-branches policy is left alone. Both need an
admin token on the repo. GitHub answers a write it won't allow with a 404, and the fixer says so.
To declare what the repo has today rather than typing it out, run doctor --snapshot. It reads
the live settings over gh and merges them into rules.github, runs no checks, and leaves the
rest of the file alone. A field the token can't read (strict and the security toggles need admin) is
left out and listed, so a declared value for it stays as it was. It also lists every value that
differs from the standard: committing one declares it, and doctor stops flagging it. Review the
diff before you commit it.
rules.exceptions — declared deviations
A map from a doctor check name (the check string in doctor --json output) to the reason
this repo deliberately deviates. The reason is mandatory and non-empty — the schema rejects
an entry without one, so every deviation is argued in the PR that declares it.
"rules": {
"exceptions": {
"TypeScript": "this repo is the package; the tsconfig lives at src/cli/tsconfig.json"
}
}
Three rules keep it from becoming a mute button:
- Shown, never hidden. The check still appears in every report, as
declaredwith its reason, and the summary carries adeclared: Ncount. Only the exit code changes: a declared exception no longer fails the run. - A stale exception is itself a finding. An entry naming a check
doctordoes not run — a typo, or a check that was renamed or removed — is reported asdriftunder the check nameDeclared exceptions, so it can't silently do nothing (or silently stop suppressing). - Per-repo by construction. The file lives in the repo it excuses, so an exception that is legitimate here cannot leak into a repo where the same finding is real.
A bulk fix / fix --yes skips declared checks; a targeted fix <target> still applies,
since naming the fixer is an explicit override.
Deprecated fields
rules.brand and rules.docs (the docs-site and brand scaffolds) moved to
@rtorcato/shared-docs (#718). rules.aiLoop and
rules.requiredSkills moved to .repo-ai.json, owned by the optional
@infrazero/repo-ai (see
Using with repo-ai). They still validate, so existing files keep
working, and are removed in the next major. Move them with npx @infrazero/repo-ai fix config.
rules.aiLoop
| Field | Type | Required | Description |
|---|---|---|---|
agentUser | string | no | Login that in-flight work is assigned to, so `assignee` says whose turn it is. Must be an assignable collaborator; the skills verify that at runtime. |
rules.requiredSkills
An array of skill names, e.g. ["ai-loop", "ai-issue"].
Comparing against another repo
There is no guideline package, and there never will be: the rules are unique to each repo,
and a rule that travels as a dependency stops being the repo's own. Sharing a guideline means
pointing at a reference repo — one whose .repo-tooling.json you consider exemplary.
# Report how this repo's config and rules differ from another repo's
npx @rtorcato/repo-tooling doctor --rules-from owner/repo
The reference is read over gh (repos/owner/repo/contents/.repo-tooling.json), so it works
for any repo your gh login can see, public or private.
Three properties make this safe to point at a repo you do not control:
- Informational, always. Differences are printed in their own section, never as check
results — they are not
drift, they do not appear in the summary counts, and they cannot change the exit code. Two repos legitimately differ; the point is seeing where. - Read and report, never apply. There is no fixer, and nothing from the reference is ever written into your repo.
- The reference is untrusted input. The
owner/repostring is shape-checked before it reaches an API path, the response is size-capped, and the JSON is validated against the published schema before a single field is read. A missing, malformed, oversized or schema-invalid reference is reported plainly and the comparison is skipped — never as a finding about your repo.
Only the comparable half is diffed: record.config and everything under rules. The assets
hashes and the writtenBy/writtenAt stamps are excluded — they differ between any two repos
by construction, so including them would bury every difference that means something.
With --json, the comparison rides alongside the results under rulesReference, and only when
the flag is given.
Sharing rules with extends
A maintainer with several repos can keep one base of rules and point each repo at it, the way
tsconfig.json and Biome do. repo-tooling ships no base of its own: the file lives somewhere you own.
{ "extends": "github:acme/standards/repo-tooling-base.json#v2", "version": 4, "record": { "...": "..." }, "rules": { "dependabot": { "onPr": "label" } } }
The base is a JSON file with a rules object (a repo's own .repo-tooling.json works too; only its
rules are read). extends takes one of:
- a relative path, resolved from the repo root:
./base.json,../standards/base.json - an npm package path to a file in an installed package:
@acme/standards/base.json - a
github:ref, read overgh:github:<owner>/<repo>/<path>[#<ref>]. Pin with#<ref>(a tag, branch or SHA).
How it behaves:
- The repo wins. The base comes first and the repo's own
rulesare deep-merged on top. Objects merge key by key; arrays and scalars in the repo replace the base's whole. - No
extends, no change. Everything above is opt-in. - Never silent.
doctoradds anExtendsrow. If the base cannot be read, is not valid JSON, fails the published schema, or has anextendsof its own (one level only), the row isdriftand only the repo's own rules apply. Agithub:base is not fetched under--offline; the row readsskipped, and values from that base do not apply in that run. - The base is never written.
fixanddoctor --snapshotwrite only this repo's file, and never copy a base value into it.doctor --snapshotlists the rules still coming from the base. - The base is untrusted input, like a
--rules-fromreference: the spec is shape-checked before it reaches a path or an API call, the file is size-capped, and itsrulesare validated against the schema before they are read.
Lists of sibling repos and fleet sweeps stay in your own tooling.
Starting a new repo from another one
The same reference, the other direction:
npx @rtorcato/repo-tooling setup --from owner/repo -d ./my-new-lib
The wizard is seeded, not skipped: every question is still asked, with that repo's answers as the defaults instead of the built-in ones. Nothing is written that you did not see.
Only record.config crosses over. projectName is never seeded (a new repo is not the
reference repo), the record-side stamps are not copied (the new repo writes its own writtenBy
and starts with no assets), and rules stays behind — an exceptions entry excuses a
deviation in the repo that argued for it, so copying one would mute a check somewhere it is
still a real finding.
--from seeds the wizard, so it is ignored (with a warning) alongside --preset or --config,
which skip the wizard entirely.
Version history
| Version | Change |
|---|---|
| 1 | Initial format. |
| 2 | Added config.language (multi-language seam). Older files migrate to js on read. |
| 3 | Added assets — pristine hashes of copied presets, so doctor can tell a local fork from a stale copy. |
| 4 | Split the file into record (tool-written, stamped) and rules (human-written, unstamped) subtrees. Nothing renamed or dropped — the flat v3 fields moved into them. |
Older files are migrated in memory on read and rewritten at the current version on the next save.
The pre-rename .js-tooling.json is still read as a fallback and replaced on the next write.