Skip to main content

.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. setup creates it, fix keeps it current, and its writtenBy/writtenAt stamps 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​

FieldTypeRequiredDescription
$schemastringnoURL of this schema; stamped on every write so editors validate the file.
extendsstringnoA 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.
versionintegeryesLockfile 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.
recordobjectyesThe 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.
rulesobjectnoThe 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​

FieldTypeRequiredDescription
configobjectyesThe resolved setup configuration this repo was scaffolded or audited with.
assetsobjectnoPreset 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.
writtenBystringyesPackage name and version that last wrote the record subtree.
writtenAtstring (date-time)yesISO 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):

FieldTypeRequiredDescription
projectNamestringyes
languagejs | swift | perl | pythonno
projectTypelibrary | web-app | node-api | nextjs-app | react-appyes
typescriptobjectyes
lintingobjectyes
formattingobjectyes
testingobjectyes
gitHooksbooleanyes
commitLintbooleanyes
semanticReleasebooleanyes
changesetsbooleanno
releasePleasebooleanno
oxlintbooleanno
vitePlusbooleanno
securityAutomationbooleanyes
bundlertsup | esbuild | rollup | rolldown | vite | noneyes
treeshakeCheckbooleanno
publintbooleanno
badgesbooleanno
aiSetupbooleanno
turborepobooleanno
nxbooleanno
tailwindbooleanno
docsSitebooleanno
brandbooleanno
bunbooleanno
docsobjectno

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.

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/" }
]
}
}
FieldTypeRequiredDescription
namestringyesThe server name as it would appear in .mcp.json.
importancenice-to-have | important | criticalyesHow much of the repo's workflow assumes the server.
whystringyesOne 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" adds label (default needs-review) and never merges, so a reviewer or a review bot can pick the PR up by label. Its workflow token gets contents: read, since only merging needs contents: 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"]
}
}
FieldTypeRequiredDescription
requiredChecksarraynoRequired 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).
strictbooleannoRequire branches to be up to date before merging. Standard: false.
autoMergebooleannoAllow auto-merge. Standard: true.
deleteOnMergebooleannoDelete head branches on merge. Standard: true.
vulnerabilityAlertsbooleannoDependabot vulnerability alerts. Standard: true.
automatedSecurityFixesbooleannoDependabot automated security fixes. Standard: true.
privateVulnerabilityReportingbooleannoPrivate vulnerability reporting (the "Report a vulnerability" button). Standard: true.
actionsCanCreatePullRequestsbooleannoAllow GitHub Actions to create and approve pull requests. Standard: on for a Changesets repo (its Version Packages PR needs it), off otherwise.
releaseReviewersarraynoGitHub user logins required to approve the `release` environment. Unchecked when absent.
releaseBranchesarraynoBranches 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).
  • requiredChecks is 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, so test does not cover a matrix leg like test (node 22). Require the ci gate job instead of the legs.
  • false is applied as off. fix github-settings turns a feature off when the rules say false, 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 declared with its reason, and the summary carries a declared: N count. 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 doctor does not run — a typo, or a check that was renamed or removed — is reported as drift under the check name Declared 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​

FieldTypeRequiredDescription
agentUserstringnoLogin 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/repo string 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 over gh: 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 rules are 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. doctor adds an Extends row. If the base cannot be read, is not valid JSON, fails the published schema, or has an extends of its own (one level only), the row is drift and only the repo's own rules apply. A github: base is not fetched under --offline; the row reads skipped, and values from that base do not apply in that run.
  • The base is never written. fix and doctor --snapshot write only this repo's file, and never copy a base value into it. doctor --snapshot lists the rules still coming from the base.
  • The base is untrusted input, like a --rules-from reference: the spec is shape-checked before it reaches a path or an API call, the file is size-capped, and its rules are 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​

VersionChange
1Initial format.
2Added config.language (multi-language seam). Older files migrate to js on read.
3Added assets — pristine hashes of copied presets, so doctor can tell a local fork from a stale copy.
4Split 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.