@sebastian-software/standards

The single source of truth for repository standards across the sebastian-software org — reference files, migration changelogs, agent instructions and a CLI to check and apply them.

The three repositories

The system is three small repos with sharply separated jobs, plus whatever Renovate you already run:

flowchart TB
    RC["renovate-config<br/>— the update rules"]
    ST["standards<br/>— source of truth"]
    TPL["repo-template<br/>— starts new repos"]
    RN{{"Renovate<br/>self-hosted or Mend"}}
    REPOS["Managed repos<br/>(topic: managed-deps)"]
    AGENT["LLM agent<br/>judgement work"]

    ST -->|new version| RN
    RC -->|preset / rules| RN
    RN -->|bump PR + apply| REPOS
    TPL -.->|use this template| REPOS
    REPOS -.->|pending.json| AGENT
    AGENT -.->|commit on branch| REPOS

Loading

• standards (this repo) — the source of truth: reference files, the version stamp, migration changelogs and the CLI. The payload Renovate ships.
• renovate-config — one shared Renovate preset that says how updates behave (what automerges, what groups). The only org-specific configuration.
• repo-template — the GitHub template new repos start from; it consumes both of the above.

How it works

Every managed repository carries a .repometa.json stamp:

{ "standards": 3, "visibility": "oss", "since": 2026, "platform": "github" }

This package defines the current standards version (manifest.json), the reference files per scope (reference/common, reference/node, reference/rust) and one migration changelog per version bump (changes/). Drift detection is a cheap, deterministic version comparison; applying updates is split between the CLI (mechanics) and an agent following SKILL.md (judgement).

CLI

standards init    # create .repometa.json interactively in a fresh repo
                  #   --visibility oss|private   skip the prompt for visibility
                  #   --since <int>              skip the prompt for the initial year
                  #   --yes                      non-interactive (use defaults / flags only)
                  #   --force                    overwrite an existing .repometa.json
standards check   # report drift, exit 1 if any (part of agent:check)
standards apply   # write managed files, seed missing ones, update branding, bump stamp
                  #   --from-version <int>    explicit baseline for pending-marker selection
                  #   --emit-pending <path>    write a JSON marker describing pending judgement work
standards sync    # apply + run an agent (claude or codex) locally on the pending changelog entries

All managed repositories invoke this package via pnpm dlx @sebastian-software/standards; no devDependency installation is required, regardless of stack. Every such invocation must carry --config.minimum-release-age=0 — pnpm 11 defaults minimumReleaseAge to 24h, so without the bypass dlx resolves a version older than the one apply used to write the stamp, and check then reports false drift right after a release.

Renovate-driven workflow

The system is split so that any Renovate setup can keep repos current — the deterministic half needs no special server features, and the agent half plugs in where it fits your infrastructure.

Deterministic half — works with any Renovate, including the hosted Mend app. Renovate detects that a repo's .repometa.json#standards stamp is behind the package's manifest.json#currentVersion and opens a bump PR. The repo's own CI runs standards check (part of agent:check), so drift always surfaces as a red check. The mechanical sync is standards apply — byte-exact for managed files, seed-once for adaptable ones, marker-based for the README branding.

Judgement half — an LLM agent. Changelog steps that need judgement are carried out by an agent, in one of two ways:

• Local / interactive: standards sync runs apply and then spawns claude or codex on the pending changelog entries. Works anywhere.
• Fully automated (self-hosted Renovate): a postUpgradeTasks step runs standards apply --from-version {{currentValue}} --emit-pending .standards/pending.json on the upgrade branch. The PR then carries all mechanical changes plus a JSON marker that an external agent (OpenClaw, Claude Code, Codex) picks up in pull mode and commits its judgement changes onto the same branch.

Note

The hosted Mend app cannot run postUpgradeTasks, so the fully-automated pull model requires self-hosted Renovate. With Mend, use the deterministic half plus standards sync (locally or from a CI job triggered by the bump PR).

The version model is deliberately stack-agnostic: Renovate reads manifest.json#currentVersion as an integer via a custom datasource, so Rust, docs-only or mixed repos never see an npm semver. See renovate-config for the shared preset and the self-hosted worker configuration, and changes/0002-renovate-pending.md for the full server-side contract.

File ownership

Kind	Meaning	Examples
managed	byte-exact, overwritten on apply	.oxfmtrc.json
seeded	created once, repos may adapt them	eslint.config.ts, tsconfig.json
section	marker-delimited README block owned by the standards	branding footer

Development

pnpm install
pnpm agent:check   # lint + format + typecheck + build + test + self-check

This repository applies its own standards (standards check runs against it in CI).

Onboarding a new repo

The step-by-step procedure for adding a new repo to the standards system (new repo or legacy migration, GitHub or Forgejo) lives in docs/runbooks/onboard-repo.md.

License

MIT

---

Built by Sebastian Software — consulting for TypeScript, React & Rust.
Work with us · More open source

Copyright © 2026 Sebastian Software GmbH