jdi-cli 0.1.0

package/core/commands/jdi-plan.md

@@ -0,0 +1,73 @@
+---
+name: jdi-plan
+description: Generates phase PLAN.md. Decomposes into tasks with files_modified, acceptance, parallelism waves.
+argument_hint: "<phase_number> [--review]"
+runtime_intent:
+  invokes_agent: jdi-planner
+runtime_overrides:
+  claude:
+    allowed-tools: [Read, Write, Bash, Grep, Glob, AskUserQuestion, Agent]
+  copilot:
+    tools: [read, write, grep, glob]
+  opencode:
+    agent: jdi-planner
+    subtask: true
+    model: anthropic/claude-sonnet-4-20250514
+  antigravity:
+    triggers:
+      - "/jdi-plan"
+      - "plan phase {N}"
+---
+
+<objective>
+Generates PLAN.md for the given phase. Decomposes into tasks (max 8), groups into parallelism waves, maps files_modified and acceptance.
+</objective>
+
+<arguments>
+- `phase_number` (required): phase number, e.g. `1`, `2`
+- `--review` (optional): show preview and ask for approval before saving
+</arguments>
+
+<process>
+
+### Step 1: Validation
+```bash
+test -d .jdi/ || { echo "Not a JDI project. Run /jdi-new."; exit 1; }
+test -f .jdi/PROJECT.md || { echo "PROJECT.md missing."; exit 1; }
+```
+
+Verify phase CONTEXT.md exists:
+```bash
+ls .jdi/phases/{NN}*/CONTEXT.md 2>/dev/null || { echo "CONTEXT.md missing. Run /jdi-discuss {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}*/CONTEXT.md || true
+fi
+# Windows: pwsh -File "$JDI_LIB/jdi-monitor.ps1" -Paths @(...)
+```
+
+### Step 2: Spawn planner
+Invoke `jdi-planner` with phase_number. Wait.
+
+### Step 3: Verify
+```bash
+test -f .jdi/phases/{NN}*/PLAN.md || { echo "PLAN.md not created"; exit 1; }
+```
+
+### Step 4: Confirm
+Show plan summary + suggest `/jdi-do {N}`.
+
+</process>
+
+<gates>
+- pre: `.jdi/PROJECT.md` + `.jdi/phases/{NN-slug}/CONTEXT.md` exist
+- post: PLAN.md created + STATE.md updated + commit
+</gates>
+
+<errors>
+- CONTEXT.md missing -> suggest `/jdi-discuss {N}`
+- Phase does not exist in ROADMAP -> error
+- Planner cancelled -> exit clean
+</errors>

package/core/commands/jdi-ship.md

@@ -0,0 +1,146 @@
+---
+name: jdi-ship
+description: Finalizes phase after verify. Updates ROADMAP.md, marks phase as done, advances pointer to next.
+argument_hint: "<phase_number>"
+runtime_intent:
+  invokes_agent: none
+runtime_overrides:
+  claude:
+    allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion]
+  copilot:
+    tools: [read, write, edit, grep, glob, terminal]
+  opencode:
+    subtask: true
+  antigravity:
+    triggers:
+      - "/jdi-ship"
+      - "finalize phase {N}"
+---
+
+<objective>
+Finalizes phase after /jdi-verify approves. Updates ROADMAP.md (phase: done), advances STATE to next phase, final commit.
+</objective>
+
+<arguments>
+- `phase_number` (required)
+</arguments>
+
+<process>
+
+### Step 1: Validation
+```bash
+test -d .jdi/ || { echo "Not a JDI project."; exit 1; }
+
+# Verify REVIEW.md exists
+ls .jdi/phases/{NN}*/REVIEW.md 2>/dev/null || {
+  echo "REVIEW.md missing. /jdi-verify {N}."
+  exit 1
+}
+
+# Read verdict
+VERDICT=$(grep -oE 'Verdict:\*\* (APPROVED|APPROVED_WITH_WARNINGS|BLOCKED)' .jdi/phases/{NN}*/REVIEW.md | awk '{print $2}')
+
+if [ "$VERDICT" = "BLOCKED" ]; then
+  echo "Phase {N} BLOCKED. Fix before ship."
+  exit 1
+fi
+```
+
+### Step 2: Confirm with user (only if WITH_WARNINGS)
+
+If `VERDICT=APPROVED_WITH_WARNINGS`:
+```
+Phase {N} has uncorrected warnings. Ship anyway?
+- Yes, ship (warnings remain in REVIEW.md)
+- No, fix first
+```
+
+If "No" -> exit clean.
+
+### Step 3: Update ROADMAP.md
+
+Edit `.jdi/ROADMAP.md`:
+- Phase {N}: `status: done`
+- Phase {N+1}: `status: ready` (if exists)
+
+If no phase {N+1}:
+```
+All phases complete.
+Project delivered.
+```
+
+### Step 4: Update STATE.md
+
+```markdown
+current_phase: {N+1 or done}
+phase_status: ready (if {N+1} exists) or complete
+next_step: /jdi-discuss {N+1} or done
+```
+
+### Step 5: Archive old phases (compaction)
+
+Read `archive_after` from `.jdi/config.json` (default 5). If current phase advances to `N+1`, and a phase exists with number `<= (N+1) - archive_after`, move to `.jdi/archive/`.
+
+```bash
+ARCHIVE_AFTER=5
+if [ -f .jdi/config.json ]; then
+  if command -v jq >/dev/null 2>&1; then
+    ARCHIVE_AFTER=$(jq -r '.compaction.archive_after // 5' .jdi/config.json)
+  fi
+fi
+
+NEXT=$((N + 1))
+THRESHOLD=$((NEXT - ARCHIVE_AFTER))
+
+if [ "$THRESHOLD" -ge 1 ]; then
+  mkdir -p .jdi/archive
+  test -f .jdi/archive/index.md || echo "# Archive index" > .jdi/archive/index.md
+
+  for dir in .jdi/phases/*/; do
+    NN=$(basename "$dir" | grep -oE '^[0-9]+' || true)
+    [ -z "$NN" ] && continue
+    NN_NUM=$((10#$NN))  # force decimal
+    if [ "$NN_NUM" -le "$THRESHOLD" ]; then
+      VERDICT_OLD=$(grep -oE 'Verdict:\*\* (APPROVED|APPROVED_WITH_WARNINGS|BLOCKED)' "$dir/REVIEW.md" 2>/dev/null | awk '{print $2}' || echo "UNKNOWN")
+      mv "$dir" .jdi/archive/
+      echo "- $(basename "$dir"): ${VERDICT_OLD} (archived $(date -u +%F))" >> .jdi/archive/index.md
+    fi
+  done
+fi
+# Windows: equivalent in PowerShell — Move-Item + Add-Content
+```
+
+Archived phases remain accessible via `.jdi/archive/` but exit the default read-path. Read-depth rule (`ARCHITECTURE.md > Read-depth scaling`) treats archive as `<= current - 2`.
+
+### Step 6: Final commit
+
+```bash
+git add .jdi/ROADMAP.md .jdi/STATE.md .jdi/archive/ 2>/dev/null
+git commit -m "feat({NN-slug}): ship phase {N} ({VERDICT})"
+```
+
+Optional tag (if PROJECT.md has `tag_phases: true`):
+```bash
+git tag "phase-{N}-{slug}"
+```
+
+### Step 7: Confirm
+
+```
+Phase {N} shipped.
+{if more phases:} Next: /jdi-discuss {N+1}
+{if last:} Project delivered. Tag: phase-{N}-{slug}
+```
+
+</process>
+
+<gates>
+- pre: REVIEW.md exists + verdict != BLOCKED
+- post: ROADMAP.md + STATE.md updated + old phases archived (if applicable) + commit (+ optional tag)
+</gates>
+
+<errors>
+- REVIEW missing -> /jdi-verify
+- Verdict BLOCKED -> abort
+- Already shipped -> abort with warning
+</errors>

package/core/commands/jdi-verify.md

@@ -0,0 +1,159 @@
+---
+name: jdi-verify
+description: Runs phase quality gates via reviewer specialist. Build, tests, coverage, lint, security checks. Verdict APPROVED / APPROVED_WITH_WARNINGS / BLOCKED.
+argument_hint: "<phase_number>"
+runtime_intent:
+  invokes_agent: dynamic
+runtime_overrides:
+  claude:
+    allowed-tools: [Read, Bash, Grep, Glob, Agent]
+  copilot:
+    tools: [read, grep, glob, terminal]
+  opencode:
+    subtask: true
+    model: anthropic/claude-sonnet-4-20250514
+  antigravity:
+    triggers:
+      - "/jdi-verify"
+      - "verify phase {N}"
+---
+
+<objective>
+Verifies the phase was delivered correctly. Runs gates defined in the project's reviewer specialist. Verdict blocks or releases the ship.
+</objective>
+
+<arguments>
+- `phase_number` (required)
+</arguments>
+
+<process>
+
+### Step 1: Validation
+```bash
+test -d .jdi/ || { echo "Not a JDI project."; exit 1; }
+
+# Verify reviewer exists
+ls .jdi/agents/jdi-reviewer-*.md 2>/dev/null | head -1 || {
+  echo "Reviewer missing. /jdi-bootstrap."
+  exit 1
+}
+
+# Verify phase was executed
+ls .jdi/phases/{NN}*/SUMMARY.md 2>/dev/null || {
+  echo "Phase {N} not executed. /jdi-do {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}*/SUMMARY.md || true
+fi
+# Windows: pwsh -File "$JDI_LIB/jdi-monitor.ps1" -Paths @(...)
+```
+
+### Step 2: Resolve reviewer specialist(s)
+
+```bash
+REVIEWERS=$(grep -oE 'jdi-reviewer-[a-z0-9-]+' .jdi/reviewers.md | sort -u)
+REVIEWER_COUNT=$(echo "$REVIEWERS" | wc -l)
+echo "Reviewers registered: $REVIEWER_COUNT"
+```
+
+**Single-stack** (`REVIEWER_COUNT == 1`): one reviewer, normal flow.
+**Multi-stack** (`REVIEWER_COUNT > 1`): chain reviewers in registry order. Each writes its own REVIEW segment; aggregate verdict = worst-case (1 BLOCK = overall BLOCK).
+
+### Step 3: Spawn reviewer(s)
+
+**Single-stack:**
+```
+Agent(
+  subagent_type="${REVIEWERS}",
+  description="Verify phase {N}",
+  prompt="phase={N}, mode=verify"
+)
+```
+
+**Multi-stack:** spawn each reviewer in sequence (NOT parallel — build/test commands may conflict on ports, locks, output dirs):
+
+```
+for REVIEWER in $REVIEWERS:
+  Agent(
+    subagent_type="$REVIEWER",
+    description="Verify phase {N} ({REVIEWER})",
+    prompt="phase={N}, mode=verify, reviewer_segment=${REVIEWER}"
+  )
+  # Each reviewer appends to .jdi/phases/{NN-slug}/REVIEW.md under section
+  # "## Reviewer: {REVIEWER}" with its own gate results and verdict
+```
+
+Each reviewer scopes its gates to its `file_glob` (from frontmatter `scope.file_glob`). Coverage threshold enforced only on files matching the glob.
+
+Reviewers are read-only. Wait for completion before next.
+
+### Step 4: Read aggregate verdict
+
+```bash
+test -f .jdi/phases/{NN}*/REVIEW.md || { echo "REVIEW.md not created"; exit 1; }
+
+# Collect all per-reviewer verdicts
+VERDICTS=$(grep -oE 'Verdict:\*\* (APPROVED|APPROVED_WITH_WARNINGS|BLOCKED)' .jdi/phases/{NN}*/REVIEW.md | awk '{print $2}')
+
+# Worst-case wins: BLOCK > WARNINGS > APPROVED
+if echo "$VERDICTS" | grep -q BLOCKED; then
+  VERDICT=BLOCKED
+elif echo "$VERDICTS" | grep -q APPROVED_WITH_WARNINGS; then
+  VERDICT=APPROVED_WITH_WARNINGS
+else
+  VERDICT=APPROVED
+fi
+
+# For single-stack, this collapses to the single reviewer's verdict — backward compatible.
+```
+
+### Step 5: Update STATE
+
+```markdown
+current_phase: {N}
+phase_status: {verified|blocked}
+phase_verdict: {APPROVED|APPROVED_WITH_WARNINGS|BLOCKED}
+next_step: {if APPROVED or WITH_WARNINGS: /jdi-ship {N}; if BLOCKED: fix and /jdi-do {N} again}
+```
+
+```bash
+git add .jdi/phases/{NN-slug}/REVIEW.md .jdi/STATE.md
+git commit -m "docs({NN-slug}): verify phase ({VERDICT})"
+```
+
+### Step 6: Confirm
+
+**APPROVED:**
+```
+Phase {N}: APPROVED. Next: /jdi-ship {N}
+```
+
+**APPROVED_WITH_WARNINGS:**
+```
+Phase {N}: APPROVED_WITH_WARNINGS ({count} warnings).
+REVIEW.md: .jdi/phases/{NN-slug}/REVIEW.md
+Next: /jdi-ship {N} (or fix first)
+```
+
+**BLOCKED:**
+```
+Phase {N}: BLOCKED ({count} blockers). REVIEW.md: .jdi/phases/{NN-slug}/REVIEW.md
+Fix → /jdi-do {N} → /jdi-verify {N}
+```
+
+</process>
+
+<gates>
+- pre: SUMMARY.md exists + reviewer registered in .jdi/reviewers.md
+- post: REVIEW.md created + STATE updated
+</gates>
+
+<errors>
+- Reviewer missing -> /jdi-bootstrap
+- SUMMARY missing -> /jdi-do
+- Reviewer fails -> show error, keep state, suggest retry
+</errors>

package/core/skills/clean-code/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: clean-code
+description: Clean Code. Human-readable code, optimized for reading (read 10x more than written). Names reveal intent, small functions, no redundant comments, explicit error handling, no magic numbers. Applies in any language.
+type: skill
+applies_to: |
+  Loaded by doer when writing code (any code change).
+  Loaded by reviewer at gate 5 to detect code smells.
+loaded_by:
+  - jdi-doer-{slug}
+  - jdi-reviewer-{slug}
+runtime_overrides:
+  antigravity:
+    triggers:
+      - "Clean Code"
+      - "clean code"
+      - "code smells"
+      - "code readability"
+---
+
+# Skill: Clean Code
+
+> Code is read 10x more than written. Optimize for reading.
+
+Not about pretty style. About **making reader understand in 1 pass**, without mentally simulating execution.
+
+## Rules
+
+### 1. Names reveal intent
+
+- **Variable**: what it **is**, not how it's stored (`elapsedSeconds` > `t` > `time`)
+- **Function**: what it **does**, verb + object (`calculateTax(order)`, not `tax(order)`)
+- **Boolean**: yes/no question (`isActive`, `hasPermission`, `canSubmit`)
+- **Class/module**: noun (`OrderRepository`, `EmailValidator`)
+- **Interface**: role/capability (`Repository`, `Cacheable`) — no `I`/`Abstract` prefix if language doesn't require
+
+### Anti-names
+
+| Wrong | Right |
+|---|---|
+| `data`, `info`, `value`, `temp`, `result` | something descriptive of the context |
+| `processData()` | `parseUserPayload()`, `applyDiscount()`, etc |
+| `Manager`, `Helper`, `Util` | name of the real responsibility |
+| `flag`, `status` | `isComplete`, `paymentStatus` |
+| `obj`, `item`, `thing` | actual type |
+| Abbreviations: `usr`, `ctx`, `mgr`, `cfg` | `user`, `context` (exception: well-established domain convention) |
+| Variables with `_2`, `_new`, `_old` | refactor until 1 remains |
+
+### 2. Small functions
+
+- **Size**: ideally < 20 lines. If over 50, almost certainly doing too much.
+- **1 abstraction level**: inside function, all operations at same level. Mixing "open connection" + "calculate tax" = no.
+- **3-4 params max**: more than that signals either missing object or too much responsibility.
+- **1 logical exit**: early return is OK; multiple returns mid-complex-logic is bad.
+
+### 3. Functions do **one** thing
+
+If you describe function as "does X **and** Y", split into two. Function name must be precise.
+
+Exception: orchestrators (controllers, command handlers) coordinate — OK to describe as "validates, saves, notifies" if each step is a call to another function.
+
+### 4. Comments
+
+**Default: DON'T write**.
+
+Well-named code doesn't need to explain **what** it does. If you feel like writing a comment, first attempt: rename function/variable.
+
+### Comments OK when:
+
+- **Why** non-obvious: workaround for specific bug, surprising design decision, external constraint
+- **Critical invariant**: "this array MUST be sorted for binary search to work"
+- **TODO/FIXME marker** with ticket link: `// TODO(#1234): handle UTF-16 surrogate`
+- **Pitfall warning**: "// don't call this in a loop, O(n^2)"
+- **Public API doc**: contract for caller (params, returns, exceptions)
+
+### Comments bad when:
+
+- Explain **what** (code already says)
+- Repeat the function name in English
+- Comment goes stale relative to code
+- "// removed on XX/YY" left in the tree
+- "// hack" without explanation
+- "// not sure why this works" — investigate, don't guess
+
+### 5. Explicit error handling
+
+- **Never silence exception**: `try { ... } catch {}` is **latent bug**
+- **Explicit handling**: structured log + rethrow OR return Result/Either
+- **Errors are part of the contract**: document what can fail
+- **Boundary**: handle error at the boundary (controller, top-level handler), not at every internal call
+- **Validation**: at the entry (boundary), not scattered
+
+### 6. No magic numbers/strings
+
+- Number or string with meaning becomes a **named constant**
+- `if (status === 3)` becomes `if (status === OrderStatus.Shipped)`
+- `setTimeout(fn, 86400000)` becomes `setTimeout(fn, MS_PER_DAY)`
+- Exception: 0, 1, -1, universally clear cases
+
+### 7. Command-Query Separation (CQS)
+
+- **Query**: returns info, does **not** mutate state
+- **Command**: mutates state, does **not** return (or returns void/minimal ack)
+
+`function getUser(id)` that **also** updates last_access violates CQS — caller doesn't expect side-effect. Split.
+
+### 8. Boy Scout Rule
+
+> Leave the campground cleaner than you found it.
+
+Touched a file? Small cleanness improvement is OK in the same commit:
+- Rename obscure variable
+- Split giant function you already had to read
+- Remove stale comment
+- Delete dead code
+
+No heavy unrelated refactor — atomic commit still rules.
+
+### 9. Formatting
+
+- **Auto-format**: linter/formatter on the project (prettier, dotnet format, ruff format, gofmt) — no human decisions
+- **Member order**: consistent convention (publics before privates, or group by feature)
+- **Blank line**: separates logical blocks. Function all glued together is hard to scan.
+- **Consistent indentation**: respect project convention
+
+### 10. Symmetry and consistency
+
+- Functions at same "level" have similar signature
+- `getUserById, getUserByEmail` — consistent param order
+- Exceptions "as is" vs "throws" vs Result — pick **one** style in the project
+- `null` vs `undefined` vs `Option` — pick **one**
+- Consistent naming convention (camelCase, PascalCase, snake_case) following the language
+
+## Classic code smells
+
+| Smell | Symptom |
+|---|---|
+| **Long function** | > 50 lines |
+| **Long parameter list** | > 4 params |
+| **God class** | 1 class does everything |
+| **Feature envy** | method uses more data from **another** class than its own |
+| **Data clump** | same 3-4 params bundled in multiple places -> object |
+| **Primitive obsession** | everything is string/int, no value objects |
+| **Scattered switch statements** | OCP violated |
+| **Shotgun surgery** | simple change touches N files |
+| **Divergent change** | 1 class changes for 5 different reasons (SRP) |
+| **Dead code** | function/parameter/var never used |
+| **Speculative generality** | flexibility without caller (YAGNI) |
+| **Comments compensating bad code** | refactor code, delete comment |
+| **Magic numbers** | 86400, 1024 with no name |
+| **Silenced exceptions** | `catch {}`, `catch (Exception _) { }` |
+| **Long if/else chains** | use polymorphism/strategy |
+| **Inconsistent naming** | `getUser` here, `fetchAccount` there, `loadOrder` over there |
+| **Boolean parameter** | `fn(true)` at caller — nobody knows what `true` means |
+
+## Procedure
+
+### Doer
+
+After writing:
+1. **Name review**: does each variable/function have a name that stands without a comment? Rename if not.
+2. **Size**: any function > 30 lines? Split.
+3. **Magic**: any number/string without obvious meaning? Constant.
+4. **Redundant comments**: any comment that just repeats the code? Delete.
+5. **Error handling**: any silent `catch {}`? Log or rethrow.
+
+### Reviewer (gate 5)
+
+```bash
+# Long functions
+awk '/^(function|def|public |private |protected |async )/ { start=NR; name=$0 }
+     /^}$|^\s{0,2}}\s*$/ { if (NR-start > 50) print FILENAME":"start": function with "(NR-start)" lines: "name }' src/**/*.{ts,cs,py,go,java}
+
+# Magic numbers (typical suspects)
+grep -RnE '\b(86400|3600|1024|65535|1000000)\b' src/
+
+# Silent catch
+grep -RnE 'catch\s*(\([^)]*\))?\s*\{\s*\}' src/
+grep -RnE 'except.*:\s*pass\s*$' src/
+grep -RnE 'catch.*:.*ignore' src/
+
+# TODO without ticket
+grep -RnE 'TODO(?!.*#\d+)|FIXME(?!.*#\d+)' src/
+
+# Suspect boolean params
+grep -RnE 'function \w+\([^)]*: bool|: boolean' src/
+
+# Generic name
+grep -RnE '\b(data|info|value|temp|tmp|result|obj|item|thing)\b\s*[:=]' src/ | head -20
+
+# Dead code (linter catches — confirm)
+
+# Obvious comments
+grep -RnE '^\s*//\s*(get|set|return|increment|decrement|loop|iterate)\b' src/
+```
+
+Relevant match -> WARN or BLOCK depending on severity.
+
+## Inputs
+
+- Diff/content of the file
+- Project convention (linter config, naming convention from PROJECT.md)
+
+## Outputs
+
+Does NOT produce a file. Modifies judgement.
+
+## Examples
+
+### Example 1: bad names
+
+Wrong:
+```python
+def calc(d, t):
+    r = d * t * 0.18
+    return r
+```
+
+Right:
+```python
+VAT_RATE = 0.18
+
+def calculate_vat(amount: Decimal, qty: int) -> Decimal:
+    return amount * qty * VAT_RATE
+```
+
+### Example 2: giant function
+
+Wrong: 1 function of 120 lines validating, saving, sending email, logging.
+
+Right: 4 functions of 20 lines each + 1 orchestrator of 15 lines that coordinates.
+
+### Example 3: silenced exception
+
+Wrong:
+```typescript
+try {
+  await sendNotification(user)
+} catch {}
+```
+
+Latent bug — notification failure disappears.
+
+Right:
+```typescript
+try {
+  await sendNotification(user)
+} catch (err) {
+  logger.error("notification failed", { userId: user.id, err })
+  // intentional: notification is best-effort, doesn't block flow
+}
+```
+
+Comment here justifies the "why" of the no-rethrow.
+
+### Example 4: boolean param
+
+Wrong: `createUser("alice", "alice@x.com", true, false)`
+
+Right: `createUser({ name: "alice", email: "alice@x.com", admin: true, sendWelcome: false })`
+
+Caller becomes self-documented.