@benzotti/jedi 0.1.0

package/README.md

@@ -0,0 +1,615 @@
+  ```
+    ⠀⠀⠀⠀⠀⠀⠀⠀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+    ⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+    ⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+    ⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+    ⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+    ⠀⠀⠀⠀⠠⠀⠀⠀⡇⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+    ⠀⠀⠀⠀⠀⠈⠳⣴⣿⠄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+    ⠀⠒⠒⠒⠒⠒⢺⢿⣿⢗⠒⠒⠒⠒⠒⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+    ⠀⠀⠀⠀⠀⠀⠁⣸⣿⣦⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+    ⠀⠀⠀⠀⠀⢀⣾⡟⠋⢹⣷⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+    ⠀⠀⠀⠀⢀⣿⡟⣴⣶⡄⣿⣧⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+    ⠀⠀⠀⢰⣿⣿⣧⢻⣿⣿⣿⣿⡟⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+    ⠀⠀⠀⠈⢻⣿⣿⣷⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+    ⠀⠀⠀⠀⢸⠿⣿⣿⣿⣿⣿⣿⣦⣤⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀
+    ⠀⠀⠀⠀⣾⠀⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣶⣤⡀⠀⠀⠀⠀⠀
+    ⠀⠀⠀⠀⣿⣏⣻⣿⣿⣿⣿⣿⠋⣿⣿⣿⣿⣿⠙⣿⣷⣶⣤⣤⡄
+    ⠀⠀⠀⠀⢻⢇⣿⣿⣿⣿⣿⠹⠀⢹⣿⣿⣿⡇⠀⢟⣿⣿⡿⠋⠀
+    ⠀⠀⠀⠀⢘⣼⣿⣿⣿⣿⣿⡆⠀⢸⣿⠛⣿⡇⠀⢸⡿⠋⠀⠀⠀
+    ⠀⠀⠀⠀⣾⣿⣿⣿⣿⣿⣿⣿⣦⣈⠻⠴⠟⣁⣴⣿⣿⠗⠀⠀⠀
+    ⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠋⠀⠀⠀⠀
+    ⠀⠀⢀⣿⣿⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠁⠀⠀⠀⠀⠀
+    ⠀⠀⣾⣿⡏⠀⠹⣿⠿⠿⠿⠿⣿⣿⣿⠿⠛⠁⠀⠀⠀⠀⠀⠀⠀
+    ⠀⢰⣿⡿⠀⠀⠀⠀⠀⠀⠀⠀⠀⢿⣿⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀
+    ⠀⣿⣿⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⣿⣧⠀⠀⠀⠀⠀⠀⠀⠀⠀
+    ⣰⣿⡏⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢿⣿⣄⠀⠀⠀⠀⠀⠀⠀⠀
+    ⠉⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠉⠉⠀⠀⠀⠀⠀⠀⠀⠀
+     ██╗███████╗██████╗ ██╗
+     ██║██╔════╝██╔══██╗██║
+     ██║█████╗  ██║  ██║██║
+██   ██║██╔══╝  ██║  ██║██║
+╚█████╔╝███████╗██████╔╝██║
+ ╚════╝ ╚══════╝╚═════╝ ╚═╝
+```
+
+# JDI Framework
+
+A componentised, context-efficient AI development framework for Claude Code. JDI orchestrates specialised agents to plan, implement, review, and ship features — from single-file fixes to full-stack multi-wave implementations.
+
+---
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Commands](#commands)
+- [Features](#features)
+  - [Planning and Implementation](#planning-and-implementation)
+  - [Git Worktrees](#git-worktrees)
+  - [Agent Teams](#agent-teams)
+  - [Complexity Router](#complexity-router)
+  - [PR Workflow](#pr-workflow)
+  - [Verification and Quality Gates](#verification-and-quality-gates)
+  - [Component System](#component-system)
+  - [Model Routing](#model-routing)
+  - [State Management](#state-management)
+  - [PR Feedback Learning](#pr-feedback-learning)
+- [Agents](#agents)
+- [Teams](#teams)
+- [Configuration](#configuration)
+- [Directory Structure](#directory-structure)
+- [Architecture](#architecture)
+
+---
+
+## Getting Started
+
+### 1. Install JDI
+
+```bash
+bun install -g @benzotti/jedi
+```
+
+Then initialise in your project:
+
+```bash
+jdi init
+```
+
+Or run the init command directly inside Claude Code:
+
+```
+/jdi:init
+```
+
+This creates:
+- `.jdi/framework/` — Framework files (agents, components, teams, etc.)
+- `.claude/commands/jdi/` — Slash command stubs for all JDI commands
+- `.jdi/` — Project state directory with plans, config, and research
+
+Use `--force` to regenerate all files (overwrites existing).
+
+### 2. Plan a Feature
+
+```
+/jdi:create-plan "PROJ-1234 Add user authentication"
+```
+
+JDI spawns a planner agent that researches your codebase, then produces a structured implementation plan at `.jdi/plans/`.
+
+### 3. Implement the Plan
+
+```
+/jdi:implement-plan
+```
+
+JDI evaluates the plan's complexity and routes it accordingly — a single agent for small changes, or a full Agent Teams swarm for multi-stack multi-wave work.
+
+### 4. Commit and Ship
+
+```
+/jdi:commit
+/jdi:generate-pr
+```
+
+Create conventional commits and generate a PR with a structured description.
+
+### Quick Changes
+
+For small, focused changes that don't need full orchestration:
+
+```
+/jdi:quick "fix the broken quote calculator"
+```
+
+Executes directly in the main context — no agent spawn, no team, no waves.
+
+---
+
+## Commands
+
+All commands are invoked as slash commands inside Claude Code.
+
+| Command | Type | Description |
+|---------|------|-------------|
+| `/jdi:init` | Direct | Initialise JDI in the current project |
+| `/jdi:create-plan` | Agent | Create an implementation plan (includes codebase research) |
+| `/jdi:implement-plan` | Agent | Execute a plan (single-agent or Agent Teams swarm) |
+| `/jdi:quick` | Direct | Quick focused change without orchestration |
+| `/jdi:commit` | Agent | Create a conventional commit |
+| `/jdi:generate-pr` | Agent | Generate and create a pull request |
+| `/jdi:pr-review` | Agent | Review a PR and post line comments to GitHub |
+| `/jdi:pr-feedback` | Agent | Address PR review comments |
+| `/jdi:worktree` | Direct | Create an isolated git worktree with full project environment |
+| `/jdi:worktree-remove` | Direct | Remove a worktree and clean up all resources |
+| `/jdi:status` | Direct | Show current framework state and suggest next action |
+
+**Agent commands** spawn a Task agent with isolated context (~300 tokens in main context). **Direct commands** execute in the main context.
+
+### Command Flags
+
+#### `/jdi:create-plan`
+
+| Flag | Description |
+|------|-------------|
+| `--worktree` | Create an isolated git worktree with full project environment (databases, deps, migrations, seeders per adapter config) before planning |
+| `--worktree-lightweight` | Create a worktree with minimal setup (deps + migrate only) |
+
+#### `/jdi:implement-plan`
+
+| Flag | Description |
+|------|-------------|
+| `--worktree` | Create a full-environment worktree before executing |
+| `--worktree-lightweight` | Create a lightweight worktree before executing |
+| `--team` | Force Agent Teams mode (even for simple plans) |
+| `--single` | Force single-agent mode (even for complex plans) |
+
+If `state.yaml` has `worktree.active: true` (set by `create-plan --worktree`), the implementation automatically runs inside that worktree.
+
+#### `/jdi:worktree`
+
+| Flag | Description |
+|------|-------------|
+| `--lightweight` | Skip databases, web server setup — just deps and migrate |
+| `--base <branch>` | Base branch to create worktree from (default: `master`) |
+
+#### `/jdi:worktree-remove`
+
+| Flag | Description |
+|------|-------------|
+| `--force` | Skip confirmation prompt |
+| `--keep-branch` | Don't delete the git branch after removal |
+
+#### `/jdi:init`
+
+| Flag | Description |
+|------|-------------|
+| `--force` | Overwrite all existing command stubs |
+
+---
+
+## Features
+
+### Planning and Implementation
+
+JDI follows a plan-then-execute workflow:
+
+1. **Research** — The planner agent analyses your codebase, gathers context, and identifies patterns before writing the plan.
+2. **Plan** — Produces a structured `PLAN.md` with task breakdown, dependencies, wave computation, and success criteria.
+3. **Execute** — The complexity router decides whether to use a single specialist agent or a full Agent Teams swarm.
+4. **Verify** — Quality gates run automatically after execution (lint, type checking, tests).
+5. **Commit** — Each task gets its own atomic conventional commit.
+
+Plans are written to `.jdi/plans/{phase}-{plan}-PLAN.md` and can be reviewed before execution.
+
+### Git Worktrees
+
+JDI provides full-environment git worktrees for isolated development. Unlike the built-in `EnterWorktree` tool, JDI worktrees set up the complete project environment via adapter configs:
+
+**Full worktree** (`--worktree`):
+- Creates project databases per adapter config
+- Configures environment files with worktree-specific settings
+- Installs dependencies per adapter config
+- Runs project bootstrap (migrations, seeders, post-setup)
+- Configures web server per adapter config
+
+**Lightweight worktree** (`--worktree-lightweight`):
+- Installs dependencies and runs migrations only
+- Skips databases, web server setup, seeders, and post-setup
+
+Worktree names are derived from ticket IDs and task descriptions (e.g., `"PROJ-1234 Add user auth"` becomes `proj-1234-add-user-auth`). Cleanup via `/jdi:worktree-remove` reverses all setup, removes the worktree, and deletes the branch.
+
+### Agent Teams
+
+For complex plans, JDI uses Claude Code's native Agent Teams to orchestrate multiple specialist agents working in parallel:
+
+1. **TeamCreate** — Creates a shared task list
+2. **TaskCreate** — Creates tasks with dependencies per the plan
+3. **Spawn Specialists** — Routes tasks to the right agent by tech stack
+4. **Wave Coordination** — Agents execute in dependency-ordered waves
+5. **Deferred Operations** — Orchestrator collects file creation and commits from agents, then executes them
+6. **Cleanup** — Graceful shutdown and team deletion
+
+Agents operate in isolated sandboxed contexts. They can edit existing files but cannot create new files or make git commits directly — these are reported as `files_to_create` and `commits_pending` for the orchestrator to execute.
+
+### Complexity Router
+
+The complexity router (`<JDI:ComplexityRouter />`) evaluates the plan and decides the execution mode:
+
+| Signal | Simple | Complex |
+|--------|--------|---------|
+| Task count | 1-3 | >3 |
+| Tech stacks | Single (PHP-only or TS-only) | Mixed (PHP + TS/React) |
+| Wave count | 1 | >1 |
+
+**If ANY signal is "Complex"**, the plan uses Agent Teams mode. All signals must be "Simple" for single-agent mode.
+
+Override with `--team` (force swarm) or `--single` (force single-agent).
+
+**Tech-stack routing** per task:
+
+| Task Stack | Agent(s) |
+|-----------|----------|
+| PHP only | jdi-backend |
+| TS/React only | jdi-frontend |
+| Full-stack | jdi-backend + jdi-frontend |
+| Config/docs | jdi-backend (default) |
+
+### PR Workflow
+
+JDI provides a complete PR lifecycle:
+
+**`/jdi:pr-review <number>`** — Structured code review with severity-classified findings:
+- Checks out the PR branch and reads all changed files in full
+- Applies a comprehensive checklist (correctness, security, performance, architecture, style, testing, type safety)
+- Classifies findings by severity (blocker, major, minor, suggestion, question, praise)
+- Posts all findings as line comments in a single atomic GitHub review
+- Supports `--no-comments` for local-only review (writes to `.jdi/reviews/`)
+- Supports focus areas and ClickUp context via additional arguments
+
+**`/jdi:pr-feedback <number>`** — Addresses review comments systematically, learning from team patterns.
+
+**`/jdi:generate-pr`** — Creates a PR with a structured description derived from the implementation plan and commits.
+
+### Verification and Quality Gates
+
+JDI runs multi-level verification after implementation:
+
+**Three-level verification** for every artefact:
+1. **Existence** — Does it exist at the expected path?
+2. **Substantive** — Is it real implementation, not a stub?
+3. **Wired** — Is it connected to the system (imported, registered, routed)?
+
+**Verification scopes:**
+
+| Scope | Verifies |
+|-------|----------|
+| `task` | Current task criteria and done conditions |
+| `plan` | All tasks + plan success criteria |
+| `phase` | All plans + phase must-haves |
+| `requirements` | All v1 requirements coverage |
+
+**Quality gates** run automatically:
+- `composer check-style` / `composer stan` / `composer test` (PHP)
+- `bun run lint` / `bun run typecheck` / `bun run test:vitest` (TypeScript)
+
+Backend tests are a **mandatory blocking gate** — verification fails if `composer test` fails.
+
+### Component System
+
+JDI uses a JSX-like component syntax for reusable instructions:
+
+```markdown
+<JDI:Commit />                      # Full component
+<JDI:Commit:Message />              # Specific section
+<JDI:Verify scope="plan" />         # With parameters
+<JDI:PRReview post="false" />       # Boolean parameter
+```
+
+Components are **lazy-loaded on-demand** by agents — not pre-embedded in commands. When an agent encounters a `<JDI:*>` tag, it reads the component file, executes the instructions, and returns to the calling context.
+
+**Available components:**
+
+| Component | Category | Purpose |
+|-----------|----------|---------|
+| `Commit` | execution | Create conventional commits |
+| `Verify` | execution | Multi-level verification |
+| `VerifyAdvanced` | execution | Phase and requirements verification |
+| `CodebaseContext` | execution | Load and cache codebase analysis |
+| `PRReview` | quality | Structured PR review with line comments |
+| `PRReviewLocal` | quality | Write review to local file |
+| `TaskBreakdown` | planning | Break features into tasks |
+| `WaveComputation` | planning | Compute dependency-ordered waves |
+| `AgentBase` | meta | Base protocol for all agents |
+| `AgentTeamsOrchestration` | meta | Agent Teams lifecycle management |
+| `ComplexityRouter` | meta | Route plans to single-agent or swarm |
+| `TeamRouter` | meta | Route commands to teams |
+| `StateUpdate` | meta | Update state.yaml fields |
+
+### Model Routing
+
+JDI routes different agents to different Claude models based on a configurable profile:
+
+| Profile | Description | Planner | Executor | Researcher | Verifier |
+|---------|-------------|---------|----------|------------|----------|
+| `quality` | Maximum reasoning power | Opus | Opus | Sonnet | Sonnet |
+| `balanced` | Smart allocation (default) | Opus | Sonnet | Sonnet | Sonnet |
+| `budget` | Conserve quota | Sonnet | Sonnet | Haiku | Haiku |
+
+Individual agents can be overridden in `jdi-config.yaml` regardless of the active profile.
+
+### State Management
+
+JDI tracks all progress in external YAML files (no context pollution):
+
+| File | Purpose |
+|------|---------|
+| `.jdi/config/state.yaml` | Runtime state — current phase, plan, task, progress, commits, blockers |
+| `.jdi/config/variables.yaml` | Shareable variables across agents |
+| `.jdi/config/jdi-config.yaml` | Global configuration (workflow, models, quality gates) |
+| `.jdi/PROJECT.yaml` | Project vision and constraints |
+| `.jdi/REQUIREMENTS.yaml` | Scoped requirements with REQ-IDs |
+| `.jdi/ROADMAP.yaml` | Phase structure and plan statuses |
+
+### PR Feedback Learning
+
+When processing PR comments, JDI detects learning phrases like:
+- "we usually do this"
+- "we prefer to"
+- "convention is"
+
+These patterns are automatically captured to learnings files in `.jdi/framework/learnings/` (categorised by backend, frontend, testing, devops, general) for future reference.
+
+---
+
+## Agents
+
+JDI has 16 specialised agents, each with a defined spec and clear boundaries:
+
+### Engineering
+
+| Agent | Role | Spec |
+|-------|------|------|
+| `jdi-backend` | Backend Engineer (PHP/Laravel) | `.jdi/framework/agents/jdi-backend.md` |
+| `jdi-frontend` | Frontend Engineer (React/TypeScript) | `.jdi/framework/agents/jdi-frontend.md` |
+| `jdi-architect` | Systems Architect | `.jdi/framework/agents/jdi-architect.md` |
+| `jdi-executor` | Senior Fullstack Engineer | `.jdi/framework/agents/jdi-executor.md` |
+
+### Product and Research
+
+| Agent | Role | Spec |
+|-------|------|------|
+| `jdi-planner` | Product Manager / Planner | `.jdi/framework/agents/jdi-planner.md` |
+| `jdi-researcher` | Senior Analyst | `.jdi/framework/agents/jdi-researcher.md` |
+| `jdi-product-lead` | Product Lead | `.jdi/framework/agents/jdi-product-lead.md` |
+| `jdi-ux-designer` | Lead UI/UX Designer | `.jdi/framework/agents/jdi-ux-designer.md` |
+
+### Quality Assurance
+
+| Agent | Role | Spec |
+|-------|------|------|
+| `jdi-quality` | Lead QA Developer | `.jdi/framework/agents/jdi-quality.md` |
+| `jdi-verifier` | Senior QA Developer | `.jdi/framework/agents/jdi-verifier.md` |
+
+### DevOps
+
+| Agent | Role | Spec |
+|-------|------|------|
+| `jdi-devops` | DevOps Engineer | `.jdi/framework/agents/jdi-devops.md` |
+
+### Supporting
+
+| Agent | Role | Spec |
+|-------|------|------|
+| `jdi-committer` | Commit specialist | `.jdi/framework/agents/jdi-committer.md` |
+| `jdi-pr-generator` | PR generation | `.jdi/framework/agents/jdi-pr-generator.md` |
+| `jdi-pr-feedback` | PR feedback handler | `.jdi/framework/agents/jdi-pr-feedback.md` |
+| `jdi-debugger` | Debugging specialist | `.jdi/framework/agents/jdi-debugger.md` |
+| `jdi-head-engineering` | Head of Engineering (oversight) | `.jdi/framework/agents/jdi-head-engineering.md` |
+
+All agents inherit the `<JDI:AgentBase />` protocol which defines sandbox awareness, structured returns, communication patterns, and component resolution.
+
+---
+
+## Teams
+
+Agents are organised into 5 teams, each with defined responsibilities and boundaries:
+
+| Team | Members | Purpose |
+|------|---------|---------|
+| **Engineering** | jdi-backend, jdi-frontend, jdi-architect, jdi-executor | All coding — features, bugs, refactoring across full stack |
+| **Product & Research** | jdi-planner, jdi-researcher, jdi-product-lead, jdi-ux-designer | Requirements, research, planning — does NOT write code |
+| **Quality Assurance** | jdi-quality, jdi-verifier | Testing (Pest/Vitest), verification, quality gates |
+| **DevOps** | jdi-devops | Docker, AWS, CI/CD, worktrees, infrastructure |
+| **Micro-Management** | jdi-product-lead, jdi-head-engineering | Engineering oversight — **opt-in only** via `--oversight` |
+
+### Team Routing
+
+Commands are automatically routed to the appropriate team:
+
+| Command | Primary Team | Pattern |
+|---------|-------------|---------|
+| `create-plan` | Product & Research | Sequential |
+| `implement-plan` | Engineering | Parallel |
+| `pr-review` | Quality Assurance | Parallel (with Engineering context) |
+| `pr-feedback` | Engineering | Sequential |
+| `commit` | Engineering | Direct (no team) |
+| `generate-pr` | Engineering | Direct (no team) |
+
+### Collaboration Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| **Sequential** | Primary team executes, writes state, next team reads state |
+| **Parallel (Oversight)** | Engineering executes; Micro-Management monitors and flags concerns |
+| **Parallel (Context)** | QA reviews code; Engineering provides context |
+| **Direct** | Single agent, single Task invocation, no team coordination |
+
+---
+
+## Configuration
+
+Global configuration lives in `.jdi/config/jdi-config.yaml`:
+
+```yaml
+# Workflow mode
+workflow:
+  mode: yolo          # yolo (autonomous) | interactive (confirm gates) | strict (all confirmations)
+  depth: standard     # shallow | standard | deep (task granularity)
+  parallelisation: true
+  commit_docs: true
+
+# Agent toggles
+agents:
+  research: true      # Run research before planning
+  plan_check: true    # Validate plans before execution
+  verifier: true      # Verify outcomes after execution
+
+# Model routing profile
+models:
+  profile: balanced   # quality | balanced | budget
+  overrides:
+    planner: null     # Override specific agents (opus | sonnet | haiku | null)
+    executor: null
+
+# Quality gates
+quality:
+  run_lint_before_commit: true
+  run_tests_before_pr: true
+  require_verification: true
+
+# Git settings
+git:
+  auto_stage: false
+  require_clean_worktree: false
+  protected_branches: [main, master, develop]
+
+# Context management
+context:
+  max_files_per_task: 5
+  split_threshold_tasks: 3
+  context_budget_warning: 0.5
+  context_budget_critical: 0.7
+```
+
+---
+
+## Directory Structure
+
+### Package Source (this repo)
+
+```
+src/                                 # CLI source (TypeScript)
+├── commands/                        # CLI commands (init, plan, status, components)
+├── utils/                           # Utilities (detect-project, state, resolve-components)
+└── index.ts                         # Entry point
+
+framework/                           # Distributable framework (single source of truth)
+├── agents/                          # Agent specifications (20 agents)
+├── commands/                        # Command stub templates (copied to .claude/commands/jdi/)
+├── components/                      # Reusable component instructions
+│   ├── execution/                   # Commit, Verify, CodebaseContext
+│   ├── planning/                    # TaskBreakdown, WaveComputation
+│   ├── quality/                     # PRReview, PRReviewLocal
+│   └── meta/                        # AgentBase, ComplexityRouter, TeamRouter, StateUpdate
+├── teams/                           # Team definitions (5 teams)
+├── adapters/                        # Project-type configs (laravel, nextjs, node, generic)
+├── config/                          # Configuration templates
+├── hooks/                           # Pre-commit, checkpoint, worktree cleanup
+├── rules/                           # Commit rules, deviation rules
+├── templates/                       # PLAN, PROJECT, REQUIREMENTS, ROADMAP templates
+├── learnings/                       # Empty category shells for PR review learnings
+└── jedi.md                          # Full framework architecture doc
+```
+
+### Installed in User Projects (via `jdi init`)
+
+```
+.jdi/framework/                        # Framework files (installed by jdi init)
+├── agents/                          # Agent specifications
+├── components/                      # Reusable component instructions
+├── teams/                           # Team definitions
+├── config/                          # Configuration templates
+├── hooks/                           # Pre-commit, checkpoint, worktree cleanup
+├── rules/                           # Commit rules, deviation rules
+├── templates/                       # Scaffolding templates
+├── learnings/                       # Patterns learned from PR reviews
+└── jedi.md                          # Full framework architecture doc
+
+.claude/commands/jdi/                # Slash command stubs (~300 tokens each)
+├── create-plan.md
+├── implement-plan.md
+├── quick.md
+├── commit.md
+├── generate-pr.md
+├── pr-review.md
+├── pr-feedback.md
+├── worktree.md
+├── worktree-remove.md
+├── init.md
+└── status.md
+
+.jdi/                                # Project state (created by /jdi:init)
+├── plans/                           # Implementation plans
+├── research/                        # Research documentation
+├── codebase/                        # Codebase analysis (SUMMARY.md)
+├── reviews/                         # Local PR reviews (when --no-comments)
+├── config/
+│   ├── state.yaml                   # Runtime state
+│   ├── variables.yaml               # Shared variables
+│   ├── jdi-config.yaml              # Global config
+│   └── adapter.yaml                 # Project-type adapter config
+├── PROJECT.yaml                     # Project context
+├── REQUIREMENTS.yaml                # Scoped requirements
+└── ROADMAP.yaml                     # Phase structure
+```
+
+---
+
+## Architecture
+
+JDI is built on three core principles:
+
+### Minimal Context
+
+Commands are ultra-minimal stubs (~300 tokens). Heavy specs, components, and rules stay out of the main context window. Agents read what they need on-demand in their isolated context.
+
+| Scenario | Without JDI | With JDI | Savings |
+|----------|-------------|----------|---------|
+| Single command | ~6,900 tokens | ~300 tokens | 95% |
+| 5-command workflow | ~34,500 tokens | ~1,500 tokens | 96% |
+
+### Agent Delegation
+
+Complex operations spawn agents via the Task tool. Each agent runs in an isolated context with its own spec, components, and rules. The orchestrator stays lightweight.
+
+```
+┌─────────────────────────────────────────────┐
+│ MAIN CONTEXT                                │
+│                                             │
+│  User: /jdi:create-plan "Add user auth"     │
+│         │                                   │
+│         ▼                                   │
+│  ┌──────────────────────┐                   │
+│  │ Command Stub (~300)  │                   │
+│  └──────────┬───────────┘                   │
+│             │ Task tool spawns agent         │
+│             ▼                               │
+└─────────────────────────────────────────────┘
+              │
+              ▼
+┌─────────────────────────────────────────────┐
+│ AGENT CONTEXT (Isolated, Fresh)             │
+│                                             │
+│  jdi-planner reads spec, researches,        │
+│  creates plan → Returns result to main      │
+└─────────────────────────────────────────────┘
+```
+
+### External State
+
+All state lives in YAML files on disk. No context pollution from state tracking. Agents read state when they need it and report updates for the orchestrator to write.
+
+---
+
+*Jedi — Context-efficient development through agent delegation.*