JDI — Just Do It

       ██╗██████╗ ██╗
       ██║██╔══██╗██║
       ██║██║  ██║██║
  ██   ██║██║  ██║██║
  ╚█████╔╝██████╔╝██║
   ╚════╝ ╚═════╝ ╚═╝

  ◄══════════════════════════════════════════════|=|◉|=|/////|==
  ◄══════════════════════════════════════════════|=|◉|=|/////|==
  ◄══════════════════════════════════════════════|=|◉|=|/////|==

  Cut through the chaos. Ship the work. [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

Every phase command accepts either a slug (auth-flow, canonical) or an integer position (2, display ordering). Slugs are stable across branch merges; positions are not. New phases default to slug-as-ID; legacy NN-slug projects keep working until you opt into /jdi-migrate-phases.

Greenfield (new project)

/jdi-new "<short description>"             <- research + PROJECT.md + ROADMAP.md (schema v2)
/jdi-bootstrap                             <- doer + reviewer per project
/jdi-discuss <slug|position>               <- capture locked decisions (CONTEXT.md)
/jdi-plan    <slug|position>               <- decompose into tasks + waves (PLAN.md)
/jdi-do      <slug|position>               <- execute via doer specialist (SUMMARY.md)
/jdi-verify  <slug|position>               <- gates via reviewer (REVIEW.md)
/jdi-ship    <slug|position>               <- update ROADMAP, advance phase

# Roadmap mutation (run anytime, multi-developer safe)
/jdi-add-phase "<name>" [--slug s] [--before <slug>|--after <slug>]
/jdi-remove-phase <slug|position> [--force]

# v0/v1 → v2 migration (one-time, non-destructive)
/jdi-migrate-phases [--dry-run]            <- adds schema_version: 2 + phases.json

# Continuity / where did I stop?
/jdi-status                                <- compact snapshot: phase + last action + next step

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 <slug|position>               <- ... same as greenfield from here
/jdi-plan    <slug|position>
/jdi-do      <slug|position>
/jdi-verify  <slug|position>
/jdi-ship    <slug|position>

/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 <slug|position>

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

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

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).

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

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

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)

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

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/.

npx jdi-cli@latest build

Misc

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)

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:

Installs @playwright/test as devDependency (detects pnpm/yarn/bun/npm via lockfile)
Installs Chromium browser (npx playwright install chromium, ~170MB) — skippable with --skip-browser
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 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:

Detects Playwright. If absent, asks before installing (4 options: Chromium / all browsers / skip gate 7 / cancel review)
Detects package manager via lockfile
Spawns your dev server, waits for ready (60s poll timeout)
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
Kills dev server (always, even on error)
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:

Auto-detect fires
Bootstrap asks: "Detected React in package.json. Confirm frontend?"
If yes, 3 extra questions: dev server command (default per framework), frontend URL (default per framework), critical paths (default /)
Persists frontend: section in PROJECT.md
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:

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                   # schema_version, current_phase_slug, current_phase, adopted flag, next step
│   ├── DECISIONS.md               # append-only (v1: D-1, D-2, ...; v2: D-YYYY-MM-DD-slug-seq — multi-dev safe)
│   ├── VERSION                    # JDI version installed
│   ├── specialists.md             # registry of doer specialists
│   ├── reviewers.md               # registry of reviewer specialists
│   ├── registry.md                # append-only audit trail of specialist creation
│   ├── phases.json                # v2 only: manifest mapping position <-> slug (legacy folders flagged)
│   ├── agents/                    # per-project specialists
│   │   ├── jdi-doer-{slug}.md
│   │   └── jdi-reviewer-{slug}.md
│   ├── phases/
│   │   ├── <slug>/                # v2 layout (default for new projects)
│   │   │   ├── 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)
│   │   └── NN-<slug>/             # v1 legacy layout — NEVER renamed (preserves git history)
│   └── 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.

Invariants

PROJECT.md is immutable after /jdi-new or /jdi-adopt
DECISIONS.md is append-only. Locked decisions never reverse. v1 uses D-1, D-2, …; v2 uses deterministic D-YYYY-MM-DD-slug-seq (collision-free across developer branches)
registry.md is append-only — audit trail
Phase slugs never change. Existing NN-slug/ folders are never renamed on migration. Numeric positions (### Phase 3) are display-only and may renumber on insert/remove
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`

Multi-developer concurrency (schema v2)

Multiple developers can run JDI in parallel on the same project as long as the project is on schema v2.

The problem with v1 (numeric IDs):

Phase identifier was the position in ROADMAP (current_phase: 5).
Two developers on parallel branches both pick total_phases + 1 → both create .jdi/phases/06-foo/ and .jdi/phases/06-bar/ → silent collision on merge.
D-X decision IDs and R-X registry entries had the same race.

How v2 fixes it:

Phase identifier is a slug (auth-flow, payments). Validated at creation: shape ([a-z][a-z0-9-]{2,39}, no --, no trailing -), reserved-word list (current, all, archive, …), uniqueness vs folders AND ROADMAP.
Folder layout becomes .jdi/phases/<slug>/ (no NN- prefix). Two developers picking different slugs produce disjoint folders — git merges cleanly. Two developers picking the same slug surface as an explicit git conflict, not a silent overwrite.
### Phase N: heading is display-only — may renumber when phases are inserted/removed without affecting slug references.
DECISIONS.md IDs become deterministic: D-{YYYY-MM-DD}-{phase_slug}-{seq} (collision-free across branches).
Commit scopes use slugs: chore(payments): ... instead of chore(NN-payments): ....

Recommended workflow with multiple developers:

git pull
/jdi-add-phase "<name>" --slug <unique-slug>   # validator refuses duplicates locally
git push                                       # if remote moved, pull/rebase first; slug collision (rare) is a real signal

Migration from v1 (existing projects on numeric IDs):

/jdi-migrate-phases --dry-run   # show audit + plan, write nothing
/jdi-migrate-phases             # confirm, write schema_version: 2 + phases.json

Idempotent: re-running on a v2 project is a no-op.
Non-destructive: existing NN-slug/ folders are NEVER renamed (git history references stay valid). New phases use slug-only folders.
Pre-flight audit checks folder/ROADMAP parity, duplicate canonical slugs, and slug shape — aborts with a named error before writing anything.
Refuses when .jdi/ working tree is dirty (unless --force) so the migration commit stays auditable.

Both schemas coexist after migration — old folders keep working, new folders use the new layout. Every command accepts both ID forms (/jdi-do 2 and /jdi-do auth-flow resolve to the same phase).

Schema detection is automatic via STATE.md's schema_version field (1 or absent = v1; 2 = v2). The resolver (bin/lib/jdi-resolve-phase.{sh,ps1}) and validator (bin/lib/jdi-validate-slug.{sh,ps1}) ship in the npm package.

Doctor — 12 sections

npx jdi-cli doctor
npx jdi-cli doctor --verbose

Dependencies (git, bash detection)
Runtimes installed (claude, copilot, antigravity, opencode)
Optional tooling (ctx7, gh CLI)
JDI repo integrity (core/)
Adapters built (runtimes/)
Current project (.jdi/ files)
Runtime installed in project
Git hooks configured
Working tree clean
Playwright + MCP status (all 4 CLIs)
Caveman plugin status (user vs project scope)
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:

cd /path/to/your/project
npx jdi-cli@latest update

Preview without applying:

npx jdi-cli@latest update --dry-run

Force specialists regen (no prompt):

npx jdi-cli@latest update --force-specialists

Skip specialists regen even if template changed:

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

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:

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 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 <slug\|position>`	phase id (slug or int)	`--auto` (asker decides everything, no questions)	Adaptive question loop → CONTEXT.md
`/jdi-plan <slug\|position>`	phase id	`--review` (preview PLAN.md before save)	Decompose phase into tasks + waves → PLAN.md
`/jdi-do <slug\|position>`	phase id	`--sequential` (force sequential even if waves permit parallel)	Execute tasks via doer specialist(s) → SUMMARY.md
`/jdi-verify <slug\|position>`	phase id	—	Run reviewer gates → REVIEW.md (APPROVED / APPROVED_WITH_WARNINGS / BLOCKED)
`/jdi-ship <slug\|position>`	phase id	—	Update ROADMAP, advance phase. Gates: verdict must not be BLOCKED
`/jdi-add-phase "<name>"`	phase name (required)	`--goal "<text>"`, `--slug <slug>`, `--before <slug>` \| `--after <slug>`, `--reason "<text>"`. Legacy `--at <pos>` accepted on v1 only.	Register a new phase in ROADMAP.md. Slug-as-ID — validates shape, reserved words, uniqueness. Multi-developer safe (slug collisions surface as git conflict).
`/jdi-remove-phase <slug\|position>`	phase id (required)	`--force` (required if artifacts exist)	Remove a future or pending phase. Refuses for `done`, current, or past phases. Archives existing artifacts to `.jdi/archive/removed-<slug>/`. Slugs of remaining phases are NEVER changed (display positions renumber).
`/jdi-migrate-phases`	—	`--dry-run`, `--force` (bypass clean-tree gate)	Migrate a v1 project (numeric phase IDs, `NN-slug/` folders) to v2 (slug-as-ID). Non-destructive — does NOT rename folders. Adds `schema_version: 2` + `.jdi/phases.json` manifest. Idempotent. Required for safe multi-developer parallel `/jdi-add-phase`.
`/jdi-status`	—	—	Read-only snapshot. Prints schema, current phase (slug + position), status, verdict, last artifact, last commit, next step. No agent invoked. Safe anytime.

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 <slug\|position>`	phase id	`--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 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?":

Pick Recreate
At the multi-stack question, pick the new total count (e.g. was single → now "Multi 2 pairs")
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):

Copy an existing specialist as a template:

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

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

Append rows to .jdi/specialists.md and .jdi/reviewers.md:

| NewStack | jdi-doer-myapp-newstack | **/*.{ext1,ext2} | executor for files matching glob |
| jdi-reviewer-myapp-newstack | **/*.{ext1,ext2} | /jdi-verify | yes, if BLOCKED |

Append to .jdi/registry.md (audit trail):

## R-{N+1} ({date})
**Type:** specialist (doer + reviewer, manual add)
**Slug:** myapp-newstack
**Stack:** NewStack

Commit:

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 for per-runtime mapping details.

Power users — shell scripts direct

For containers, minimal environments, or no-Node setups:

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:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
# Or per-call:
pwsh -ExecutionPolicy Bypass -File .\bin\jdi-build.ps1

Philosophy

Fresh context per agent — each spawn has a clean window
Thin orchestrator — commands load context, spawn agent, route
File-based state — .jdi/ in md/json, no DB
Locked decision = immutable — D-XX never reverses
1 task = 1 atomic commit
Per-project specialists — doer/reviewer customized, not generic
Wave-based parallelism — parallel within wave, sequential between
Security > Performance > Best Practices (declared invariant)

Conventions

Conventional Commits everywhere. Per-task atomic commits during /jdi-do. Orchestrator writes final chore(state): phase {slug} executed (v2; v1 legacy uses position)
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

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
# OR
pwsh -ExecutionPolicy Bypass -File .\bin\jdi-build.ps1

After download, may need Unblock-File:

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

ls .claude/commands/    # or .github/prompts/, .opencode/commands/

If empty, reinstall:

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 <slug|position> again (re-executes affected tasks), then /jdi-verify <slug|position>. When verdict != BLOCKED, ship unblocks.

Token budget too high in large phase

PLAN.md with >8 tasks indicates phase is too large. Split:

Edit ROADMAP.md, split current phase into 2 or 3
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.

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.

Publishing to npm (maintainers)

Push a v*.*.* tag and GitHub Actions handles the rest (.github/workflows/npm-publish.yml):

# 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.

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
.github/workflows		.github/workflows
bin		bin
core		core
runtimes		runtimes
templates-jdi-folder		templates-jdi-folder
.gitignore		.gitignore
AGENTS.md		AGENTS.md
ARCHITECTURE.md		ARCHITECTURE.md
COMMANDS.md		COMMANDS.md
CREATE-EXAMPLE.md		CREATE-EXAMPLE.md
CREATE.md		CREATE.md
EXTENSION.md		EXTENSION.md
LICENSE		LICENSE
MEMORY.md		MEMORY.md
PORTABILITY.md		PORTABILITY.md
README.md		README.md
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

JDI — Just Do It

Why

The flow

Greenfield (new project)

Brownfield (existing project)

Ralph mode (auto-iterate)

Quickstart — npx in 30 seconds

Prerequisites

CLI subcommands

install <runtime> — install JDI into the project

install-playwright — Playwright dev dep + chromium browser + MCP config

install-caveman — clone Caveman plugin

update — refresh runtime files, preserve state

uninstall [runtime] — remove JDI files

doctor — environment diagnostic

build — regenerate runtimes/ from core/ (contributors only)

Misc

Install globally (optional)

Optional add-ons

Playwright MCP — live browser tool for all 4 CLIs

Caveman plugin — token compression

Frontend support — auto-detect + UI/UX gates

What auto-loads

Finding severity

How it turns on

How to turn off

Multi-stack — N specialist pairs

How it routes

State model — .jdi/

Invariants

Gates between commands

Multi-developer concurrency (schema v2)

Doctor — 12 sections

Update

Uninstall

Agents inventory

Skills inventory

Commands inventory

Adding a specialist mid-project

Runtimes supported

Power users — shell scripts direct

Philosophy

Conventions

Reset (full wipe + restart)

Troubleshooting

Build script fails on Linux/Mac

Windows: .sh scripts don't run in PowerShell

Windows: PowerShell blocks .ps1 execution

Windows: git hooks don't fire

Slash command doesn't appear in runtime

Specialist not generated by /jdi-bootstrap

Phase BLOCKED in /jdi-verify, can't /jdi-ship

Token budget too high in large phase

MCP playwright doesn't appear after install

See also

License

Contributing

Publishing to npm (maintainers)

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Quickstart — `npx` in 30 seconds

`install <runtime>` — install JDI into the project

`install-playwright` — Playwright dev dep + chromium browser + MCP config

`install-caveman` — clone Caveman plugin

`update` — refresh runtime files, preserve state

`uninstall [runtime]` — remove JDI files

`doctor` — environment diagnostic

`build` — regenerate runtimes/ from core/ (contributors only)

State model — `.jdi/`

Packages