jdi-cli 0.1.0

package/README.md

@@ -0,0 +1,789 @@
+# JDI — Just Do It
+
+Lean workflow toolkit for solo dev + AI assistant. Adaptive loop, atomic commits, file-based state, fresh context per agent, wave-based parallelism. Per-project specialists that already know your stack.
+
+## Why
+
+Full-blown AI workflows (33+ agents, 60+ commands, 100+ subworkflows) burn tokens and ceremony in solo projects. JDI ships what matters and cuts the rest:
+
+- **6 core agents** + **2 per-project** (doer + reviewer, generated by `/jdi-bootstrap`)
+- **10 commands** in a fixed loop + ralph mode + brownfield entry + meta
+- **File-based state** in `.jdi/` (Markdown + frontmatter, no DB)
+- **Multi-runtime:** Claude Code, GitHub Copilot, Google Antigravity, OpenCode
+- **Zero runtime deps** — Node stdlib only
+- **Brownfield supported** — adopt existing projects, not just greenfield
+- **Multi-stack** — N specialist pairs with file-glob routing (e.g. backend C# + frontend React)
+- **Optional MCP** — one-shot Playwright MCP install across all 4 CLIs
+
+## The flow
+
+### Greenfield (new project)
+
+```
+/jdi-new "<short description>"     <- research + PROJECT.md + ROADMAP.md
+/jdi-bootstrap                     <- doer + reviewer per project
+/jdi-discuss <N>                   <- capture locked decisions (CONTEXT.md)
+/jdi-plan <N>                      <- decompose into tasks + waves (PLAN.md)
+/jdi-do <N>                        <- execute via doer specialist (SUMMARY.md)
+/jdi-verify <N>                    <- gates via reviewer (REVIEW.md)
+/jdi-ship <N>                      <- update ROADMAP, advance phase
+```
+
+### Brownfield (existing project)
+
+```
+/jdi-adopt                         <- scan repo, infer stack/code-design, confirm with user
+/jdi-bootstrap                     <- doer + reviewer (adopted-aware: coverage only on new files)
+/jdi-discuss <N>                   <- ... same as greenfield from here
+/jdi-plan <N>
+/jdi-do <N>
+/jdi-verify <N>
+/jdi-ship <N>
+```
+
+`/jdi-adopt` detects manifests (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `*.csproj`, `pom.xml`), infers layout (DDD / Vertical Slice / Clean / Hexagonal / The Method / legacy-mixed), reads `README.md` for vision hint, captures existing assets, and ALWAYS confirms code-design with you before locking (D-1). Records boundary commit hash in D-2 so reviewer enforces coverage only on files created AFTER adoption.
+
+### Ralph mode (auto-iterate)
+
+Instead of manually running `/jdi-do` then `/jdi-verify`, use:
+
+```
+/jdi-loop <N>
+```
+
+Runs `/jdi-do` ↔ `/jdi-verify` in a bounded loop (default 5 iter per round, max 3 resets = 15 iter absolute). Exits when verdict is `APPROVED` or `APPROVED_WITH_WARNINGS`. Oscillation detection cuts dead loops early.
+
+## Quickstart — `npx` in 30 seconds
+
+```bash
+cd /path/to/your/project
+npx jdi-cli@latest install opencode
+```
+
+Done. Swap `opencode` for `claude`, `copilot`, `antigravity`, or `all` depending on your active runtime.
+
+> No `cd` first? `npx` runs in the current directory. Always confirm with `pwd` (Linux/Mac) or `Get-Location` (Windows).
+
+### Prerequisites
+
+- **Node.js 18+** (for `npx`)
+- **git**
+- At least one runtime: Claude Code, GitHub Copilot, Antigravity, or OpenCode
+
+## CLI subcommands
+
+Quick reference of every flag per subcommand:
+
+### `install <runtime>` — install JDI into the project
+
+| Flag | Values | Default | Purpose |
+|---|---|---|---|
+| `--scope` / `-s` | `user` \| `project` | `project` | `project` writes `.claude/`/`.opencode/`/etc into the project; `user` writes to `~/.claude/`, `~/.config/opencode/`, `~/.gemini/antigravity/` |
+| `--no-color` | flag | false | Disable ANSI colors |
+
+```bash
+npx jdi-cli@latest install claude
+npx jdi-cli@latest install copilot
+npx jdi-cli@latest install antigravity --scope user
+npx jdi-cli@latest install opencode
+npx jdi-cli@latest install all                       # all 4 runtimes at once
+```
+
+### `install-playwright` — Playwright dev dep + chromium browser + MCP config
+
+| Flag | Values | Default | Purpose |
+|---|---|---|---|
+| `--skip-browser` | flag | false | Skip `npx playwright install chromium` (~170MB) |
+| `--skip-mcp` | flag | false | Only install dep + browser, skip injecting MCP configs |
+| `--runtime` | `claude` \| `opencode` \| `copilot` \| `antigravity` \| `all` | `all` | Limit MCP injection to one runtime |
+| `--antigravity-scope` | `user` \| `project` | `user` | `~/.gemini/settings.json` vs `.gemini/settings.json` |
+
+Injects MCP into all 4 detected runtimes (see Playwright section above for paths).
+
+```bash
+npx jdi-cli@latest install-playwright
+npx jdi-cli@latest install-playwright --skip-browser
+npx jdi-cli@latest install-playwright --runtime claude
+npx jdi-cli@latest install-playwright --runtime copilot
+npx jdi-cli@latest install-playwright --skip-mcp                 # just dep + browser
+npx jdi-cli@latest install-playwright --antigravity-scope project
+```
+
+### `install-caveman` — clone Caveman plugin
+
+| Flag | Values | Default | Purpose |
+|---|---|---|---|
+| `--repo` | git URL | `https://github.com/JuliusBrussee/caveman.git` | Override caveman source repo (fork support) |
+| `--scope` | `user` \| `project` | `user` | `~/.claude/plugins/caveman/` vs `.claude/plugins/caveman/` |
+| `--force` | flag | false | Overwrite existing install without prompt |
+
+```bash
+npx jdi-cli@latest install-caveman                       # user scope, default repo
+npx jdi-cli@latest install-caveman --scope project
+npx jdi-cli@latest install-caveman --repo https://github.com/forked/caveman.git --force
+```
+
+### `update` — refresh runtime files, preserve state
+
+| Flag | Values | Default | Purpose |
+|---|---|---|---|
+| `--dry-run` | flag | false | Show what would change without applying |
+| `--force-specialists` | flag | false | Regenerate specialists without asking (assumes Yes) |
+| `--skip-specialists` | flag | false | Leave specialists alone even if template changed |
+
+```bash
+npx jdi-cli@latest update
+npx jdi-cli@latest update --dry-run
+npx jdi-cli@latest update --force-specialists
+npx jdi-cli@latest update --skip-specialists
+```
+
+Update does NOT refresh Playwright dep, MCP configs, or Caveman plugin. Re-run their respective subcommands to refresh.
+
+### `uninstall [runtime]` — remove JDI files
+
+| Flag | Values | Default | Purpose |
+|---|---|---|---|
+| `--scope` | `user` \| `project` \| `both` | `both` | Limit removal scope |
+| `--dry-run` | flag | false | Preview without applying |
+| `--yes` | flag | false | Skip all interactive prompts |
+| `--purge` | flag | false | **DESTRUCTIVE:** also wipe `.jdi/` (locked decisions lost) |
+
+```bash
+npx jdi-cli@latest uninstall                          # all detected runtimes, preserves .jdi/
+npx jdi-cli@latest uninstall claude
+npx jdi-cli@latest uninstall opencode --scope user
+npx jdi-cli@latest uninstall --dry-run                # preview
+npx jdi-cli@latest uninstall --yes                    # skip prompts
+npx jdi-cli@latest uninstall --purge --yes            # WIPE EVERYTHING including .jdi/
+```
+
+### `doctor` — environment diagnostic
+
+| Flag | Values | Default | Purpose |
+|---|---|---|---|
+| `--verbose` / `-v` | flag | false | Show note-level (debug) lines |
+
+```bash
+npx jdi-cli@latest doctor
+npx jdi-cli@latest doctor --verbose
+```
+
+### `build` — regenerate runtimes/ from core/ (contributors only)
+
+No flags. Used inside the JDI source repo after editing `core/`.
+
+```bash
+npx jdi-cli@latest build
+```
+
+### Misc
+
+```bash
+npx jdi-cli@latest --version
+npx jdi-cli@latest help
+```
+
+> Use `@latest` to force a fresh pull from npm. Without it, `npx` may use a cached older version.
+
+### Install globally (optional)
+
+```bash
+npm i -g jdi-cli
+jdi install opencode
+jdi doctor
+```
+
+After that, `jdi` works without `npx`.
+
+## Optional add-ons
+
+### Playwright MCP — live browser tool for all 4 CLIs
+
+`npx jdi-cli install-playwright` does three things:
+
+1. Installs `@playwright/test` as devDependency (detects pnpm/yarn/bun/npm via lockfile)
+2. Installs Chromium browser (`npx playwright install chromium`, ~170MB) — skippable with `--skip-browser`
+3. Injects Playwright MCP server config into all detected runtimes:
+
+| CLI | MCP config path |
+|---|---|
+| Claude Code | `.claude/settings.local.json` (`mcpServers.playwright`) |
+| OpenCode | `.opencode/opencode.jsonc` (`mcp.playwright`) |
+| GitHub Copilot (VS Code) | `.vscode/mcp.json` (`servers.playwright`) |
+| Antigravity (Google) | `~/.gemini/settings.json` user-scope OR `.gemini/settings.json` project-scope (`mcpServers.playwright`) |
+
+Idempotent: skips dep if already in `package.json`, skips MCP entry if already present.
+
+Restart your runtime to load the MCP after install.
+
+If `frontend.has_frontend: true` is set in `PROJECT.md`, `/jdi-bootstrap` will offer this install interactively (step S9).
+
+### Caveman plugin — token compression
+
+`npx jdi-cli install-caveman` clones the [Caveman](https://github.com/JuliusBrussee/caveman) plugin into:
+
+- **User scope (default):** `~/.claude/plugins/caveman/`
+- **Project scope:** `.claude/plugins/caveman/`
+
+Caveman is a Claude Code plugin that compresses LLM output ~75% by dropping articles/filler/pleasantries while preserving full technical accuracy. Useful for long sessions where context budget matters.
+
+After install, restart Claude Code. Toggle with `/caveman lite|full|ultra` or disable with `stop caveman`.
+
+`/jdi-bootstrap` offers this install interactively (step S9.5, project-agnostic).
+
+## Frontend support — auto-detect + UI/UX gates
+
+If your project has a web interface, JDI activates an extra set of UI/UX-focused gates. Detection runs against:
+
+- `package.json` for React, Vue, Svelte, Solid, Angular, Astro, Next, Nuxt, Remix, SvelteKit, Qwik, Preact
+- Razor/Blazor (`*.razor`, `*.cshtml`)
+- Django/Flask templates (`templates/*.html`)
+- Rails (`app/views/*.erb`)
+- Laravel (`resources/views/*.blade.php`)
+- Plain `index.html`
+
+### What auto-loads
+
+**Skill `frontend-rules`** — universal UI/UX checklist (**WCAG 2.2 AA + Nielsen + Material/Apple HIG**). Framework-agnostic. Covers:
+
+- Accessibility (contrast 4.5:1, focus visible, keyboard nav, ARIA, semantic HTML, touch targets, labels)
+- Mandatory states (loading / empty / error / success / disabled)
+- Forms (validation, autocomplete, inputmode, password toggle, destructive confirmations)
+- Performance UX (CLS < 0.1, LCP < 2.5s, INP < 200ms, optimistic UI)
+- Mobile-first responsive
+- i18n + l10n + RTL
+- UI security (token never in localStorage, CSP, CSRF, `target=_blank` with noopener)
+- BLOCK-level anti-patterns table with WCAG rule citations
+
+Doer applies it before writing code. Reviewer uses it as a gate 5 checklist.
+
+**Skill `frontend-validator`** — gate 7 of the reviewer. Runs Playwright + axe-core in a real browser:
+
+1. Detects Playwright. If absent, **asks before installing** (4 options: Chromium / all browsers / skip gate 7 / cancel review)
+2. Detects package manager via lockfile
+3. Spawns your dev server, waits for ready (60s poll timeout)
+4. Per critical route × **mobile (375×667)** + **desktop (1280×720)**:
+   - Captures console errors
+   - Captures network failures (4xx, 5xx, requestfailed)
+   - Runs axe-core (WCAG 2.0/2.1/2.2 AA + best-practices)
+   - Detects horizontal scroll
+   - Fullpage screenshot
+5. Kills dev server (always, even on error)
+6. JSON output in `.jdi/cache/ui-findings.json`
+
+### Finding severity
+
+| Finding | Severity |
+|---|---|
+| Console error on any route | BLOCK |
+| Network 5xx on critical route | BLOCK |
+| A11y violation `critical` or `serious` | BLOCK |
+| Horizontal scroll on mobile | BLOCK |
+| A11y violation `moderate`, network 4xx | WARN |
+| A11y violation `minor`, scroll on desktop | INFO |
+| Dev server timeout | INCONCLUSIVE (warn) |
+| User declined Playwright install | SKIPPED (warn) |
+
+Never BLOCK on technical failure — only on real findings. `.jdi/cache/` is auto-gitignored.
+
+### How it turns on
+
+You do nothing. When you run `/jdi-bootstrap` in a project with UI:
+
+1. Auto-detect fires
+2. Bootstrap asks: "Detected React in `package.json`. Confirm frontend?"
+3. If yes, 3 extra questions: dev server command (default per framework), frontend URL (default per framework), critical paths (default `/`)
+4. Persists `frontend:` section in `PROJECT.md`
+5. Injects `<skills_to_load>` into doer + reviewer
+
+From then on, `/jdi-do` loads `frontend-rules` when a task touches UI files; `/jdi-verify` runs gate 7 with Playwright.
+
+### How to turn off
+
+Edit `PROJECT.md`:
+```yaml
+frontend:
+  has_frontend: false
+```
+
+Gate 7 returns `SKIPPED`. Skill does not load.
+
+## Multi-stack — N specialist pairs
+
+By default, JDI creates **1 doer + 1 reviewer per project**. For fullstack (backend + frontend), mobile (iOS + Android), or polyglot projects, opt into multi-stack at `/jdi-bootstrap`:
+
+```
+Bootstrap asks: "Project stack count?"
+  - Single (1 specialist pair)
+  - Multi (2 pairs — e.g. backend + frontend)
+  - Multi (3 pairs — e.g. backend + frontend + infra)
+  - Multi (custom count)
+```
+
+For each specialist, you provide a `stack_label` + `file_glob`:
+
+| Specialist | Stack label | File glob |
+|---|---|---|
+| 1 | Backend C# | `**/*.{cs,csproj,sln}` |
+| 2 | Frontend React | `**/*.{ts,tsx,jsx,css,scss}` |
+| 3 | Infra Terraform | `**/*.{tf,tfvars}` |
+
+### How it routes
+
+- `.jdi/specialists.md` + `.jdi/reviewers.md` get one row per pair (schema v2 adds `File glob` column)
+- `/jdi-plan` matches each task's `files_modified` against globs and auto-assigns a specialist per task. Tasks spanning 2+ globs auto-split into sub-tasks
+- `/jdi-do` reads `task.specialist` from PLAN.md and spawns the right doer per task. Within a wave, different tasks may spawn different specialists in parallel (disjoint scopes)
+- `/jdi-verify` chains reviewers sequentially (build/test ports + locks would clash if parallel). Each reviewer scopes gates to its glob. Final verdict = worst-case (1 BLOCK = overall BLOCK)
+
+Single-stack projects (1 row) stay unchanged — backward compatible.
+
+## State model — `.jdi/`
+
+```
+your-project/
+├── .jdi/                          # state files (generated by JDI commands)
+│   ├── PROJECT.md                 # vision, stack, code-design (LOCKED after /jdi-new or /jdi-adopt)
+│   ├── ROADMAP.md                 # phases list (greenfield: MVP features, adopted: new features)
+│   ├── STATE.md                   # current phase, adopted flag, next step
+│   ├── DECISIONS.md               # append-only D-1, D-2, ... (locked decisions)
+│   ├── VERSION                    # JDI version installed
+│   ├── specialists.md             # registry of doer specialists (schema v2)
+│   ├── reviewers.md               # registry of reviewer specialists (schema v2)
+│   ├── registry.md                # append-only R-1, R-2, ... (audit trail of specialist creation)
+│   ├── agents/                    # per-project specialists
+│   │   ├── jdi-doer-{slug}.md
+│   │   └── jdi-reviewer-{slug}.md
+│   ├── phases/{NN-slug}/
+│   │   ├── CONTEXT.md             # from /jdi-discuss
+│   │   ├── PLAN.md                # from /jdi-plan
+│   │   ├── SUMMARY.md             # from /jdi-do
+│   │   ├── REVIEW.md              # from /jdi-verify (verdict)
+│   │   └── LOOP.md                # only if /jdi-loop ran (ralph state)
+│   └── cache/                     # gitignored — gate 7 artifacts (screenshots, JSON findings)
+├── .claude/                       # (if runtime=claude)
+│   ├── agents/jdi-*.md
+│   ├── commands/jdi-*.md
+│   └── settings.example.json
+├── .githooks/                     # no-op by default
+├── .gitattributes                 # normalizes CRLF
+├── CLAUDE.md                      # runtime instructions
+└── {your code}
+```
+
+For other runtimes, swap `.claude/` for `.github/`, `.gemini/antigravity/`, or `.opencode/`. See [PORTABILITY.md](PORTABILITY.md).
+
+### Invariants
+
+- `PROJECT.md` is **immutable** after `/jdi-new` or `/jdi-adopt`
+- `DECISIONS.md` is **append-only** (`D-1`, `D-2`, …). Locked decisions never reverse
+- `registry.md` is **append-only** (`R-1`, `R-2`, …) — audit trail
+- Every command is **idempotent** — re-running prompts before overwrite
+- Reviewer is **read-only by design** (no Write/Edit). Doer is the only writer
+
+## Gates between commands
+
+| From | To | Gate |
+|---|---|---|
+| `/jdi-discuss` | `/jdi-plan` | `CONTEXT.md` exists |
+| `/jdi-plan` | `/jdi-do` | PLAN valid (every task has `files_modified`, `acceptance`, `dependencies`, `test`, `specialist`) |
+| `/jdi-do` | `/jdi-verify` | `SUMMARY.md` exists |
+| `/jdi-verify` | `/jdi-ship` | `REVIEW.md` verdict ≠ `BLOCKED` |
+
+## Doctor — 12 sections
+
+```bash
+npx jdi-cli doctor
+npx jdi-cli doctor --verbose
+```
+
+1. Dependencies (git, bash detection)
+2. Runtimes installed (claude, copilot, antigravity, opencode)
+3. Optional tooling (ctx7, gh CLI)
+4. JDI repo integrity (`core/`)
+5. Adapters built (`runtimes/`)
+6. Current project (`.jdi/` files)
+7. Runtime installed in project
+8. Git hooks configured
+9. Working tree clean
+10. Playwright + MCP status (all 4 CLIs)
+11. Caveman plugin status (user vs project scope)
+12. Specialists (single vs multi-stack, reviewer chain length)
+
+## Update
+
+Dedicated command — detects installed runtimes, overwrites runtime files, preserves state, offers to regenerate specialists if templates changed:
+
+```bash
+cd /path/to/your/project
+npx jdi-cli@latest update
+```
+
+Preview without applying:
+
+```bash
+npx jdi-cli@latest update --dry-run
+```
+
+Force specialists regen (no prompt):
+
+```bash
+npx jdi-cli@latest update --force-specialists
+```
+
+Skip specialists regen even if template changed:
+
+```bash
+npx jdi-cli@latest update --skip-specialists
+```
+
+**What update touches:**
+- Overwrites agents, commands, skills in detected runtimes
+- Preserves `.jdi/PROJECT.md`, `DECISIONS.md`, `ROADMAP.md`, `STATE.md`, `phases/`, `registry.md`
+- Preserves custom config (`opencode.jsonc`, `settings.json`)
+- Updates `.jdi/VERSION`
+- Detects old specialists (without `<skills_to_load>`) and offers `/jdi-bootstrap` regen
+
+**What update does NOT touch:**
+- `@playwright/test` (run `jdi install-playwright` to refresh)
+- Chromium browser
+- MCP configs in `.claude/settings.local.json` / `.opencode/opencode.jsonc` / `.vscode/mcp.json` / `~/.gemini/settings.json`
+- Caveman plugin (run `jdi install-caveman --force` to refresh)
+
+## Uninstall
+
+```bash
+cd /path/to/your/project
+npx jdi-cli@latest uninstall                          # all detected runtimes, preserves .jdi/
+npx jdi-cli@latest uninstall claude                   # one runtime
+npx jdi-cli@latest uninstall opencode --scope user
+npx jdi-cli@latest uninstall --dry-run                # preview
+npx jdi-cli@latest uninstall --yes                    # skip prompts
+npx jdi-cli@latest uninstall --purge --yes            # DESTRUCTIVE: also wipe .jdi/
+```
+
+`--purge` permanently deletes locked decisions. Back up `.jdi/DECISIONS.md` and `.jdi/ROADMAP.md` first if relevant.
+
+Manual fallback:
+```bash
+rm -rf .claude/ .github/ .gemini/antigravity/ .opencode/ .githooks/ CLAUDE.md AGENTS.md
+# .jdi/ separate — destructive
+rm -rf .jdi/
+```
+
+## Agents inventory
+
+**Core (6 — shipped):**
+
+| Agent | Model | Role |
+|---|---|---|
+| `jdi-researcher` | Opus | Greenfield discovery — spawned by `/jdi-new` |
+| `jdi-adopter` | Opus | Brownfield discovery — spawned by `/jdi-adopt` |
+| `jdi-bootstrap` | Sonnet | Wrapper that generates specialists |
+| `jdi-asker` | Sonnet | Adaptive question loop (CONTEXT.md) |
+| `jdi-planner` | Opus | Decompose phase into tasks + waves |
+| `jdi-architect` | Opus | Meta (create + specialist modes) |
+
+**Per-project (generated by `/jdi-bootstrap`):**
+
+| Agent | Model | Role |
+|---|---|---|
+| `jdi-doer-{slug}` | Sonnet | Executor — knows stack, conventions, test framework |
+| `jdi-reviewer-{slug}` | Sonnet | Read-only gates (build/test/coverage/lint/security/UI) |
+
+Every flow agent has access to web tools (WebSearch, WebFetch, MCP `context7`) for on-demand research. Limits per agent — see each agent's `<research_tools>` block.
+
+## Skills inventory
+
+**Universal programming principles (auto-loaded by doer + reviewer):**
+
+| Skill | What |
+|---|---|
+| `dry` | Don't Repeat Yourself — knowledge duplication vs code coincidence, rule of three |
+| `kiss` | Keep It Simple — anti over-engineering, complexity must pay its cost |
+| `yagni` | You Aren't Gonna Need It — no speculative code, generalize after 3rd case |
+| `solid` | SRP/OCP/LSP/ISP/DIP with detection heuristics |
+| `clean-code` | Intentional names, small functions, explicit error handling, classic smells |
+
+**Frontend-conditional (auto-loaded if `has_frontend: true`):**
+
+| Skill | What |
+|---|---|
+| `frontend-rules` | WCAG 2.2 AA + UX checklist, framework-agnostic |
+| `frontend-validator` | Gate 7 — Playwright + axe-core live validation |
+
+See [AGENTS.md](AGENTS.md) for full details.
+
+## Commands inventory
+
+**Main loop (7):**
+
+| Command | Args | Flags | Purpose |
+|---|---|---|---|
+| `/jdi-new <description>` | description (optional) | `--reset` (wipes `.jdi/` first, asks confirm) | Greenfield entry: researcher + PROJECT.md + ROADMAP.md |
+| `/jdi-bootstrap` | — | — (idempotent: prompts Recreate/Keep/Cancel if specialists exist) | Generate doer + reviewer per project. Multi-stack opt-in via interactive question |
+| `/jdi-discuss <N>` | phase number | — | Adaptive question loop → CONTEXT.md |
+| `/jdi-plan <N>` | phase number | `--review` (preview PLAN.md before save, ask approve/edit/cancel) | Decompose phase into tasks + waves → PLAN.md |
+| `/jdi-do <N>` | phase number | `--sequential` (force sequential execution even if waves permit parallel) | Execute tasks via doer specialist(s) → SUMMARY.md |
+| `/jdi-verify <N>` | phase number | — | Run reviewer specialist gates → REVIEW.md (verdict APPROVED / APPROVED_WITH_WARNINGS / BLOCKED) |
+| `/jdi-ship <N>` | phase number | — | Update ROADMAP, advance phase. Gates: verdict must not be BLOCKED |
+
+**Brownfield entry (1):**
+
+| Command | Args | Flags | Purpose |
+|---|---|---|---|
+| `/jdi-adopt <description>` | description (optional override; defaults to README/inferred) | — | Scan existing repo, infer stack/code-design, confirm with user, mark `adopted: true` + D-2 boundary commit |
+
+**Ralph mode (1):**
+
+| Command | Args | Flags | Purpose |
+|---|---|---|---|
+| `/jdi-loop <N>` | phase number | `--max-iter=N` (default 5), `--max-resets=N` (default 3) | Auto-iterate `/jdi-do` ↔ `/jdi-verify` until APPROVED. Oscillation detection, human gate between rounds |
+
+**Meta (1, contributors only):**
+
+| Command | Args | Flags | Purpose |
+|---|---|---|---|
+| `/jdi-create <description>` | description (optional) | — | Generate new generic agent/skill in `core/`. For contributors editing JDI source, not consumers |
+
+See [COMMANDS.md](COMMANDS.md) for full details.
+
+### Adding a specialist mid-project
+
+`/jdi-bootstrap` is idempotent but its current "Recreate" mode wipes ALL specialists and regenerates. There is no `--add` mode yet (planned). To add a specialist to an existing multi-stack project today:
+
+**Option A — Re-run bootstrap (nukes manual edits):**
+
+```
+/jdi-bootstrap
+```
+
+When asked "Specialist already exists. Recreate / Keep / Cancel?":
+1. Pick **Recreate**
+2. At the multi-stack question, pick the new total count (e.g. was single → now "Multi 2 pairs")
+3. Provide `stack_label` + `file_glob` for each (existing + new)
+
+**Caveat:** any hand-edits in `.jdi/agents/jdi-doer-{slug}.md` or `jdi-reviewer-{slug}.md` get overwritten. If you have customizations, back them up first.
+
+**Option B — Manual edit (preserves customizations):**
+
+1. Copy an existing specialist as a template:
+   ```bash
+   cp .jdi/agents/jdi-doer-myapp.md      .jdi/agents/jdi-doer-myapp-newstack.md
+   cp .jdi/agents/jdi-reviewer-myapp.md  .jdi/agents/jdi-reviewer-myapp-newstack.md
+   ```
+2. Edit both:
+   - Rename inside `name:` and references
+   - Update `scope.file_glob` + `scope.stack_label` frontmatter
+   - Update `<role>` block (stack scope + STACK + TEST_FRAMEWORK + COVERAGE_MIN)
+   - Update build/test/lint/coverage commands in reviewer gates
+3. Append rows to `.jdi/specialists.md` and `.jdi/reviewers.md`:
+   ```markdown
+   | NewStack | jdi-doer-myapp-newstack | **/*.{ext1,ext2} | executor for files matching glob |
+   | jdi-reviewer-myapp-newstack | **/*.{ext1,ext2} | /jdi-verify | yes, if BLOCKED |
+   ```
+4. Append to `.jdi/registry.md` (audit trail):
+   ```markdown
+   ## R-{N+1} ({date})
+   **Type:** specialist (doer + reviewer, manual add)
+   **Slug:** myapp-newstack
+   **Stack:** NewStack
+   ```
+5. Commit:
+   ```bash
+   git add .jdi/agents/ .jdi/specialists.md .jdi/reviewers.md .jdi/registry.md
+   git commit -m "chore(jdi): add NewStack specialist (manual)"
+   ```
+
+From the next `/jdi-plan`, the new specialist routes automatically based on its glob.
+
+**Option C — Wait for `/jdi-bootstrap --add`** (planned next minor):
+
+```
+/jdi-bootstrap --add    # asks 1 new specialist only, preserves existing
+```
+
+## Runtimes supported
+
+| Runtime | Tier | npx install |
+|---|---|---|
+| Claude Code | tier 1 | `npx jdi-cli install claude` |
+| GitHub Copilot | tier 1 | `npx jdi-cli install copilot` |
+| OpenCode | tier 1 | `npx jdi-cli install opencode` |
+| Google Antigravity | tier 2 | `npx jdi-cli install antigravity --scope user` |
+| All | — | `npx jdi-cli install all` |
+
+Default scope: `project`. For user-scope global: `--scope user`.
+
+**Power users (shell scripts direct, no Node):**
+
+| Runtime | Bash | PowerShell |
+|---|---|---|
+| Claude | `jdi-install.sh claude` | `jdi-install.ps1 -Runtime claude` |
+| OpenCode | `jdi-install.sh opencode --scope user` | `jdi-install.ps1 -Runtime opencode -Scope user` |
+
+See [PORTABILITY.md](PORTABILITY.md) for per-runtime mapping details.
+
+## Power users — shell scripts direct
+
+For containers, minimal environments, or no-Node setups:
+
+```bash
+git clone https://github.com/slipalison/jdi-cli.git
+cd jdi-cli
+
+# Build adapters
+./bin/jdi-build.sh                                 # Linux/Mac
+.\bin\jdi-build.ps1                                # Windows
+
+# Install in your project
+cd /path/to/your/project
+/path/to/jdi-cli/bin/jdi-install.sh claude --scope project
+# Windows: C:\path\to\jdi-cli\bin\jdi-install.ps1 -Runtime claude -Scope project
+```
+
+**Windows note:** if PowerShell blocks `.ps1`:
+```powershell
+Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
+# Or per-call:
+pwsh -ExecutionPolicy Bypass -File .\bin\jdi-build.ps1
+```
+
+## Philosophy
+
+1. **Fresh context per agent** — each spawn has a clean window
+2. **Thin orchestrator** — commands load context, spawn agent, route
+3. **File-based state** — `.jdi/` in md/json, no DB
+4. **Locked decision = immutable** — D-XX never reverses
+5. **1 task = 1 atomic commit**
+6. **Per-project specialists** — doer/reviewer customized, not generic
+7. **Wave-based parallelism** — parallel within wave, sequential between
+8. **Security > Performance > Best Practices** (declared invariant)
+
+## Conventions
+
+- **Conventional Commits** everywhere. Per-task atomic commits during `/jdi-do`. Orchestrator writes final `chore(state): phase {N} executed`
+- **Code + prompts + docs in English** (was pt-BR before v1.8)
+- Default coverage gate: **80%** unless `PROJECT.md` overrides
+- Adopted brownfield projects enforce coverage only on files created AFTER D-2 boundary commit
+- Git hooks ship as **no-op** — reviewer covers quality gates, users opt-in to hooks themselves
+- Conventional Commits scope = phase slug
+
+## Reset (full wipe + restart)
+
+```
+/jdi-new --reset "<new description>"
+```
+
+Deletes `.jdi/` after confirmation. Recreates from scratch. **CAUTION** — loses DECISIONS.md, ROADMAP.md, etc.
+
+## Troubleshooting
+
+### Build script fails on Linux/Mac
+
+Check deps: `bash --version`, `awk --version`, `sed --version`. Use bash >= 4.
+
+### Windows: .sh scripts don't run in PowerShell
+
+Use the `.ps1` equivalents:
+- `bin/jdi-build.sh` → `bin/jdi-build.ps1`
+- `bin/jdi-install.sh` → `bin/jdi-install.ps1`
+- `bin/jdi-doctor.sh` → `bin/jdi-doctor.ps1`
+
+Or run via Git Bash / WSL.
+
+### Windows: PowerShell blocks .ps1 execution
+
+```powershell
+Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
+# OR
+pwsh -ExecutionPolicy Bypass -File .\bin\jdi-build.ps1
+```
+
+After download, may need `Unblock-File`:
+```powershell
+Get-ChildItem .\bin\*.ps1 | Unblock-File
+```
+
+### Windows: git hooks don't fire
+
+Hooks are bash scripts. Windows needs Git for Windows (ships `bash.exe`). Without it, hooks are silently ignored.
+
+JDI default: hooks are no-op. If you don't customize, this blocks nothing.
+
+### Slash command doesn't appear in runtime
+
+```bash
+ls .claude/commands/    # or .github/prompts/, .opencode/commands/
+```
+
+If empty, reinstall:
+```bash
+npx jdi-cli install <runtime> --scope project
+```
+
+### Specialist not generated by /jdi-bootstrap
+
+Check `PROJECT.md` has stack + code-design. Edit manually if missing, then re-run bootstrap (idempotent — prompts before overwrite):
+```
+/jdi-bootstrap
+```
+
+### Phase BLOCKED in /jdi-verify, can't /jdi-ship
+
+REVIEW.md lists blockers. Fix code, run `/jdi-do <N>` again (re-executes affected tasks), then `/jdi-verify <N>`. When verdict != BLOCKED, ship unblocks.
+
+### Token budget too high in large phase
+
+PLAN.md with >8 tasks indicates phase is too large. Split:
+1. Edit ROADMAP.md, split current phase into 2 or 3
+2. Run `/jdi-discuss <N>` for each (smaller CONTEXT.md each)
+
+### MCP playwright doesn't appear after install
+
+Restart the runtime. For Claude Code: `/mcp` to verify. For OpenCode: `opencode reload`. For Copilot: VS Code palette `MCP: List Servers`. For Antigravity: restart Antigravity.
+
+## See also
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) — technical overview
+- [AGENTS.md](AGENTS.md) — agents detailed
+- [COMMANDS.md](COMMANDS.md) — commands detailed
+- [MEMORY.md](MEMORY.md) — `.jdi/` schema
+- [EXTENSION.md](EXTENSION.md) — create specialists/agents/skills
+- [CREATE.md](CREATE.md) + [CREATE-EXAMPLE.md](CREATE-EXAMPLE.md) — `/jdi-create` walkthrough
+- [PORTABILITY.md](PORTABILITY.md) — multi-runtime details
+
+## License
+
+MIT.
+
+## Contributing
+
+Run `/jdi-create` inside the JDI source repo to add generic agents/skills. It runs against `core/templates/{agent,skill}.md` with automatic integration.
+
+Pull requests: describe the problem (who needs this? how many users?) before adding a new agent. JDI grows **carefully** — soft cap: 6 core agents, 25 core skills. See [EXTENSION.md](EXTENSION.md).
+
+## Publishing to npm (maintainers)
+
+Push a `v*.*.*` tag and GitHub Actions handles the rest (`.github/workflows/npm-publish.yml`):
+
+```bash
+# 1. Bump version in package.json
+# 2. Rebuild runtimes/
+node bin/jdi.js build
+
+# 3. Commit + push main
+git add -A && git commit -m "chore(release): X.Y.Z"
+git push origin main
+
+# 4. Tag + push tag (triggers workflow)
+git tag -a vX.Y.Z -m "vX.Y.Z — short description"
+git push origin vX.Y.Z
+
+# 5. Watch
+gh run watch
+```
+
+Workflow verifies tag matches `package.json`, runs `npm publish --provenance --access public`. Provenance badge appears on the npm page via sigstore OIDC.
+
+`package.json` `files:` controls what ships in the tarball.