# 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

```bash
# 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

```bash
# 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:**
```yaml
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:**
```yaml
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:

```bash
# 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:**
```bash
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:

```bash
# 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:
```bash
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:
```markdown
<!--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:
```bash
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