1st commit

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-<version>/
+├─ install/                    # build output (git-ignored)
+│  └─ cascadingdev-<version>/  # 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-<version>/`:
+
+- `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_<date>_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-<version>/
+```
+
+**6.3 Smoke test the bundle**
+```bash
+python3 install/cascadingdev-<version>/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-<version>.zip cascadingdev-<version>
+```
+
+**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 <tagged release>
+python3 tools/build_installer.py
+python3 install/cascadingdev-<version>/setup_cascadingdev.py --target <path>
+```
+
+(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

assets/templates/design_doc.md

@@ -0,0 +1,9 @@
+# Design — <FR id / Title>
+
+## Context & Goals
+## Non-Goals & Constraints
+## Options Considered
+## Decision & Rationale
+## Architecture Diagram(s)
+## Risks & Mitigations
+## Acceptance Criteria (measurable)

assets/templates/discussion.md

@@ -0,0 +1,25 @@
+type: discussion
+stage: <feature|design|implementation|testing|review>
+status: OPEN
+feature_id: <FR_...>
+created: <YYYY-MM-DD>
+
+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

assets/templates/feature_request.md

@@ -0,0 +1,10 @@
+# Feature Request: <title>
+
+**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):

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"

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)