ScaffoldGuard

scaffold-guard generates strict starter repositories for teams using coding agents. It creates local validation commands, GitHub Actions workflows or GitLab CI pipelines, and agent instructions for Codex, Claude Code, and Cursor. The default minimal profile adds guardrails only. The python, typescript, and monorepo profiles add Python, TypeScript, or mixed Python+TypeScript starter layouts.

The PyPI package is scaffold-guard; the installed command is scaffold-guard.

Documentation: https://damienbenveniste.github.io/ScaffoldGuard/

Install

uv tool install scaffold-guard
scaffold-guard version

Publishing

Maintainers publish scaffold-guard through GitHub Actions Trusted Publishing. No PyPI API token is required. To release a new version, create a GitHub Release or manually run the Publish workflow from main.

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md before opening a change.

Please report security issues privately through SECURITY.md, not in public issues.

Quickstart

Start the guided setup and answer the prompts. This example assumes you enter my_project as the project name and keep the default minimal profile.

scaffold-guard init
cd my_project
scaffold-guard check
scaffold-guard validate --quick

Generated projects include CI and local development defaults, but the user-facing CLI remains the installed scaffold-guard command.

For non-interactive use with defaults, pass the options as flags:

scaffold-guard init my_project --agent all

If you already created and entered a project folder, run the same guided setup command from that folder. Press Enter at the project-name prompt to use the current directory. Existing unrelated files are preserved; if a generated destination such as README.md already exists, ScaffoldGuard stops unless you rerun with --force.

scaffold-guard init

Generate for one agent surface:

scaffold-guard init codex_demo --agent codex
scaffold-guard init claude_demo --agent claude
scaffold-guard init cursor_demo --agent cursor

Choose GitLab CI instead of GitHub Actions when needed:

scaffold-guard init gitlab_demo --ci gitlab

Generate a full Python package scaffold when you want source, tests, docs, and package tooling. Guided setup lets you choose strict, standard, or disabled Ruff linting; strict, standard, or disabled Python type checking; and whether type checking uses mypy, Pyright, or both. Strict Ruff plus mypy and Pyright are the defaults.

scaffold-guard init python_demo --guided
cd python_demo
uv sync --all-groups
scaffold-guard validate --quick

Generate a TypeScript package when you want npm scripts and configurable TypeScript tooling. Strict compiler mode, Biome, and Vitest are enabled by default and can be changed during guided setup or with flags:

scaffold-guard init ts_demo --profile typescript
cd ts_demo
npm install
scaffold-guard validate --quick

Generate a Python + TypeScript monorepo when you want both language workspaces managed from one repository. The default application layout puts the Python workspace in apps/api and the TypeScript workspace in apps/web:

scaffold-guard init app_demo --profile monorepo
cd app_demo
uv sync --all-groups
npm install
scaffold-guard validate --quick

Guided setup prompts for the monorepo layout. For non-interactive generation, choose application, library, or custom with flags:

scaffold-guard init app_demo --profile monorepo --monorepo-layout application
scaffold-guard init sdk_demo --profile monorepo --monorepo-layout library
scaffold-guard init custom_demo --profile monorepo --monorepo-layout custom \
  --python-workspace services/api --typescript-workspace clients/web

The library layout uses packages/core and packages/client. Custom workspace paths must be explicit, safe, non-overlapping relative directories.

Use --dry-run to preview files and --force to overwrite known generated files.

Generated Project

The default minimal profile creates guardrails only:

my_project/
  .scaffold-guard/manifest.json
  AGENTS.md
  .codex/config.toml
  .codex/hooks.json
  .codex/agents/*.toml
  .codex/hooks/workflow-evidence.sh
  .codex/rules/git.rules
  .codex/rules/validation.rules
  README.md
  LICENSE
  pyproject.toml
  scaffold-guard.toml
  .github/workflows/ci.yml  # or .gitlab-ci.yml

The python profile adds a Python package scaffold:

my_project/
  .scaffold-guard/manifest.json
  AGENTS.md
  README.md
  LICENSE
  pyproject.toml
  mkdocs.yml
  pyrightconfig.json  # when Pyright is enabled
  scaffold-guard.toml
  .github/workflows/  # or .gitlab-ci.yml
  docs/
  examples/
  src/my_project/
  tests/unit/
  tests/integration/

The typescript profile adds a TypeScript package scaffold with configurable compiler strictness, Biome, and Vitest defaults:

my_project/
  .scaffold-guard/manifest.json
  AGENTS.md
  README.md
  LICENSE
  pyproject.toml
  package.json
  tsconfig.json
  tsconfig.build.json
  biome.json  # when Biome is enabled
  vitest.config.ts  # when Vitest is enabled
  scaffold-guard.toml
  .github/workflows/ci.yml  # or .gitlab-ci.yml
  src/
  tests/  # when Vitest is enabled

The monorepo profile adds Python and TypeScript workspaces. Its default application layout is:

my_project/
  .scaffold-guard/manifest.json
  AGENTS.md
  README.md
  LICENSE
  pyproject.toml
  package.json
  biome.json  # when Biome is enabled
  pyrightconfig.json  # when Pyright is enabled
  scaffold-guard.toml
  .github/workflows/ci.yml  # or .gitlab-ci.yml
  apps/api/
  apps/web/

The library layout replaces those workspace roots with packages/core/ and packages/client/. A custom layout uses the exact safe relative directories passed with --python-workspace and --typescript-workspace.

Adapter files are added according to --agent:

For Codex, AGENTS.md remains behavioral guidance: it tells agents how to work in the repository. .codex/config.toml enables Codex features and project-scoped agent defaults, .codex/rules/*.rules handles command permission policy, and .codex/hooks.json runs generated hook commands for mechanical workflow evidence and checks around tool use through .codex/hooks/workflow-evidence.sh. Generated Codex git rules allow repo-local uv run scaffold-guard publish as the audited approval-free commit and push path while protecting raw git commit and git push.

Commands

scaffold-guard init [NAME] [--guided] [--profile minimal|python|typescript|monorepo] [--monorepo-layout application|library|custom] [--python-workspace PATH] [--typescript-workspace PATH] [--agent codex|claude|cursor|all] [--ci github|gitlab] [--ruff strict|standard|off] [--python-typecheck strict|standard|off] [--python-typechecker mypy+pyright|mypy|pyright] [--typescript-mode strict|standard] [--typescript-lint biome|off] [--typescript-test vitest|off]
scaffold-guard check [--path .] [--json]
scaffold-guard inspect-diff [--path .] [--base main] [--json]
scaffold-guard validate [--path .] [--quick] [--json]
scaffold-guard upgrade [--path .] [--apply] [--json] [--accept-legacy PATH]
uv run scaffold-guard publish [--path .] --message "Update project" [--all|--file PATH] [--remote origin] [--branch feature] [--quick]
scaffold-guard compile-rules [--path .] [--agent codex|claude|cursor|all] [--dry-run] [--force]
scaffold-guard doctor [--path .] [--json]
scaffold-guard version

compile-rules default regeneration only replaces existing managed files when their current content exactly matches the content ScaffoldGuard would render. Generated markers identify managed files, but markers alone are not proof that a file can be replaced. Use --force only after review when replacement is intentional. After installing a newer ScaffoldGuard version, preview and apply scaffold-guard upgrade before running compile-rules so structured metadata and managed templates advance together.

Use repo-local uv run scaffold-guard publish --message "Update project" --all only after an explicit user request to publish from a generated project. The repo-local invocation resolves the generated project's pinned ScaffoldGuard version, runs generated-project validation, refuses mixed staged and unstaged scope, commits with an explicit message, and pushes the reviewed branch.

Use scaffold-guard upgrade to preview generated-project maintenance before writing anything. Add --apply only after reviewing the preview and explicitly choosing to write. Upgrades reconcile hash-clean managed files, limit structured migrations to reserved metadata in scaffold-guard.toml and the scaffold-guard development requirement or tool-carrier in pyproject.toml, and never touch seed files. Orphans are reported, not deleted or pruned. After an applied upgrade, run scaffold-guard check and scaffold-guard validate. Existing v0.2 monorepos are recorded with the internal legacy layout and their existing packages/python and packages/typescript workspace paths; upgrade does not move or delete their seed files.

Profile choices:

For when to use each command, available options, and exit-code behavior, read the full command reference: https://damienbenveniste.github.io/ScaffoldGuard/commands/

Local Development

Run the package gate from this repository:

uv sync --all-groups --frozen
uv run ruff format --check .
uv run ruff check .
uv run mypy src tests
uv run pyright
uv run pytest tests --cov=scaffold_guard --cov-report=term-missing --cov-fail-under=95
uv run mkdocs build --strict
uv build

Limitations

V1 is a developer CLI, not a SaaS product or policy server. It does not include telemetry, external AI calls, Claude hooks, a plugin system, Homebrew automation, or automatic adoption of mature existing repositories.

Homebrew distribution, more specialized project profiles, and richer policy configuration are intentionally deferred until after the PyPI package is stable.