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

## Build, Test, and Development Commands
- `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.

## Coding Style & Naming Conventions
- 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.

## Testing Guidelines
- 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.

## Commit & Pull Request Guidelines
- 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.