76 lines
4.5 KiB
Markdown
76 lines
4.5 KiB
Markdown
# 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.
|
||
* **Automated Status Promotion:** Discussion statuses are automatically promoted based on participant votes (e.g., `OPEN` → `READY_FOR_DESIGN`).
|
||
* **Cascading Rules System:** Automation behavior is defined by the nearest `.ai-rules.yml` file.
|
||
* **Participant Agents:** Rules can invoke modular Python scripts registered per discussion to post comments, diagrams, or reminders.
|
||
* **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 <path>]`**: Zips the current installer bundle.
|
||
* **`cdev bundle-smoke [--keep] [--ramble] [--bundle <path>] [--target <path>]`**: Unpacks the zipped installer and runs it into a temporary directory for testing.
|
||
* **`cdev feature <name> [--title <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. If the GUI is unavailable or `--no-ramble` is specified, it falls back to interactive terminal prompts.
|
||
|
||
## 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.
|
||
|
||
## Participant Agents
|
||
|
||
Rules can list `participants` to invoke standalone agent scripts such as `agents/moderator.py` or `agents/visualizer.py`. These scripts import the shared SDK in `src/cascadingdev/agent/` to read the staged discussion,
|
||
ask an AI provider for structured output, and append a single block (vote, reminder, diagram reference) before generator outputs run. Set `background: true` for tool-style agents that should continue their work after the commit completes; these service agents respond with information only and never cast votes. This architecture makes it easy to add new personas without touching the core runner.
|
||
|
||
## 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.
|