docs: Add CLAUDE.md and restructure DESIGN.md for clarity
Major documentation improvements: 1. Add CLAUDE.md - Comprehensive guide for AI assistants working in this repo - Repository architecture and directory structure - Common development commands and workflows - Build system explanation - Key concepts and design philosophy 2. Restructure DESIGN.md - Clarify three directory contexts: CascadingDev Repo, Install Bundle, User Project - Add clear section headers and visual separation - Mark future/unimplemented features with 🚧 emoji - Document undocumented wins: META system and Ramble providers - Add comprehensive Ramble documentation (mock and claude providers) - Document template META system with code examples 3. Fix setup_project.py - Correct error message path (was scripts/hooks/pre-commit, now assets/hooks/pre-commit) These changes address confusion between tooling source, distribution bundle, and generated user projects while highlighting sophisticated features like the self-describing template system and multi-provider Ramble GUI. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
d78b0d83c8
commit
536d885b6b
|
|
@ -0,0 +1,336 @@
|
||||||
|
# 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.
|
||||||
|
|
||||||
|
## 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
|
||||||
737
docs/DESIGN.md
737
docs/DESIGN.md
|
|
@ -59,137 +59,198 @@ Human → Git Commit → Pre-commit Hook → AI Generator → Markdown Artifact
|
||||||
Orchestrator ← Discussion Summaries ← AI Moderator
|
Orchestrator ← Discussion Summaries ← AI Moderator
|
||||||
```
|
```
|
||||||
|
|
||||||
## Repository Layout
|
## Repository Layouts
|
||||||
|
|
||||||
|
This section clarifies three different directory structures that are easy to confuse:
|
||||||
|
|
||||||
|
### Terminology
|
||||||
|
- **CascadingDev Repo** — The tooling project (this repository) that builds installers
|
||||||
|
- **Install Bundle** — The distributable artifact created by `tools/build_installer.py`
|
||||||
|
- **User Project** — A new repository scaffolded when a user runs the installer
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### A) CascadingDev Repository (Tooling Source)
|
||||||
|
|
||||||
|
This is the development repository where CascadingDev itself is maintained.
|
||||||
|
|
||||||
### Canonical Structure (Per-Feature Folders)
|
|
||||||
```text
|
```text
|
||||||
/ (repository root)
|
CascadingDev/ # This repository
|
||||||
├─ .ai-rules.yml # Global defaults + file associations
|
├─ src/cascadingdev/ # Core Python modules
|
||||||
├─ automation/ # Orchestrator & adapters
|
│ ├─ cli.py # Developer CLI (cdev command)
|
||||||
│ ├─ workflow.py # Python status/reporting (v1 non-blocking)
|
│ ├─ setup_project.py # Installer script (copied to bundle)
|
||||||
|
│ ├─ utils.py # Version management, utilities
|
||||||
|
│ ├─ feature_seed.py # Feature scaffolding logic
|
||||||
|
│ ├─ rules_seed.py # Rules seeding logic
|
||||||
|
│ ├─ fs_scaffold.py # Filesystem utilities
|
||||||
|
│ └─ ramble_integration.py # Ramble GUI integration
|
||||||
|
├─ assets/ # Single source of truth for shipped files
|
||||||
|
│ ├─ hooks/
|
||||||
|
│ │ └─ pre-commit # Git hook template (bash script)
|
||||||
|
│ ├─ templates/ # Templates copied to user projects
|
||||||
|
│ │ ├─ USER_GUIDE.md # Daily usage guide
|
||||||
|
│ │ ├─ feature_request.md # Feature request template
|
||||||
|
│ │ ├─ feature.discussion.md # Discussion template
|
||||||
|
│ │ ├─ feature.discussion.sum.md # Summary template
|
||||||
|
│ │ ├─ design_doc.md # Design document template
|
||||||
|
│ │ ├─ root_gitignore # Root .gitignore template
|
||||||
|
│ │ ├─ process/
|
||||||
|
│ │ │ └─ policies.yml # Machine-readable policies
|
||||||
|
│ │ └─ rules/
|
||||||
|
│ │ ├─ root.ai-rules.yml # Root cascading rules
|
||||||
|
│ │ └─ features.ai-rules.yml # Feature-level rules
|
||||||
|
│ └─ runtime/ # Scripts copied to bundle & user projects
|
||||||
|
│ ├─ ramble.py # GUI for feature creation (PySide6/PyQt5)
|
||||||
|
│ ├─ create_feature.py # CLI for feature creation
|
||||||
|
│ └─ .gitignore.seed # Gitignore seed patterns
|
||||||
|
├─ tools/ # Build and test automation
|
||||||
|
│ ├─ build_installer.py # Creates install bundle
|
||||||
|
│ ├─ smoke_test.py # Basic validation tests
|
||||||
|
│ └─ bundle_smoke.py # End-to-end installer testing
|
||||||
|
├─ install/ # Build output directory (git-ignored)
|
||||||
|
│ └─ cascadingdev-<version>/ # Generated installer bundle (see section B)
|
||||||
|
├─ docs/ # System documentation
|
||||||
|
│ ├─ DESIGN.md # This comprehensive design document
|
||||||
|
│ └─ INSTALL.md # Installation instructions
|
||||||
|
├─ tests/ # Test suite (planned, not yet implemented)
|
||||||
|
│ ├─ unit/
|
||||||
|
│ ├─ integration/
|
||||||
|
│ └─ bin/
|
||||||
|
├─ VERSION # Semantic version (e.g., 0.1.0)
|
||||||
|
├─ pyproject.toml # Python package configuration
|
||||||
|
├─ README.md # Public-facing project overview
|
||||||
|
└─ CLAUDE.md # AI assistant guidance
|
||||||
|
|
||||||
|
FUTURE (planned but not yet implemented):
|
||||||
|
├─ automation/ # 🚧 M1: Orchestration layer
|
||||||
|
│ ├─ workflow.py # Status reporting, vote parsing
|
||||||
│ ├─ adapters/
|
│ ├─ adapters/
|
||||||
│ │ ├─ claude_adapter.py # Model interface (future)
|
│ │ ├─ claude_adapter.py # AI model integration
|
||||||
│ │ ├─ gitea_adapter.py # Gitea API integration (future)
|
│ │ └─ gitea_adapter.py # Gitea API integration
|
||||||
│ │ └─ agent_coordinator.py # Role routing & task allocation (future)
|
│ └─ agents.yml # Agent role definitions
|
||||||
│ ├─ agents.yml # Role → stages mapping
|
|
||||||
│ └─ config.yml # Configuration (future)
|
|
||||||
├─ process/ # Process documentation & templates
|
|
||||||
│ ├─ policies.md # Human-friendly policy documentation
|
|
||||||
│ ├─ policies.yml # Machine-readable policy configuration
|
|
||||||
│ └─ templates/
|
|
||||||
│ ├─ feature_request.md
|
|
||||||
│ ├─ discussion.md
|
|
||||||
│ ├─ design_doc.md
|
|
||||||
│ └─ implementation_plan.md
|
|
||||||
├─ Docs/
|
|
||||||
│ ├─ features/
|
|
||||||
│ │ ├─ .ai-rules.yml # Folder-scoped rules for all features
|
|
||||||
│ │ ├─ FR_YYYY-MM-DD_<slug>/ # Individual feature folders
|
|
||||||
│ │ │ ├─ request.md # Original feature request
|
|
||||||
│ │ │ ├─ discussions/ # Stage-specific conversations
|
|
||||||
│ │ │ │ ├─ feature.discussion.md # Discuss the request
|
|
||||||
│ │ │ │ ├─ feature.discussion.sum.md # Summary of the request discussion
|
|
||||||
│ │ │ │ ├─ design.discussion.md # Discuss the design
|
|
||||||
│ │ │ │ ├─ design.discussion.sum.md # Summary of the design discussion
|
|
||||||
│ │ │ │ ├─ implementation.discussion.md # Track implementation
|
|
||||||
│ │ │ │ ├─ implementation.discussion.sum.md # Summary of the implementation discussion
|
|
||||||
│ │ │ │ ├─ testing.discussion.md # Plan/track testing
|
|
||||||
│ │ │ │ ├─ testing.discussion.sum.md # Summary of the testing discussion
|
|
||||||
│ │ │ │ ├─ review.discussion.md # Final review
|
|
||||||
│ │ │ │ └─ review.discussion.sum.md # Summary of the review discussion
|
|
||||||
│ │ │ ├─ design/ # Design artifacts
|
|
||||||
│ │ │ │ ├─ design.md # Evolving design document
|
|
||||||
│ │ │ │ └─ diagrams/ # Architecture diagrams
|
|
||||||
│ │ │ ├─ implementation/ # Implementation artifacts
|
|
||||||
│ │ │ │ ├─ plan.md # Implementation plan
|
|
||||||
│ │ │ │ └─ tasks.md # Task checklist
|
|
||||||
│ │ │ ├─ testing/ # Testing artifacts
|
|
||||||
│ │ │ │ ├─ testplan.md # Test strategy
|
|
||||||
│ │ │ │ └─ checklist.md # Test checklist
|
|
||||||
│ │ │ ├─ review/ # Review artifacts
|
|
||||||
│ │ │ │ └─ findings.md # Feature-specific review findings
|
|
||||||
│ │ │ └─ bugs/ # Auto-generated bug reports
|
|
||||||
│ │ │ └─ BUG_YYYYMMDD_<slug>/
|
|
||||||
│ │ │ ├─ report.md
|
|
||||||
│ │ │ ├─ discussion.md
|
|
||||||
│ │ │ └─ fix/
|
|
||||||
│ │ │ ├─ plan.md
|
|
||||||
│ │ │ └─ tasks.md
|
|
||||||
│ ├─ discussions/
|
|
||||||
│ │ └─ reviews/ # Code reviews from hook
|
|
||||||
│ └─ diagrams/
|
|
||||||
│ └─ file_diagrams/ # PlantUML from source files
|
|
||||||
├─ src/ # Application source code
|
|
||||||
└─ tests/ # System test suite
|
|
||||||
├─ unit/
|
|
||||||
├─ integration/
|
|
||||||
└─ bin/
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
**Purpose:** Development, testing, and building the installer. The `assets/` directory is the single source of truth for all files shipped to users.
|
||||||
|
|
||||||
The sections below describe the meta-infrastructure of CascadingDev itself — how it builds and distributes the installer that generates user projects.
|
---
|
||||||
|
|
||||||
|
### B) Install Bundle (Distribution Artifact)
|
||||||
|
|
||||||
|
This is the self-contained, portable installer created by `tools/build_installer.py`.
|
||||||
|
|
||||||
|
```text
|
||||||
|
cascadingdev-<version>/ # Distributable bundle
|
||||||
|
├─ setup_cascadingdev.py # Installer entry point (stdlib only)
|
||||||
|
├─ ramble.py # GUI for first feature (optional)
|
||||||
|
├─ create_feature.py # CLI tool for creating features
|
||||||
|
├─ assets/ # Embedded resources
|
||||||
|
│ ├─ hooks/
|
||||||
|
│ │ └─ pre-commit # Pre-commit hook template
|
||||||
|
│ └─ templates/ # All templates from source assets/
|
||||||
|
│ ├─ USER_GUIDE.md
|
||||||
|
│ ├─ feature_request.md
|
||||||
|
│ ├─ feature.discussion.md
|
||||||
|
│ ├─ feature.discussion.sum.md
|
||||||
|
│ ├─ design_doc.md
|
||||||
|
│ ├─ root_gitignore
|
||||||
|
│ ├─ process/
|
||||||
|
│ │ └─ policies.yml
|
||||||
|
│ └─ rules/
|
||||||
|
│ ├─ root.ai-rules.yml
|
||||||
|
│ └─ features.ai-rules.yml
|
||||||
|
├─ INSTALL.md # Bundle-local instructions
|
||||||
|
└─ VERSION # Version metadata
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
**Purpose:** End-user distribution. Can be zipped and shared. Requires only Python 3.10+ stdlib (PySide6 optional for GUI).
|
||||||
|
|
||||||
|
**Rationale:** Minimal, auditable, portable. No external dependencies for core functionality. Users can inspect all files before running.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### C) User Project (Generated by Installer)
|
||||||
|
|
||||||
|
This is the structure created when a user runs `setup_cascadingdev.py --target /path/to/project`.
|
||||||
|
|
||||||
|
```text
|
||||||
|
my-project/ # User's application repository
|
||||||
|
├─ .git/ # Git repository
|
||||||
|
│ └─ hooks/
|
||||||
|
│ └─ pre-commit # Installed automatically from bundle
|
||||||
|
├─ .gitignore # Generated from root_gitignore template
|
||||||
|
├─ .ai-rules.yml # Root cascading rules (from templates/rules/)
|
||||||
|
├─ USER_GUIDE.md # Daily workflow reference
|
||||||
|
├─ ramble.py # Copied from bundle (optional GUI helper)
|
||||||
|
├─ create_feature.py # Copied from bundle (CLI tool)
|
||||||
|
├─ Docs/ # Documentation and feature tracking
|
||||||
|
│ ├─ features/ # All features live here
|
||||||
|
│ │ ├─ .ai-rules.yml # Feature-level cascading rules
|
||||||
|
│ │ └─ FR_YYYY-MM-DD_<slug>/ # Individual feature folders
|
||||||
|
│ │ ├─ request.md # Original feature request
|
||||||
|
│ │ └─ discussions/ # Stage-specific conversation threads
|
||||||
|
│ │ ├─ feature.discussion.md # Feature discussion
|
||||||
|
│ │ ├─ feature.discussion.sum.md # Auto-maintained summary
|
||||||
|
│ │ ├─ design.discussion.md # Design discussion
|
||||||
|
│ │ ├─ design.discussion.sum.md # Auto-maintained summary
|
||||||
|
│ │ ├─ implementation.discussion.md # Implementation tracking
|
||||||
|
│ │ ├─ implementation.discussion.sum.md
|
||||||
|
│ │ ├─ testing.discussion.md # Test planning
|
||||||
|
│ │ ├─ testing.discussion.sum.md
|
||||||
|
│ │ ├─ review.discussion.md # Final review
|
||||||
|
│ │ └─ review.discussion.sum.md
|
||||||
|
│ │ ├─ design/ # Design artifacts (created during design stage)
|
||||||
|
│ │ │ ├─ design.md # Evolving design document
|
||||||
|
│ │ │ └─ diagrams/ # Architecture diagrams
|
||||||
|
│ │ ├─ implementation/ # Implementation artifacts
|
||||||
|
│ │ │ ├─ plan.md # Implementation plan
|
||||||
|
│ │ │ └─ tasks.md # Task checklist
|
||||||
|
│ │ ├─ testing/ # Testing artifacts
|
||||||
|
│ │ │ ├─ testplan.md # Test strategy
|
||||||
|
│ │ │ └─ checklist.md # Test checklist
|
||||||
|
│ │ ├─ review/ # Review artifacts
|
||||||
|
│ │ │ └─ findings.md # Code review findings
|
||||||
|
│ │ └─ bugs/ # Bug sub-cycles (future)
|
||||||
|
│ │ └─ BUG_YYYYMMDD_<slug>/
|
||||||
|
│ │ ├─ report.md
|
||||||
|
│ │ ├─ discussion.md
|
||||||
|
│ │ └─ fix/
|
||||||
|
│ │ ├─ plan.md
|
||||||
|
│ │ └─ tasks.md
|
||||||
|
│ ├─ discussions/ # Global discussions (future)
|
||||||
|
│ │ └─ reviews/ # Code reviews from hook
|
||||||
|
│ └─ diagrams/ # Auto-generated diagrams (future)
|
||||||
|
│ └─ file_diagrams/ # PlantUML from source files
|
||||||
|
├─ process/ # Process configuration
|
||||||
|
│ ├─ policies.yml # Machine-readable policies (voting, gates)
|
||||||
|
│ └─ templates/ # Local template overrides (optional)
|
||||||
|
├─ src/ # User's application source code
|
||||||
|
│ └─ (user's code)
|
||||||
|
└─ tests/ # User's test suite
|
||||||
|
├─ unit/
|
||||||
|
└─ integration/
|
||||||
|
|
||||||
|
FUTURE (not currently created, planned for M1+):
|
||||||
|
├─ automation/ # 🚧 M1: Orchestration layer
|
||||||
|
│ ├─ workflow.py # Vote parsing, status reporting
|
||||||
|
│ ├─ adapters/ # Model and platform integrations
|
||||||
|
│ └─ agents.yml # Agent role configuration
|
||||||
|
```
|
||||||
|
|
||||||
|
**Purpose:** This is the user's actual project repository where they develop their application while using the CascadingDev workflow.
|
||||||
|
|
||||||
|
**Key Points:**
|
||||||
|
- The first feature request defines the entire project's purpose
|
||||||
|
- All discussions are version-controlled alongside code
|
||||||
|
- Pre-commit hook maintains summary files automatically
|
||||||
|
- Templates can be overridden locally in `process/templates/`
|
||||||
|
- The `automation/` directory is planned but not yet implemented (M1)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Installation & Distribution Architecture
|
## Installation & Distribution Architecture
|
||||||
|
|
||||||
### Terminology (clarified)
|
### First-Run Flow (User's Project Initialization)
|
||||||
- **CascadingDev** — this tooling project (the code in this repository).
|
|
||||||
- **User’s project** — a new repository scaffolded by running CascadingDev’s installer.
|
|
||||||
- **Install bundle** — the small, distributable folder produced by the build process (unzipped and executed by end users).
|
|
||||||
|
|
||||||
|
|
||||||
### Repository Layout (authoritative)
|
|
||||||
|
|
||||||
Note: This section refers to the CascadingDev repository itself. For the structure of a user’s generated project, see “First-Run Flow” below.
|
|
||||||
```text
|
|
||||||
CascadingDev/
|
|
||||||
├─ src/cascadingdev/ # core logic & optional dev CLI
|
|
||||||
├─ assets/ # single source of truth for shipped files
|
|
||||||
│ ├─ hooks/pre-commit
|
|
||||||
│ ├─ templates/
|
|
||||||
│ │ ├─ USER_GUIDE.md
|
|
||||||
│ │ ├─ design_doc.md
|
|
||||||
│ │ ├─ discussion.md
|
|
||||||
│ │ ├─ feature_request.md
|
|
||||||
│ │ ├─ process/
|
|
||||||
│ │ │ └─ policies.yml
|
|
||||||
│ │ └─ rules/
|
|
||||||
│ │ ├─ root.ai-rules.yml # this becomes ./.ai-rules.yml
|
|
||||||
│ │ └─ features.ai-rules.yml # this becomes Docs/features/.ai-rules.yml
|
|
||||||
│ └─ runtime/{ramble.py,create_feature.py}
|
|
||||||
├─ tools/build_installer.py # creates install/cascadingdev-<version>/
|
|
||||||
├─ install/ # build output (git-ignored)
|
|
||||||
│ ├─ setup_cascadingdev.py
|
|
||||||
│ ├─ assets/ # shipped templates + hooks
|
|
||||||
│ ├─ ramble.py # optional GUI helper
|
|
||||||
│ ├─ create_feature.py # feature bootstrap tool (also copied to user repo)
|
|
||||||
│ ├─ INSTALL.md # how to run the installer (bundle-local)
|
|
||||||
│ └─ VERSION
|
|
||||||
├─ docs
|
|
||||||
│ └─ DESIGN.md # this document (not copied into user repos)
|
|
||||||
├─ VERSION # semantic version of CascadingDev
|
|
||||||
├─ README.md, docs/, tests/
|
|
||||||
```
|
|
||||||
|
|
||||||
**Why:** All runtime assets live once under `assets/`.
|
|
||||||
The builder copies only what end users need into a clean bundle.
|
|
||||||
Development happens in `src/` and is testable; distribution is “unzip + run”.
|
|
||||||
|
|
||||||
|
|
||||||
### Install Bundle Specification
|
|
||||||
|
|
||||||
Contents of `install/cascadingdev-<version>/`:
|
|
||||||
|
|
||||||
- `setup_cascadingdev.py` — single-file installer (stdlib-only)
|
|
||||||
- `ramble.py` — optional GUI dialog for first feature request (PySide6/PyQt5)
|
|
||||||
- `create_feature.py` — CLI to create a feature (also copied into user project)
|
|
||||||
- `assets/hooks/pre-commit` — git pre-commit template (executable)
|
|
||||||
- `assets/templates/*.md` — feature/discussion/design templates
|
|
||||||
- `INSTALL.md` — bundle-local instructions
|
|
||||||
- `VERSION` — set from repo root `VERSION`
|
|
||||||
|
|
||||||
+**Rationale:** Minimal, auditable, portable. The user guide lives in the user project; the system design (this file) stays in CascadingDev.
|
|
||||||
|
|
||||||
### First-Run Flow (User’s Project Initialization)
|
|
||||||
|
|
||||||
User runs:
|
User runs:
|
||||||
```bash
|
```bash
|
||||||
|
|
@ -224,6 +285,438 @@ Important: The CascadingDev DESIGN.md is not copied into user projects. The firs
|
||||||
|
|
||||||
Policy: v1 is non-blocking; blocking checks are introduced gradually in later versions.
|
Policy: v1 is non-blocking; blocking checks are introduced gradually in later versions.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Template META System & Ramble Integration
|
||||||
|
|
||||||
|
### Overview
|
||||||
|
|
||||||
|
CascadingDev includes a sophisticated **template metadata system** that allows templates to be self-describing. This enables dynamic GUI generation, field validation, and flexible template rendering without hardcoding form structures in the installer.
|
||||||
|
|
||||||
|
**Status**: ✅ **Fully implemented** (v0.1.0)
|
||||||
|
|
||||||
|
### Template META Format
|
||||||
|
|
||||||
|
Templates can include JSON metadata inside HTML comments at the top of the file:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
<!--META
|
||||||
|
{
|
||||||
|
"kind": "feature_request",
|
||||||
|
"ramble_fields": [
|
||||||
|
{"name": "Title", "hint": "camelCase, ≤24 chars", "default": "initialProjectDesign"},
|
||||||
|
{"name": "Intent"},
|
||||||
|
{"name": "Summary", "hint": "≤2 sentences"}
|
||||||
|
],
|
||||||
|
"criteria": {
|
||||||
|
"Title": "camelCase, <= 24 chars",
|
||||||
|
"Summary": "<= 2 sentences"
|
||||||
|
},
|
||||||
|
"hints": [
|
||||||
|
"What is it called?",
|
||||||
|
"Who benefits most?",
|
||||||
|
"What problem does it solve?"
|
||||||
|
],
|
||||||
|
"tokens": ["FeatureId", "CreatedDate", "Title", "Intent", "Summary"]
|
||||||
|
}
|
||||||
|
-->
|
||||||
|
|
||||||
|
# Feature Request: {Title}
|
||||||
|
|
||||||
|
**Intent**: {Intent}
|
||||||
|
**Summary**: {Summary}
|
||||||
|
|
||||||
|
**Meta**: FeatureId: {FeatureId} • Created: {CreatedDate}
|
||||||
|
```
|
||||||
|
|
||||||
|
### META Fields Reference
|
||||||
|
|
||||||
|
| Field | Type | Purpose | Example |
|
||||||
|
|-------|------|---------|---------|
|
||||||
|
| `kind` | string | Template type identifier | `"feature_request"` |
|
||||||
|
| `ramble_fields` | array | Field definitions for Ramble GUI | See below |
|
||||||
|
| `criteria` | object | Validation rules per field | `{"Title": "camelCase, <= 24 chars"}` |
|
||||||
|
| `hints` | array | User guidance prompts | `["What is it called?"]` |
|
||||||
|
| `tokens` | array | List of available placeholder tokens | `["FeatureId", "Title"]` |
|
||||||
|
|
||||||
|
### ramble_fields Specification
|
||||||
|
|
||||||
|
Each field in `ramble_fields` is an object with:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "FieldName", // Required: field identifier
|
||||||
|
"hint": "display hint", // Optional: shown to user as guidance
|
||||||
|
"default": "defaultValue" // Optional: pre-filled value
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```json
|
||||||
|
"ramble_fields": [
|
||||||
|
{"name": "Title", "hint": "camelCase, ≤24 chars", "default": "initialProjectDesign"},
|
||||||
|
{"name": "Intent"},
|
||||||
|
{"name": "ProblemItSolves"},
|
||||||
|
{"name": "BriefOverview"},
|
||||||
|
{"name": "Summary", "hint": "≤2 sentences"}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
### How META is Processed
|
||||||
|
|
||||||
|
**In `setup_project.py`** (`src/cascadingdev/setup_project.py:64-115`):
|
||||||
|
|
||||||
|
1. **Parsing** (`load_template_with_meta()`):
|
||||||
|
```python
|
||||||
|
meta, body = load_template_with_meta(template_path)
|
||||||
|
# meta = {"ramble_fields": [...], "criteria": {...}, ...}
|
||||||
|
# body = template text without META comment
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Extraction** (`meta_ramble_config()`):
|
||||||
|
```python
|
||||||
|
fields, defaults, criteria, hints = meta_ramble_config(meta)
|
||||||
|
# fields = ["Title", "Intent", "Summary", ...]
|
||||||
|
# defaults = {"Title": "initialProjectDesign"}
|
||||||
|
# criteria = {"Title": "camelCase, <= 24 chars"}
|
||||||
|
# hints = ["What is it called?", ...]
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Rendering** (`render_placeholders()`):
|
||||||
|
```python
|
||||||
|
values = {"Title": "myFeature", "FeatureId": "FR_2025-10-30_...", ...}
|
||||||
|
rendered = render_placeholders(body, values)
|
||||||
|
# Replaces {Token} and {{Token}} with actual values
|
||||||
|
```
|
||||||
|
|
||||||
|
### Token Replacement Rules
|
||||||
|
|
||||||
|
The `render_placeholders()` function supports two-pass replacement:
|
||||||
|
|
||||||
|
1. **First pass**: Replace `{{Token}}` (double braces) - for tokens that shouldn't be re-processed
|
||||||
|
2. **Second pass**: Replace `{Token}` (single braces) using Python's `.format_map()`
|
||||||
|
|
||||||
|
**System-provided tokens:**
|
||||||
|
- `{FeatureId}` - Generated feature ID (e.g., `FR_2025-10-30_initial-feature-request`)
|
||||||
|
- `{CreatedDate}` - Current date in `YYYY-MM-DD` format
|
||||||
|
- `{Title}`, `{Intent}`, etc. - User-provided field values
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ramble: AI-Powered Feature Capture GUI
|
||||||
|
|
||||||
|
### Overview
|
||||||
|
|
||||||
|
**Ramble** is a sophisticated PySide6/PyQt5 GUI application that helps users articulate feature requests through AI-assisted structured input. It supports multiple AI providers, generates PlantUML diagrams, and returns validated JSON output.
|
||||||
|
|
||||||
|
**Status**: ✅ **Fully implemented** (v0.1.0)
|
||||||
|
|
||||||
|
**Location**: `assets/runtime/ramble.py` (copied to user projects and install bundle)
|
||||||
|
|
||||||
|
### Key Features
|
||||||
|
|
||||||
|
1. **Multi-Provider Architecture** - Pluggable AI backends
|
||||||
|
2. **Dynamic Field Generation** - Driven by template META
|
||||||
|
3. **Field Locking** - Lock fields to preserve context across regenerations
|
||||||
|
4. **PlantUML Integration** - Auto-generate and render architecture diagrams
|
||||||
|
5. **Validation Criteria** - Per-field rules from template metadata
|
||||||
|
6. **Graceful Fallback** - Terminal prompts if GUI fails
|
||||||
|
|
||||||
|
### Supported Providers
|
||||||
|
|
||||||
|
| Provider | Status | Description | Usage |
|
||||||
|
|----------|--------|-------------|-------|
|
||||||
|
| **mock** | ✅ Stable | No external calls, derives fields from ramble text | Default, no setup required |
|
||||||
|
| **claude** | ✅ Stable | Claude CLI integration via subprocess | Requires `claude` CLI in PATH |
|
||||||
|
|
||||||
|
**Provider Selection:**
|
||||||
|
```bash
|
||||||
|
# Mock provider (no AI, instant)
|
||||||
|
python ramble.py --provider mock --fields Title Summary
|
||||||
|
|
||||||
|
# Claude CLI provider
|
||||||
|
python ramble.py --provider claude \
|
||||||
|
--claude-cmd /path/to/claude \
|
||||||
|
--fields Title Summary Intent
|
||||||
|
```
|
||||||
|
|
||||||
|
### Provider Protocol
|
||||||
|
|
||||||
|
All providers implement the `RambleProvider` protocol:
|
||||||
|
|
||||||
|
```python
|
||||||
|
class RambleProvider(Protocol):
|
||||||
|
def generate(
|
||||||
|
self,
|
||||||
|
*,
|
||||||
|
prompt: str, # User's base prompt
|
||||||
|
ramble_text: str, # User's freeform notes
|
||||||
|
fields: List[str], # Required field names
|
||||||
|
field_criteria: Dict[str, str], # Validation rules per field
|
||||||
|
locked_context: Dict[str, str], # Previously locked field values
|
||||||
|
) -> Dict[str, Any]:
|
||||||
|
"""
|
||||||
|
Returns:
|
||||||
|
{
|
||||||
|
"summary": str,
|
||||||
|
"fields": Dict[str, str],
|
||||||
|
"uml_blocks": List[Tuple[str, Optional[bytes]]],
|
||||||
|
"image_descriptions": List[str]
|
||||||
|
}
|
||||||
|
"""
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Mock Provider
|
||||||
|
|
||||||
|
**Purpose**: Fast, deterministic testing and offline use.
|
||||||
|
|
||||||
|
**Behavior**:
|
||||||
|
- Derives summary from last 25 words of ramble text
|
||||||
|
- Creates placeholder fields with word count
|
||||||
|
- Generates simple actor-system UML diagram
|
||||||
|
- Returns generic image descriptions
|
||||||
|
|
||||||
|
**Example Output**:
|
||||||
|
```python
|
||||||
|
{
|
||||||
|
"summary": "User wants to track metrics and export them.",
|
||||||
|
"fields": {
|
||||||
|
"Title": "Title: Derived from ramble (42 words). [criteria: camelCase, <=24 chars]",
|
||||||
|
"Intent": "Intent: Derived from ramble (42 words).",
|
||||||
|
},
|
||||||
|
"uml_blocks": [("@startuml\nactor User\n...\n@enduml", None)],
|
||||||
|
"image_descriptions": ["Illustrate the core actor..."]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Claude CLI Provider
|
||||||
|
|
||||||
|
**Purpose**: Production-quality AI-generated structured output.
|
||||||
|
|
||||||
|
**Setup Requirements**:
|
||||||
|
```bash
|
||||||
|
# Install Claude CLI (npm)
|
||||||
|
npm install -g @anthropics/claude-cli
|
||||||
|
|
||||||
|
# Or provide custom path
|
||||||
|
python ramble.py --provider claude --claude-cmd /custom/path/to/claude
|
||||||
|
```
|
||||||
|
|
||||||
|
**Features**:
|
||||||
|
- Spawns `claude` subprocess with structured prompt
|
||||||
|
- Includes locked field context in prompt
|
||||||
|
- Enforces per-field criteria
|
||||||
|
- Extracts PlantUML blocks from response
|
||||||
|
- Timeout protection (default 120s)
|
||||||
|
- Debug logging to `/tmp/ramble_claude.log`
|
||||||
|
|
||||||
|
**Constructor Options**:
|
||||||
|
```python
|
||||||
|
ClaudeCLIProvider(
|
||||||
|
cmd="claude", # Command name or path
|
||||||
|
extra_args=[], # Additional CLI args
|
||||||
|
timeout_s=120, # Subprocess timeout
|
||||||
|
tail_chars=8000, # Max response length
|
||||||
|
use_arg_p=True, # Use -p flag for prompt
|
||||||
|
debug=False, # Enable debug logging
|
||||||
|
log_path="/tmp/ramble_claude.log"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Prompt Structure**:
|
||||||
|
The provider builds a comprehensive prompt including:
|
||||||
|
1. User's base prompt
|
||||||
|
2. Locked field context (from previously locked fields)
|
||||||
|
3. User's ramble notes
|
||||||
|
4. Required field list with criteria
|
||||||
|
5. PlantUML and image description requests
|
||||||
|
6. JSON output format specification
|
||||||
|
|
||||||
|
### Integration with Installer
|
||||||
|
|
||||||
|
**In `setup_project.py:151-218`** (`run_ramble_and_collect()`):
|
||||||
|
|
||||||
|
```python
|
||||||
|
def run_ramble_and_collect(target: Path, provider: str = "mock", claude_cmd: str = "claude"):
|
||||||
|
# 1. Load template META to get field configuration
|
||||||
|
fr_tmpl = INSTALL_ROOT / "assets" / "templates" / "feature_request.md"
|
||||||
|
meta, _ = load_template_with_meta(fr_tmpl)
|
||||||
|
field_names, _defaults, criteria, hints = meta_ramble_config(meta)
|
||||||
|
|
||||||
|
# 2. Build dynamic Ramble command from META
|
||||||
|
args = [
|
||||||
|
sys.executable, str(ramble),
|
||||||
|
"--provider", provider,
|
||||||
|
"--fields", *field_names, # From template META
|
||||||
|
]
|
||||||
|
|
||||||
|
if criteria:
|
||||||
|
args += ["--criteria", json.dumps(criteria)]
|
||||||
|
if hints:
|
||||||
|
args += ["--hints", json.dumps(hints)]
|
||||||
|
|
||||||
|
# 3. Launch Ramble, capture JSON output
|
||||||
|
proc = subprocess.run(args, capture_output=True, text=True)
|
||||||
|
|
||||||
|
# 4. Parse JSON or fall back to terminal prompts
|
||||||
|
try:
|
||||||
|
return json.loads(proc.stdout)
|
||||||
|
except:
|
||||||
|
# Terminal fallback: collect fields via input()
|
||||||
|
return collect_via_terminal()
|
||||||
|
```
|
||||||
|
|
||||||
|
### Ramble GUI Workflow
|
||||||
|
|
||||||
|
1. **User writes freeform notes** in the "Ramble" text area
|
||||||
|
2. **Clicks "Generate"** → Provider processes ramble text
|
||||||
|
3. **Review generated fields** → Edit as needed
|
||||||
|
4. **Lock important fields** → Prevents overwrite on regenerate
|
||||||
|
5. **Regenerate if needed** → Locked fields feed back as context
|
||||||
|
6. **Review PlantUML diagrams** → Auto-rendered if plantuml CLI available
|
||||||
|
7. **Click "Submit"** → Returns JSON to installer
|
||||||
|
|
||||||
|
**Output Format**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"summary": "One or two sentence summary",
|
||||||
|
"fields": {
|
||||||
|
"Title": "metricsExportFeature",
|
||||||
|
"Intent": "Enable users to track and export usage metrics",
|
||||||
|
"ProblemItSolves": "Currently no way to analyze usage patterns",
|
||||||
|
"BriefOverview": "Add metrics collection and CSV/JSON export",
|
||||||
|
"Summary": "Track usage metrics and export to various formats."
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Terminal Fallback
|
||||||
|
|
||||||
|
If Ramble GUI fails (missing PySide6, JSON parse error, etc.), the installer falls back to terminal input:
|
||||||
|
|
||||||
|
```python
|
||||||
|
def ask(label, default=""):
|
||||||
|
try:
|
||||||
|
v = input(f"{label}: ").strip()
|
||||||
|
return v or default
|
||||||
|
except EOFError:
|
||||||
|
return default
|
||||||
|
|
||||||
|
fields = {
|
||||||
|
"Title": ask("Title (camelCase, <=24 chars)", "initialProjectDesign"),
|
||||||
|
"Intent": ask("Intent", "—"),
|
||||||
|
"Summary": ask("One- or two-sentence summary", ""),
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Adding New Providers
|
||||||
|
|
||||||
|
To add a new provider (e.g., `deepseek`, `openai`):
|
||||||
|
|
||||||
|
1. **Create provider class** in `ramble.py`:
|
||||||
|
```python
|
||||||
|
class DeepseekProvider:
|
||||||
|
def generate(self, *, prompt, ramble_text, fields, field_criteria, locked_context):
|
||||||
|
# Call Deepseek API
|
||||||
|
response = call_deepseek_api(...)
|
||||||
|
return {
|
||||||
|
"summary": ...,
|
||||||
|
"fields": {...},
|
||||||
|
"uml_blocks": [...],
|
||||||
|
"image_descriptions": [...]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Register in CLI parser**:
|
||||||
|
```python
|
||||||
|
p.add_argument("--provider",
|
||||||
|
choices=["mock", "claude", "deepseek"], # Add here
|
||||||
|
default="mock")
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Instantiate in main()**:
|
||||||
|
```python
|
||||||
|
if args.provider == "deepseek":
|
||||||
|
provider = DeepseekProvider(api_key=os.getenv("DEEPSEEK_API_KEY"))
|
||||||
|
```
|
||||||
|
|
||||||
|
### Advanced Features
|
||||||
|
|
||||||
|
**PlantUML Support**:
|
||||||
|
- Ramble extracts `@startuml...@enduml` blocks from provider responses
|
||||||
|
- Auto-renders to PNG if `plantuml` CLI available
|
||||||
|
- Falls back to text display if rendering fails
|
||||||
|
|
||||||
|
**Image Generation** (Optional):
|
||||||
|
- Supports Stability AI and Pexels APIs
|
||||||
|
- Requires API keys via environment variables
|
||||||
|
- Displays images in GUI if generated
|
||||||
|
|
||||||
|
**Field Locking**:
|
||||||
|
- Checkbox next to each field
|
||||||
|
- Locked fields are highlighted and included in next generation prompt
|
||||||
|
- Enables iterative refinement without losing progress
|
||||||
|
|
||||||
|
**Criteria Validation**:
|
||||||
|
- Displayed alongside each field as hints
|
||||||
|
- Passed to AI provider to enforce constraints
|
||||||
|
- No automatic validation (relies on AI compliance)
|
||||||
|
|
||||||
|
### Configuration Examples
|
||||||
|
|
||||||
|
**Basic usage (mock provider)**:
|
||||||
|
```bash
|
||||||
|
python ramble.py \
|
||||||
|
--fields Title Intent Summary \
|
||||||
|
--prompt "Describe your feature idea"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Production usage (Claude)**:
|
||||||
|
```bash
|
||||||
|
python ramble.py \
|
||||||
|
--provider claude \
|
||||||
|
--claude-cmd ~/.npm-global/bin/claude \
|
||||||
|
--fields Title Intent ProblemItSolves BriefOverview Summary \
|
||||||
|
--criteria '{"Title":"camelCase, <=24 chars","Summary":"<=2 sentences"}' \
|
||||||
|
--hints '["What is it?","Who benefits?","What problem?"]' \
|
||||||
|
--prompt "Describe your initial feature request"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Installer integration**:
|
||||||
|
```bash
|
||||||
|
python setup_cascadingdev.py \
|
||||||
|
--target /path/to/project \
|
||||||
|
--provider claude \
|
||||||
|
--claude-cmd /usr/local/bin/claude
|
||||||
|
```
|
||||||
|
|
||||||
|
### Benefits of META + Ramble System
|
||||||
|
|
||||||
|
1. **No Hardcoding**: Field lists and validation rules live in templates
|
||||||
|
2. **Dynamic Forms**: GUI adapts to template changes automatically
|
||||||
|
3. **Consistent UX**: Same Ramble workflow for all template types
|
||||||
|
4. **Extensible**: Add new providers without changing core logic
|
||||||
|
5. **Offline Capable**: Mock provider works without network
|
||||||
|
6. **AI-Assisted**: Users get help articulating complex requirements
|
||||||
|
7. **Reversible**: All input is stored in git, easily editable later
|
||||||
|
|
||||||
|
### Limitations & Future Work
|
||||||
|
|
||||||
|
**Current Limitations**:
|
||||||
|
- No automatic field validation (relies on AI compliance)
|
||||||
|
- PlantUML rendering requires external CLI tool
|
||||||
|
- Claude provider requires separate CLI installation
|
||||||
|
- No streaming/incremental updates during generation
|
||||||
|
|
||||||
|
**Potential Enhancements** (not yet planned):
|
||||||
|
- Native API providers (no CLI subprocess)
|
||||||
|
- Real-time field validation
|
||||||
|
- Multi-turn conversation support
|
||||||
|
- Provider comparison mode (generate with multiple providers)
|
||||||
|
- Template validator that checks META integrity
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
### Build & Release Process (repeatable)
|
### Build & Release Process (repeatable)
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -139,7 +139,7 @@ def install_precommit_hook(target: Path):
|
||||||
hook_dst = hooks_dir / "pre-commit"
|
hook_dst = hooks_dir / "pre-commit"
|
||||||
|
|
||||||
if not hook_src.exists():
|
if not hook_src.exists():
|
||||||
say("[-] pre-commit hook source missing at scripts/hooks/pre-commit in the installer.")
|
say("[-] pre-commit hook source missing at assets/hooks/pre-commit in the installer bundle.")
|
||||||
return
|
return
|
||||||
|
|
||||||
# Copy hook content and make it executable
|
# Copy hook content and make it executable
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue