New Python Project

---
name: new-python-project
description: "Bootstrap a new Python project from a proven scaffold. Use whenever the user asks to start, create, scaffold, or set up a new Python tool, library, CLI, package, service, or experiment repo — or says 'set up a project the usual way'. Do NOT hand-roll a project structure from memory when this skill is available: run its script instead. Produces a src-layout package with pyproject.toml, tests, Makefile, an agent contract (AGENTS.md + CLAUDE.md), operating docs, a review checklist, and a definition of done — a project any agent or human can pick up cold."
---

# New Python Project

This skill instantiates the scaffold stored in `assets/template/`. The
scaffold's guarantees: a fresh generation **installs cleanly, passes
`make test`, and answers `--help`** before any feature code is written. Do
not improvise a different layout when this skill applies.

## 1. When to use / when not

- **Use**: any brand-new Python repo — tool, library, CLI, service skeleton,
  experiment that may outlive the week.
- **Do not use**: adding code to an existing project (respect its existing
  layout instead), or a non-Python project (you may still copy the
  conventions in `assets/OPERATING_MANUAL.md`, which are language-agnostic;
  only the template itself is Python).

## 2. Gather the three inputs

Derive these without asking, unless the rules below force a question:

1. **project_name** — kebab-case, from the user's own words for the thing
   (e.g. "a log deduplicator" → `log-deduplicator`). Strip filler words.
   Rules: lowercase letters, digits, hyphens only; must not collide with an
   existing directory at the target location.
2. **package_name** — `project_name` with hyphens replaced by underscores.
   Must be a valid Python identifier: if it starts with a digit or clashes
   with a stdlib module name you know (e.g. `json`, `test`), prefix or
   reword it, and note the choice.
3. **description** — one sentence, taken from the user's request. If the
   request contains no describable purpose, use a neutral one-liner and flag
   in your report that the description is a placeholder.

Only ask the user if the project's *purpose* is genuinely unknowable from
the request — never ask about naming mechanics.

## 3. Choose the target directory

| Situation | Target |
|---|---|
| User named a path | that path |
| Current directory is empty or clearly meant to become the project | current directory |
| Otherwise | a new sibling directory named `<project_name>` under the user's usual projects location (default: home or current directory) |

Never generate inside another project's source tree.

## 4. Generate

```bash
python3 <this-skill>/scripts/new_project.py TARGET_DIR \
    --name PROJECT_NAME --description "ONE SENTENCE" [--package PACKAGE_NAME]
```

The script is stdlib-only. It refuses to write into a non-empty directory,
replaces all placeholders, copies the review checklist and definition of
done into `docs/`, and fails loudly if any placeholder survives. Trust its
exit code: nonzero means the generation is unusable — read its message, fix
the input, rerun.

If the target is non-empty and the script refuses: NEVER delete or
overwrite the existing content to force it. Generate into a fresh temporary
sibling directory instead, show the user what exists in their target versus
what the scaffold provides, and move files in only after they choose how to
merge.

## 5. Prove the scaffold before building on it (mandatory)

Run, in order, inside the new project:

```bash
make setup       # creates .venv and installs the package + dev tools
make test        # must end in "passed"
make run         # prints the CLI help
```

If any step fails, fix the environment or report — do not start feature
work on an unproven skeleton. Record the passing output; it is the baseline
for all later work.

If `make` is unavailable (e.g. bare Windows), run the underlying commands —
they are what the Makefile targets contain:

| Target | Raw commands |
|---|---|
| `setup` | `python3 -m venv .venv` then `.venv/bin/pip install -e ".[dev]"` (Windows: `.venv\Scripts\pip`) |
| `test` | `.venv/bin/python -m pytest` |
| `lint` | `.venv/bin/python -m ruff check src tests` |
| `run` | `.venv/bin/python -m <package_name>.cli --help` |

Git: initialize a repository only if the user wants one, and follow the
user's stated git conventions. Default: do not commit or push unless asked.

## 6. Customization decision rules

Apply immediately after generation, before feature work:

| Project kind | Do this |
|---|---|
| No CLI needed (pure library) | delete `src/<pkg>/cli.py` and `src/<pkg>/__main__.py`, remove the `[project.scripts]` table from `pyproject.toml`, delete `test_cli_*` and `test_python_dash_m_*` tests in `tests/test_smoke.py`, remove the `run` target's help note in `AGENTS.md` |
| Web service | add the framework to `[project] dependencies`; keep src layout; the app factory lives in `src/<pkg>/`; document run commands in `docs/OPERATING.md` and the `Makefile` `run` target |
| Data / research work | add a `notebooks/` directory; importable logic still goes in `src/<pkg>/`, never only in notebooks |
| Needs config | prefer a documented `config/` file or env vars read in ONE module; document every variable in `docs/OPERATING.md` |

After customizing, rerun `make test` — the skeleton must stay green.

## 7. First feature

Build the first real feature under the `plan-and-verify` skill if it is
available. The scaffold's `AGENTS.md` tells future agents the same.

## 8. What each generated file is for

| File | Purpose | Edit when |
|---|---|---|
| `README.md` | human-first overview with an explicit "what this does not provide" boundary section | every user-visible change |
| `AGENTS.md` | the agent contract: commands, conventions, definition of done | commands or conventions change |
| `CLAUDE.md` | one-line pointer importing `AGENTS.md` | never (keep as pointer) |
| `pyproject.toml` | metadata, deps, pytest/ruff config | deps or tooling change |
| `Makefile` | `setup` / `test` / `lint` / `format` / `run` | new routine commands |
| `src/<pkg>/` | all importable code | always |
| `src/<pkg>/__main__.py` | enables `python -m <pkg>` | never (keep as thin wrapper over `cli.main`) |
| `tests/` | hermetic tests (no network, no real endpoints, no sleeps) | every behavior change |
| `docs/OPERATING.md` | how to run and operate this specific project | operational behavior changes |
| `docs/DECISIONS.md` | dated log of decisions that are not obvious from code | every non-obvious decision |
| `docs/REVIEW_CHECKLIST.md` | pre-merge checklist (copied from scaffold) | team conventions evolve |
| `docs/DEFINITION_OF_DONE.md` | what "done" means here (copied from scaffold) | team conventions evolve |

## Files in this skill

- `scripts/new_project.py` — the generator (stdlib-only).
- `assets/template/` — the scaffold source tree with `{{placeholders}}`.
- `assets/OPERATING_MANUAL.md` — language-agnostic conventions the scaffold
  implements; read it when adapting these ideas outside Python.
- `assets/REVIEW_CHECKLIST.md`, `assets/DEFINITION_OF_DONE.md` — copied into
  each generated project's `docs/`.