Path 03 — Python package

A Python package others (or future-you) install: library on PyPI/private index, importable module, optional console scripts. One primary artifact — not a polyglot monorepo unless shared code already forces it.

Assumes Path 01 / Path 02 habits: vision, tests, honest docs, CI that means something. A CLI implemented in Python can sit on Path 02; use this path when the main product is the importable package (with or without entry points).

What “Python package” means here

• pyproject.toml (preferred) defining name, deps, optional extras, build backend
• Install via pip / uv / poetry / private index; versioned releases
• Success = a cold developer pip installs (or uv adds) and completes the primary job via import or console script

What to ignore (for now)

Skip	Why
Multi-service deploy mesh	Packages are published, not “deployed” like apps — see Compute only if you also ship a service
Monorepo “just in case”	One package first; extract when duplication hurts (kiss / repos monorepo)
Supporting every Python forever	Declare requires-python; test the matrix you claim
Agent swarms for packaging	One writer; clear done-when

Reading order

1. Lifecycle: How work flows — usually Deliver / Maintain
2. Architecture: Architecture · language defaults (Python is already the pick)
3. Concepts: Smallest Next Step · Evidence over Vibes · Stop Conditions · Vision-Tied Goals
4. Strategies: Orient · Track Work · Craft and Harden · Ship · Diagnose and Fix when imports break
5. Practices: Research It · Test It · KISS · Document It · Repos (ci, release workflow) · Check Readiness · Issues / Pulls · Merge It

Treat agents and other packages as users: stable public API, typed where it helps, no surprise side effects on import.

Starter DAG

flowchart TD
  A[Vision: one job the package enables] --> B[pyproject + src layout]
  B --> C[Happy-path import or console script]
  C --> D[test-it: unit + one install smoke]
  D --> E[document-it: install, API, examples]
  E --> F[repos ci: lint/type/test on matrix you claim]
  F --> G[Version + publish to index]
  G --> H[pulls / merge-it for changes]

Right-sized tasks:

1. Name the public API surface and non-goals.
2. src/ layout + build backend that others can install from git/PyPI.
3. Tests that fail when the API regresses; optional console script smoke.
4. README: install, minimal example, versioning policy.
5. CI + a repeatable release (tag → build → publish).

Skills cheat sheet

Moment	Skill
API / packaging choices	research-it · kiss
Prove behavior	test-it · check-readiness
Docs / examples	document-it
CI / trusted publishing	repos ci · repos ci harden · repos secrets if OIDC to PyPI
Bugs	diagnose-bug · fix-it
Lost	idk-now

Graduate when

• The package is one of many shared libs / apps → Path 04 — Monorepo
• You also run long-lived or serverless compute beside the library → Compute deployments
• A thin CLI is the main UX → prefer Path 02 and keep the library internal or dual-published deliberately

Follow-Up Prompt

Want kiss on the public API surface, or repos ci for a first test+publish workflow?