CascadingDev Architecture
System Overview
┌─────────────────────────────────────────────────────────────────────────┐
│ Git Repository │
│ ┌─────────────────┐ │
│ │ .ai-rules.yml │ ◄── Cascading configuration │
│ │ src/ │ │
│ │ .ai-rules.yml │ ◄── Folder-specific overrides │
│ │ feature.py │ │
│ │ discussions/ │ │
│ │ FEAT-001.md │ ◄── Structured discussion files │
│ └─────────────────┘ │
│ │ │
│ ▼ git commit │
│ ┌─────────────────┐ │
│ │ Pre-commit Hook │ │
│ │ ┌─────────────┐ │ │
│ │ │ Safety │ │ ◄── Secret scanning, validation │
│ │ │ Checks │ │ │
│ │ └─────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────┐ │ │
│ │ │ Rules │ │ ◄── Load cascading .ai-rules.yml │
│ │ │ Resolution │ │ │
│ │ └─────────────┘ │ │
│ └────────┼────────┘ │
└───────────┼─────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────────┐
│ CmdForge Tool Engine │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ Provider Abstraction (Claude, Codex, Gemini, DeepSeek, Ollama) │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────┼───────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Agent 1 │ │ Agent 2 │ │ Agent N │ │
│ │ Tools │ │ Tools │ │ Tools │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└───────────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────────┐
│ Orchestrated Discussions │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Parse │ │ Route │ │ Vote │ │
│ │ Discussion │──▶│ Mentions │──▶│ Counter │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ Status │ │
│ │ Promoter │ │
│ └─────────────┘ │
└───────────────────────────────────────────────────────────────────────┘
Rules Resolution
The .ai-rules.yml system uses cascading inheritance:
# Root .ai-rules.yml
agents:
- moderator
- architect
- security
stages:
- feature
- design
- implementation
- testing
- review
providers:
primary: claude
fallback:
- codex
- gemini
# src/.ai-rules.yml (inherits and overrides)
agents:
- pragmatist # Add pragmatist for implementation code
- perfectionist # Add perfectionist for code quality
# Inherits stages and providers from parent
Key Modules
| Module | Location | Purpose |
|---|---|---|
cascading.rules | src/rules/ | YAML parsing, inheritance resolution |
cascading.hooks | src/hooks/ | Pre-commit hook logic |
cascading.agents | src/agents/ | Agent definitions and prompts |
cascading.safety | src/safety/ | Secret scanning, validation |
cascading.installer | src/installer/ | Bundle generation |
Data Flow
- Commit Trigger: User runs
git commit - Hook Execution: Pre-commit hook starts
- Safety Checks: Scan for secrets, validate files
- Rules Load: Resolve cascading
.ai-rules.yml - Agent Dispatch: Send files to configured agents via CmdForge
- Discussion Update: Append agent responses to discussion files
- Vote Count: Calculate consensus from voting
- Status Promotion: Update status if threshold met
- Summary Generation: Create/update summary files
- Commit Proceeds: If all checks pass
Configuration Files
| File | Purpose |
|---|---|
.ai-rules.yml | Agent selection, stages, providers |
.ai-ignore | Files to exclude from AI processing |
.ai-secrets | Patterns for secret detection |