# 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](https://gitea.brrd.tech/rob/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

```bash
# 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](https://gitea.brrd.tech/rob/SmartTools)** - AI provider abstraction
2. **[Orchestrated Discussions](https://gitea.brrd.tech/rob/orchestrated-discussions)** - Multi-agent discussion orchestration
3. **[Ramble](https://gitea.brrd.tech/rob/ramble)** - AI-powered structured field extraction GUI
4. **[Artifact Editor](https://gitea.brrd.tech/rob/artifact-editor)** - AI-enhanced diagram and model creation