Scaffold

New Python Project

Scaffold a project that passes the verify loop green before handover. The base rules live in [templates/AGENTS.md](./templates/AGENTS.md) — that copy is canonical; edit it there when the base evolves (existing repos keep their snapshots).

1. Resolve decisions (lightweight — not a full grill)

Infer answered decisions from the request. If name and kind are clear and no runtime dependency is mentioned, use no runtime dependencies and proceed without confirmation. Use the current working directory as the project parent unless the user specifies another location or that would overwrite an existing project.

1. Name — package name (snake_case importable). Default: derive from the user's description.
2. Kind — what is it?

• Importable library (default) -> uv init --lib
• CLI tool -> uv init --app --package (gives src/ layout + [project.scripts] entry)
• Bare uv init --app is off the table — AGENTS.md mandates src/ layout.

1. Known runtime dependencies — any to add now? Default: none; add later with uv add.

Do not ask about git remotes, CI, or licensing — out of scope, user wires those later.

2. Scaffold

Run in order:

1. uv init --lib (or --app --package )
2. uv add --dev pytest ruff ty hypothesis prek then uv add if any
3. Append [templates/pyproject-snippet.toml](./templates/pyproject-snippet.toml) to the generated pyproject.toml
4. Copy [templates/AGENTS.md](./templates/AGENTS.md) into the repo root as AGENTS.md. If the agent reads a separate config file, point it at the base. If either file already exists, don't overwrite — show a diff against the template and ask.

> Claude Code: write CLAUDE.md containing exactly @AGENTS.md.

1. Copy [templates/pre-commit-config.yaml](./templates/pre-commit-config.yaml) to .pre-commit-config.yaml
2. Write tests/test_smoke.py — import the package's public surface and make one real assertion (e.g. against the generated hello()), so pytest collects at least one test (zero tests = exit code 5 = verify loop red). Note in the test that it should be replaced by the first real test.
3. git init if not already a repo, then uv run prek install

3. Verify

Run the full loop from AGENTS.md:

uv run ruff check --fix && uv run ruff format && uv run ty check && uv run pytest

All four must pass. Fix anything red before continuing — the user receives a working repo, not a TODO list.

4. Implement requested behavior

If the request includes product behavior, a green scaffold is not done:

1. Continue with the tdd tracer-bullet loop: one behavior test, valid RED, minimal implementation (minimal per the AGENTS.md Laziness ladder — don't scaffold structure the behavior doesn't need yet).
2. Replace the generated smoke test once real behavior coverage exists.
3. Run the full verify loop again.

Do not hand over requested behavior covered only by an import, hasattr, or callability test.

5. Hand over

Report: tree of what was created, the verify-loop result, and next steps — uv add real dependencies, trim AGENTS.md sections that don't fit this project, and offer (don't auto-run) an initial commit.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DavisMcCracken
• Source: DavisMcCracken/pyxis
• License: MIT

Install and usage instructions live in the source repository linked above.