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