# Scaffold

> Scaffold a new Python project on the uv + ruff + ty + pytest + prek stack. Use when the user wants to create or bootstrap a new Python project, package, library, CLI, or repo.

- **Type:** Skill
- **Install:** `agentstack add skill-davismccracken-pyxis-scaffold`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [DavisMcCracken](https://agentstack.voostack.com/s/davismccracken)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [DavisMcCracken](https://github.com/DavisMcCracken)
- **Source:** https://github.com/DavisMcCracken/pyxis/tree/main/skills/scaffold

## Install

```sh
agentstack add skill-davismccracken-pyxis-scaffold
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.
3. **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`.
5. Copy [templates/pre-commit-config.yaml](./templates/pre-commit-config.yaml) to `.pre-commit-config.yaml`
6. 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.
7. `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](https://github.com/DavisMcCracken)
- **Source:** [DavisMcCracken/pyxis](https://github.com/DavisMcCracken/pyxis)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-davismccracken-pyxis-scaffold
- Seller: https://agentstack.voostack.com/s/davismccracken
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.