85 lines
7.2 KiB
Markdown
85 lines
7.2 KiB
Markdown
# CascadingDev (CDev)
|
||
|
||
**CDev** — short for *Cascading Development* — is a **Git-native AI–human collaboration framework** that automates documentation, discussion summaries, and code review directly within your repository.
|
||
It lets you build self-documenting projects where AI assists in generating and maintaining feature discussions, design docs, and implementation plans — all version-controlled alongside your code.
|
||
|
||
---
|
||
|
||
## Key Features
|
||
- **Git-Integrated Workflow** — every discussion, decision, and artifact lives in Git.
|
||
- **Automated Status Promotion** — discussion statuses are automatically promoted based on participant votes (e.g., `OPEN` → `READY_FOR_DESIGN`).
|
||
- **Multi-Provider AI System** — automatic fallback chains (Claude → Codex → Gemini) with intelligent model selection (fast/quality).
|
||
- **Cascading Rules System** — nearest `.ai-rules.yml` defines how automation behaves.
|
||
- **Participant Agents** — register modular scripts in `.ai-rules.yml` that act on staged discussions before generator outputs run.
|
||
- **Stage-Per-Discussion Model** — separate files for feature, design, implementation, testing, and review.
|
||
- **Pre-commit Hook** — automatically maintains summaries, diagrams, and vote tallies.
|
||
- **Ramble GUI** — friendly PySide6/PyQt5 dialog for capturing structured feature requests.
|
||
- **Deterministic Builds** — a reproducible installer bundle you can unzip and run anywhere.
|
||
|
||
---
|
||
|
||
## Quick Start (Developers)
|
||
|
||
```bash
|
||
# 1. Create and activate a virtual environment
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install --upgrade pip wheel PySide6
|
||
|
||
# 2. Build the installer bundle
|
||
python tools/build_installer.py
|
||
|
||
# 3. Test-install into a temporary folder
|
||
python install/cascadingdev-*/setup_cascadingdev.py --target /tmp/myproject --no-ramble
|
||
```
|
||
## About this project
|
||
|
||
CascadingDev is a sophisticated, Git-native framework designed to weave AI collaboration directly into the software development lifecycle. Its core philosophy is that the Git repository should be the single
|
||
source of truth for not just code, but also for the discussions, decisions, and documentation that shape it.
|
||
|
||
It achieves this through a clever combination of:
|
||
|
||
* A Staged Workflow: Development progresses through distinct, version-controlled stages (Feature Request, Design, Implementation, etc.), each with its own set of Markdown-based artifacts.
|
||
* A Pre-commit Hook: This is the primary engine of automation. On every git commit, a hook analyzes the changed files.
|
||
* Cascading Rules (`.ai-rules.yml`): These files define the automation logic. The hook finds the nearest rule file to a changed file and executes the instructions within, such as summarizing a discussion or
|
||
generating the artifacts for the next stage.
|
||
* Participant Agents (`agents/*.py`): Rule entries can list participant scripts, which are executed before any generator outputs. Each agent uses the shared SDK in `src/cascadingdev/agent/` to read the staged file,
|
||
call an AI provider, and append structured responses (moderator votes, diagrams, research notes). Add `background: true` to let tool-style agents (e.g., researcher or visualizer) run asynchronously after the commit finishes—these service agents provide information only and never cast votes.
|
||
* AI-Powered Actions: The rules trigger AI models to perform tasks like:
|
||
* Summarizing discussions into companion .sum.md files.
|
||
* Promoting status: Automatically changing a discussion's status (e.g., from OPEN to READY_FOR_DESIGN) when the team votes READY.
|
||
* Generating new documents: Creating a draft design document once a feature discussion is approved.
|
||
* Creating and populating source code: Creating a script or a test once called to action from an implementaion discussion.
|
||
* Human-in-the-Loop: The system uses a voting mechanism (VOTE: READY) and configurable policies to ensure that critical transitions require human approval, blending AI automation with human oversight.
|
||
* The `Ramble` GUI: A user-friendly desktop application that uses AI to help developers articulate and structure their initial feature requests, which kicks off the entire workflow.
|
||
|
||
In essence, this is a system for building self-documenting and self-organizing projects where the administrative overhead of tracking decisions and updating documentation is largely automated.
|
||
|
||
* The Git-Native Approach: By avoiding external databases or services, the entire project context is self-contained, portable, and version-controlled. This is powerful.
|
||
* The Pre-commit Workflow: Integrating the automation into the git commit command is a seamless way to embed this process into a developer's natural workflow without requiring them to learn a host of new commands
|
||
for daily work.
|
||
* Flexibility and Control: The cascading rules system provides a flexible way to define automation at different levels of the project, and the policy files (process/policies.yml) give teams fine-grained control
|
||
over the process, including the crucial human safety gates.
|
||
* Cost/Quality Optimization: The ability to select different AI models based on task complexity (model_hint: fast vs. quality)
|
||
|
||
Imagined Workflow: Developing a New Feature
|
||
|
||
Here’s how a developer, Alex, would use CascadingDev to build a new feature:
|
||
|
||
1. Initiate the Feature: Alex runs python create_feature.py. The Ramble GUI opens. Alex types in some rough notes about needing a "new user profile page." The integrated AI helps him refine this into a structured
|
||
request with a clear title, intent, and summary. He submits it.
|
||
2. First Commit: The system automatically creates the feature request file (request.md) and the initial discussion file (feature.discussion.md). This is all committed to the repository.
|
||
3. Discussion and Voting: Alex's assembles a team of humans and bots, teammates review the feature.discussion.md file. They add comments and, when they're satisfied with the scope, they each add a VOTE: READY line to their comments.
|
||
4. Automatic Promotion: The next time anyone makes a commit, the pre-commit hook runs. It parses the discussion, sees that the votes meet the "ready" criteria defined in the rules, and automatically:
|
||
* Changes the status in feature.discussion.md to status: READY_FOR_DESIGN.
|
||
* Generates a new design.discussion.md file.
|
||
* Creates a draft design/design.md document, pre-populated with context from the feature request.
|
||
* Updates the feature.discussion.sum.md with the final decisions and vote tally.
|
||
All of these changes are seamlessly added to the user's commit.
|
||
5. Iterative Design and Implementation: This cycle continues. The team discusses the technical design in design.discussion.md, and the AI keeps the design/design.md document updated. Once they vote the design
|
||
READY, the system creates the implementation plan and tasks.
|
||
6. Complete Context: When a developer finally submits the code for review, the pull request contains not only the source code changes but also the entire history of the feature's evolution—the initial request, the
|
||
discussions, the design decisions, and the implementation plan—all linked and version-controlled.
|
||
|
||
This creates a powerful, transparent, and low-friction development process.
|