JDI

** Software Agent workflows for Claude Code **

Orchestrate specialised agents to plan, implement, review, and ship features — from single-file fixes to full-stack multi-wave implementations.

Table of Contents

• Usage Modes
• Getting Started
• Commands
• GitHub Actions Setup
• Features
• Agents
• Teams

Usage Modes

JDI runs in three modes with identical capabilities:

| Mode | How | Best For | |------|-----|----------| | Claude Code App | /jdi:create-plan, /jdi:implement-plan, etc. | Interactive development with Claude Code | | CLI | jdi plan, jdi implement, jdi quick, etc. | Terminal workflows, scripting, CI | | GitHub Actions | Comment Hey JDI plan ... on issues/PRs | Autonomous code generation from issue comments |

Getting Started

Claude Code App

bun install -g @benzotti/jdi
jdi init

Then inside Claude Code:

/jdi:create-plan "Add user authentication"
/jdi:implement-plan
/jdi:commit
/jdi:generate-pr

CLI

bun install -g @benzotti/jdi
jdi init

jdi plan "Add user authentication"
jdi implement
jdi quick "fix the broken quote calculator"
jdi review 42
jdi pr

GitHub Actions

jdi setup-action

Then on any issue or PR, comment:

Hey JDI plan Add user authentication
Hey JDI implement
Hey JDI quick fix the broken login button

See GitHub Actions Setup for details.

Commands

| Slash Command | CLI Equivalent | Description | |---------------|----------------|-------------| | /jdi:init | jdi init | Initialise JDI in the current project | | /jdi:create-plan | jdi plan <desc> | Create an implementation plan | | /jdi:implement-plan | jdi implement [plan] | Execute a plan (single-agent or Agent Teams) | | /jdi:quick | jdi quick <desc> | Quick focused change without orchestration | | /jdi:commit | jdi commit | Create a conventional commit | | /jdi:generate-pr | jdi pr | Generate and create a pull request | | /jdi:pr-review | jdi review <pr> | Review a PR and post line comments | | /jdi:pr-feedback | jdi feedback | Address PR review comments | | /jdi:worktree | jdi worktree | Create an isolated git worktree | | /jdi:worktree-remove | jdi worktree-remove | Remove a worktree and clean up | | /jdi:status | jdi status | Show current state and suggest next action |

CLI Flags

jdi plan

| Flag | Description | |------|-------------| | --print | Print prompt to stdout instead of executing | | --output <file> | Write prompt to file |

jdi implement

| Flag | Description | |------|-------------| | --team | Force Agent Teams mode | | --single | Force single-agent mode | | --dry-run | Preview changes without writing files | | --print | Print prompt to stdout |

jdi quick

| Flag | Description | |------|-------------| | --dry-run | Preview changes without writing files | | --print | Print prompt to stdout |

jdi pr

| Flag | Description | |------|-------------| | --draft | Create as draft PR | | --base <branch> | Base branch (default: main) | | --no-push | Skip pushing the branch | | --dry-run | Show generated PR without creating |

GitHub Actions Setup

Installation

Run jdi setup-action to generate the workflow file, or manually copy action/workflow-template.yml to .github/workflows/jdi.yml.

Required

| Secret | Required | Description | |--------|----------|-------------| | ANTHROPIC_API_KEY | Yes | Claude API key | | CLICKUP_API_TOKEN | No | ClickUp integration for ticket-driven development |

Optional

| Variable | Description | |----------|-------------| | JDI_AUTH_ENABLED | Set to true to restrict JDI to write collaborators | | JDI_ALLOWED_USERS | Comma-separated list of allowed GitHub usernames |

Comment Syntax

| Command | Description | |---------|-------------| | Hey JDI plan <description> | Create an implementation plan | | Hey JDI implement | Execute the current plan | | Hey JDI implement --dry-run | Preview implementation without writing | | Hey JDI quick <description> | Make a quick change | | Hey JDI review | Review the current PR | | Hey JDI do <clickup-url> | Full flow: plan + implement from ticket | | Hey JDI ping | Check framework status |

Conversation Flow

1. Comment Create a plan for ... to start planning
2. JDI posts the plan and asks for feedback
3. Reply with refinement feedback (e.g. "change task 2 ...")
4. Say "approved" or "lgtm" to lock the plan
5. Comment implement the plan to execute
6. Reply with follow-up feedback to iterate on the implementation

Features

Planning and Implementation

1. Research — The planner agent analyses your codebase and gathers context
2. Plan — Produces a structured PLAN.md with task breakdown, dependencies, and success criteria
3. Execute — The complexity router decides single-agent or Agent Teams mode
4. Verify — Quality gates run automatically after execution
5. Commit — Each task gets its own atomic conventional commit

Git Worktrees

Full-environment git worktrees for isolated development:

• Full worktree (--worktree): databases, dependencies, migrations, seeders, web server
• Lightweight worktree (--worktree-lightweight): dependencies and migrations only

State Management

| File | Purpose | |------|---------| | .jdi/config/state.yaml | Runtime state — position, progress, review status | | .jdi/config/adapter.yaml | Project-type adapter config (tech stack, quality gates) | | .jdi/config/jdi-config.yaml | Global configuration (workflow, models) |

Agents

Engineering

| Agent | Role | |-------|------| | jdi-backend | Backend Engineer | | jdi-frontend | Frontend Engineer | | jdi-architect | Systems Architect | | jdi-programmer | Senior Fullstack Engineer |

Product and Research

| Agent | Role | |-------|------| | jdi-planner | Product Manager / Planner | | jdi-researcher | Senior Analyst | | jdi-product-lead | Product Lead | | jdi-ux-designer | Lead UI/UX Designer |

Quality Assurance

| Agent | Role | |-------|------| | jdi-quality | Lead QA Developer | | jdi-verifier | Senior QA Developer |

DevOps

| Agent | Role | |-------|------| | jdi-devops | DevOps Engineer |

Supporting

| Agent | Role | |-------|------| | jdi-committer | Commit specialist | | jdi-pr-generator | PR generation | | jdi-pr-feedback | PR feedback handler | | jdi-debugger | Debugging specialist | | jdi-head-engineering | Head of Engineering (oversight) | | jdi-codebase-mapper | Codebase indexing | | jdi-feedback-learner | Learning extraction | | jdi-plan-checker | Plan validation |

Teams

| Team | Members | Purpose | |------|---------|---------| | Engineering | backend, frontend, architect, executor | All coding | | Product & Research | planner, researcher, product-lead, ux-designer | Planning (no code) | | Quality Assurance | quality, verifier | Testing, verification | | DevOps | devops | Infrastructure, CI/CD | | Leads | product-lead, head-engineering | Oversight (opt-in) |