457 lines
16 KiB
Markdown
457 lines
16 KiB
Markdown
# 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
|