Skip to content

ScaffoldGuard

scaffold-guard creates strict starter repositories for coding-agent workflows. The default minimal profile adds agent guardrails, GitHub Actions or GitLab CI, local policy checks, and agent instruction files without forcing a Python package layout. The python, typescript, and monorepo profiles add typed Python, TypeScript, or mixed Python+TypeScript starter layouts.

What V1 Provides

  • scaffold-guard init for minimal guardrails, Python packages, TypeScript packages, or Python+TypeScript monorepos.
  • AGENTS.md behavioral guidance plus .codex/config.toml feature defaults, .codex/agents/*.toml worker defaults, .codex/rules/*.rules command permission policy, and .codex/hooks.json workflow checks when Codex is selected.
  • CLAUDE.md plus .claude/rules/*.md when Claude Code is selected.
  • .cursor/rules/*.mdc when Cursor is selected.
  • scaffold-guard check for fast local policy checks.
  • scaffold-guard inspect-diff for diff-specific validation guidance.
  • scaffold-guard upgrade for a read-only preview and an explicit, reviewed --apply path.
  • scaffold-guard validate, publish, compile-rules, doctor, and version.

See the command reference for when to use each command, available options, and exit-code behavior.

Basic Flow

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

uv tool install scaffold-guard
scaffold-guard init
cd my_project
scaffold-guard check
scaffold-guard validate --quick

The init command starts guided setup when NAME is omitted. Leave the project-name prompt blank to initialize the current empty folder, or enter a name to create a new project directory. Choose python when you want Python source, tests, docs, and Python tooling. Choose typescript for npm and TypeScript tooling. Choose monorepo when one repository should contain Python and TypeScript workspaces. Monorepo guided setup asks for an application layout (apps/api plus apps/web, the default), a library layout (packages/core plus packages/client), or two explicit safe relative workspace paths for a custom layout. Python and monorepo guided setup asks for Ruff linting strictness, Python type-checking strictness, and the Python type checker. TypeScript and monorepo guided setup asks for TypeScript compiler, formatter/linter, and test-runner choices. Pass NAME and flags for non-interactive use with defaults. Use --ci gitlab when the generated project should use GitLab CI instead of GitHub Actions.

For non-interactive custom monorepos, pass --monorepo-layout custom together with both --python-workspace and --typescript-workspace.

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

Read the quickstart first, then use the command reference, adapter, and checks pages when tuning a generated project.