diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..68ac18f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,30 @@ +# Repository Guidelines + +## Project Structure & Module Organization +- `src/cascadingdev/` hosts the CLI (`cli.py`), installer logic (`setup_project.py`), scaffolding helpers (`feature_seed.py`, `rules_seed.py`, `fs_scaffold.py`), and shared utilities; keep new modules here under clear snake_case names. +- `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-/` 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___()` 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. diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..93e7cbb --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,68 @@ +# CascadingDev Project Overview + +**CascadingDev** (CDev) is a Python project designed as a Git-native AI–human collaboration framework. It automates documentation, discussion summaries, and code review directly within a Git repository, enabling the creation of self-documenting projects. AI assists in generating and maintaining feature discussions, design documents, and implementation plans, all version-controlled alongside the code. + +## Key Features + +* **Git-Integrated Workflow:** All discussions, decisions, and artifacts are version-controlled within Git. +* **Cascading Rules System:** Automation behavior is defined by the nearest `.ai-rules.yml` file. +* **Stage-Per-Discussion Model:** Uses separate files for different stages like feature, design, implementation, testing, and review. +* **Pre-commit Hook:** Automatically maintains summaries, diagrams, and vote tallies. +* **Ramble GUI:** A PySide6/PyQt5-based graphical user interface for capturing structured feature requests, integrating with AI providers like Claude. +* **Deterministic Builds:** Provides a reproducible installer bundle. + +## Technologies Used + +* **Python:** Primary language for the project. +* **PySide6/PyQt5:** For the Ramble GUI. +* **PlantUML:** For generating diagrams. +* **Claude CLI:** An AI provider integrated with the Ramble GUI. +* **Git:** Core version control system. + +## Building and Running + +The project uses `setuptools` for building. The main CLI entry point is `cdev`. + +### Installation and Setup + +1. **Create and activate a virtual environment:** + ```bash + python3 -m venv .venv + source .venv/bin/activate + pip install --upgrade pip wheel PySide6 + ``` +2. **Build the installer bundle:** + ```bash + python tools/build_installer.py + ``` +3. **Test-install into a temporary folder:** + ```bash + python install/cascadingdev-*/setup_cascadingdev.py --target /tmp/myproject --no-ramble + ``` + +### CLI Commands + +* **`cdev --version`**: Show the project version. +* **`cdev doctor`**: Checks the environment and required templates. +* **`cdev smoke`**: Runs a smoke test. +* **`cdev build`**: Builds the installer bundle without bumping the version. +* **`cdev release --kind [major|minor|patch]`**: Bumps the project version (major, minor, or patch) and rebuilds the installer. +* **`cdev pack [--out ]`**: Zips the current installer bundle. +* **`cdev bundle-smoke [--keep] [--ramble] [--bundle ] [--target ]`**: Unpacks the zipped installer and runs it into a temporary directory for testing. +* **`cdev feature [--title ] [--description <desc>] [--target <dir>] [--no-ramble] [...]`**: Creates a new feature scaffold. This command can optionally open a "Ramble" dialog for guided feature definition using an AI. + +## Development Conventions + +* **Git-centric:** The workflow is heavily integrated with Git for version control and collaboration. +* **AI-assisted:** AI tools (like Claude via the Ramble GUI) are used to assist in generating documentation, summaries, and design elements. +* **Rule-driven:** The project uses a cascading rules system (`.ai-rules.yml`) to define automation behavior. +* **Pre-commit hooks:** Used to automate tasks before commits. + +## Further Exploration + +* `docs/DESIGN.md`: Design documentation template. +* `docs/FEATURE_REQUEST.md`: Feature request template. +* `docs/USER_GUIDE.md`: User guide template. +* `assets/templates/rules/`: Contains AI rule definitions. +* `assets/hooks/pre-commit`: The pre-commit hook script. +* `assets/runtime/ramble.py`: Source code for the Ramble GUI. diff --git a/src/cascadingdev.egg-info/PKG-INFO b/src/cascadingdev.egg-info/PKG-INFO new file mode 100644 index 0000000..e073cd4 --- /dev/null +++ b/src/cascadingdev.egg-info/PKG-INFO @@ -0,0 +1,5 @@ +Metadata-Version: 2.4 +Name: cascadingdev +Version: 0.1.0 +Summary: CascadingDev: scaffold rule-driven multi-agent project repos +Requires-Python: >=3.10 diff --git a/src/cascadingdev.egg-info/SOURCES.txt b/src/cascadingdev.egg-info/SOURCES.txt new file mode 100644 index 0000000..0b9e8c4 --- /dev/null +++ b/src/cascadingdev.egg-info/SOURCES.txt @@ -0,0 +1,16 @@ +README.md +VERSION +pyproject.toml +src/cascadingdev/__init__.py +src/cascadingdev/cli.py +src/cascadingdev/feature_seed.py +src/cascadingdev/fs_scaffold.py +src/cascadingdev/ramble_integration.py +src/cascadingdev/rules_seed.py +src/cascadingdev/setup_project.py +src/cascadingdev/utils.py +src/cascadingdev.egg-info/PKG-INFO +src/cascadingdev.egg-info/SOURCES.txt +src/cascadingdev.egg-info/dependency_links.txt +src/cascadingdev.egg-info/entry_points.txt +src/cascadingdev.egg-info/top_level.txt \ No newline at end of file diff --git a/src/cascadingdev.egg-info/dependency_links.txt b/src/cascadingdev.egg-info/dependency_links.txt new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/src/cascadingdev.egg-info/dependency_links.txt @@ -0,0 +1 @@ + diff --git a/src/cascadingdev.egg-info/entry_points.txt b/src/cascadingdev.egg-info/entry_points.txt new file mode 100644 index 0000000..c9ec8f3 --- /dev/null +++ b/src/cascadingdev.egg-info/entry_points.txt @@ -0,0 +1,2 @@ +[console_scripts] +cdev = cascadingdev.cli:main diff --git a/src/cascadingdev.egg-info/top_level.txt b/src/cascadingdev.egg-info/top_level.txt new file mode 100644 index 0000000..8042bef --- /dev/null +++ b/src/cascadingdev.egg-info/top_level.txt @@ -0,0 +1 @@ +cascadingdev