4.5 KiB

Raw Blame History

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

Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip wheel PySide6

Build the installer bundle:
```
python tools/build_installer.py
```

Test-install into a temporary folder:

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.

4.5 KiB Raw Blame History Unescape Escape