@benzotti/jdi 0.1.46

package/framework/config/state.yaml

@@ -0,0 +1,72 @@
+session:
+  id: null
+  started_at: null
+  last_activity: null
+
+project:
+  name: null
+  root: null
+  initialised: false
+  initialised_at: null
+
+position:
+  phase: null
+  phase_name: null
+  plan: null
+  plan_name: null
+  task: null
+  task_name: null
+  status: idle
+
+progress:
+  phases_total: 0
+  phases_completed: 0
+  plans_total: 0
+  plans_completed: 0
+  tasks_total: 0
+  tasks_completed: 0
+
+current_plan:
+  path: null
+  tasks: []
+  completed_tasks: []
+  current_task_index: null
+
+current_phase:
+  waves:
+    computed: false
+    total_waves: 0
+    current_wave: null
+    structure: []
+  plans_by_wave: {}
+
+worktree:
+  active: false
+  path: null
+  branch: null
+  created_at: null
+  type: null
+
+continuation:
+  file: null
+  paused_at: null
+  resume_action: null
+
+commits:
+  session_commits: []
+  last_commit_hash: null
+  last_commit_message: null
+
+checkpoints:
+  last_checkpoint: null
+  checkpoint_type: null
+  awaiting_response: false
+
+deviations: []
+
+blockers: []
+
+metadata:
+  context_usage_estimate: 0
+  agent_spawns: 0
+  errors_encountered: 0

package/framework/config/variables.yaml

@@ -0,0 +1,43 @@
+feature:
+  name: null
+  description: null
+  type: null
+  branch: null
+  pr_number: null
+  pr_url: null
+
+context:
+  clickup_task_id: null
+  clickup_task_url: null
+  figma_url: null
+  figma_node_id: null
+  requirements_source: null
+
+implementation:
+  approach: null
+  key_decisions: []
+  files_created: []
+  files_modified: []
+  dependencies_added: []
+
+review:
+  reviewer: null
+  review_status: null
+  comments_total: 0
+  comments_resolved: 0
+  changes_requested: []
+
+testing:
+  test_files: []
+  coverage_before: null
+  coverage_after: null
+  tests_added: 0
+  tests_passed: null
+
+references:
+  related_files: []
+  related_components: []
+  documentation_urls: []
+  api_endpoints: []
+
+custom: {}

package/framework/hooks/checkpoint.md

@@ -0,0 +1,196 @@
+---
+name: checkpoint
+description: Handles checkpoint interactions
+trigger: checkpoint_reached
+---
+
+# Checkpoint Hook
+
+Handles pausing execution and managing user interaction at checkpoints.
+
+---
+
+## Trigger
+
+Fires when:
+- Task type is `checkpoint:human-verify`
+- Task type is `checkpoint:decision`
+- Task type is `checkpoint:human-action`
+- Auth gate or credential requirement detected
+
+---
+
+## Checkpoint Types
+
+### human-verify
+
+User needs to test/verify something.
+
+**Flow:**
+1. Present what was built
+2. Provide verification steps
+3. Wait for "approved" or issues
+
+**Template:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ JDI ► CHECKPOINT: Verification Required
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase:** {phase} | **Plan:** {plan} | **Task:** {n}/{total}
+
+## What Was Built
+
+{Summary of completed work}
+
+## Please Verify
+
+1. {Step 1}
+2. {Step 2}
+3. {Step 3}
+
+## Expected Behaviour
+
+{What you should see}
+
+───────────────────────────────────────────────────────────────
+
+Reply "approved" to continue, or describe any issues found.
+```
+
+### decision
+
+User needs to make a choice.
+
+**Flow:**
+1. Present decision context
+2. Show options with trade-offs
+3. Record choice and rationale
+
+**Template:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ JDI ► CHECKPOINT: Decision Required
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Decision:** {What needs to be decided}
+
+## Context
+
+{Why this decision matters}
+
+## Options
+
+| Option | Pros | Cons |
+|--------|------|------|
+| A: {option} | {pros} | {cons} |
+| B: {option} | {pros} | {cons} |
+| C: {option} | {pros} | {cons} |
+
+## Recommendation
+
+{If applicable, what we recommend and why}
+
+───────────────────────────────────────────────────────────────
+
+Reply with your choice (A/B/C) and any additional context.
+```
+
+### human-action
+
+User needs to do something manually.
+
+**Flow:**
+1. Explain what's needed
+2. Provide steps
+3. Wait for "done" confirmation
+4. Verify action worked
+
+**Template:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ JDI ► CHECKPOINT: Manual Action Required
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Action:** {What you need to do}
+
+## Why This Can't Be Automated
+
+{Reason - credentials, external system, etc.}
+
+## Steps
+
+1. {Step 1}
+2. {Step 2}
+3. {Step 3}
+
+## How to Verify
+
+{How we'll confirm it worked}
+
+───────────────────────────────────────────────────────────────
+
+Reply "done" when complete.
+```
+
+---
+
+## State Management
+
+On checkpoint:
+
+```yaml
+checkpoints:
+  last_checkpoint: "{timestamp}"
+  checkpoint_type: "{type}"
+  checkpoint_task: "{task_id}"
+  awaiting_response: true
+```
+
+On response:
+
+```yaml
+checkpoints:
+  awaiting_response: false
+  last_response: "{user_response}"
+  response_at: "{timestamp}"
+```
+
+---
+
+## Response Handling
+
+### "approved" / "done"
+- Continue to next task
+- Clear awaiting_response
+
+### Issues described
+- Parse user feedback
+- Return to task with feedback context
+- Address issues
+- Re-present checkpoint
+
+### Decision made
+- Record decision
+- Record rationale if provided
+- Apply decision to remaining work
+- Continue execution
+
+---
+
+## Timeout Behaviour
+
+If checkpoint awaits response for extended time:
+- State preserved in state.yaml
+- Can resume with `/jdi-implement-plan --resume`
+- Progress is not lost
+
+---
+
+## Outputs
+
+| Output | Purpose |
+|--------|---------|
+| Checkpoint display | User interaction |
+| State update | Track checkpoint |
+| Decision record | Document choices |

package/framework/hooks/jdi-worktree-cleanup.md

@@ -0,0 +1,123 @@
+---
+name: jdi-worktree-cleanup
+description: Clean up git worktree and associated branch after execution
+---
+
+# Worktree Cleanup Hook
+
+Clean up the git worktree and associated branch after worktree-based execution completes.
+
+---
+
+## When to Execute
+
+This hook is invoked after worktree execution completes, either:
+- After a **merge** (branch was merged into current branch)
+- After a **discard** (changes were discarded)
+
+---
+
+## Cleanup Steps
+
+### 1. Remove the Git Worktree
+
+```bash
+git worktree remove .worktrees/jdi-{plan-id} --force
+```
+
+The `--force` flag is used to handle cases where the worktree has uncommitted changes (which shouldn't happen in normal flow but provides safety).
+
+### 2. Delete the Branch
+
+**If branch was merged:**
+```bash
+git branch -d jdi/{plan-id}
+```
+Uses `-d` (safe delete) since the branch was already merged.
+
+**If branch was NOT merged (discard):**
+```bash
+git branch -D jdi/{plan-id}
+```
+Uses `-D` (force delete) since the branch was never merged.
+
+### 3. Remove Empty Worktrees Directory
+
+```bash
+rmdir .worktrees 2>/dev/null
+```
+
+Only removes the directory if it's empty. Silently fails if other worktrees exist.
+
+---
+
+## Error Handling
+
+### Worktree Removal Fails
+
+If the worktree removal fails (e.g., uncommitted changes, locked files):
+
+```
+⚠️ Warning: Could not remove worktree automatically.
+
+Manual cleanup commands:
+  git worktree remove .worktrees/jdi-{plan-id} --force
+  rm -rf .worktrees/jdi-{plan-id}
+```
+
+### Branch Deletion Fails
+
+If the branch deletion fails:
+
+```
+⚠️ Warning: Could not delete branch automatically.
+
+Manual cleanup command:
+  git branch -D jdi/{plan-id}
+```
+
+---
+
+## State Update
+
+After cleanup, update `.jdi/config/state.yaml`:
+
+1. Read `.jdi/config/state.yaml`
+2. Clear any worktree-related state:
+   ```yaml
+   worktree:
+     active: false
+     path: null
+     branch: null
+   ```
+3. Write the updated YAML back
+
+---
+
+## Full Cleanup Sequence
+
+```bash
+# 1. Remove worktree
+git worktree remove .worktrees/jdi-{plan-id} --force
+
+# 2. Delete branch (use -d if merged, -D if not)
+git branch -d jdi/{plan-id}  # or -D for discarded
+
+# 3. Clean up empty directory
+rmdir .worktrees 2>/dev/null
+
+# 4. Update state (handled by Read/Write tools)
+```
+
+---
+
+## Usage Example
+
+Called from `jdi-implement-plan.md` Step 3: Post-Execution:
+
+```
+After user selects "merge" or "discard":
+1. If merge: git merge jdi/{plan-id}
+2. Invoke this cleanup hook
+3. Report cleanup complete
+```

package/framework/hooks/lint-fix-frontend.md

@@ -0,0 +1,59 @@
+---
+name: lint-fix-frontend
+description: Auto-fix ESLint issues on frontend files after edit
+trigger: PostToolUse (Edit|Write)
+type: claude-code-hook
+---
+
+# Lint Fix Frontend Hook
+
+Automatically runs `bun run lint:fix` after Claude Code (or an agent) edits or writes a file.
+
+---
+
+## Trigger
+
+Fires when:
+- Claude Code edits a file (Edit tool)
+- Claude Code writes a file (Write tool)
+- Any JDI agent edits/writes files via subagents
+
+**Claude Code event:** `PostToolUse` with matcher `Edit|Write`
+
+---
+
+## Behaviour
+
+Runs `bun run lint:fix` (`turbo lint -- --fix`) asynchronously in the background so Claude is not blocked. Covers all frontend workspaces via turbo.
+
+---
+
+## Installation
+
+Registered automatically by `/jdi:init` in `.claude/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run lint:fix",
+            "timeout": 30,
+            "async": true
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Manual Override
+
+To temporarily disable, remove the `PostToolUse` entry from `.claude/settings.local.json`.

package/framework/hooks/on-pause.md

@@ -0,0 +1,213 @@
+---
+name: on-pause
+description: Actions to perform when work is paused, generates continuation file
+trigger: pause_request
+---
+
+# On-Pause Hook
+
+Actions performed when the user requests to pause work or when a session ends naturally.
+
+---
+
+## Trigger
+
+Fires when:
+- User explicitly requests to pause (`/jdi:pause`)
+- Session is ending (user leaves)
+- Blocking issue encountered (Rule 4 deviation)
+- Checkpoint requires extended user action
+
+---
+
+## Purpose
+
+Create a continuation file that enables seamless resumption:
+1. Capture current position precisely
+2. Record context that would be lost
+3. Provide clear next action
+4. Enable fresh context resumption
+
+---
+
+## Actions
+
+### 1. Capture Current State
+
+```bash
+# Read current state
+cat .jdi/config/state.yaml
+
+# Extract position
+PHASE=$(yq -r '.position.phase' .jdi/config/state.yaml)
+PLAN=$(yq -r '.position.plan' .jdi/config/state.yaml)
+TASK=$(yq -r '.position.task' .jdi/config/state.yaml)
+STATUS=$(yq -r '.position.status' .jdi/config/state.yaml)
+```
+
+### 2. Identify Next Action
+
+Based on current status, determine what should happen next:
+
+| Status | Next Action |
+|--------|-------------|
+| `planning` | Continue planning |
+| `executing` | Resume task execution |
+| `verifying` | Complete verification |
+| `blocked` | Resolve blocker |
+| `checkpoint` | Await user response |
+
+### 3. Capture Session Context
+
+Gather context that would be lost:
+- Recent decisions made
+- Key discoveries
+- Warnings or concerns
+- User preferences expressed
+
+### 4. Generate Continuation File
+
+Create `.jdi/CONTINUE-HERE.md`:
+
+```markdown
+---
+paused_at: {ISO timestamp}
+phase: {N}
+plan: {NN}
+task: {N or null}
+status: {status}
+---
+
+# Continue Here
+
+## Quick Resume
+
+**Last completed:** {description of last completed work}
+**Current status:** {what's in progress}
+**Next action:** `{command to run}`
+
+## Position
+
+| Level | Value | Name |
+|-------|-------|------|
+| Phase | {N} | {phase_name} |
+| Plan | {NN} | {plan_name} |
+| Task | {N} | {task_name or "N/A"} |
+| Status | {status} | |
+
+## Context from This Session
+
+### Decisions Made
+{List of decisions made during this session}
+
+### Key Discoveries
+{Important findings or learnings}
+
+### Warnings/Concerns
+{Any issues to be aware of}
+
+### User Preferences
+{Any preferences expressed by user}
+
+## To Resume
+
+### Option 1: Continue Where Left Off
+```bash
+/jdi:resume
+```
+
+### Option 2: Manual Resume
+```bash
+# If task was in progress:
+/jdi:implement-plan {phase}-{plan} --resume-from-task {task}
+
+# If planning:
+/jdi:create-plan {phase}
+
+# If verifying:
+/jdi:verify {phase}
+```
+
+## Recent Commits
+
+| Time | Hash | Message |
+|------|------|---------|
+{List recent commits from session}
+
+## Files Modified (Uncommitted)
+
+```bash
+git status --short
+```
+
+{Output of uncommitted changes, if any}
+
+## Blockers (if any)
+
+{Description of any blocking issues}
+
+---
+
+*Generated by JDI on-pause hook at {timestamp}*
+```
+
+### 5. Update State
+
+Mark session as paused:
+
+```yaml
+position:
+  status: paused
+session:
+  paused_at: "{timestamp}"
+  continuation_file: ".jdi/CONTINUE-HERE.md"
+```
+
+### 6. Display Pause Summary
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ JDI ► SESSION PAUSED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Paused at: Phase {N}, Plan {NN}, Task {N}
+Status: {status}
+
+Continuation file: .jdi/CONTINUE-HERE.md
+
+To resume: /jdi:resume
+
+───────────────────────────────────────────────────────
+```
+
+---
+
+## Continuation File Location
+
+The continuation file is always at: `.jdi/CONTINUE-HERE.md`
+
+This file is:
+- Overwritten on each pause (only one active)
+- Deleted after successful resume
+- Human-readable for manual recovery
+
+---
+
+## Integration with Resume
+
+The `/jdi:resume` command:
+1. Reads `.jdi/CONTINUE-HERE.md`
+2. Loads context specified in the file
+3. Executes the `next_action`
+4. Deletes the continuation file on success
+
+---
+
+## Success Criteria
+
+- [ ] Current position captured accurately
+- [ ] Next action clearly identified
+- [ ] Session context preserved
+- [ ] Continuation file is self-contained
+- [ ] State updated to paused
+- [ ] User informed of how to resume