ScaffoldGuard: Instructions file for Codex

Agent Instructions

These rules apply to every code, test, documentation, template, and configuration change in this repository.

Product Orientation

• Build scaffold-guard: a PyPI-installable Python CLI that generates strict starter repositories designed for safe coding-agent collaboration.
• Public user-facing docs should present uv tool install scaffold-guard followed by the installed scaffold-guard command. Do not advertise transient no-install execution paths, uvx, or uv run scaffold-guard ... in user-facing install or quickstart flows. Keep uv run scaffold-guard ... only for repo-local development, CI, or generated agent operating instructions when project-local dependency resolution is required.
• Preserve the V1 promise: generate a repository with clear agent instructions, strict local tooling, GitHub Actions or GitLab CI, and policy checks that catch common agent mistakes. The default minimal profile should add guardrails only; python should be explicit when users want Python package folders and tooling; typescript and monorepo should be explicit when users want TypeScript or mixed Python+TypeScript starter layouts.
• New monorepo projects should use semantic workspace layouts: application generates apps/api and apps/web, library generates packages/core and packages/client, and custom requires two explicit safe relative paths. Preserve recorded workspace paths when upgrading existing projects; never rename or move user-owned seed directories automatically.
• Keep scaffold-guard init friendly for first-time users: omitting NAME starts guided setup, and leaving the project-name prompt blank initializes the current empty directory. Passing NAME and flags remains the stable automation path. Keep . as a compatibility alias for current-directory automation, but do not present it as the primary guided user flow. Do not add guided-only generation behavior without matching non-interactive flags.
• Guided setup should present meaningful setup choices, not one yes/no prompt per mature tool when a preset or scoped selector is clearer. Keep Python and TypeScript tool prompts profile-aware, and keep generated files, config, CI, validation, docs, and agent instructions synchronized with those choices.
• Keep V1 focused on a developer CLI. Do not add a SaaS dashboard, telemetry, external AI calls, complex YAML DSL, plugin ecosystem, package/release publish automation, or automatic mutation of mature existing repositories. A guarded git commit/push wrapper is acceptable only when it validates, refuses mixed scope, and requires explicit user intent.
• When generated instructions, Codex rules, CI, or docs depend on a ScaffoldGuard command added after the initial release, define its minimum supported ScaffoldGuard version in one shared code constant and render that dependency floor into every generated project profile that can invoke it. Use project-local uv run scaffold-guard ... command forms when stale global installs could shadow the generated dependency.
• Always generate AGENTS.md for scaffolded projects. Treat it as the shared cross-agent instruction source.
• Keep adapter behavior explicit:
  • Codex uses AGENTS.md for behavior.
  • Claude Code uses CLAUDE.md as a wrapper that imports AGENTS.md, with optional .claude/rules/.
  • Cursor uses .cursor/rules/*.mdc plus AGENTS.md.
• Prefer small, shippable V1 behavior over speculative framework design.