From 536d885b6b3b6b0ea4f502419e0037ed16a6f5de Mon Sep 17 00:00:00 2001 From: rob Date: Thu, 30 Oct 2025 12:31:33 -0300 Subject: [PATCH] docs: Add CLAUDE.md and restructure DESIGN.md for clarity MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- CLAUDE.md | 336 ++++++++++++++ docs/DESIGN.md | 737 +++++++++++++++++++++++++----- src/cascadingdev/setup_project.py | 2 +- 3 files changed, 952 insertions(+), 123 deletions(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..199e310 --- /dev/null +++ b/CLAUDE.md @@ -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-/ # 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-/` +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-/` 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 + +``` + +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 diff --git a/docs/DESIGN.md b/docs/DESIGN.md index 1152fef..295a27c 100644 --- a/docs/DESIGN.md +++ b/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-/ # 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_/ # 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_/ -β”‚ β”‚ β”‚ β”œβ”€ 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-/ # 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_/ # 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_/ +β”‚ β”‚ β”œβ”€ 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-/ -β”œβ”€ 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-/`: - -- `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 + + +# 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) diff --git a/src/cascadingdev/setup_project.py b/src/cascadingdev/setup_project.py index 2ce8a43..eca3ad2 100644 --- a/src/cascadingdev/setup_project.py +++ b/src/cascadingdev/setup_project.py @@ -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