33 lines
3.1 KiB
Markdown
33 lines
3.1 KiB
Markdown
# 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/config.py`, `automation/patcher.py`, and `automation/runner.py` implement AI rule evaluation, diff application, and run from the pre-commit hook; `automation/workflow.py` remains the non-blocking status reporter.
|
||
- `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.
|
||
- Guard automation logic with `pytest tests/test_workflow.py` to confirm staged-vs-working-tree handling before shipping workflow changes.
|
||
- 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.
|