Skip to main content

Overview

What the Lupinum OSS standard is for, what a standard repository looks like, and the one rule for tooling.

Lupinum maintains a set of open-source libraries with very little human time. Agents do most of the routine work. This standard keeps that sustainable:

  • Lazy maintenance. A maintainer reviews pull requests and clicks two buttons to release. Everything else is automated or delegated to agents.
  • Real security. npm publishing cannot happen without the maintainer's approval, never uses a stored token, and never runs dependency code while it holds publish rights.
  • Minimal tooling. A repository contains the library, its tests, its docs and a small amount of standard setup. Nothing else.

The governed repositories are listed in fleet/libraries.json.

What a standard repository looks like

Every library has the same layout. The root holds only what a visitor or an agent looks for first, and the configuration files that tools require there.

README.md, LICENSE   what visitors read first
AGENTS.md            one page for agents: commands, hard rules, library principles
CHANGELOG.md         generated by Changesets (in each package of a monorepo instead)
package.json, pnpm-workspace.yaml, pnpm-lock.yaml
                     plus the tool configuration files that must sit in the root
src/ or packages/    the library
docs/                documentation site, optional (Ginko Docs; Vercel deploys it through Git)
.changeset/          Changesets config and pending changesets
.github/
  workflows/         ci.yml, release.yml, preview.yml
  ISSUE_TEMPLATE/, pull_request_template.md
  CONTRIBUTING.md    short; GitHub shows it from here
  SECURITY.md        how to report, which versions get fixes
  renovate.json
.claude/CLAUDE.md    one line that imports AGENTS.md
internals/           notes for maintainers and agents, not for users
  decisions.md       dated decision log: "Dn: decision — why"
  migrations.md      temporary compatibility code and when it goes (only while there is some)

Nothing else goes in the root. Move a note into internals/, a community file into .github/, and delete configuration that no tool reads.

Package scripts stay close to this list: dev, build, lint, format, typecheck, test, docs:dev, docs:build, verify and changeset. pnpm verify runs the core checks CI runs, so run it before you open a pull request. A slow suite (end-to-end tests, a build matrix) can run only as an extra CI job; internals/decisions.md names it and says why.

Docs for agents in consumer projects

Every published package ships its documentation, so an agent working in a consumer project reads the docs that match the installed version:

  • pnpm build copies the rendered docs pages into dist/agent/ with an AGENTS.md index. The package exports it as <package>/agent-docs.
  • The package's own README (the one npm and node_modules show) has an Agent setup section. It tells the agent how to find the index and which short pointer to add to the consumer's AGENTS.md. The pointer names the installed package, so it stays correct after upgrades. Consumers copy no docs and install no skill.

The starters include both, and the audit fails a package without the export or the README section.

There is no MAINTAINING.md and no procedure handbook inside a repository. Procedures live in this handbook. Library-specific knowledge lives in AGENTS.md and internals/decisions.md.

The rule for tooling

A check or script is allowed only if it guards behavior that a user relies on, or a real attack path. Process documentation is not security. See Adding tooling for examples.

What this repository provides

  • This handbook. Eleven pages. Read the one you need.
  • The Checklist. It decides when a library follows the standard: one ID per item.
  • Starters in starters/. Generate a new repository that already follows the standard.
  • The audit. pnpm audit:repos checks every governed repository against the checklist through its files, gh api and the npm registry, and reports whether the repository follows the standard and the open items. It never changes anything.
  • The lupinum-oss agent skill in skill/. It points agents at this handbook and the audit, and starts when someone builds, adopts, releases or checks a library.

Change the standard

Open a pull request against lupinum-dev/lupinum-oss. Add an entry to its internals/decisions.md that says what changes and why. Update the handbook, the checklist, the starters and the audit in the same pull request. Existing repositories adopt the change through their own normal pull requests; run the audit to find them.