New python project

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

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:

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/.