CascadingDev/CLAUDE.md

CLAUDE.md

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

Overview

CascadingDev (CDev) is a Git-native AI-human collaboration framework that automates documentation, discussion summaries, and code review directly within repositories. It's a tooling project that generates installer bundles which users run to scaffold new projects with the CDev workflow.

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

This CLAUDE.md describes working on the CascadingDev tooling itself.

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
│   ├── bundle_smoke.py      # End-to-end installer test
│   └── smoke_test.py        # Basic validation
├── install/                 # Build output (git-ignored)
│   └── cascadingdev-<ver>/  # Distributable installer bundle
├── docs/                    # System design documentation
│   ├── DESIGN.md            # Comprehensive architecture doc
│   └── INSTALL.md           # Installation instructions
└── VERSION                  # Semantic version (e.g., 0.1.0)

Core Workflow

1. Development: Modify code in src/cascadingdev/ or assets in assets/
2. Build: Run cdev build to create installer bundle in install/cascadingdev-<ver>/
3. Test: Run cdev smoke or cdev bundle-smoke to validate
4. Package: Run cdev pack to create distributable ZIP
5. Release: Run cdev release --kind [major|minor|patch] to bump version and rebuild

Common Commands

Development Workflow

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

# Install in development mode
pip install -e .

# Check environment and required files
cdev doctor

# Build the installer bundle (without version bump)
cdev build

# Run basic validation
cdev smoke

# Bump version and rebuild (default: patch)
cdev release --kind [major|minor|patch]

# Create distributable ZIP
cdev pack

# Test the bundle end-to-end
cdev bundle-smoke --keep --target /tmp/test-project

Testing the Installer

# Build and test-install into a temporary folder
cdev build
python install/cascadingdev-*/setup_cascadingdev.py --target /tmp/myproject --no-ramble

# Or use bundle-smoke for automated testing
cdev bundle-smoke --target /tmp/test --keep

Working with Git

The current branch is converge-cli. This repository doesn't have a configured main branch, so when creating PRs, verify the target branch with the maintainer.

Build System

How the Build Works

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:
   • Templates (*.md, policies.yml, .ai-rules.yml)
   • Git hooks (pre-commit)
   • Runtime scripts (ramble.py, create_feature.py)
4. Copies src/cascadingdev/setup_project.py as the installer entry point
5. Creates bundle-local INSTALL.md and VERSION

Important: All user-facing files must live in assets/. The build script is the single point that defines what gets shipped.

Bundle Contents

The installer bundle is self-contained and requires only Python 3.10+ stdlib (PySide6 optional for GUI):

• setup_cascadingdev.py - Main installer script
• ramble.py - Optional GUI for creating first feature
• create_feature.py - CLI tool for creating features (also copied to user projects)
• assets/ - All templates, hooks, and configuration files
• VERSION - Version metadata
• INSTALL.md - Bundle-local instructions

What Gets Shipped vs. What Stays

Shipped to user projects:

• USER_GUIDE.md - Daily usage instructions
• .ai-rules.yml - Cascading rules system configuration
• pre-commit hook - Discussion/summary automation
• Feature templates (feature_request.md, discussion templates)
• policies.yml - Process configuration
• create_feature.py - Feature creation tool

Stays in CascadingDev repo:

• DESIGN.md - System architecture (27k+ tokens)
• README.md - Project overview
• Development tools and tests
• Source code in src/

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) is the core automation engine:

• Scans for potential secrets (blocks commit on match)
• Ensures discussion files have companion .sum.md summary files
• Creates summary templates with marker blocks for AI-maintained content
• Fast and lightweight (pure bash, no Python dependencies)

Stage-Per-Discussion Model

User projects organize features into stages with separate discussion files:

• feature.discussion.md - Initial feature discussion
• design.discussion.md - Design discussion
• implementation.discussion.md - Implementation tracking
• testing.discussion.md - Test planning
• review.discussion.md - Final review

Each has a .sum.md companion maintained by the hook.

Installation Flow

When a user runs setup_cascadingdev.py:

1. Prompts for target directory (or uses --target)
2. Creates canonical folder structure (Docs/features/, process/, etc.)
3. Copies templates and hooks from bundle
4. Initializes git repository
5. Installs pre-commit hook
6. Optionally launches Ramble GUI for first feature request
7. Creates initial commit to activate the hook

Python Module Structure

src/cascadingdev/cli.py

Main CLI entry point registered as cdev command in pyproject.toml.

Commands:

• doctor - Validate environment and required files
• smoke - Run basic smoke tests
• build - Build installer bundle
• release - Bump version and rebuild
• pack - Create distributable ZIP
• bundle-smoke - End-to-end installer validation

src/cascadingdev/setup_project.py

Standalone installer script (copied to bundle as setup_cascadingdev.py). Must work with stdlib only.

Key functions:

• ensure_dir(), write_if_missing(), copy_if_missing() - File operations
• load_template_with_meta() - Parse templates with JSON metadata
• render_placeholders() - Simple {Token} replacement
• meta_ramble_config() - Extract Ramble GUI configuration from template metadata

src/cascadingdev/utils.py

Shared utilities for version management and subprocess execution.

AI Configuration System

Overview

CascadingDev supports multiple AI providers with automatic fallback chains. Configuration is centralized in config/ai.yml and copied to all generated projects, allowing users to customize their preferred providers without editing source code.

Multi-Provider Architecture

Configuration File: config/ai.yml

The AI configuration supports three optimization levels:

1. Default (balanced) - command_chain: Balanced speed/quality for typical tasks
2. Fast - command_chain_fast: Speed-optimized for simple tasks (vote counting, gate checks)
3. Quality - command_chain_quality: Quality-optimized for complex tasks (design, implementation planning)

Example configuration:

runner:
  # Default command chain (balanced speed/quality)
  command_chain:
    - "claude -p"
    - "codex --model gpt-5"
    - "gemini --model gemini-2.5-flash"

  # Fast command chain (optimized for speed/cost)
  command_chain_fast:
    - "claude -p"
    - "codex --model gpt-5-mini"
    - "gemini --model gemini-2.5-flash"

  # Quality command chain (optimized for complex tasks)
  command_chain_quality:
    - "claude -p"
    - "codex --model o3"
    - "gemini --model gemini-2.5-pro"

  sentinel: "CASCADINGDEV_NO_CHANGES"

How Model Selection Works

1. Rule Definition - .ai-rules.yml specifies model_hint: fast or model_hint: quality per rule
2. Runner Propagation - automation/runner.py reads hint and passes to generate_output()
3. Prompt Injection - automation/patcher.py injects TASK COMPLEXITY: FAST into prompt
4. Chain Selection - ModelConfig.get_commands_for_hint() selects appropriate command chain
5. Fallback Execution - Commands tried left→right until one succeeds

Example rule with model hint:

rules:
  feature_discussion_writer:
    model_hint: fast  # Simple vote counting - use fast models
    instruction: |
      Maintain feature discussion with votes...      

  design_discussion_writer:
    model_hint: quality  # Complex architecture work - use quality models
    instruction: |
      Propose detailed architecture...      

Supported Providers

Provider	CLI Tool	Command Example	Authentication	Model Selection
Claude	claude	claude -p	Run claude and sign in	Auto-selects subagent based on TASK COMPLEXITY hint
OpenAI Codex	codex	codex --model gpt-5	Run codex and sign in with ChatGPT	Specify model via --model flag
Google Gemini	gemini	gemini --model gemini-2.5-flash	Run gemini and sign in with Google	Specify model via --model flag

Claude Subagent Setup

Recommended approach: Use the provided setup script to create Claude subagents that respond to TASK COMPLEXITY hints:

# One-time setup (creates ~/.claude/agents/cdev-patch.md and cdev-patch-quality.md)
./tools/setup_claude_agents.sh

This creates two subagent files:

• cdev-patch.md - Uses Haiku model (fast, cost-efficient) - activated by TASK COMPLEXITY: FAST
• cdev-patch-quality.md - Uses Sonnet model (higher quality) - activated by TASK COMPLEXITY: QUALITY

When claude -p receives a prompt with TASK COMPLEXITY: FAST, it automatically selects the cdev-patch subagent (Haiku). For TASK COMPLEXITY: QUALITY, it selects cdev-patch-quality (Sonnet).

Verify installation:

claude agents list
# Should show: cdev-patch, cdev-patch-quality

Implementation Modules

• automation/ai_config.py - Configuration loader with AISettings, RunnerSettings, RambleSettings dataclasses
• automation/runner.py - Reads model_hint from rules and passes to patcher (lines 94-112)
• automation/patcher.py - Implements ModelConfig.get_commands_for_hint() and prompt injection (lines 63-77, 409-428)
• config/ai.yml - User-editable configuration file shipped with every project

Environment Overrides

Users can override config/ai.yml temporarily via environment variables:

# Override command for a single commit
CDEV_AI_COMMAND="claude -p" git commit -m "use quality model"

# Override provider
CDEV_AI_PROVIDER="claude-cli" git commit -m "message"

Environment variables take precedence over config/ai.yml but don't modify the file.

Fallback Behavior

If all providers in a chain fail:

• Automation logs errors to stderr
• Pre-commit hook continues (non-blocking)
• Vote tracking (Phase 1) still runs
• Manual intervention may be needed for AI-generated content

Design Philosophy

Git-Native

Everything lives in Git as Markdown. No external databases, dashboards, or SaaS dependencies.

Self-Documenting

The first feature request in a user's project defines the entire project. Subsequent features extend that foundation.

Deterministic & Reproducible

The installer bundle is unzip-and-run. No network dependencies during installation (except optional PySide6).

Lightweight & Fast

Pre-commit hook is pure bash for speed. Python orchestration is optional and non-blocking.

Important Notes

When Modifying Templates

After changing any file in assets/, you must rebuild:

cdev build

The build script copies from assets/ to install/. Changes don't take effect until rebuilt.

When Adding New Templates

1. Add template to assets/templates/
2. Update tools/build_installer.py to copy it
3. Update src/cascadingdev/setup_project.py if installer needs to process it
4. Rebuild and test with cdev build && cdev bundle-smoke

Secret Detection

The pre-commit hook includes basic secret scanning using regex patterns. It blocks commits containing:

• API keys (api_key, api-key)
• Secrets (secret)
• Access tokens (access_token, access-token)
• Private keys (private_key, private-key)

Followed by 12+ alphanumeric characters. Use --no-verify for false positives, but add proper allowlisting.

Python Version Requirement

Minimum Python 3.10 required. The installer uses modern type hints and f-strings.

Architecture Patterns

Assets as Single Source of Truth

All shipped files originate in assets/. The build process is the only consumer. This ensures:

• No duplicate maintenance
• Clear separation of dev vs. shipped files
• Easy auditing of what gets distributed

Bundle Installer Pattern

The installer is self-contained and portable:

• Single entry point (setup_cascadingdev.py)
• Stdlib-only dependencies (except optional GUI)
• Embeds all necessary assets
• Can be zipped and distributed

Template Metadata System

Templates can include JSON metadata in HTML comments:

<!--META {"fields": ["title", "author"], "validators": {"title": "required"}} -->

The installer extracts metadata to configure Ramble GUI forms without hardcoding.

Common Development Patterns

Adding a New CLI Command

1. Edit src/cascadingdev/cli.py
2. Add subparser with sub.add_parser("command_name", help="...")
3. Handle in main() with if args.cmd == "command_name":
4. Create corresponding tool script in tools/ if needed

Modifying the Pre-commit Hook

1. Edit assets/hooks/pre-commit (bash script)
2. Test locally by copying to a test repo's .git/hooks/
3. Rebuild bundle with cdev build
4. Test with cdev bundle-smoke

Testing Changes

Always test in a fresh project:

cdev build
cdev bundle-smoke --target /tmp/test-$(date +%s) --keep
cd /tmp/test-*
# Verify the installation worked correctly

Maintenance Notes

Version Management

Version is stored in VERSION file at repo root. Use cdev release to bump:

• --kind major - Breaking changes (0.1.0 → 1.0.0)
• --kind minor - New features (0.1.0 → 0.2.0)
• --kind patch - Bug fixes (0.1.0 → 0.1.1)

Documentation

• DESIGN.md - Comprehensive system design (very large, 27k+ tokens)
• README.md - Public-facing overview
• USER_GUIDE.md - Shipped to user projects, daily usage instructions
• CLAUDE.md - This file, for AI assistant context

When DESIGN.md Is Too Large

The design document is extensive. For specific questions:

• Read specific sections with offset/limit parameters
• Focus on repository structure and workflow sections
• Refer to code comments in setup_project.py for installation details