scaffold-guard 0.1.0

Generate guarded Python project starters for Codex, Claude Code, and Cursor.

ScaffoldGuard

scaffold-guard generates strict Python starter repositories for teams using coding agents. It creates a typed package layout, local validation commands, GitHub Actions workflows, and agent instructions for Codex, Claude Code, and Cursor.

The PyPI package and uvx entrypoint are scaffold-guard; the canonical installed command is scaffold-guard.

Install

After the package is published to PyPI:

uvx scaffold-guard version

From a local checkout or built wheel:

uv sync --all-groups
uv run scaffold-guard version
uv build
uvx --from dist/scaffold_guard-0.1.0-py3-none-any.whl scaffold-guard version

Publishing

PyPI publishing is prepared through GitHub Actions Trusted Publishing. Before the first release, configure a PyPI pending publisher for:

Project name: scaffold-guard
Owner: damienbenveniste
Repository: ScaffoldGuard
Workflow: publish.yml
Environment: pypi

No PyPI API token is required. After the pending publisher exists, publish a GitHub Release or manually run the Publish workflow from main.

Quickstart

Generate a project with every supported adapter:

uvx scaffold-guard init my_project --agent all
cd my_project
uv sync --all-groups
uv run scaffold-guard check
uv run scaffold-guard validate --quick

Generate for one agent surface:

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

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

Generated Project

The default package profile creates:

my_project/
  AGENTS.md
  README.md
  LICENSE
  pyproject.toml
  pyrightconfig.json
  scaffold-guard.toml
  .github/workflows/
  docs/
  examples/
  src/my_project/
  tests/unit/
  tests/integration/

Adapter files are added according to --agent:

Agent	Generated instruction files
codex	AGENTS.md
claude	AGENTS.md, CLAUDE.md, .claude/rules/*.md
cursor	AGENTS.md, .cursor/rules/*.mdc
all	all of the above

Commands

scaffold-guard init NAME [--agent codex|claude|cursor|all]
scaffold-guard check [--path .] [--json]
scaffold-guard inspect-diff [--path .] [--base main] [--json]
scaffold-guard validate [--path .] [--quick] [--json]
scaffold-guard compile-rules [--path .] [--agent codex|claude|cursor|all] [--dry-run] [--force]
scaffold-guard doctor [--path .] [--json]
scaffold-guard version

check runs fast policy checks. inspect-diff explains validation obligations for changed files in a git repository. validate runs the generated project's configured validation gate. compile-rules regenerates managed agent instruction files from templates. doctor reports local tool and generated project health.

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, Codex or Claude hooks, a plugin system, Homebrew automation, or automatic upgrades for mature existing repositories.

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