Standards

Copy only the parts your project needs. This repository is a catalog, not an installable package. Its templates cover formatting, linting, static analysis, tests, dependency hygiene, and repeatable CI gates.

The maintained profiles are C#, Rust, Python, TypeScript, Shell, Go, Kotlin, Swift, and Markdown/MDX. The secondary repository, standards-archive, preserves the other profiles as a dormant catalog. Each catalog owns its shared tooling; changes do not synchronize between them.

Each template starts strict but stays close to its ecosystem. Use it as a high-signal baseline. Then narrow or remove rules that do not fit the project's risk, lifecycle, domain, or team tolerance.

The baseline supports agent-driven delivery. The human owns product intent, constraints, and acceptance; agents perform bounded implementation and verification. A fresh agent entering a repository should discover its workflows and contracts locally, then report results that the project's gates verify. Conventional layouts, explicit side effects, and actionable failures reduce the human's need to supervise implementation details.

A project holds only its current state. Each change removes what it makes obsolete, proof lives in the gate rather than in tracked reports, and every test defends a real failure. The shared agent guide states these rules. The hygiene task enforces their mechanical part in every local standards:check; the isolated Dagger gate copies the tree without .git and skips it.

Every tool, rule, and abstraction must remove identifiable uncertainty, defects, or manual work at an acceptable runtime and maintenance cost. Fast terminal interactions and short feedback loops are part of that contract. Uniform project task names help agents switch contexts; wrapping ordinary host commands adds no such benefit.

Adoption Model

Treat this repository as a source catalog. Do not copy it wholesale or keep a permanent dependency on it. An agent that adopts these standards must:

1. Inspect the target repository and identify its actual languages, tools, workflows, and release surfaces.
2. Copy the shared baseline and only the language or tooling profiles that match those surfaces.
3. Merge the relevant language-specific AGENTS.md fragments into the copied shared/AGENTS.md.
4. Review every copied file line by line. Keep each rule, pattern, task, tool, dependency, detector, and instruction only when it applies to the target repository.
5. Remove unused ecosystem coverage wherever it appears. Check agent guides, mise configuration and task fragments, workflows, documentation, and tool configuration. This list is illustrative, not exhaustive.
6. Adapt paths, package metadata, policies, and verification tasks to the target repository, then run its copied mise gates.

The finished baseline must describe the target repository, not the full catalog. shared means broadly reusable, not universally applicable. For example, a TypeScript-only repository must remove Kotlin tasks, outputs, tools, and guidance from every copied file that contains them. Apply the same test to every language, tool, workflow, and policy outside the target repository's surface. Keep cross-cutting rules such as secret scanning and Git guidance when they still apply. Copy the shared .gitignore, .gitattributes, and .gitleaks.toml whole: their broad ecosystem coverage costs nothing when unused and protects the repository when it adds an ecosystem.

What to Copy

• shared/ provides generic top-level project files: AGENTS.md, .gitattributes, .gitleaks.toml, and .gitignore.
• Mise/ provides the .config/mise templates and the developer command surface.
• Dagger/ provides the optional module behind the explicit dagger:standards:check mise task.
• Each language or tooling folder contains one of the profiles listed below.
• extras/workstation/ holds optional personal workstation bootstrap scripts.

The root files maintain the catalog. The small standalone projects under testers/ prove each language template through the documented mise layout. Each fixture commits .config/mise/mise.lock for deterministic Linux tool resolution. standards.manifest.toml maps profiles to their canonical templates, tester fixtures, task fragments, exact mirror files, and required tester-only files.

Root AGENTS.md, .gitignore, .gitattributes, and .config/mise/ govern this repository; they are not project defaults. docs/IDEAS.md holds deferred catalog-wide proposals.

Create a Project Baseline

1. Copy the shared files

Start with the files shared across ecosystems:

cp shared/AGENTS.md /path/to/project/AGENTS.md
cp shared/.gitattributes /path/to/project/.gitattributes
cp shared/.gitleaks.toml /path/to/project/.gitleaks.toml
cp shared/.gitignore /path/to/project/.gitignore

2. Add the mise tasks

Copy the mise configuration into its conventional location:

Mise/config.toml    -> .config/mise/config.toml
Mise/tasks/hygiene  -> .config/mise/tasks/hygiene
Mise/conf.d/*.toml  -> .config/mise/conf.d/

Keep only the language fragments from conf.d that the project uses. For example, a Python and TypeScript project would retain 20-python.toml and 20-ts.toml.

mise usage gives the minimum mise release for the copied configuration and its fragments, and the reasons for it.

3. Add Dagger isolation if needed

Projects that need isolated Dagger checks should also copy the task fragment and module:

Mise/conf.d/10-dagger.toml -> .config/mise/conf.d/10-dagger.toml
Dagger/dagger.json          -> dagger.json
Dagger/dagger/              -> dagger/

4. Choose the profiles

Copy each language or tooling folder that the project needs:

• C#/ — pinned .NET and Microsoft Testing Platform configuration, strict compiler and analyzer policy, central package management, locked restore, application-boundary guidance, Release build and test defaults, a banned-API wall, mutation testing, and the agent-driven doctrine shared with the Rust, TS, and Python profiles.
• Go/ — a Go module baseline with gofumpt, module hygiene, go vet, a custom restricted-dialect analyzer, golangci-lint, govulncheck, tests, race, coverage, and benchmark tasks.
• Kotlin/ — a Gradle Kotlin/JVM baseline with ktlint, Detekt, warnings as errors, dependency locking, and dependency-verification generation tasks.
• Markdown/ — a Bun-backed Markdown/MDX baseline with Oxfmt formatting, markdownlint structure checks, semantic YAML frontmatter validation, MDX compile checks through remark/rehype and Shiki, offline local link checks with lychee, and low-noise typo checks with typos.
• Python/ — pyproject and uv-based configuration for Ruff, basedpyright, Bandit, pytest/coverage, deptry, Hypothesis property tests, mutmut mutation testing, a banned-API wall, wheel and source builds, plus optional deeper mypy, documentation, complexity, slots, and dead-code checks. Shares the agent-driven doctrine with Rust, TS, and C#.
• Rust/ — Cargo, rustfmt, Clippy, rustdoc/doctest, locked workspace, cargo package and cargo-deny dependency-policy defaults, mutation testing, and an agent-driven development doctrine in its AGENTS.md.
• Shell/ — a Bash-first glue-code baseline with shfmt, ShellCheck, parser checks, Bats tests, and a shebang policy for project-owned scripts.
• Swift/ — a SwiftPM baseline with a pinned Swift toolchain, native swift-format linting, Swift 6 concurrency checking with Swift 7 upcoming features, warnings as errors, strict memory-safety diagnostics, a policy check for target settings and reasoned exceptions, Swift Testing under Thread Sanitizer, coverage summaries, an OSV dependency audit, and automatic downstream CI.
• TS/ — selectively Effect v4-enabled, Bun-backed TypeScript with strict tsc, typed Oxlint plus Oxfmt as the primary workflow, Effect Schema boundaries and diagnostics, semantic and negative tests, mutation testing and knip gates, automatic CI, and a separately validated ESLint plus Prettier secondary workflow. Shares the Rust profile's agent-driven doctrine.

A language folder may also contain an AGENTS.md. Those files are merge fragments, not standalone guides: copy shared/AGENTS.md first, then merge the language sections into it.

5. Adapt the baseline

The copyable files use neutral project names, conventional src and tests directories, and generic package namespaces. Replace those placeholders when the project uses a different layout or architectural boundary. Package identity, author, maintainer, copyright, license, and publication metadata must match the project's legal and release posture.

A template is a strict seed, not a finished architecture. Begin with the ecosystem-native formatter, compiler or type checker, test runner, and lockfile policy. Keep a dependency advisory gate when the ecosystem provides a dependable, high-signal option. Otherwise, keep its native integrity controls and choose project-specific auditing after adoption. Style-only rules, coverage policy, release profiles, and heavier optional analyzers can wait until the project has taken shape.

Applications and CLIs should usually commit lockfiles, pin toolchains exactly, and run audits in CI. Libraries may need wider runtime version ranges, different release profiles, and narrower public API gates. Existing projects should adopt strict checks through reviewed suppressions or CI ratchets. Do not broadly disable rules only to get a green build.

The aggregate mise tasks use marker files so the defaults remain copyable. Monorepos and mixed-tooling repositories should replace this generic dispatcher with explicit project-specific task dependencies or narrower markers.

6. Verify the copied baseline

1. Remove language task files that do not apply.
2. Adjust package names, namespaces, source directories, and test directories.
3. Run mise install.
4. Run mise run standards.
5. Run mise run standards:check.
6. Commit the resulting lockfiles. These include the mise lockfile for the chosen configuration layout, such as .config/mise/mise.lock, and any package-manager lockfiles the project uses.

Optional: set up a workstation

The personal bootstrap scripts are at extras/workstation/macbook-setup.sh and extras/workstation/wsl-setup.sh. Read the relevant script before you run it directly on the target machine. They install host tools through native installers. WSL also provisions Node through mise and enables cached interactive runtime switching; macOS keeps native runtime paths without mise activation. Project tasks work without interactive activation or shims. See the workstation guide for shell defaults and maintenance.

Use Mise for Development and CI

Developers and CI use the same project workflow commands. Ordinary utilities such as tokei, rg, and git run directly; see mise usage for the boundary between project tasks and host tools.

mise install
mise run fmt
mise run fmt:check
mise run lint
mise run test
mise run standards
mise run standards:check
mise run secrets
mise run sbom

mise run standards applies each detected language's safe autofixes. mise run standards:check runs the CI-grade aggregate gate, scans for secrets with the shared .gitleaks.toml, and runs hygiene. hygiene prints the tree's size by category and rejects history directories, leftover, versioned, or dated file names, handoff notes, and references to undefined tasks. Adapt its constants and add language-aware project rules at the end of its checks.

This catalog has no CI of its own: every gate runs locally before push. Use targeted gates for routine catalog maintenance and the aggregate gate for cross-cutting validation.

The Rust, TypeScript, C#, Python, and Swift profiles each contain a copyable workflow for downstream projects. Those run automatically for pull requests, merge-queue groups, and pushes to main, and also support manual dispatch. All the workflows use the same locked command surface and pin one locally tested mise release. Configuration min_version values are floors, not pins.

The downstream repository host must protect merges with all of these settings:

• require the copied workflow's quality job;
• require review from Code Owners;
• dismiss stale approvals when new commits are pushed; and
• disallow bypass of the ruleset or branch protection.

The latest-push approval option is useful defense in depth, but it does not replace stale-approval dismissal because that approver need not be the code owner. Committed YAML cannot configure these host settings. Expensive project-specific integration or deployment checks may remain separate, but they do not replace the fast, static, deterministic gate.

mise run sbom writes an optional CycloneDX JSON SBOM under sbom/. Set SYFT_SOURCE_NAME and SYFT_SOURCE_VERSION when its release metadata should differ from the directory name and default 0.0.0 version.

If the Dagger template is installed, mise run dagger:standards:check runs standards:check in an official, digest-pinned mise Linux reference container. The task definitions remain in mise.

Maintain the Catalog

The repository root requires mise 2026.9.18 or newer, the highest fixture floor, which the Swift fixture's native backend sets. The root gate runs every fixture, and mise does not enforce a fixture's own min_version when its tasks run from the monorepo root. The root .config/mise/mise.lock pins jactionlint, gitleaks, Python, and the root Markdown and Shell tools. bun.lock pins the Markdown JavaScript dependencies.

Before you hand off a change, check each surface that changed. For a changed profile, read its tester and task_prefix from standards.manifest.toml and run:

mise run //<tester>:<task-prefix>:standards:check

These fixture gates include audits, proof, package checks, and slower quality checks. When you change a template, update its fixture and refresh the affected lockfiles. This keeps the copied layout proven.

Run mise run standards:drift after you change a template, shared task, manifest entry, or fixture configuration. For other root files, run the closest root check. For example, use mise run md:standards:check for Markdown.

Use mise run standards:check when explicitly requested and after changes to shared or aggregate infrastructure that can affect unrelated fixtures. The aggregate gate first scans for secrets and runs hygiene, before fixture tests write temporary probe files into the tree. It then validates the TypeScript ESLint and Prettier secondary workflow, checks drift, Markdown, and Shell, and runs every tester fixture, in parallel.

The root mise configuration discovers fixture tasks through the explicit testers/* monorepo configuration roots. Its [settings].jobs value bounds concurrent task execution; language tools also set their own concurrency.

[monorepo] lockfile = false keeps each committed fixture lockfile beside its standalone configuration. The root gate runs every fixture through the native //testers/...:standards:check path wildcard, so one scheduler attributes output to each project.

Under MISE_LOCKED=1, mise 2026.10.19 checks the Rust fixture's rust-toolchain.toml against the root lockfile instead of the fixture's when the fixture's tasks run from the root. It logs two rust@<version> is not in the lockfile warnings and leaves Rust out of those tasks' environment. mise install still installs the locked toolchain, and the tasks run the rustup cargo already on PATH. rustup selects the toolchain from the same rust-toolchain.toml, because the root configuration unsets an inherited RUSTUP_TOOLCHAIN, which would otherwise outrank that file.

To run an optional isolated proof, use the Dagger entrypoint of the representative Python fixture:

mise run //testers/python:dagger:standards:check

The profile-contract portion of the root gate has three focused checkers. scripts/check-standards-drift.py keeps shared task fragments, aggregate task dispatch, fixture configurations, Dagger fragments, full-configuration shared files, and declared mirror files in sync, and runs the hygiene task against seeded clean and dirty trees. scripts/check-ignore-contracts.py exercises mutation-output ignore scope with Git's matcher. scripts/check-profile-governance.mjs fails if the catalog ships a root workflow. It lints the downstream workflow YAML with jactionlint's default profile, which adds security and policy rules to the correctness checks, honors no jactionlint ignore comment, and fails on a finding of any level. It then parses the downstream YAML to enforce the workflow, Code Owners, host-setting, and pull-request contracts. Fixture source and tests outside the declared mirrors stay small.

When adding or changing a profile:

1. Update standards.manifest.toml.
2. Add or update the matching testers/<profile> fixture.
3. Keep every declared mirror path byte-for-byte aligned.
4. Refresh the affected fixture lockfiles.
5. Run mise run standards:drift and the affected fixture gate.