102 lines
3.8 KiB
Markdown
102 lines
3.8 KiB
Markdown
# 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
|