jdi-cli 0.1.0

package/runtimes/claude/commands/jdi-do.md

@@ -0,0 +1,200 @@
+---
+name: jdi-do
+description: Executes phase. Automatic routing to project's doer specialist. Wave-based parallel if phase has >=3 independent tasks.
+argument_hint: "<phase_number> [--sequential]"
+runtime_intent:
+  invokes_agent: dynamic
+runtime_overrides:
+  claude:
+    allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion, Agent]
+  copilot:
+    tools: [read, write, edit, grep, glob, terminal]
+  opencode:
+    subtask: true
+    model: anthropic/claude-sonnet-4-20250514
+  antigravity:
+    triggers:
+      - "/jdi-do"
+      - "execute phase {N}"
+---
+
+<objective>
+Executes all tasks of the given phase. Reads PLAN.md, groups into waves, dispatches doer specialist (jdi-doer-{slug}). Wave-based parallelism, sequential dispatch (one Agent per message with `run_in_background`).
+</objective>
+
+<arguments>
+- `phase_number` (required)
+- `--sequential` (optional): forces sequential execution even if waves allow parallel. Useful for debug.
+</arguments>
+
+<process>
+
+### Step 1: Validation
+```bash
+test -d .jdi/ || { echo "Not a JDI project. /jdi-new."; exit 1; }
+test -f .jdi/STATE.md || { echo "STATE.md missing."; exit 1; }
+
+# Verify specialist exists
+ls .jdi/agents/jdi-doer-*.md 2>/dev/null | head -1 || {
+  echo "Doer specialist missing. Run /jdi-bootstrap."
+  exit 1
+}
+
+# Verify PLAN.md exists for phase
+ls .jdi/phases/{NN}*/PLAN.md 2>/dev/null || {
+  echo "PLAN.md missing for phase {N}. Run /jdi-plan {N}."
+  exit 1
+}
+
+# Context budget warm-up (does not block)
+JDI_LIB="$(dirname "$(command -v jdi 2>/dev/null || echo /usr/local/bin/jdi)")/../lib"
+if [ -f "$JDI_LIB/jdi-monitor.sh" ]; then
+  bash "$JDI_LIB/jdi-monitor.sh" .jdi/PROJECT.md .jdi/DECISIONS.md .jdi/phases/{NN}*/PLAN.md .jdi/phases/{NN}*/CONTEXT.md || true
+fi
+# Windows: pwsh -File "$JDI_LIB/jdi-monitor.ps1" -Paths @(...)
+```
+
+### Step 2: Resolve doer specialist(s)
+
+Read `.jdi/specialists.md`. Detect single vs multi-stack.
+
+```bash
+DOER_COUNT=$(grep -cE 'jdi-doer-[a-z0-9-]+' .jdi/specialists.md)
+echo "Specialists registered: $DOER_COUNT"
+
+if [ "$DOER_COUNT" -eq 0 ]; then
+  echo "No doer registered. Run /jdi-bootstrap."
+  exit 1
+fi
+```
+
+**Single-stack** (`DOER_COUNT == 1`): take that doer, ignore task.specialist.
+```bash
+DOER=$(grep -oE 'jdi-doer-[a-z0-9-]+' .jdi/specialists.md | head -1)
+```
+
+**Multi-stack** (`DOER_COUNT > 1`): for each task in PLAN.md, read its `**Specialist:**` field (planner set this). Dispatch to that specialist. Tasks in same wave can spawn DIFFERENT specialists in parallel.
+
+```bash
+# Per task, extract specialist from PLAN.md
+TASK_SPEC=$(awk -v t="$task_id" '/^#### '"$task_id"':/{flag=1} flag && /^\*\*Specialist:\*\*/{print $2; exit}' .jdi/phases/{NN}*/PLAN.md)
+```
+
+If task lacks specialist field (legacy PLAN.md pre-1.12) → fallback to first doer registered.
+
+### Step 3: Read PLAN.md, group waves
+
+Parse PLAN.md, extract:
+- List of pending tasks (`status: pending`)
+- Each task's wave
+- Files_modified
+
+If `--sequential` or phase has <3 parallel tasks: use sequential execution (1 doer at a time).
+
+Otherwise: wave-based parallel.
+
+### Step 4: Intra-wave overlap check (safety)
+
+For each wave:
+- Get list of files_modified per task
+- Check pair-by-pair: do 2 tasks share a file?
+- If yes -> override to sequential for that wave (warn user)
+
+### Step 5: Execute waves
+
+**For each wave in order:**
+
+```
+[wave {W}/{total}] starting, {N} tasks
+```
+
+**If parallel (>=2 tasks in wave + no overlap + not --sequential):**
+
+Sequential dispatch — ONE `Agent()` per message with `run_in_background: true`. Each task resolves its OWN `subagent_type` from task.specialist (multi-stack):
+
+```
+# For each task in wave, resolve specialist:
+TASK_SPECIALIST = <task.specialist field from PLAN.md> OR <single doer fallback>
+
+Agent(
+  subagent_type="${TASK_SPECIALIST}",   # may differ per task in multi-stack
+  description="Execute T-{X}.{Y} phase {N}",
+  prompt="phase={N}, task=T-{X}.{Y}, mode=single_task",
+  run_in_background: true
+)
+```
+
+Within a wave, multi-stack projects may spawn DIFFERENT specialists in parallel (e.g. `jdi-doer-myapp-backend` and `jdi-doer-myapp-frontend` simultaneously — different file scopes, disjoint `files_modified`).
+
+Wait for all to return before next wave.
+
+**If sequential:** same prompt, no `run_in_background`, one at a time.
+
+Doer reads PLAN.md/PROJECT.md/CONTEXT.md on its own — specialist convention.
+
+### Step 6: After each wave
+
+Read updated PLAN.md (doer updates status). Count:
+- completed
+- blocked
+- pending
+
+If any task `blocked` in critical wave -> stop execution, mark phase `partial`, skip to Step 8.
+
+### Step 7: After all waves
+
+Verify SUMMARY.md was created:
+```bash
+test -f .jdi/phases/{NN}*/SUMMARY.md || { echo "warn: SUMMARY missing"; }
+```
+
+### Step 8: Update STATE
+
+```markdown
+current_phase: {N}
+phase_status: {executed|partial}
+next_step: /jdi-verify {N}
+```
+
+```bash
+git add .jdi/STATE.md
+git commit -m "chore(state): phase {N} executed"
+```
+
+### Step 9: Confirm
+
+```
+Phase {N}: {done}/{total} tasks ({blocked} blocked), {W} waves, {count} files.
+SUMMARY: .jdi/phases/{NN-slug}/SUMMARY.md
+Next: /jdi-verify {N}
+```
+
+</process>
+
+<gates>
+- pre: PLAN.md exists + doer specialist registered in .jdi/specialists.md
+- post: tasks executed (partial or total), SUMMARY.md created, STATE updated
+</gates>
+
+<errors>
+- Doer missing -> /jdi-bootstrap
+- PLAN missing -> /jdi-plan
+- Doer fails on task -> task stays `blocked`, continue with the rest (does not abort all)
+- Entire wave blocked -> abort phase, mark `partial`
+</errors>
+
+<runtime_notes>
+
+**Claude Code:**
+- Real sequential dispatch works via `run_in_background: true` in separate Agent calls
+- Wait for completion via tool result notifications
+
+**Copilot:**
+- Subagent spawning does not return reliable signal
+- Default = automatic `--sequential` in Copilot
+- Loop foreach task, dispatch one at a time
+
+**OpenCode/Antigravity:**
+- Use runtime's native Task/spawn
+- Parallelism if runtime supports
+</runtime_notes>

package/runtimes/claude/commands/jdi-loop.md

@@ -0,0 +1,315 @@
+---
+name: jdi-loop
+description: Ralph loop — orchestrates auto dev↔review until APPROVED verdict. 5 iter cap, human gate + reset (max 3 resets = 15 iter absolute). Oscillation detection cuts dead loop early.
+argument_hint: "<phase_number> [--max-iter=5] [--max-resets=3]"
+runtime_intent:
+  invokes_agent: dynamic
+runtime_overrides:
+  claude:
+    allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion, Agent]
+  copilot:
+    tools: [read, write, edit, grep, glob, terminal]
+  opencode:
+    subtask: true
+    model: anthropic/claude-sonnet-4-20250514
+  antigravity:
+    triggers:
+      - "/jdi-loop"
+      - "ralph loop phase {N}"
+      - "auto review phase {N}"
+---
+
+<objective>
+Runs the `/jdi-do {N}` -> `/jdi-verify {N}` cycle in loop until APPROVED or APPROVED_WITH_WARNINGS verdict, with no human action between iters. Absolute cap: 5 iter per round + max 3 resets (15 iter total). Ask user before resetting.
+
+Ralph pattern (Huntley + ASDLC):
+- Generator/Judge separation (doer writes, reviewer reads)
+- Bounded iteration (explicit cap)
+- Objective exit criteria (REVIEW.md APPROVED verdict)
+- Context rotation (each Agent spawn = fresh context)
+- State persistence (LOOP.md + git commits)
+- Oscillation detection (finding hash compare)
+</objective>
+
+<arguments>
+- `phase_number` (required)
+- `--max-iter=N` (optional, default 5): iter per round before human gate
+- `--max-resets=N` (optional, default 3): reset rounds before kill switch
+</arguments>
+
+<process>
+
+### Step 1: Validation
+
+```bash
+test -d .jdi/ || { echo "Not a JDI project. /jdi-new."; exit 1; }
+test -f .jdi/STATE.md || { echo "STATE.md missing."; exit 1; }
+
+# Specialists registered
+ls .jdi/agents/jdi-doer-*.md 2>/dev/null | head -1 || {
+  echo "Doer missing. /jdi-bootstrap."; exit 1;
+}
+ls .jdi/agents/jdi-reviewer-*.md 2>/dev/null | head -1 || {
+  echo "Reviewer missing. /jdi-bootstrap."; exit 1;
+}
+
+# PLAN exists
+ls .jdi/phases/{NN}*/PLAN.md 2>/dev/null || {
+  echo "PLAN missing for phase {N}. /jdi-plan {N}."; exit 1;
+}
+```
+
+### Step 2: Initialize or resume LOOP.md
+
+Path: `.jdi/phases/{NN-slug}/LOOP.md`
+
+```bash
+LOOP_FILE=".jdi/phases/{NN-slug}/LOOP.md"
+
+if [ ! -f "$LOOP_FILE" ]; then
+  cat > "$LOOP_FILE" <<EOF
+---
+phase: {N}
+iter: 0
+total_resets: 0
+status: running
+max_iter_per_round: ${MAX_ITER:-5}
+max_resets: ${MAX_RESETS:-3}
+created_at: $(date -Iseconds)
+---
+
+## History
+
+EOF
+fi
+```
+
+If already exists:
+- Read `iter`, `total_resets`, `status` from frontmatter
+- Terminal states (abort):
+  - `status == converged` -> abort: "Phase already converged. /jdi-ship {N}"
+  - `status == killed` -> abort: "Hard cap reached. Plan needs human review."
+- Resumable states (continue — go back to running):
+  - `status == escalated` -> reset `iter: 0`, `status: running`, `total_resets` preserved, append marker `--- RESUMED from escalated at {ts} ---` in history. Continue loop.
+  - `status == paused` -> reset `iter: 0`, `status: running`, `total_resets` preserved, append marker `--- RESUMED from paused at {ts} ---` in history. Continue loop.
+- Active state:
+  - `status == running` -> resume from current iter (session crash mid-loop case)
+
+### Step 3: Main loop
+
+```
+loop:
+  iter++
+
+  # --- Step A: dispatch doer ---
+  Agent(
+    subagent_type=$DOER,
+    description="Loop iter {iter} doer phase {N}",
+    prompt="phase={N}, mode=ralph_loop, iter={iter}"
+  )
+
+  # Doer detects ralph mode via presence of LOOP.md + REVIEW.md (Step 1 of specialist).
+  # If REVIEW.md verdict=BLOCKED, focuses on fixing blockers.
+
+  # --- Step B: dispatch reviewer ---
+  Agent(
+    subagent_type=$REVIEWER,
+    description="Loop iter {iter} reviewer phase {N}",
+    prompt="phase={N}, mode=verify, iter={iter}"
+  )
+
+  # --- Step C: parse verdict ---
+  REVIEW_FILE=".jdi/phases/{NN-slug}/REVIEW.md"
+  test -f "$REVIEW_FILE" || { echo "REVIEW.md not created at iter {iter}"; exit 1; }
+
+  VERDICT=$(grep -oE 'Verdict:\*\* (APPROVED|APPROVED_WITH_WARNINGS|BLOCKED)' "$REVIEW_FILE" | awk '{print $2}')
+
+  # --- Step D: hash findings (oscillation detection) ---
+  FINDING_BODY=$(awk '
+    /^## Blockers/ { flag=1; next }
+    /^## Warnings/ { flag=1; next }
+    /^## / { flag=0 }
+    flag { print }
+  ' "$REVIEW_FILE")
+
+  FINDING_HASH=$(echo "$FINDING_BODY" | sed 's/[0-9]\{4\}-[0-9]\{2\}-[0-9]\{2\}T[^ ]*//g' | tr '[:upper:]' '[:lower:]' | grep -v '^[[:space:]]*$' | sort -u | sha256sum | cut -c1-12)
+  [ -z "$FINDING_HASH" ] && FINDING_HASH=$(echo -n "" | sha256sum | cut -c1-12)
+
+  # --- Step E: append history to LOOP.md ---
+  # Append line in ## History of LOOP.md:
+  #   - iter {N}: {VERDICT}, hash={HASH}, commit={SHA}, ts={ISO}
+
+  COMMIT_SHA=$(git rev-parse --short HEAD)
+  cat >> "$LOOP_FILE" <<EOF
+- iter $iter: $VERDICT, hash=$FINDING_HASH, commit=$COMMIT_SHA, ts=$(date -Iseconds)
+EOF
+
+  # Update frontmatter (iter, status)
+  # ... sed/awk substitute "iter:" line in frontmatter
+
+  # --- Step F: convergence check ---
+  if [ "$VERDICT" = "APPROVED" ] || [ "$VERDICT" = "APPROVED_WITH_WARNINGS" ]; then
+    # converged
+    Update LOOP.md frontmatter -> status: converged
+    Update STATE.md -> phase_status: verified, phase_verdict: $VERDICT, next_step: /jdi-ship {N}
+    git add .jdi/phases/{NN-slug}/LOOP.md .jdi/STATE.md
+    git commit -m "chore({phase-slug}): loop converged at iter $iter ($VERDICT)"
+    echo "Phase {N} converged at iter $iter. Verdict: $VERDICT"
+    echo "Next: /jdi-ship {N}"
+    exit 0
+  fi
+
+  # --- Step G: oscillation detection (early-escalate) ---
+  # Compare FINDING_HASH with previous iter's hash
+  # Guard: need >=2 iter lines in LOOP.md history to compare
+  ITER_COUNT=$(grep -cE '^- iter [0-9]+:' "$LOOP_FILE")
+  if [ "$ITER_COUNT" -ge 2 ]; then
+    PREV_HASH=$(grep -E '^- iter [0-9]+:' "$LOOP_FILE" | tail -2 | head -1 | grep -oE 'hash=[a-f0-9]+' | cut -d= -f2)
+  else
+    PREV_HASH=""
+  fi
+
+  if [ -n "$PREV_HASH" ] && [ "$FINDING_HASH" = "$PREV_HASH" ]; then
+    AskUserQuestion(
+      question="Oscillation detected on phase {N}. Iter $iter and $((iter-1)) have SAME finding hash ($FINDING_HASH). Loop not progressing. What now?",
+      options=[
+        "Continue (reset counter, 5 more iter)" => continue_with_reset,
+        "Abort loop (status=escalated, stays in REVIEW.md)" => abort,
+        "Adjust plan (status=paused, you edit PLAN.md/CONTEXT.md, re-run /jdi-loop {N})" => pause
+      ]
+    )
+
+    case answer:
+      continue_with_reset: goto reset_logic
+      abort: goto abort_logic
+      pause: goto pause_logic
+  fi
+
+  # --- Step H: cap check ---
+  if [ "$iter" -ge "${MAX_ITER:-5}" ]; then
+    AskUserQuestion(
+      question="Phase {N}: $iter iter without APPROVED. Cost grows. What now?",
+      options=[
+        "Continue (reset counter, ${MAX_ITER:-5} more iter)" => continue_with_reset,
+        "Abort (status=escalated)" => abort,
+        "Adjust plan (status=paused)" => pause
+      ]
+    )
+
+    case answer:
+      continue_with_reset: goto reset_logic
+      abort: goto abort_logic
+      pause: goto pause_logic
+  fi
+
+  # otherwise, next iter
+  continue
+```
+
+### Step 4: Reset logic
+
+```
+reset_logic:
+  total_resets++
+
+  if [ "$total_resets" -ge "${MAX_RESETS:-3}" ]; then
+    # Absolute kill switch
+    Update LOOP.md -> status: killed
+    Update STATE.md -> phase_status: blocked, phase_verdict: BLOCKED, next_step: human review of PLAN.md/CONTEXT.md (loop killed)
+    git add .jdi/phases/{NN-slug}/LOOP.md .jdi/STATE.md
+    git commit -m "chore({phase-slug}): loop killed (3 resets, $((iter * total_resets)) iter total)"
+    echo "Hard cap reached (${MAX_RESETS:-3} resets). Loop killed."
+    echo "Action: manually review PLAN.md or CONTEXT.md. Maybe fragment phase."
+    exit 1
+  fi
+
+  # Reset counter, history append-only
+  iter=0
+  Update LOOP.md frontmatter -> iter: 0, total_resets: $total_resets
+  Append in LOOP.md history: "--- RESET $total_resets at $(date -Iseconds) ---"
+  echo "Reset $total_resets/${MAX_RESETS:-3}. New round of ${MAX_ITER:-5} iter."
+  goto loop
+```
+
+### Step 5: Abort logic
+
+```
+abort_logic:
+  Update LOOP.md -> status: escalated
+  Update STATE.md -> phase_status: blocked, phase_verdict: BLOCKED, next_step: review REVIEW.md, fix manually or /jdi-loop {N} to resume
+  git add .jdi/phases/{NN-slug}/LOOP.md .jdi/STATE.md
+  git commit -m "chore({phase-slug}): loop aborted at iter $iter (user escalated)"
+  echo "Loop aborted. REVIEW.md has latest findings."
+  echo "Re-run /jdi-loop {N} to resume (status returns to running automatically)."
+  exit 0
+```
+
+### Step 6: Pause logic
+
+```
+pause_logic:
+  Update LOOP.md -> status: paused
+  Update STATE.md -> phase_status: paused, next_step: edit PLAN.md/CONTEXT.md and re-run /jdi-loop {N}
+  echo "Loop paused. Edit PLAN.md or CONTEXT.md."
+  echo "When ready: /jdi-loop {N}. Will resume with status=running, iter=0, same total_resets."
+  exit 0
+```
+
+### Step 7: Final confirmation (convergence)
+
+```
+Phase {N}: converged at $iter iter (resets: $total_resets). Verdict: $VERDICT.
+LOOP.md + REVIEW.md in .jdi/phases/{NN-slug}/
+Next: /jdi-ship {N}
+```
+
+</process>
+
+<gates>
+- pre: PLAN.md + doer + reviewer registered in specialists.md/reviewers.md
+- post: final status in LOOP.md ∈ {converged, escalated, paused, killed} + STATE updated
+- invariant: each iter = doer commit + reviewer commit (granular audit trail)
+</gates>
+
+<errors>
+- Doer/reviewer missing -> /jdi-bootstrap
+- PLAN missing -> /jdi-plan
+- LOOP.md corrupted (invalid frontmatter) -> backup to LOOP.md.bak, recreate from scratch
+- REVIEW.md not created by reviewer -> exit 1 with error
+- No changes in working dir after doer iter (doer did nothing) -> warn, but continue (reviewer may still find uncorrected previous issues)
+</errors>
+
+<runtime_notes>
+
+**Claude Code:**
+- Native AskUserQuestion for human gate
+- Sequential Agent dispatch inside the loop (does not parallelize doer+reviewer — sequential by design)
+
+**Copilot:**
+- No native AskUserQuestion — use question in main chat and wait for answer before proceeding
+- Loop control inline in command body (orchestrator = Copilot's main thread)
+
+**OpenCode:**
+- subtask: true for subagent dispatch
+- Human gate question via main prompt
+
+**Antigravity:**
+- Skill discovered by trigger ("ralph loop phase 2", "auto review phase 2")
+- AskUserQuestion via skill prose (ask + wait for text answer)
+- Loop control inline in skill body
+</runtime_notes>
+
+<rules>
+- NEVER skip human gate when iter >= max_iter or oscillation detected — controlled cost is invariant
+- NEVER reset total_resets — only iter
+- LOOP.md history is APPEND-ONLY (audit trail, never erase)
+- Reviewer remains read-only always — doer is the only writer
+- Each iter produces atomic commits (granularity preserved)
+- Absolute hard cap = max_iter * max_resets (default 15) — non-negotiable kill switch
+</rules>
+
+<references>
+- Ralph Wiggum technique (ghuntley.com/ralph)
+- ASDLC Ralph Loop pattern (asdlc.io/patterns/ralph-loop)
+- Convergence: P(C) = 1 - (1 - p_success)^n
+</references>

package/runtimes/claude/commands/jdi-new.md

@@ -0,0 +1,131 @@
+---
+name: jdi-new
+description: Entry point for new project. Runs research + asker, generates PROJECT.md + ROADMAP.md.
+argument_hint: "<short project description>"
+runtime_intent:
+  invokes_agent: jdi-researcher
+runtime_overrides:
+  claude:
+    allowed-tools: [Read, Write, Bash, Grep, Glob, AskUserQuestion, WebSearch, WebFetch, Agent]
+  copilot:
+    tools: [read, write, grep, glob, terminal]
+  opencode:
+    agent: jdi-researcher
+    subtask: true
+    model: anthropic/claude-sonnet-4-20250514
+  antigravity:
+    triggers:
+      - "/jdi-new"
+      - "create project"
+      - "new app"
+---
+
+<objective>
+Initializes new JDI project. Runs research + key questions + generates PROJECT.md, ROADMAP.md, STATE.md, DECISIONS.md.
+</objective>
+
+<arguments>
+- `description` (optional but recommended): short text of what to build.
+
+Examples:
+- `/jdi-new "TODO app .NET 10 + React 19"`
+- `/jdi-new "Inventory REST API in Python + FastAPI"`
+- `/jdi-new "Go CLI tool for log parsing"`
+- `/jdi-new` (asker starts from scratch)
+</arguments>
+
+<process>
+
+### Step 1: Validation
+```bash
+test -d .jdi/ && {
+  echo ".jdi/ already exists. Use /jdi-new --reset to start over (CAUTION: wipes state)."
+  exit 1
+}
+
+# Suggest /jdi-adopt if directory is NOT empty (likely brownfield)
+file_count=$(find . -maxdepth 3 -type f \
+  -not -path './.git/*' -not -path './node_modules/*' \
+  -not -path './.venv/*' -not -path './venv/*' \
+  -not -path './target/*' -not -path './dist/*' -not -path './build/*' \
+  -not -path './bin/*' -not -path './obj/*' \
+  2>/dev/null | wc -l)
+
+if [ "$file_count" -ge 3 ]; then
+  # Ask before continuing — could be greenfield in monorepo
+  echo "Directory has $file_count code files. Looks like existing project."
+  echo "For brownfield projects, /jdi-adopt detects stack/code-design automatically."
+  echo "Continue with /jdi-new anyway? (recommended: /jdi-adopt)"
+  # AskUserQuestion: [Continue /jdi-new] / [Switch to /jdi-adopt] / [Cancel]
+fi
+```
+
+PowerShell:
+```powershell
+if (Test-Path .jdi) { Write-Error ".jdi/ already exists. Use /jdi-new --reset."; exit 1 }
+$files = Get-ChildItem -Recurse -File -Depth 3 -ErrorAction SilentlyContinue |
+  Where-Object { $_.FullName -notmatch '\\(\.git|node_modules|\.venv|venv|target|dist|build|bin|obj)\\' }
+if ($files.Count -ge 3) {
+  Write-Host "Directory has $($files.Count) files. Consider /jdi-adopt instead of /jdi-new."
+  # Sequential AskUserQuestion
+}
+```
+
+If `--reset` passed, AskUserQuestion confirms + wipes `.jdi/`.
+
+### Step 2: Spawn researcher
+Invoke `jdi-researcher` passing description. Wait.
+
+### Step 3: Verify outputs
+```bash
+test -f .jdi/PROJECT.md || { echo "PROJECT.md not created"; exit 1; }
+test -f .jdi/ROADMAP.md || { echo "ROADMAP.md not created"; exit 1; }
+test -f .jdi/STATE.md || { echo "STATE.md not created"; exit 1; }
+```
+
+### Step 4: Create config.json (token/context budget)
+
+If `.jdi/config.json` does not yet exist, write the default below. Defaults (200k context, 60/70% warn/critical, coverage 80%) cover 95% of cases. User edits if running a 1M-window model or wanting tighter thresholds.
+
+```json
+{
+  "$schema_version": "1.1",
+  "context_window": 200000,
+  "thresholds": {
+    "warn_pct": 60,
+    "critical_pct": 70
+  },
+  "budgets": {
+    "max_context_chars": 6000,
+    "max_plan_chars": 12000,
+    "max_summary_chars": 8192
+  },
+  "compaction": {
+    "keep_phases": 2,
+    "archive_after": 5
+  },
+  "coverage_min": 80
+}
+```
+
+Canonical reference for the default also lives in `templates-jdi-folder/config.json` (shipped by npm package) — for users wanting to regenerate manually.
+
+### Step 5: Confirm
+
+```
+{project_name} initialized. {N} phases planned in .jdi/.
+Next: /jdi-bootstrap
+```
+
+</process>
+
+<gates>
+- pre: directory without existing `.jdi/` (or `--reset`)
+- post: PROJECT.md + ROADMAP.md + STATE.md + DECISIONS.md + config.json created, initial commit made
+</gates>
+
+<errors>
+- `.jdi/` already exists -> suggest `--reset` or use current project
+- Researcher cancelled -> exit clean
+- Researcher failed -> show error, no commit
+</errors>