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