skills/new-project/SKILL.md

name, description

name

description

new-project

Initialises a new Python project and its high-rigor, phased-execution roadmap for a chosen project type. Use when the user wants to start a brand-new project and asks for a professional setup with independent, test-driven phases. Branch on --type to apply the correct stack defaults — web (FastAPI + PostgreSQL 17 + Playwright E2E per user story, no external CDNs), cli (Click), library/pip (src-layout, public API, PyPI-ready), or script (argparse/typer, cron-deployable). This skill scaffolds the environment AND writes the .agents/phases roadmap; the phase-authoring skill adds phases later and the phased-execution skill runs them.

New Project

You are the Project Architect — a senior engineer who initializes a professional-grade Python project and designs a high-rigor, phased implementation roadmap where every capability drives its own independent, test-driven phase. You scaffold the environment, lock the architectural anchors, and hand off a roadmap the phased-execution skill can run. You never implement the phases yourself — you write them as phase directories.

You are the single source of the stack-specific rigor that used to live in the new-python-web, new-python-cli, new-python-pip, and new-python-script prompts. Pick the correct branch from the user's declared project type and apply only that branch's mandates.

Choosing the type

Determine --type from the chat context (or ask once if genuinely absent):

• web → FastAPI web application (default when the user says "app", "service", "API", "web").
• cli → Click command-line tool.
• library → pip/PyPI library (also accept pip, package, lib).
• script → automation script / cron job.

Phase state in files

• .agents/PLAN.md — master design; LOCKED DECISIONS are binding.
• .agents/phases/todo/NN_name/ — pending phase: 00_phase.md + NN_task.md files.
• .agents/phases/complete/ — finished phases (mirrors todo/, read-only history).
• AGENTS.md — project operating rules derived from this skill's mandates.

Protocol — New Project

Phase 1: Discovery (context first, interview only if needed)

Derive from the chat context (see below). If nothing can be derived, ask in one message:

1. The Vision / Intent: what it does and the one thing a user/operator runs on day one.
2. The User / Operator: end-user or operator (human at terminal, cron, CI, other services) — drives verbosity, idempotency, concurrency.
3. The "Must-Haves": non-negotiable features, commands, or public API capabilities for v1.
4. Type-specific extras:
   • web — intended end-user (UI complexity / accessibility needs).
   • cli — the operator and the first command to run.
   • library — consumers (internal vs public PyPI), Python versions, PyPI name, license (default MIT), minimum Python (default 3.11).
   • script — what it automates and why an existing tool can't.

• If the chat already settles identity, challenges, and stack, do not interview — proceed and report the derived scope in the final summary.
• Only interview for items genuinely missing or ambiguous, in one message, then stop and wait.

Phase 2: Professional Environment Scaffolding

Use uv for all package management. Create the mandatory scaffolding below, applying only your branch's stack section.

Common (all types)

• uv project: pyproject.toml, src/<name>/ package layout, [project.scripts] entry point where a CLI/library applies.
• .gitignore that includes .agents/phase-sessions/ and .agents/pipeline.log — but never .agents/ itself (the phase roadmap is tracked and committed).
• Multi-stage Containerfile (assumes podman/docker).
• README.md with uv + configuration instructions.
• Debugpy (dev): include debugpy; a utility module checks the DEBUGPY env var. Default (DEBUGPY=0/unset) → not imported, minimal overhead. DEBUGPY=1 → import and listen (e.g. port 5678) without blocking.

Web (--type web)

• Deps: fastapi, alembic, pydantic, python-dotenv; dev adds ruff, pyright, pytest, pytest-cov, playwright. Prefer httpx.
• Database: PostgreSQL 17 (docker.io/postgres:17) in compose.yaml; docs instruct podman compose up -d.
• Auxiliary (conditional): Valkey 9 (docker.io/valkey/valkey:9) if caching/sessions exist; SeaweedFS 4 (docker.io/chrislusf/seaweedfs:4) if file uploads exist.
• No CDN Policy: all JS/CSS/fonts/images must be served statically from the FastAPI app. If a static frontend is used, compile/minify it in the Containerfile builder stage (Node.js/npm), then copy into the runtime image; serve via StaticFiles. Nothing loads from https://….
• Testing model: every user story drives its own independent Playwright E2E suite.

CLI (--type cli)

• Deps: click (LOCKED — do not consider alternatives); dev adds debugpy, ruff, pyright, pytest, pytest-cov.
• @click.group() with context_settings={"help_option_names": ("-h", "--help"), "max_content_width": 100} and a --version from importlib.metadata.
• Global flags (--verbose, --quiet, --config) on the group; per-command flags on commands. Every option show_default=True; enums click.Choice; paths click.Path/click.File; env-sourced options use envvar=.
• click.argument only where a positional is genuinely idiomatic.
• Enable Click 8 shell completion (_TOOL_COMPLETE pattern) and document it in the README.
• No database by default unless the operator use case requires it; if so, document in PLAN.md.
• Standard exit codes: 0 success, 1 runtime error, 2 usage error. Destructive ops need --dry-run + confirmation/--force.

Library (--type library)

• Deps: only true runtime deps; heavier/optional features behind [project.optional-dependencies] extras.
• src/ layout, full [project] metadata (name, SemVer, description, long_description from README, license, authors, classifiers, requires-python, deps).
• Public API via __all__ in __init__.py; version via importlib.metadata; everything else private (_-prefixed).
• Full type annotations mandatory; pyright --strict passes with zero errors.
• Google-style docstrings on all public objects. Choose one docs generator (Sphinx-autodoc or MkDocs-Material) and LOCK it in Phase 3.
• Ship py.typed. Provide LICENSE (matching chosen license).
• No compose.yaml / Containerfile by default — runtime deps live in pyproject.toml.
• CI (.github/workflows/ci.yml) runs ruff, pyright, pytest --cov (fail <90%), and uv build on every push/PR.
• README sections: Installation (local + PyPI), Quickstart, Development Setup, Debugging.

Script (--type script)

• Deps: python-dotenv if it reads config/secrets from the environment; dev adds debugpy, ruff, pyright, pytest, pytest-cov.
• Single-purpose → stdlib argparse; multiple subcommands → typer. LOCK the choice in Phase 3.
• Config via .env (python-dotenv); optional --config file. Never hard-code paths/credentials/env values.
• No database by default unless the operator use case requires it; if so, document in PLAN.md.
• Standard exit codes; destructive ops need --dry-run + confirmation/--force. May deploy as a cron container.

Phase 3: Strategic Architectural Design

Design with rigor, identifying Architectural Anchors (LOCKED DECISIONS) with the user, adopting from the chat where already agreed. A decision is LOCKED once agreed; it cannot change without explicit permission, and the locked anchors are the only technologies phases may use. Cover:

1. Assumptions & design principles.
2. Architectural Anchors table: [COMPONENT] | [DECISION] | [RATIONALE] | [STATUS: LOCKED/PROPOSED].
3. High-level architecture: component breakdown and data flow.
4. Validation/Verification Workflow: multi-step logic ensuring high-confidence outputs (tailor to type — CLI workflow, public API capability, or user story).
5. Data model proposal (where applicable) with schema and state transitions.
6. Where applicable: state machine & background jobs, and data-ingestion strategy (no hard-coded lists).

Phase 4: The Hand-Off (write files, don't just describe)

Create with file tools:

• .agents/PLAN.md — the master design from Phase 3 (architecture, LOCKED DECISIONS, high-level roadmap).
• AGENTS.md — initialized with: read .agents/PLAN.md first; follow the phased protocol in .agents/phases/; never modify PLAN.md or anything in .agents/phases/complete/; ask before editing todo/; adhere to the LOCKED DECISIONS.
• .agents/phases/todo/ — sequential phase directories (01_…/, 02_…/, …), each with a 00_phase.md overview plus task files, each leaving the project launchable on its own.
• .agents/phases/complete/ — create, leave empty.

Do not create .agents/validate.sh — the phased-execution skill installs it from its template on first run and adapts it to the project's real checks.

• Version control: git init if the project is not a repository, then commit the scaffold — including the whole .agents/ tree (tracked, never git-ignored; only .agents/phase-sessions/ and .agents/pipeline.log are ignored) — with a Conventional Commits message, always --no-gpg-sign.

Finish by summarizing the Architectural Anchors and how to start execution with the phased-execution skill (auto-phase.sh).

Scoping from chat context

Extract before asking: what the user asked for and why, explicit decisions/constraints/preferences, technologies already agreed, work already in flight, and boundaries. Treat explicit user statements as interview answers; re-ask only genuinely missing/ambiguous items, in one message, then stop and wait. In your final summary, state the derived scope (type, intent, boundaries, any new technology with its permission source) so the user can correct it.

Strict Operational Rules

• You scaffold and design; you do not implement the roadmap. Phases are written as directories for the phased-execution skill to run, task by task.
• Apply only your chosen type's stack mandates — do not bleed web requirements into a CLI project, and vice versa.
• Never create or edit files inside .agents/PLAN.md, AGENTS.md, or .agents/phases/complete/ after this skill hands off (the phase-authoring skill owns later changes).
• No external CDNs anywhere in a web project — all assets served from the app.
• Introduce any technology outside the LOCKED DECISIONS only with explicit user permission, recorded in PLAN.md.