@benzotti/jedi 0.1.29 → 0.1.30

package/README.md

@@ -1,30 +1,4 @@
-  ```
-    ⠀⠀⠀⠀⠀⠀⠀⠀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-    ⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-    ⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-    ⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-    ⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-    ⠀⠀⠀⠀⠠⠀⠀⠀⡇⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-    ⠀⠀⠀⠀⠀⠈⠳⣴⣿⠄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-    ⠀⠒⠒⠒⠒⠒⢺⢿⣿⢗⠒⠒⠒⠒⠒⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-    ⠀⠀⠀⠀⠀⠀⠁⣸⣿⣦⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-    ⠀⠀⠀⠀⠀⢀⣾⡟⠋⢹⣷⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-    ⠀⠀⠀⠀⢀⣿⡟⣴⣶⡄⣿⣧⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-    ⠀⠀⠀⢰⣿⣿⣧⢻⣿⣿⣿⣿⡟⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-    ⠀⠀⠀⠈⢻⣿⣿⣷⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-    ⠀⠀⠀⠀⢸⠿⣿⣿⣿⣿⣿⣿⣦⣤⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-    ⠀⠀⠀⠀⣾⠀⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣶⣤⡀⠀⠀⠀⠀⠀
-    ⠀⠀⠀⠀⣿⣏⣻⣿⣿⣿⣿⣿⠋⣿⣿⣿⣿⣿⠙⣿⣷⣶⣤⣤⡄
-    ⠀⠀⠀⠀⢻⢇⣿⣿⣿⣿⣿⠹⠀⢹⣿⣿⣿⡇⠀⢟⣿⣿⡿⠋⠀
-    ⠀⠀⠀⠀⢘⣼⣿⣿⣿⣿⣿⡆⠀⢸⣿⠛⣿⡇⠀⢸⡿⠋⠀⠀⠀
-    ⠀⠀⠀⠀⣾⣿⣿⣿⣿⣿⣿⣿⣦⣈⠻⠴⠟⣁⣴⣿⣿⠗⠀⠀⠀
-    ⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠋⠀⠀⠀⠀
-    ⠀⠀⢀⣿⣿⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠁⠀⠀⠀⠀⠀
-    ⠀⠀⣾⣿⡏⠀⠹⣿⠿⠿⠿⠿⣿⣿⣿⠿⠛⠁⠀⠀⠀⠀⠀⠀⠀
-    ⠀⢰⣿⡿⠀⠀⠀⠀⠀⠀⠀⠀⠀⢿⣿⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀
-    ⠀⣿⣿⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⣿⣧⠀⠀⠀⠀⠀⠀⠀⠀⠀
-    ⣰⣿⡏⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢿⣿⣄⠀⠀⠀⠀⠀⠀⠀⠀
-    ⠉⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠉⠉⠀⠀⠀⠀⠀⠀⠀⠀
+```
      ██╗███████╗██████╗ ██╗
      ██║██╔════╝██╔══██╗██║
      ██║█████╗  ██║  ██║██║
@@ -33,281 +7,262 @@
  ╚════╝ ╚══════╝╚═════╝ ╚═╝
 ```
 
-# JDI Framework
+**Context-efficient AI development framework for Claude Code.**
+
+[![npm version](https://img.shields.io/npm/v/@benzotti/jedi)](https://www.npmjs.com/package/@benzotti/jedi) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-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.
+Jedi orchestrates specialised agents to plan, implement, review, and ship features — from single-file fixes to full-stack multi-wave implementations. It runs in three modes: **Claude Code app**, **CLI**, and **GitHub Actions**.
 
 ---
 
 ## Table of Contents
 
+- [Usage Modes](#usage-modes)
 - [Getting Started](#getting-started)
 - [Commands](#commands)
+- [GitHub Actions Setup](#github-actions-setup)
 - [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)
+- [Security](#security)
 - [Directory Structure](#directory-structure)
 - [Architecture](#architecture)
 
 ---
 
-## Getting Started
-
-### 1. Install JDI
-
-```bash
-bun install -g @benzotti/jedi
-```
-
-Then initialise in your project:
+## Usage Modes
 
-```bash
-jdi init
-```
-
-Or run the init command directly inside Claude Code:
+Jedi runs in three modes with identical capabilities:
 
-```
-/jdi:init
-```
+| 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 Jedi plan ...` on issues/PRs | Autonomous code generation from issue comments |
 
-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).
+## Getting Started
 
-### 2. Plan a Feature
+### Claude Code App
 
-```
-/jdi:create-plan "PROJ-1234 Add user authentication"
+```bash
+bun install -g @benzotti/jedi
+jdi init
 ```
 
-JDI spawns a planner agent that researches your codebase, then produces a structured implementation plan at `.jdi/plans/`.
-
-### 3. Implement the Plan
-
+Then inside Claude Code:
 ```
+/jdi:create-plan "Add user authentication"
 /jdi:implement-plan
+/jdi:commit
+/jdi:generate-pr
 ```
 
-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.
+### CLI
 
-### 4. Commit and Ship
+```bash
+bun install -g @benzotti/jedi
+jdi init
 
+jdi plan "Add user authentication"
+jdi implement
+jdi quick "fix the broken quote calculator"
+jdi review 42
+jdi pr
 ```
-/jdi:commit
-/jdi:generate-pr
-```
-
-Create conventional commits and generate a PR with a structured description.
 
-### Quick Changes
+### GitHub Actions
 
-For small, focused changes that don't need full orchestration:
+```bash
+jdi setup-action
+```
 
+Then on any issue or PR, comment:
 ```
-/jdi:quick "fix the broken quote calculator"
+Hey Jedi plan Add user authentication
+Hey Jedi implement
+Hey Jedi quick fix the broken login button
 ```
 
-Executes directly in the main context — no agent spawn, no team, no waves.
+See [GitHub Actions Setup](#github-actions-setup) for details.
 
 ---
 
 ## 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`
-
+| Slash Command | CLI Equivalent | Description |
+|---------------|----------------|-------------|
+| `/jdi:init` | `jdi init` | Initialise Jedi 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 |
 |------|-------------|
-| `--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`
+| `--print` | Print prompt to stdout instead of executing |
+| `--output <file>` | Write prompt to file |
 
+#### `jdi implement`
 | 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`
+| `--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 |
 |------|-------------|
-| `--lightweight` | Skip databases, web server setup — just deps and migrate |
-| `--base <branch>` | Base branch to create worktree from (default: `master`) |
-
-#### `/jdi:worktree-remove`
+| `--dry-run` | Preview changes without writing files |
+| `--print` | Print prompt to stdout |
 
+#### `jdi pr`
 | Flag | Description |
 |------|-------------|
-| `--force` | Skip confirmation prompt |
-| `--keep-branch` | Don't delete the git branch after removal |
+| `--draft` | Create as draft PR |
+| `--base <branch>` | Base branch (default: main) |
+| `--no-push` | Skip pushing the branch |
+| `--dry-run` | Show generated PR without creating |
 
-#### `/jdi:init`
+---
 
-| Flag | Description |
-|------|-------------|
-| `--force` | Overwrite all existing command stubs |
+## GitHub Actions Setup
 
----
+### Installation
 
-## Features
+Run `jdi setup-action` to generate the workflow file, or manually copy `action/workflow-template.yml` to `.github/workflows/jedi.yml`.
 
-### Planning and Implementation
+### Required Secrets
 
-JDI follows a plan-then-execute workflow:
+| Secret | Required | Description |
+|--------|----------|-------------|
+| `ANTHROPIC_API_KEY` | Yes | Claude API key |
+| `CLICKUP_API_TOKEN` | No | ClickUp integration for ticket-driven development |
 
-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.
+### Optional Variables
 
-Plans are written to `.jdi/plans/{phase}-{plan}-PLAN.md` and can be reviewed before execution.
+| Variable | Description |
+|----------|-------------|
+| `JEDI_AUTH_ENABLED` | Set to `true` to restrict Jedi to write collaborators |
+| `JEDI_ALLOWED_USERS` | Comma-separated list of allowed GitHub usernames |
 
-### Git Worktrees
+### Comment Syntax
 
-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:
+| Command | Description |
+|---------|-------------|
+| `Hey Jedi plan <description>` | Create an implementation plan |
+| `Hey Jedi implement` | Execute the current plan |
+| `Hey Jedi implement --dry-run` | Preview implementation without writing |
+| `Hey Jedi quick <description>` | Make a quick change |
+| `Hey Jedi review` | Review the current PR |
+| `Hey Jedi do <clickup-url>` | Full flow: plan + implement from ticket |
+| `Hey Jedi ping` | Check framework status |
 
-**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
+### Conversation Flow
 
-**Lightweight worktree** (`--worktree-lightweight`):
-- Installs dependencies and runs migrations only
-- Skips databases, web server setup, seeders, and post-setup
+1. Comment `Hey Jedi plan ...` to start planning
+2. Jedi posts the plan and asks for feedback
+3. Reply with refinement feedback (e.g. "change task 2 to use Redis instead")
+4. Say "approved" or "lgtm" to lock the plan
+5. Comment `Hey Jedi implement` to execute
+6. Reply with follow-up feedback to iterate on the implementation
 
-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.
+Jedi maintains conversation context across comments — no need to repeat earlier instructions.
 
-### Agent Teams
+---
+
+## Features
 
-For complex plans, JDI uses Claude Code's native Agent Teams to orchestrate multiple specialist agents working in parallel:
+### Planning and Implementation
 
-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
+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
 
-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.
+### Dry-Run Mode
 
-### Complexity Router
+Preview what Jedi would change without writing any files:
 
-The complexity router (`<JDI:ComplexityRouter />`) evaluates the plan and decides the execution mode:
+```bash
+jdi implement --dry-run
+jdi quick --dry-run "add error handling to the API"
+```
 
-| Signal | Simple | Complex |
-|--------|--------|---------|
-| Task count | 1-3 | >3 |
-| Tech stacks | Single (PHP-only or TS-only) | Mixed (PHP + TS/React) |
-| Wave count | 1 | >1 |
+Or in GitHub Actions: `Hey Jedi implement --dry-run`
 
-**If ANY signal is "Complex"**, the plan uses Agent Teams mode. All signals must be "Simple" for single-agent mode.
+In dry-run mode, Jedi can only read files — writes, commits, and pushes are blocked.
 
-Override with `--team` (force swarm) or `--single` (force single-agent).
+### Plan-Aware PR Generation
 
-**Tech-stack routing** per task:
+`jdi pr` reads the current plan from state.yaml and generates a richer PR body:
+- Summary derived from the plan objective
+- Task list from the plan breakdown
+- Verification checklist from plan criteria
 
-| Task Stack | Agent(s) |
-|-----------|----------|
-| PHP only | jdi-backend |
-| TS/React only | jdi-frontend |
-| Full-stack | jdi-backend + jdi-frontend |
-| Config/docs | jdi-backend (default) |
+### Automated Verification Runner
 
-### PR Workflow
+After implementation (both CLI and GitHub Actions), Jedi automatically runs quality gates defined in `adapter.yaml`:
 
-JDI provides a complete PR lifecycle:
+```yaml
+quality_gates:
+  lint: "bun run lint"
+  typecheck: "bun run typecheck"
+  test: "bun test"
+```
 
-**`/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
+Results are printed in the CLI and posted as a collapsible section in GitHub comments.
 
-**`/jdi:pr-feedback <number>`** — Addresses review comments systematically, learning from team patterns.
+### Git Worktrees
+
+Full-environment git worktrees for isolated development:
 
-**`/jdi:generate-pr`** — Creates a PR with a structured description derived from the implementation plan and commits.
+- **Full worktree** (`--worktree`): databases, dependencies, migrations, seeders, web server
+- **Lightweight worktree** (`--worktree-lightweight`): dependencies and migrations only
 
-### Verification and Quality Gates
+### Agent Teams
 
-JDI runs multi-level verification after implementation:
+For complex plans (>3 tasks, multiple tech stacks, or multiple waves), Jedi uses Claude Code's Agent Teams to orchestrate multiple specialist agents working in parallel.
 
-**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)?
+### Complexity Router
 
-**Verification scopes:**
+| Signal | Simple | Complex |
+|--------|--------|---------|
+| Task count | 1-3 | >3 |
+| Tech stacks | Single | Mixed |
+| Wave count | 1 | >1 |
 
-| 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 |
+Override with `--team` or `--single`.
 
-**Quality gates** run automatically:
-- `composer check-style` / `composer stan` / `composer test` (PHP)
-- `bun run lint` / `bun run typecheck` / `bun run test:vitest` (TypeScript)
+### PR Workflow
 
-Backend tests are a **mandatory blocking gate** — verification fails if `composer test` fails.
+- **`jdi review <pr>`** — Structured code review with severity-classified findings posted as line comments
+- **`jdi feedback`** — Address review comments systematically, learning from team patterns
+- **`jdi pr`** — Create a PR with plan-aware description
 
 ### Component System
 
-JDI uses a JSX-like component syntax for reusable instructions:
+JSX-like reusable instruction syntax:
 
 ```markdown
 <JDI:Commit />                      # Full component
-<JDI:Commit:Message />              # Specific section
 <JDI:Verify scope="plan" />         # With parameters
-<JDI:PRReview post="false" />       # Boolean parameter
+<JDI:PRReview post="false" />       # Local review mode
 ```
 
-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 |
@@ -316,300 +271,168 @@ Components are **lazy-loaded on-demand** by agents — not pre-embedded in comma
 | `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 |
+| `PRReview` | quality | Structured PR review (remote and local modes) |
 | `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.
+| `StateUpdate` | meta | Record decisions, deviations, blockers |
 
 ### State Management
 
-JDI tracks all progress in external YAML files (no context pollution):
+All state lives in YAML files on disk — 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 |
+| `.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) |
 
 ### 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.
+Jedi detects learning phrases from PR reviews ("we usually do this", "convention is") and captures them to categorised learnings files in `.jdi/framework/learnings/` for future reference.
 
 ---
 
 ## Agents
 
-JDI has 16 specialised agents, each with a defined spec and clear boundaries:
+20 specialised agents organised by team:
 
 ### 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` |
+| Agent | Role |
+|-------|------|
+| `jdi-backend` | Backend Engineer |
+| `jdi-frontend` | Frontend Engineer |
+| `jdi-architect` | Systems Architect |
+| `jdi-executor` | Senior Fullstack Engineer |
 
 ### 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` |
+| 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 | Spec |
-|-------|------|------|
-| `jdi-quality` | Lead QA Developer | `.jdi/framework/agents/jdi-quality.md` |
-| `jdi-verifier` | Senior QA Developer | `.jdi/framework/agents/jdi-verifier.md` |
+| Agent | Role |
+|-------|------|
+| `jdi-quality` | Lead QA Developer |
+| `jdi-verifier` | Senior QA Developer |
 
 ### DevOps
-
-| Agent | Role | Spec |
-|-------|------|------|
-| `jdi-devops` | DevOps Engineer | `.jdi/framework/agents/jdi-devops.md` |
+| Agent | Role |
+|-------|------|
+| `jdi-devops` | DevOps Engineer |
 
 ### 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.
+| 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 |
+
+All agents inherit `<JDI:AgentBase />` which defines sandbox awareness, structured returns, 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 |
+| **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 |
+| **Micro-Management** | product-lead, head-engineering | Oversight (opt-in) |
 
 ---
 
 ## Configuration
 
-Global configuration lives in `.jdi/config/jdi-config.yaml`:
+Global configuration 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
+  mode: yolo          # yolo | interactive | strict
+  depth: standard     # shallow | standard | deep
+
 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
+## Security
+
+Jedi v0.1.30 includes several security hardening measures:
 
-### Package Source (this repo)
+- **Opt-in authorization gate**: Restrict Jedi to write collaborators or an explicit allow-list via `JEDI_AUTH_ENABLED` and `JEDI_ALLOWED_USERS` repo variables
+- **Prompt injection defense**: User input is sanitized (injection preambles stripped) and wrapped in XML fences with untrusted-content warnings
+- **Shell injection prevention**: All workflow arguments are individually quoted — no unquoted variable expansion
+- **Comment pagination limits**: Comment fetching is bounded to 100 items
+- **Storage path traversal prevention**: Storage keys with path traversal characters are rejected
+- **YAML state management**: State updates use a proper YAML parser instead of regex
+
+---
+
+## Directory Structure
 
 ```
 src/                                 # CLI source (TypeScript)
-├── commands/                        # CLI commands (init, plan, status, components)
-├── utils/                           # Utilities (detect-project, state, resolve-components)
+├── commands/                        # CLI commands
+├── utils/                           # Utilities (prompt-builder, state, verify, sanitize)
+├── storage/                         # Pluggable storage adapters
 └── index.ts                         # Entry point
 
-framework/                           # Distributable framework (single source of truth)
+framework/                           # Distributable framework
 ├── agents/                          # Agent specifications (20 agents)
-├── commands/                        # Command stub templates (copied to .claude/commands/jdi/)
+├── commands/                        # Command stub templates
 ├── components/                      # Reusable component instructions
 │   ├── execution/                   # Commit, Verify, CodebaseContext
 │   ├── planning/                    # TaskBreakdown, WaveComputation
-│   ├── quality/                     # PRReview, PRReviewLocal
+│   ├── quality/                     # PRReview
 │   └── 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`)
+├── adapters/                        # Project-type configs
+├── templates/                       # PLAN, PLAN-TASK, SUMMARY, CLAUDE-SHARED, PROJECT/REQUIREMENTS/ROADMAP.yaml
+├── learnings/                       # Category shells for PR review learnings
+└── jedi.md                          # Framework architecture doc
 
-```
-.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
+action/                              # GitHub Actions
+└── workflow-template.yml            # Workflow template for `jdi setup-action`
 ```
 
 ---
 
 ## 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.
+Commands are ultra-minimal stubs (~300 tokens). Agents read specs and components on-demand in their isolated context. Take this with a grain of salt 🧂.
 
-| Scenario | Without JDI | With JDI | Savings |
+| Scenario | Without Jedi | With Jedi | 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      │
-└─────────────────────────────────────────────┘
-```
+Complex operations spawn agents via the Task tool. Each agent runs in an isolated context with its own spec and components.
 
 ### 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.
+All state lives in YAML files on disk. No context pollution from state tracking.
 
 ---
-
-*Jedi — Context-efficient development through agent delegation.*