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)

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