Code Foundry

code-foundry is a versioned repository baseline for TypeScript, Rust, Python, Solidity, and mixed-language projects. It provides language-aware workflows, native testing, security automation, releases, hooks, repository policy, and agent instructions from one initializer.

Quick start

Run this from the root of a repository:

npx code-foundry init

Initialization is repository-aware. It detects supported languages, package manager, profile, release strategy, and toolchain preference, then writes the resolved choices to .github/code-foundry.yml.

# Review or change the generated configuration, then render it
npx code-foundry sync

For an existing installation, use npx code-foundry sync. Run npx code-foundry doctor to inspect the resulting repository configuration.

If .github/code-foundry.yml already exists, init uses it as the repository contract. For normal updates, edit that file and run npx code-foundry sync.

What it installs

• Short workflow callers for pull-request validation, protected scheduled/manual audits, Draft Guard, Draft PR, Release PR, and Release.
• A deterministic performance lane with ordered command support, stable result artifacts, and an optional shared Node package budget profile.
• A deterministic eval tier (ci eval) that runs a repository's behavior-eval harness against a shared report contract with optional budgets, keeping task outcomes comparable across revisions and executors.
• An opt-in product-quality runner for static sites, web apps, Workers, and published packages.
• A small .githooks/pre-commit launcher with language-aware formatting and linting.
• An optional .mise.toml/mise.lock, repository profile configuration, and standard GitHub forms and policy files.
• AGENTS instructions, CODEOWNERS, license/notice files, and reusable release configuration.

The workflow implementation lives in the versioned runtime repository. A consumer repository keeps only the callers and the small local entrypoints it needs. Custom workflows—such as deployment, indexing, Slither, or search—are preserved and can coexist with the standard baseline.

Configuration

The generated configuration is the one place to control the baseline. See Configuration reference for the visual configuration guide and Initialization and synchronization for the init, sync, and doctor workflow.

New repositories default to GPL-3.0-or-later. Existing projects preserve an authored license unless a replacement is explicitly selected. Our maintained repositories explicitly select AGPL-3.0-or-later. Authored documentation, application files, custom workflows, and existing .mise.toml files are preserved by default. toolchain: auto uses an existing mise setup when present and otherwise uses native language tooling; choose native or mise explicitly when a repository needs a fixed policy.

Workflow model

The standard workflow triggers are:

• Pushes to main (and staging when git_workflow: staging-release is configured); main pushes also run the default-branch CodeQL scan.
• Pull requests targeting main (and staging in the staging-release topology).
• Draft PR automation for supported feature/fix branches.

Automated feature/fix and staging-promotion pull requests open as drafts. The trusted Draft Guard is a fallback for manually created or reopened ready PRs: it converts them to drafts without checking out PR code. It verifies the event head and update timestamp before changing state, and excludes Release Please version PRs whose release workflow owns readiness. Pull-request validation runs on the ready-for-review transition and on new commits while a PR remains ready; draft updates allocate no validation runner by default. Set draft_protection: false in generated consumer configuration, or pass draft-protection: false to a Cloudflare reusable workflow, to run those gates for drafts. Converting a PR to draft runs only the lightweight cancellation control. Scheduled and manually dispatched audits are unaffected.

Jobs are language-aware and skip irrelevant setup inside the applicable aggregate checks. TypeScript uses Oxlint, Oxfmt, and Bun's native test runner (repositories using another linter or formatter keep full control through their own lint/format scripts, which the runtime honors). Rust uses rustfmt, Clippy with warnings as errors, and native Cargo tests. Python uses Ruff, uv/pip-compatible setup, and native Python tests. Solidity projects retain their native toolchain and test runner.

CodeQL remains separate from CI and Security. With the default codeql: auto and dependency_review: auto policies, public repositories use the free GitHub security checks while private repositories skip them unless explicitly opted in and supported by GitHub Advanced Security. Set an unavailable private-repo capability to false during sync to omit its CodeQL job from pull requests; Dependency Review runs as a conditional Security step and does not register a separate skipped check. JavaScript, Python, and Rust audits remain available without Advanced Security. Code Foundry does not enable GitHub Code Quality or other paid GitHub features.

See Workflow and CI conventions for triggers, required checks, runners, coverage, caching, and custom workflow extensions.

The contribution policy defaults to the direct workflow: feature PRs squash into main, and Release Please version PRs use the configured release_merge_strategy (squash for direct repositories; rebase for the optional staging-release topology). Repositories with a preview/staging environment opt into git_workflow: staging-release, where feature PRs squash into staging, the promotion PR rebases into main (merge_strategy: rebase), and Release Please version PRs rebase into main. Release automation never defaults to a merge method and never merges with --admin; code-foundry doctor and code-foundry sync fail closed on any strategy outside the selected topology. GitHub Stacks is not part of this topology and does not reduce the required workflow runs.

Releases and publishing

In the default direct flow, changes reach main through feature pull requests and Release Please opens a versioned release PR against main. In the staging-release flow, a promotion PR promotes staging into main first. Generated consumer callers create a GitHub release after the version PR is merged; npm publication is opt-in through npm_publish: true and supports npm trusted publishing or an NPM_TOKEN fallback.

Code Foundry's own release caller is stricter: it qualifies the package across Node 24 and 26, stages the exact qualified archive, publishes the immutable GitHub Release, and publishes that archive through the verified publisher. See Consumer qualification and Qualified publication.

Read Release management, Release integrity and build provenance, and Publishing packages before enabling automated publishing. They are intentionally written with placeholders so they can be copied into other repositories.

Documentation and extensions

The docs/ directory contains generalized operational guides. Start with the documentation index, which groups every guide by task. Add repository-specific documentation there as well; synchronization preserves files in docs/.

License

Unless a repository says otherwise, new material is licensed under the GNU Affero General Public License v3.0-or-later. See LICENSE and NOTICE.