@benzotti/jdi 0.1.46

package/framework/commands/implement-plan.md

@@ -0,0 +1,218 @@
+---
+name: implement-plan
+description: "JDI: Execute implementation plan"
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+argument-hint: "[--team | --single | --dry-run | --skip-qa]"
+context: |
+  !cat .jdi/config/state.yaml 2>/dev/null | head -30
+---
+
+# /jdi:implement-plan
+
+Execute an approved plan with complexity-based routing. Deterministic workflow — every invocation follows the same numbered steps, in order, without skipping.
+
+**This skill follows `<JDI:StrictnessProtocol />` and `<JDI:SilentDiscovery />`. Read those components before executing any step below.**
+
+---
+
+## Flags
+
+- `--team` — Force Agent Teams mode regardless of complexity signals
+- `--single` — Force single-agent mode regardless of complexity signals
+- `--dry-run` — Preview without writing: list files that would change and agents that would be spawned, then STOP
+- `--skip-qa` — Skip the post-task `jdi-qa-tester` verification pass
+
+> **Do NOT use the built-in `EnterWorktree` tool.** If `state.yaml` has `worktree.active: true`, just `cd` into `worktree.path`.
+
+---
+
+## Orchestration
+
+The steps below are numbered and ordered. Do NOT skip, merge, or reorder them. Each step ends with a clear state transition — if you cannot produce that transition, STOP and ask.
+
+### 1. Silent Discovery
+
+Execute `<JDI:SilentDiscovery />` now. Read the scaffolding files listed in that component and store the result internally as `DISCOVERED_STATE`. Do NOT print the discovery output to the user.
+
+**Additional reads for this skill:**
+- `.jdi/codebase/SUMMARY.md` if it exists
+- `.jdi/framework/learnings/general.md` (always)
+- Domain-specific learnings based on `DISCOVERED_STATE.tech_stack`: PHP → `backend.md`, TS/React → `frontend.md`, testing → `testing.md`, devops → `devops.md`
+
+Learnings override defaults. Record which learnings files were found in `DISCOVERED_STATE.learnings_loaded`.
+
+### 2. Load Plan
+
+Read the plan index file (path from `$ARGUMENTS` or from `DISCOVERED_STATE.current_plan.path`). Parse the frontmatter for:
+
+- `tasks:` or `task_files:` (legacy monolithic vs split plan)
+- `deps:` and `waves:`
+- `tech_stack:`
+- `available_agents:` catalogue
+- `primary_agent:` pin
+
+**Format detection:** if frontmatter contains `task_files:`, this is a split plan — read each task file's frontmatter in a single batch. If absent, this is a legacy monolithic plan — all tasks are inline in the index.
+
+**Plan status gate:** if the plan's status in `state.yaml` is not `approved`, STOP and tell the user: "Plan is in status `{status}` — run `/jdi:create-plan` (or the review loop) to reach `approved` before implementing."
+
+### 3. Resolve Per-Task Agents
+
+For every task file listed in `task_files:`, record the `agent:` field from its frontmatter. This is the `subagent_type` you will pass to the Task tool when spawning.
+
+**Resolution order:**
+1. Task-level `agent:` pin from the task file frontmatter
+2. Plan-level `primary_agent:` from the index frontmatter
+3. Tech-stack default: PHP → `jdi-backend`, TS/React → `jdi-frontend`, otherwise → `general-purpose`
+
+**NEVER default everything to `general-purpose` silently.** See `framework/components/meta/AgentRouter.md`.
+
+### 4. Agent Existence Check
+
+For each pinned agent, read the matching `source:` from the plan's `available_agents` catalogue and confirm the spec exists:
+
+- **`source: jdi`** — check `.jdi/framework/agents/{name}.md` (installed projects) or `framework/agents/{name}.md` (self-hosting JDI repo)
+- **`source: claude-code`** — check `.claude/agents/{name}.md` (project-local) or `~/.claude/agents/{name}.md` (user-global)
+
+If the spec is NOT found, downgrade to `general-purpose` (with a `jdi-backend` / `jdi-frontend` spec load in the prompt) and record an `agent_downgrade:` entry listing the original pin, the downgrade target, and the reason. This entry MUST appear in the final summary — never silently change a pin.
+
+### 5. Complexity Routing
+
+Apply `<JDI:ComplexityRouter />`:
+- **Simple** (≤3 tasks, single stack/wave) → single-agent mode
+- **Complex** (>3 tasks OR multi-stack OR multi-wave) → Agent Teams swarm
+
+**Override flags:** `--team` forces Agent Teams mode; `--single` forces single-agent mode. Overrides win over complexity signals.
+
+Record the routing decision and reasoning in `DISCOVERED_STATE.routing`.
+
+### 6. Dry Run Check
+
+If `--dry-run` is present, output:
+- The resolved agent per task
+- Any `agent_downgrade:` entries
+- The routing decision
+- The list of files each task claims to touch (from task spec)
+
+Then **STOP**. Do NOT spawn agents, do NOT advance state, do NOT edit files.
+
+### 7. Advance State to Executing
+
+Run `bun run src/index.ts state executing` (in installed projects: `npx jdi state executing`). Do NOT manually edit `state.yaml`.
+
+### 8. Spawn and Execute
+
+**Platform constraint:** JDI specialists (`source: jdi`) are NOT registered Claude Code subagents and MUST be spawned via `subagent_type="general-purpose"` with identity injected via prompt text (`"You are {agent}. Read .jdi/framework/agents/{agent}.md..."`). Registered Claude Code subagents (`source: claude-code`) are spawned directly by name. See `framework/jdi.md` Critical Constraints and `framework/components/meta/AgentRouter.md` §4.
+
+**Single-agent mode:**
+- `source: jdi` → `Task(subagent_type="general-purpose", prompt="You are {plan.primary_agent}. Read .jdi/framework/agents/{plan.primary_agent}.md... PLAN: {index-path}")`
+- `source: claude-code` → `Task(subagent_type="{plan.primary_agent}", prompt="<standard spawn prompt> PLAN: {index-path}")`
+
+For split plans, the agent reads task files one at a time via the `file:` field in `state.yaml`.
+
+**Agent Teams mode:** Spawn ONE Task call per task using the source-aware pattern above. Pass `TASK_FILE: {task-file-path}` so the agent loads only its assigned task.
+
+**Prompt scoping rules (non-negotiable):**
+- One task = one spawn. Never bundle multiple tasks into one prompt.
+- Give exact file paths. Cap exploration explicitly: "read only your TASK_FILE and the files it names."
+- Request short reports (<400 words). Agents can be truncated mid-task; scoped prompts survive the budget ceiling.
+- Include a `## Project Context` block in every spawn prompt: type, tech stack, quality gates, working directory. Saves 2-3 discovery tool calls per spawn.
+- For split plans, the agent reads the `TASK_FILE` itself — do not inline task content into the prompt.
+
+**Wave-based execution:** honour `waves:` from the plan frontmatter. Spawn all tasks in wave N in parallel; wait for all returns before starting wave N+1.
+
+### 9. Advance Task State
+
+After each task's programmer returns successfully, run:
+
+```bash
+bun run src/index.ts state advance-task {task-id}
+```
+
+Do NOT advance state for tasks that failed or were skipped. Do NOT batch advance calls — advance per task, in order.
+
+### 10. Post-Task Verify (jdi-qa-tester)
+
+After each task's programmer returns, invoke `jdi-qa-tester` in `post-task-verify` mode with the task's `done_when` criteria and `files_modified` list. If verification fails with **S1** or **S2** severity, **halt the plan** and escalate to the user. Otherwise record the verification result in the task summary and proceed to commit.
+
+- **a11y-check trigger:** if `files_modified` includes UI files (components, views, templates, CSS affecting render), additionally invoke `jdi-qa-tester` in `a11y-check` mode and record the result in the same task summary.
+- **contract-check trigger:** if `files_modified` includes contract-bearing files — API routes, Controllers/Actions, DTOs, FormRequests, OpenAPI specs, exported TypeScript types, `packages/*/src/index.ts`, DB migrations, generated client code — additionally invoke `jdi-qa-tester` in `contract-check` mode. Treat any contract failure as at least **S2** and halt the plan.
+- **Skip rules:** Skipped entirely if `--skip-qa` is passed. Also skipped automatically if `files_modified` contains ONLY `.md`, `.yaml`, or `.yml` files (documentation/config doesn't get regression-tested). The programmer's structured return field `qa_verification_needed: false` is also honoured.
+- **Contract-check exception to the skip rule:** if any file in `files_modified` is a contract-bearing YAML/JSON spec (OpenAPI / Swagger — e.g. `openapi.yaml`, `swagger.json`, `api/*.yaml`, `**/openapi*.{yml,yaml,json}`; GraphQL SDL — `**/*.graphql`, `**/schema.gql`; JSON Schema — `**/schemas/**/*.json`), still invoke `contract-check` even when the doc-only skip rule would otherwise apply. `post-task-verify` and `a11y-check` remain skipped in this case — only `contract-check` runs.
+
+### 11. Execute Deferred Ops
+
+Collect `files_to_create` returns from every agent and execute them via Write tool. Apply any pending commit operations. Do NOT skip this step — sandbox-returned artefacts are real work.
+
+### 12. Run Verification Gates
+
+Execute the project's quality gates in order: tests, lint, typecheck (exact commands come from `DISCOVERED_STATE.quality_gates`). Record pass/fail per gate.
+
+If any gate fails, STOP — do not advance state to `complete`. Report the failure and enter the review loop at step 14.
+
+### 13. Advance State to Complete
+
+Run `bun run src/index.ts state complete`. Do NOT manually edit `state.yaml`.
+
+### 14. Present Summary
+
+Present the implementation summary to the user:
+
+- Tasks completed (with per-task agent and verification result)
+- Files changed (grouped by task)
+- Quality gate results
+- Any `agent_downgrade:` events
+- Deviations from the spec
+
+End with the exact prompt: _"Provide feedback to adjust, or say **approved** to finalise."_
+
+**Wait for the user's answer. Do NOT suggest commits or PRs yet.**
+
+### 15. Review Loop
+
+- **Feedback:** apply the requested code changes, re-run verification gates, increment the revision counter, and re-present the summary.
+- **Approval:** suggest a conventional commit or PR generation as the next step. Do NOT auto-run either — the user decides.
+
+**Never loop back to step 8.** Feedback refines existing tasks; it does not re-spawn agents for tasks that already completed.
+
+---
+
+## Edge Cases
+
+Pre-written responses for known deviations. When one applies, follow the scripted response rather than improvising.
+
+| Situation | Response |
+|-----------|----------|
+| Plan status is not `approved` | STOP at step 2. Tell the user to approve the plan first. Do NOT force-advance. |
+| Pinned agent not installed | Downgrade to `general-purpose`, record the downgrade, continue. Surface in the final summary. |
+| Task file missing (listed in `task_files:` but not on disk) | STOP. Report the missing file. Do NOT advance state. |
+| Programmer returns with `status: blocked` | HALT the plan. Do NOT advance task state. Surface the blocker to the user and wait. |
+| QA verification S1 or S2 failure | HALT the plan immediately. Record the failure in state. Wait for user direction before continuing. |
+| Verification gate failure at step 12 | STOP before completing. Report the failure, enter review loop. Do NOT advance state to `complete`. |
+| `--dry-run` with no changes needed | Output "no-op: plan is already at target state" and STOP. |
+| Worktree active but path missing | Ask the user: recreate the worktree, or proceed in current directory? Do NOT silently proceed. |
+| Wave has zero tasks ready | Skip the empty wave, log it, continue to the next wave. |
+| User asks to skip verification during review | Remind them of `--skip-qa` flag semantics. Do NOT skip silently. |
+
+---
+
+## HARD STOP — Verification Gate
+
+Before presenting the summary (step 14), all three must be true:
+
+1. Every task has either `advance-task` applied OR a documented failure in the summary
+2. Every QA verification trigger that fired has a recorded result
+3. Every quality gate has passed OR been explicitly flagged as failing in the summary
+
+If ANY of these is not true, STOP. Do not present a summary that implies success when work remains. Silent gaps are the failure mode this gate exists to prevent.
+
+---
+
+## Collaborative Protocol
+
+<JDI:StrictnessProtocol />
+
+---
+
+**References:** Agent base (read FIRST for cache): `.jdi/framework/components/meta/AgentBase.md` | Agent specs: `.jdi/framework/agents/jdi-backend.md`, `.jdi/framework/agents/jdi-frontend.md` | Orchestration: `.jdi/framework/components/meta/AgentTeamsOrchestration.md` | Routing: `.jdi/framework/components/meta/ComplexityRouter.md`, `.jdi/framework/components/meta/AgentRouter.md`
+
+**Plan to execute:** $ARGUMENTS

package/framework/commands/init.md

@@ -0,0 +1,65 @@
+---
+name: init
+description: "JDI: Initialise JDI commands in the current project"
+---
+
+# /jdi:init
+
+Initialise the JDI slash commands in the current project.
+
+## Direct Execution
+
+### Step 1: Create Directories
+
+```bash
+mkdir -p .claude/commands/jdi
+mkdir -p .jdi/plans .jdi/research .jdi/codebase .jdi/reviews .jdi/config .jdi/persistence .jdi/feedback
+```
+
+### Step 2: Copy Command Stubs
+
+Copy all command stubs from the framework to the project. Skip files that already exist and are >500 bytes (unless `--force`).
+
+```bash
+for file in .jdi/framework/commands/*.md; do
+  dest=".claude/commands/jdi/$(basename "$file")"
+  if [ ! -f "$dest" ] || [ "$(wc -c < "$dest")" -le 500 ] || [ "$FORCE" = "true" ]; then
+    cp "$file" "$dest"
+  fi
+done
+```
+
+> **Do NOT embed command stub content inline.** The source of truth is `.jdi/framework/commands/`. Copy from there.
+
+### Step 3: Register Claude Code Hooks
+
+Ensure `PostToolUse` lint-fix hook is in `.claude/settings.local.json` (runs `bun run lint:fix` async after Edit/Write). Merge into existing hooks, don't overwrite.
+
+Reference: `.jdi/framework/hooks/lint-fix-frontend.md`
+
+### Step 4: Register Natural Language Routing
+
+Append JDI routing block to `.claude/CLAUDE.md` if not already present (check for `## JDI Workflow Routing`). Content includes intent→skill mapping and iterative refinement instructions.
+
+### Step 5: Initialise Config Files
+
+```bash
+cp .jdi/framework/config/state.yaml .jdi/config/state.yaml
+cp .jdi/framework/config/variables.yaml .jdi/config/variables.yaml
+cp .jdi/framework/config/jdi-config.yaml .jdi/config/jdi-config.yaml
+```
+
+### Step 6: Generate Markdown Scaffolding
+
+Read templates from `.jdi/framework/templates/` and write to `.jdi/` (only if missing):
+- PROJECT.yaml, REQUIREMENTS.yaml, ROADMAP.yaml
+
+### Step 7: Display Completion
+
+List all available commands and suggest `/jdi:create-plan "your feature"` to get started.
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `--force` | Overwrite existing command files |

package/framework/commands/pr-feedback.md

@@ -0,0 +1,75 @@
+---
+name: pr-feedback
+description: "JDI: Address PR review comments systematically"
+allowed-tools: Read, Bash, Task
+argument-hint: "<pr-number-or-url>"
+context: |
+  !git branch --show-current 2>/dev/null
+---
+
+# /jdi:pr-feedback
+
+Address review comments on a pull request via the `jdi-pr-feedback` specialist.
+
+**This skill follows `<JDI:StrictnessProtocol />`. Read that component before executing any step below.**
+
+---
+
+## Orchestration
+
+### 1. Parse PR Reference
+
+Extract the PR number from `$ARGUMENTS`. Accept a bare number or a full GitHub URL. If neither is present, STOP and ask for one.
+
+### 2. Fetch Unresolved Comments
+
+Run `gh api repos/{owner}/{repo}/pulls/{number}/comments` (or equivalent) to confirm there are unresolved comments. If there are none, STOP:
+
+> "PR #{number} has no unresolved review comments. Nothing to address."
+
+### 3. Delegate to jdi-pr-feedback
+
+Spawn the specialist via Task tool. JDI specialists spawn as `general-purpose` with identity injected via prompt text:
+
+```
+Task(
+  subagent_type="general-purpose",
+  prompt="You are jdi-pr-feedback. Read .jdi/framework/agents/jdi-pr-feedback.md
+  for your full role and instructions. Also read
+  .jdi/framework/components/meta/AgentBase.md for the JDI base protocol.
+  If your spec has requires_components in frontmatter, batch-read all listed
+  components before starting.
+
+  Address feedback for PR: {pr-number}"
+)
+```
+
+### 4. Present Result
+
+After the specialist returns, summarise: comments addressed, files touched, commits made. End with:
+
+> "Feedback applied. Review the diff, then run `/jdi:commit` or push when ready."
+
+**Wait for the user's response. Do NOT auto-push.**
+
+---
+
+## Edge Cases
+
+| Situation | Response |
+|-----------|----------|
+| No PR reference | STOP at step 1. Ask for a number or URL. |
+| No unresolved comments | STOP at step 2. Nothing to do. |
+| Specialist cannot address a specific comment | Surface the blocker; the user decides whether to override or defer. |
+| Working tree dirty before start | Ask whether to stash, commit, or abort. Do NOT silently mix unrelated changes. |
+| PR is closed or merged | STOP and report — feedback on closed PRs is not actionable via this skill. |
+
+---
+
+## Collaborative Protocol
+
+<JDI:StrictnessProtocol />
+
+---
+
+**PR to address:** $ARGUMENTS

package/framework/commands/pr-review.md

@@ -0,0 +1,92 @@
+---
+name: pr-review
+description: "JDI: Review pull request with learnings-aware analysis"
+allowed-tools: Read, Bash, Task
+argument-hint: "<pr-number-or-url> [--no-comments]"
+context: |
+  !git branch --show-current 2>/dev/null
+---
+
+# /jdi:pr-review
+
+Review a pull request against the team's learnings and coding standards.
+
+**This skill follows `<JDI:StrictnessProtocol />`. Read that component before executing any step below.**
+
+---
+
+## Flags
+
+- `--no-comments` — Do not post comments to GitHub. Write the review to `.jdi/reviews/PR-{number}-review.md` instead.
+
+---
+
+## Orchestration
+
+### 1. Parse PR Reference
+
+Extract the PR number from `$ARGUMENTS`. Accept either a bare number (`123`) or a GitHub URL (`https://github.com/org/repo/pull/123`). If neither form is present, STOP:
+
+> "I need a PR number or URL. Try `/jdi:pr-review 123` or `/jdi:pr-review https://github.com/org/repo/pull/123`."
+
+### 2. Parse Flags
+
+Check for `--no-comments`. Map to the `post="false"` parameter for the `PRReview` component.
+
+### 3. Verify PR Exists
+
+Run `gh pr view {number}` to confirm the PR is reachable. If `gh` errors, STOP and report the failure — do NOT fabricate a review.
+
+### 4. Delegate to Reviewer
+
+Spawn the reviewer via Task tool. JDI specialists spawn as `general-purpose` with identity injected via prompt text:
+
+```
+Task(
+  subagent_type="general-purpose",
+  prompt="Read .jdi/framework/components/meta/AgentBase.md for the base protocol.
+
+  Read learnings before reviewing — these represent the team's coding standards
+  and MUST be cross-referenced during review:
+  - Always: .jdi/framework/learnings/general.md
+  - PHP/Laravel PRs: also .jdi/framework/learnings/backend.md
+  - React/TypeScript PRs: also .jdi/framework/learnings/frontend.md
+  - Test changes: also .jdi/framework/learnings/testing.md
+  - CI/Docker changes: also .jdi/framework/learnings/devops.md
+
+  Apply learnings as additional review criteria — flag violations and praise adherence.
+
+  Read .jdi/framework/components/quality/PRReview.md for review instructions.
+  {If --no-comments: invoke as <JDI:PRReview post=\"false\" />}
+
+  Review PR: {pr-number}"
+)
+```
+
+### 5. Present Result
+
+After the reviewer returns, summarise: number of comments posted (or file path of the written review), severity breakdown, and any blocking issues.
+
+Then **STOP**. Do NOT merge, approve, or take any follow-up action.
+
+---
+
+## Edge Cases
+
+| Situation | Response |
+|-----------|----------|
+| No PR reference in arguments | STOP at step 1. Ask for a number or URL. |
+| `gh pr view` fails (not logged in, wrong repo) | Report the error verbatim. Do NOT attempt a workaround. |
+| PR is already merged | Note it in the summary and review anyway — learnings may still apply. |
+| PR is a draft | Review as normal; flag that the PR is draft in the summary. |
+| `.jdi/framework/learnings/` missing | Reviewer falls back to base review criteria. Record the missing learnings in the summary. |
+
+---
+
+## Collaborative Protocol
+
+<JDI:StrictnessProtocol />
+
+---
+
+**PR to review:** $ARGUMENTS

package/framework/commands/quick.md

@@ -0,0 +1,124 @@
+---
+name: quick
+description: "JDI: Quick focused change (skips planner, relaxed standards)"
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+argument-hint: "<task description> [--dry-run]"
+context: |
+  !git status --short 2>/dev/null | head -20
+---
+
+# /jdi:quick
+
+Execute a small, focused change directly without full orchestration. For trivial or prototype work only — no planner, no agent spawn, no waves.
+
+**This skill follows `<JDI:StrictnessProtocol />`. Read that component before executing any step below.**
+
+---
+
+## Flags
+
+- `--dry-run` — Preview the change without writing files. List intended edits and STOP.
+
+---
+
+## Scope Gate (read first)
+
+`/jdi:quick` is for:
+
+- Single-file edits, typo fixes, log lines, variable renames
+- Prototype / exploration code where throwaway is acceptable
+- Tasks under ~30 minutes with no architectural impact
+
+`/jdi:quick` is NOT for:
+
+- Production code requiring tests, review, or sign-off
+- Multi-file refactors or anything touching contracts (API routes, DTOs, exported types, migrations)
+- Work that spans tech stacks or layers
+
+If the task doesn't fit, redirect to `/jdi:create-plan "<feature>"` before writing any code.
+
+---
+
+## Orchestration
+
+The steps below are numbered and ordered. Do NOT skip, merge, or reorder them.
+
+### 1. Parse and Classify
+
+Read `$ARGUMENTS`. If the task description suggests production-grade work (tests required, multi-file, architectural), STOP and redirect:
+
+> "This looks bigger than `/jdi:quick` is meant for. Run `/jdi:create-plan "<feature>"` instead so we agree on scope before writing code."
+
+**Wait for the user's answer. Do not proceed until they confirm `/jdi:quick` is still the right fit.**
+
+### 2. Detect Tech Stack
+
+Read the target files (inferred from `$ARGUMENTS` or the user's follow-up). Identify the stack. Record in working memory.
+
+### 3. Dry Run Check
+
+If `--dry-run` is present, list the files you would edit and the intended change per file. Then **STOP**. Do NOT write anything.
+
+### 4. Execute Change
+
+Apply the edit directly via Edit tool. No agent spawn. No TaskCreate. Scope is intentionally narrow — one concern per invocation.
+
+### 5. Verification
+
+Run only the quality gates that are cheap and relevant:
+
+- Typecheck for TS changes (`tsc --noEmit` or project-equivalent)
+- Lint for the touched file only (not the whole repo)
+- Tests only if the user explicitly asked for them — `/jdi:quick` defaults to skipping
+
+If a gate fails, STOP and report. Do NOT auto-fix beyond the scope the user requested.
+
+### 6. Report
+
+Present a 3-line summary: files changed, gates run, next suggested action. End with:
+
+> "Commit as `proto:` / `quick:` / leave uncommitted? Your call."
+
+**Wait for the user's answer. Do NOT auto-commit.**
+
+---
+
+## Relaxed Standards Mode
+
+- Prototype / throwaway code accepted
+- Tests optional (default: skip)
+- Commit message prefix: `proto:` or `quick:`
+- Framed as exploration — NOT production
+- `jdi-qa-tester` is NOT invoked in `/jdi:quick` mode. If regression checks matter, route through `/jdi:implement-plan` instead.
+
+---
+
+## Edge Cases
+
+| Situation | Response |
+|-----------|----------|
+| Task description implies production work | Redirect to `/jdi:create-plan` at step 1. Do NOT proceed. |
+| `.jdi/` directory doesn't exist | Proceed anyway — `/jdi:quick` does not require JDI scaffolding. Skip any state updates. |
+| Typecheck or lint fails after edit | Report the failure. Do NOT auto-fix unrelated issues. |
+| User asks for tests mid-task | Honour the request; run the test command once, report, then stop. |
+| Target file doesn't exist | Ask the user: create it, or did they mean a different path? |
+
+---
+
+## HARD STOP
+
+Once the edit is applied and gates have run, the skill is **DONE**.
+
+- Do NOT auto-commit.
+- Do NOT advance state.
+- Do NOT invoke any other skill.
+
+---
+
+## Collaborative Protocol
+
+<JDI:StrictnessProtocol />
+
+---
+
+**Task:** $ARGUMENTS

package/framework/commands/status.md

@@ -0,0 +1,13 @@
+---
+name: status
+description: "JDI: Show framework status"
+---
+
+# /jdi:status
+
+## Direct Execution
+
+1. Read `.jdi/config/state.yaml`
+2. Display current position and progress
+3. Show recent commits
+4. Suggest next action

package/framework/commands/worktree-remove.md

@@ -0,0 +1,32 @@
+---
+name: worktree-remove
+description: "JDI: Remove git worktree and clean up"
+---
+
+# /jdi:worktree-remove
+
+Remove a git worktree and clean up all associated resources.
+
+## Direct Execution
+
+1. **Identify worktree** from `$ARGUMENTS`:
+   - If name provided: use `.worktrees/<name>`
+   - If no arguments: read `worktree.path` from `.jdi/config/state.yaml`
+   - If neither: list worktrees via `git worktree list`, prompt which to remove
+   - `--force` flag: skip confirmation prompt
+   - `--keep-branch` flag: don't delete the git branch after removal
+2. **Confirm** with user (unless `--force`): show worktree path, branch, resources that will be cleaned up
+3. **Project-specific cleanup** (from adapter config):
+   - Drop databases per adapter config
+   - Remove web server configuration per adapter config
+4. **Remove worktree**: `git worktree remove .worktrees/<name> --force`
+5. **Delete branch** (unless `--keep-branch`):
+   - Merged: `git branch -d <name>`
+   - Unmerged: `git branch -D <name>` (warn user first)
+6. **Clean up**: `rmdir .worktrees 2>/dev/null` (only if empty)
+7. **Update state**: set `worktree.active: false`, clear `worktree.path`, `worktree.branch` in `.jdi/config/state.yaml`
+8. **Report**: what was removed
+
+Reference: .jdi/framework/hooks/jdi-worktree-cleanup.md
+
+Worktree to remove: $ARGUMENTS

package/framework/commands/worktree.md

@@ -0,0 +1,52 @@
+---
+name: worktree
+description: "JDI: Create git worktree with full environment"
+---
+
+# /jdi:worktree
+
+Create an isolated git worktree with full project environment from a ticket, task name, or description.
+
+> **CRITICAL: Do NOT use the built-in `EnterWorktree` tool.** It creates a bare worktree without project-specific setup. Always follow the Direct Execution steps below.
+
+## Direct Execution
+
+> **CRITICAL: Ordering matters.** Steps 4–7 are sequential — do NOT parallelise setup steps that depend on configuration being complete first.
+
+1. **Parse name** from `$ARGUMENTS`:
+   - Extract ticket ID if present (e.g. "PROJ-1234") — use as prefix
+   - Slugify the rest: lowercase, spaces/special chars to hyphens, strip trailing hyphens, max 40 chars
+   - Examples: `"PROJ-1234 Add user auth"` → `proj-1234-add-user-auth`
+   - Examples: `"fix broken calculator"` → `fix-broken-calculator`
+   - If no arguments, generate random adjective-noun name
+   - `--lightweight` flag: skip databases, web server setup, SSL (deps + migrate only)
+   - `--base <branch>` flag: base branch (default: main)
+2. **Validate**: check git repo, branch doesn't exist, required tools available
+3. **Create worktree**:
+   ```bash
+   mkdir -p .worktrees
+   git worktree add -b <name> .worktrees/<name> <base-branch>
+   ```
+4. **`cd` into worktree** — all subsequent commands run from inside the worktree:
+   ```bash
+   cd .worktrees/<name>
+   ```
+5. **Project-specific setup** (from adapter config, skip if `--lightweight`):
+   - Create databases per adapter config
+   - Configure environment files per adapter config
+   - Run project-specific web server setup per adapter config
+6. **Install dependencies** — these CAN run in parallel:
+   ```bash
+   # Run dependency install commands from adapter config
+   # e.g. composer install, bun install, npm install, etc.
+   ```
+7. **Project bootstrap** (run sequentially, AFTER environment is configured):
+   - Run migration commands per adapter config
+   - Run seed commands per adapter config (in dependency order)
+   - Run post-setup commands per adapter config
+8. **Update state**: set `worktree.active: true`, `worktree.path`, `worktree.branch`, `worktree.created_at`, `worktree.type` in `.jdi/config/state.yaml`
+9. **Report**: worktree path, branch, setup summary
+
+**On error**: clean up (reverse database creation, remove worktree, reverse web server setup).
+
+Worktree to create: $ARGUMENTS