CascadingDev_simplified/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

CascadingDev (CDev) - Simplified is the core of a Git-native AI-human collaboration framework. This simplified version focuses on:

• Git pre-commit hooks with safety checks
• Cascading .ai-rules.yml system
• Ramble GUI for structured feature requests
• Installer bundle generation

For advanced discussion orchestration, see Orchestrated Discussions.

Key Concept: Two Repositories

• CascadingDev repo (this codebase): The tooling that builds installer bundles
• User's project repo: A new repository scaffolded by running the installer bundle

Repository Architecture

Directory Structure

CascadingDev/
├── src/cascadingdev/        # Core Python modules and CLI
│   ├── cli.py               # Main CLI entry point (cdev command)
│   ├── setup_project.py     # Installer script (copied to bundle)
│   └── utils.py             # Shared utilities
├── assets/                  # Single source of truth for shipped files
│   ├── hooks/pre-commit     # Git hook template (bash script)
│   ├── templates/           # Markdown templates copied to user projects
│   │   ├── rules/           # .ai-rules.yml files
│   │   └── process/         # policies.yml
│   └── runtime/             # Python scripts copied to user projects
│       ├── ramble.py        # GUI for feature creation (PySide6/PyQt5)
│       └── create_feature.py # CLI for feature creation
├── tools/                   # Build and test scripts
│   ├── build_installer.py   # Creates install/ bundle
│   └── smoke_test.py        # Basic validation
├── install/                 # Build output (git-ignored)
└── VERSION                  # Semantic version

Common Commands

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

# Install in development mode
pip install -e .

# Build the installer bundle
cdev build

# Test-install into a temporary folder
python install/cascadingdev-*/setup_cascadingdev.py --target /tmp/myproject --no-ramble

Key Concepts

Cascading Rules System

The .ai-rules.yml files define automation behavior. User projects have:

• Root .ai-rules.yml - Global defaults
• Docs/features/.ai-rules.yml - Feature-specific rules

Rules are hierarchical: nearest file takes precedence.

Pre-commit Hook

The bash pre-commit hook (assets/hooks/pre-commit) provides:

• Scans for potential secrets (blocks commit on match)
• Ensures discussion files have companion .sum.md summary files
• Uses flock to prevent git corruption from concurrent commits
• Fast and lightweight (pure bash, no Python dependencies)

Environment variables:

• CDEV_SKIP_HOOK=1 - Skip all hook checks
• CDEV_SKIP_SUMMARIES=1 - Skip summary file generation

Build System

The build process (tools/build_installer.py) creates a standalone installer bundle:

1. Reads version from VERSION file
2. Creates install/cascadingdev-<version>/ directory
3. Copies essential files from assets/ to bundle
4. Copies src/cascadingdev/setup_project.py as the installer entry point

Related Projects

This project is part of a stack:

1. SmartTools - AI provider abstraction
2. Orchestrated Discussions - Multi-agent discussion orchestration
3. Ramble - AI-powered structured field extraction GUI
4. Artifact Editor - AI-enhanced diagram and model creation