Repository Guidelines

Project Structure & Module Organization

src/cascadingdev/ hosts the CLI (cli.py), installer workflow (setup_project.py), package metadata (__init__.py), and shared helpers (utils.py); keep new modules here under clear snake_case names.
automation/workflow.py provides the status reporter that scans staged discussions for votes.
assets/templates/ holds the canonical Markdown and rules templates copied into generated projects, while assets/runtime/ bundles the runtime scripts shipped with the installer.
tools/ contains maintainer scripts such as build_installer.py, bundle_smoke.py, and smoke_test.py; install/ stores the build artifacts they create.
docs/ tracks process guidance (see CLAUDE.md, GEMINI.md, DESIGN.md), and tests/ is reserved for pytest suites mirroring the package layout.

python3 -m venv .venv && source .venv/bin/activate — standard local environment; install editable deps with pip install -e ..
cdev doctor and cdev smoke — quick checks that templates and required files exist.
cdev build (or python tools/build_installer.py) — rebuilds install/cascadingdev-<ver>/ with the latest assets.
cdev pack — zips the bundle after cdev build; pair with cdev bundle-smoke --keep for end-to-end verification.
pytest -q (add tests under tests/) — target fast, module-scoped coverage before running smoke steps.

Follow PEP 8 with four-space indents, type hints (see src/cascadingdev/utils.py), and module-level constants in ALL_CAPS.
Use snake_case for functions and filenames, PascalCase only for classes, and prefer pathlib.Path over raw string paths.
Keep CLI outputs terse and flushed (utils.say), and gate side effects in if __name__ == "__main__": blocks.
Update templates and runtime scripts atomically with code changes so the installer bundle stays internally consistent.

Write pytest modules that mirror the package (e.g., tests/test_cli.py) and name tests test_<module>__<behavior>() for clarity.
Add regression fixtures whenever adjusting template contents; smoke-check with python tools/smoke_test.py before bundling.
Run cdev bundle-smoke --target /tmp/cdev-demo for full installer validation when altering setup flows or hooks.

Use Conventional Commit prefixes observed in history (docs:, build:, feat:, etc.) and keep subject lines under 72 characters.
Reference the touched modules or templates in the body, note any follow-up automation runs, and paste the relevant command output (pytest, smoke) in PR descriptions.
Link issues or design docs whenever adding or modifying workflow stages, and attach before/after screenshots for changes to generated Markdown assets.