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
|
||||
```
|
||||
|
||||
## 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
|
||||
/ (repository root)
|
||||
├─ .ai-rules.yml # Global defaults + file associations
|
||||
├─ automation/ # Orchestrator & adapters
|
||||
│ ├─ workflow.py # Python status/reporting (v1 non-blocking)
|
||||
CascadingDev/ # This repository
|
||||
├─ src/cascadingdev/ # Core Python modules
|
||||
│ ├─ cli.py # Developer CLI (cdev command)
|
||||
│ ├─ 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/
|
||||
│ │ ├─ claude_adapter.py # Model interface (future)
|
||||
│ │ ├─ gitea_adapter.py # Gitea API integration (future)
|
||||
│ │ └─ agent_coordinator.py # Role routing & task allocation (future)
|
||||
│ ├─ 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/
|
||||
│ │ ├─ claude_adapter.py # AI model integration
|
||||
│ │ └─ gitea_adapter.py # Gitea API integration
|
||||
│ └─ agents.yml # Agent role definitions
|
||||
```
|
||||
|
||||
**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
|
||||
|
||||
### Terminology (clarified)
|
||||
- **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)
|
||||
### First-Run Flow (User's Project Initialization)
|
||||
|
||||
User runs:
|
||||
```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.
|
||||
|
||||
---
|
||||
|
||||
## 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)
|
||||
|
||||
|
|
|
|||
|
|
@ -139,7 +139,7 @@ def install_precommit_hook(target: Path):
|
|||
hook_dst = hooks_dir / "pre-commit"
|
||||
|
||||
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
|
||||
|
||||
# Copy hook content and make it executable
|
||||
|
|
|
|||
Loading…
Reference in New Issue