diff --git a/DESIGN.md b/DESIGN.md index 6f14759..74d723e 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -125,6 +125,197 @@ Human → Git Commit → Pre-commit Hook → AI Generator → Markdown Artifact └─ bin/ ``` + +## 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) +```text +CascadingDev/ +├─ src/cascadingdev/ # core logic & optional dev CLI +├─ assets/ # single source of truth for shipped files +│ ├─ hooks/pre-commit +│ ├─ templates/{feature_request.md,discussion.md,design_doc.md} +│ └─ runtime/ramble.py +├─ tools/build_installer.py # creates install/cascadingdev-/ +├─ install/ # build output (git-ignored) +│ └─ cascadingdev-/ # unzip + run bundle (setup_cascadingdev.py inside) +├─ VERSION # semantic version of CascadingDev +├─ DESIGN.md, 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) +- `DESIGN.md` — copied for user reference +- `ramble.py` — GUI dialog for first feature request (PySide6/PyQt5) +- `assets/hooks/pre-commit` — git pre-commit template (executable) +- `assets/templates/*.md` — feature/discussion/design templates +- `VERSION` — set from repo root `VERSION` + +**Rationale:** Minimal, auditable, portable; no local package imports required. + + +### First-Run Flow (User’s Project Initialization) + +User runs: +```bash +python setup_cascadingdev.py --target /path/to/users-project [--no-ramble] [--provider mock] +``` + +**Installer actions:** +- Creates standard folders (`Docs/`, `process/templates/`, etc.) +- Copies templates, `ramble.py`, `DESIGN.md`, and installs pre-commit hook +- Initializes git (main branch), writes `.gitignore` +- Launches Ramble (unless `--no-ramble`) to collect the first Feature Request + +**Seeds:** +``` +Docs/features/FR__initial-feature-request/request.md +Docs/features/.../discussions/feature.discussion.md +Docs/features/.../discussions/feature.discussion.sum.md +``` + +Initial commit message: “bootstrap Cascading Development scaffolding”. + +**Fallback:** If Ramble JSON isn’t returned, installer prints to stderr and optionally falls back to terminal prompts. + + +### Pre-Commit Hook (v1 behavior) +- Fast regex secret scan on staged diffs +- Ensures each `*.discussion.md` has a companion `*.discussion.sum.md` +- Non-blocking status call to `automation/workflow.py --status` + +Policy: v1 is non-blocking; blocking checks are introduced gradually in later versions. + + +### Build & Release Process (repeatable) + +Goal: deterministic “unzip + run” artifact for each version. + +**6.1 Versioning** +- Update `VERSION` (semver): `MAJOR.MINOR.PATCH` +- Tag releases in git to match `VERSION` + +**6.2 Build the installer bundle** +```bash +python3 tools/build_installer.py +# Output: install/cascadingdev-/ +``` + +**6.3 Smoke test the bundle** +```bash +python3 install/cascadingdev-/setup_cascadingdev.py --target /tmp/my-users-project --no-ramble +# then again without --no-ramble once GUI deps are ready +``` + +**6.4 Package for distribution** +```bash +cd install +zip -r cascadingdev-.zip cascadingdev- +``` + +**Success criteria** +- Bundle runs on a clean machine with only Python + git +- Creates expected files, installs hook, commits once +- Optional GUI capture works under venv with PySide6/PyQt5 + + +### Environment Guidance (Ramble GUI) + +Recommended: create and activate a local virtualenv before running the installer. + +```bash +python3 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip wheel +python -m pip install PySide6 # or PyQt5 +``` + +The installer calls `sys.executable` for `ramble.py`, so using the venv’s Python ensures GUI dependencies are found. + +If GUI unavailable, run with `--no-ramble` or rely on terminal fallback. + + +### Idempotency & Flags + +Installer flags: +- `--target` (required): destination path for the user’s project +- `--no-ramble`: skip GUI prompt; seed using templates (or terminal fallback) +- `--provider`: specify Ramble provider (default: mock) + +Future flags (planned): +- `--force`: overwrite existing files (or back up) +- `--copy-only`: skip git init and hook install +- `--templates /path`: override shipped templates + + +### Reproducibility Playbook + +To recreate the same result later or on another machine: +```bash +git checkout +python3 tools/build_installer.py +python3 install/cascadingdev-/setup_cascadingdev.py --target +``` + +(Optional) activate venv and install PySide6 before running if you want the GUI. + + +### Roadmap (post-v0.1) +- Expand pre-commit checks (summary normalization, rule validation) +- Add `automation/workflow.py --status` for repo health +- Provide a developer CLI (`cdev init …`) that reuses installer logic +- Unit tests for scaffolding helpers (`src/cascadingdev/*`) +- Template override mechanism (`--templates`) + + +### INSTALL.md Template for Bundles + +The builder should emit an `INSTALL.md` alongside the installer bundle: + +```markdown +# CascadingDev Installer + +## Requirements +- Python 3.10+ and git +- (Optional) PySide6 or PyQt5 for Ramble GUI + +## Quick start +```bash +python setup_cascadingdev.py --target /path/to/users-project +``` + +### Options +- \`--no-ramble\`: skip GUI capture, use templates or terminal prompts +- \`--provider\`: Ramble provider (default: mock) + +### Steps performed +1. Creates standard folder layout in target +2. Copies templates, DESIGN.md, ramble.py +3. Initializes git and installs pre-commit hook +4. Launches Ramble (unless --no-ramble) +5. Seeds first feature request & discussions +6. Makes initial commit + +If GUI fails, use a virtualenv and \`pip install PySide6\`, or run with \`--no-ramble\`. +``` + +This ensures every distributed bundle includes explicit usage instructions. + + Note: Each stage discussion has a companion summary maintained automatically next to it to provide a live, scannable state of the thread. ### Naming Conventions diff --git a/assets/hooks/pre-commit b/assets/hooks/pre-commit old mode 100644 new mode 100755 diff --git a/assets/templates/design_doc.md b/assets/templates/design_doc.md index e69de29..5dc6021 100644 --- a/assets/templates/design_doc.md +++ b/assets/templates/design_doc.md @@ -0,0 +1,9 @@ +# Design — + +## Context & Goals +## Non-Goals & Constraints +## Options Considered +## Decision & Rationale +## Architecture Diagram(s) +## Risks & Mitigations +## Acceptance Criteria (measurable) \ No newline at end of file diff --git a/assets/templates/discussion.md b/assets/templates/discussion.md index e69de29..ec92d52 100644 --- a/assets/templates/discussion.md +++ b/assets/templates/discussion.md @@ -0,0 +1,25 @@ +type: discussion +stage: +status: OPEN +feature_id: +created: + +promotion_rule: + allow_agent_votes: true + ready_min_eligible_votes: all + reject_min_eligible_votes: all + +participation: + instructions: | + - Append your input at the end as: "YourName: your comment…" + - Every comment must end with a vote line: "VOTE: READY|CHANGES|REJECT" + - Agents/bots must prefix names with "AI_" + +voting: + values: [READY, CHANGES, REJECT] +--- +## Summary +2-4 sentence summary of current state + +## Participation +comments appended below \ No newline at end of file diff --git a/assets/templates/feature_request.md b/assets/templates/feature_request.md index e69de29..9d61d5e 100644 --- a/assets/templates/feature_request.md +++ b/assets/templates/feature_request.md @@ -0,0 +1,10 @@ +# Feature Request: + +**Feature ID**: <FR_YYYY-MM-DD_slug> +**Intent**: <one paragraph describing purpose> +**Motivation / Problem**: <why this is needed now> +**Constraints / Non-Goals**: <bulleted list of limitations> +**Rough Proposal**: <short implementation outline> +**Open Questions**: <bulleted list of uncertainties> +**Meta**: Created: <date> • Author: <name> +Discussion Template (process/templates/discussion.md): \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index e69de29..3116b40 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -0,0 +1,9 @@ +# pyproject.toml +[project] +name = "cascadingdev" +version = "0.1.0" +description = "CascadingDev: scaffold rule-driven multi-agent project repos" +requires-python = ">=3.10" + +[project.scripts] +cdev = "cascadingdev.cli:main" diff --git a/tools/build_installer.py b/tools/build_installer.py index ee7e071..c43d043 100644 --- a/tools/build_installer.py +++ b/tools/build_installer.py @@ -109,6 +109,7 @@ def main(): ap = argparse.ArgumentParser() ap.add_argument("--target", help="Destination path for the user's project") ap.add_argument("--no-ramble", action="store_true") + ap.add_argument("--provider", default="mock") args = ap.parse_args() target = Path(args.target or input("User's project folder: ").strip()).expanduser().resolve() @@ -135,7 +136,7 @@ def main(): install_hook(target) # ramble - req = None if args.no-ramble else run_ramble(target) + req = None if args.no_ramble else run_ramble(target, provider=args.provider) # seed FR seed_first_feature(target, req)