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 CI, Test, Security, CodeQL, Draft PR, Release PR, and Release.
• 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 two-command 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.
• Pull requests targeting staging.
• Draft PR automation for supported feature/fix branches.

Jobs are language-aware and skip irrelevant setup while remaining visible as successful required checks. TypeScript uses ESLint, Prettier, and Bun's native test runner. 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. 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 uses the staging-release workflow: feature PRs squash into staging, the promotion PR rebases into main (merge_strategy: rebase), and Release Please version PRs squash into main (release_merge_strategy: squash). Release automation never defaults to a merge method and never merges with --admin; code-foundry doctor and code-foundry sync fail closed on any other strategy. GitHub Stacks is not part of this topology and does not reduce the required workflow runs.

Releases and publishing

The standard flow promotes staging into main, lets Release Please open a versioned release PR, and creates a GitHub release after that PR is merged. npm publication is opt-in through npm_publish: true and supports npm trusted publishing or an NPM_TOKEN fallback.

Read Release management 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. Add repository-specific documentation there as well; synchronization does not replace files in docs/.

• Documentation index
• Initialization and synchronization
• Workflow and CI conventions
• Release management
• Publishing packages
• Caching and remote caching

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.