scaffold-guard 0.1.5

Generate guarded starter repositories for Codex, Claude Code, and Cursor.

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:

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

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

Generated Project

The default minimal profile creates guardrails only:

my_project/
  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/
  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/
  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:

my_project/
  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
  packages/python/
  packages/typescript/

Adapter files are added according to --agent:

Agent	Generated files
codex	AGENTS.md, .codex/config.toml, .codex/agents/*.toml, .codex/hooks.json, .codex/hooks/workflow-evidence.sh, .codex/rules/*.rules
claude	AGENTS.md, CLAUDE.md, .claude/rules/*.md
cursor	AGENTS.md, .cursor/rules/*.mdc
all	all of the above

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] [--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]
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.

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.

Profile choices:

Profile	Meaning
minimal	Guardrails only; no Python or TypeScript source scaffold
python	Python package scaffold with src/, tests, docs, and uv
typescript	TypeScript package scaffold with npm and configurable TypeScript tooling
monorepo	Python + TypeScript workspaces under packages/

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 upgrades for mature existing repositories.

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