@benzotti/jedi 0.1.0

package/framework/jedi.md

@@ -0,0 +1,336 @@
+---
+description: Entry Point and Architecture for the Jedi (JDI) framework
+model: opus
+---
+
+# Jedi (JDI) Framework
+
+**Entry Point** | Componentised prompts, Context-efficient, agent-delegated development framework.
+
+---
+
+## Core Principles
+
+| Principle | Description |
+|-----------|-------------|
+| **Minimal Context** | Commands are ultra-minimal stubs (~300 tokens). Heavy specs stay out of main context. |
+| **Agent Delegation** | Complex operations spawn agents via Task tool. Agents run in isolated context. |
+| **External State** | All state in JSON files. No context pollution from state tracking. |
+| **On-Demand Reading** | Agents read specs, components, hooks, and rules only when needed. |
+
+---
+
+## Critical Constraints
+
+> **WARNING: Task Tool `subagent_type` Parameter**
+>
+> The Claude Code Task tool **ONLY accepts `subagent_type="general-purpose"`** as a valid value.
+>
+> **If you use any other value** (e.g., `"jdi-executor"`, `"jdi-planner"`, or any custom type),
+> the agent will fail with this error:
+>
+> ```
+> classifyHandoffIfNeeded is not defined
+> ```
+
+### Correct Pattern
+
+Agent identity is passed via the **prompt parameter**, NOT the `subagent_type` parameter:
+
+```
+Task(
+  prompt="You are jdi-executor. Read .jdi/framework/agents/jdi-executor.md for instructions. Execute: {task}",
+  subagent_type="general-purpose"   ← MUST be "general-purpose"
+)
+```
+
+### Incorrect Pattern (WILL FAIL)
+
+```
+Task(
+  prompt="Execute the plan...",
+  subagent_type="jdi-executor"      ← WRONG: Causes classifyHandoffIfNeeded error
+)
+```
+
+### Why This Matters
+
+- The Task tool validates `subagent_type` against a fixed list
+- Only `"general-purpose"` is in that list
+- Any other value triggers an internal validation error
+- The cryptic `classifyHandoffIfNeeded is not defined` message masks this validation failure
+
+---
+
+## How It Works
+
+```
+┌──────────────────────────────────────────────────────┐
+│ MAIN CONTEXT                                          │
+│                                                       │
+│  User: /jdi:create-plan "Add user auth"              │
+│         │                                             │
+│         ▼                                             │
+│  ┌──────────────────────┐                            │
+│  │ Command Stub (~300)  │ ← Minimal stub             │
+│  └──────────┬───────────┘                            │
+│             │ Task tool spawns agent                  │
+│             ▼                                         │
+└──────────────────────────────────────────────────────┘
+              │
+              ▼
+┌──────────────────────────────────────────────────────┐
+│ AGENT CONTEXT (Isolated, Fresh)                       │
+│                                                       │
+│  jdi-planner reads spec, researches, creates plan    │
+│  → Returns plan_path to main context                  │
+└──────────────────────────────────────────────────────┘
+```
+
+**create-plan:** Single planner agent (includes research as Step 0).
+**implement-plan:** Complexity-routed — single agent for simple plans, Agent Teams swarm for complex plans.
+
+---
+
+## Available Commands
+
+| Command | Type | Description |
+|---------|------|-------------|
+| `/jdi:init` | Direct | Initialise JDI in current project |
+| `/jdi:create-plan` | Agent | Create implementation plan (single planner agent, includes research) |
+| `/jdi:implement-plan` | Agent | Execute plan (single agent for simple, Agent Teams for complex) |
+| `/jdi:commit` | Agent | Create conventional commit (spawns jdi-committer) |
+| `/jdi:generate-pr` | Agent | Generate and create PR (spawns jdi-pr-generator) |
+| `/jdi:pr-review` | Agent | Review PR (spawns reviewer) |
+| `/jdi:pr-feedback` | Agent | Address PR review comments (spawns jdi-pr-feedback) |
+| `/jdi:quick` | Direct | Quick focused change (no orchestration) |
+| `/jdi:map-codebase` | Agent | Analyse codebase architecture and conventions (spawns jdi-codebase-mapper) |
+| `/jdi:verify` | Agent | Run verification checks (spawns jdi-verifier) |
+
+**Agent commands:** Spawn a Task agent with isolated context (~300 tokens in main)
+**Direct commands:** Execute in main context (kept minimal)
+
+---
+
+## Component System
+
+JDI uses **JSX-like component syntax** for referencing reusable markdown:
+
+```markdown
+<JDI:Commit />                    # Full component
+<JDI:Commit:Message />            # Specific section
+<JDI:Commit scope="task" />       # With parameters
+```
+
+**How it works:** When agents encounter component references, they:
+1. Read the component file from `components/`
+2. Execute the instructions within
+3. Return to the calling context
+
+Components are **loaded on-demand** by agents, not pre-embedded in commands.
+
+---
+
+## Component Resolution Protocol
+
+**CRITICAL**: When you encounter a `<JDI:ComponentName />` tag anywhere in a spec,
+command, hook, or workflow, you MUST:
+
+1. **Parse** the tag to extract the component name, optional section, and parameters.
+   - `<JDI:Commit />` -> Component: Commit, Section: (none), Params: (none)
+   - `<JDI:StateUpdate:Progress />` -> Component: StateUpdate, Section: Progress, Params: (none)
+   - `<JDI:Commit scope="task" />` -> Component: Commit, Section: (none), Params: scope=task
+
+2. **Locate** the component file by searching these directories in order:
+   - `.jdi/framework/components/execution/{ComponentName}.md`
+   - `.jdi/framework/components/planning/{ComponentName}.md`
+   - `.jdi/framework/components/quality/{ComponentName}.md`
+   - `.jdi/framework/components/meta/{ComponentName}.md`
+
+3. **Read** the component file using the Read tool.
+
+4. **Execute** the instructions found in the component (or the specified section).
+   Apply any parameters from the tag as contextual constraints.
+
+5. **Return** to the calling context and continue execution.
+
+Component tags are NOT decorative markers. They are lazy-loaded instructions
+that MUST be resolved and executed at the point where they appear.
+
+---
+
+## State Management
+
+### JSON State Files
+
+| File | Purpose | Updates |
+|------|---------|---------|
+| `config/jdi-config.yaml` | Global settings | Manual |
+| `config/state.yaml` | Runtime state (phase, plan, task) | Automatic |
+| `config/variables.yaml` | Shareable variables | Automatic |
+
+### Project State Files
+
+When initialised in a project (`.jdi/`):
+
+| File | Purpose |
+|------|---------|
+| `PROJECT.yaml` | Project vision and constraints |
+| `REQUIREMENTS.yaml` | Scoped requirements with REQ-IDs |
+| `ROADMAP.yaml` | Phase structure |
+| `STATE.md` | Living memory across sessions |
+
+---
+
+## Context Budget
+
+| Scenario | Old Pattern | New Pattern | Savings |
+|----------|-------------|-------------|---------|
+| Single command | ~6,900 tokens | ~300 tokens | 95% |
+| 5-command workflow | ~34,500 tokens | ~1,500 tokens | 96% |
+
+**Target:** Keep main context usage minimal. Let agents do heavy work in isolated context.
+
+### Warning Thresholds
+
+| Usage | Status | Action |
+|-------|--------|--------|
+| <50% | Green | Normal operation |
+| 50-70% | Yellow | Reduce verbosity |
+| 70-85% | Orange | Essential only |
+| >85% | Red | Complete task and pause |
+
+### No Direct Fallback Rule
+
+Agent commands MUST use agent delegation. If agent spawning fails: report error, set state to "blocked", ask user for guidance. NEVER fall back to direct implementation.
+
+---
+
+## Model Profiles
+
+Three profiles control which model each agent uses. Set in `.jdi/config/jdi-config.yaml` under `models.profile`.
+
+| Profile | When to Use | Opus Agents | Token Impact |
+|---------|-------------|-------------|--------------|
+| **quality** | Critical/complex work | planner, architect, executor, debugger | Highest — full Opus power |
+| **balanced** | Typical development (default) | planner, architect | ~40% less than quality |
+| **budget** | Conserve quota | None | ~60% less than quality |
+
+**Budget mode** routes verifier, researcher, phase_researcher, plan_checker, and quality to Haiku — these are agents where thoroughness matters less than speed. Switch mid-session by editing `models.profile` in `.jdi/config/jdi-config.yaml`.
+
+---
+
+## Quick Start
+
+### New Feature
+
+```
+1. /jdi:create-plan "Add user authentication"
+   → Spawns single planner agent (researches + plans)
+   → Creates .jdi/plans/01-01-PLAN.md
+
+2. /jdi:implement-plan
+   → Routes by complexity (single agent or Agent Teams swarm)
+   → Commits per task
+
+3. /jdi:generate-pr
+   → Creates PR with structured description
+```
+
+### Quick Commit
+
+```
+1. [Make changes]
+
+2. /jdi:commit
+   → Stages files individually
+   → Creates conventional commit
+```
+
+---
+
+## Bootstrap
+
+To add JDI commands to a project:
+
+```
+/jdi:init
+```
+
+This creates:
+- `.claude/commands/jdi/` — Command stubs
+- `.jdi/` — Project state directory
+
+---
+
+## Core Rules
+
+1. **Commands are stubs** — Just spawn instructions, not full specs
+2. **Agents read on-demand** — Load what they need in their context
+3. **State is external** — YAML files, not context pollution
+4. **Components are modular** — Reusable across agents
+5. **Atomic commits** — One commit per task, staged individually
+
+---
+
+## Prompt Cache Strategy
+
+Agent spawn prompts MUST follow this load order to maximise Anthropic API prompt cache hits:
+
+```
+1. AgentBase (core)        ← ALWAYS first (static, cacheable prefix ~180 tokens)
+2. AgentBase sections      ← Sandbox/TeamMode if needed (still static)
+3. Agent spec              ← Agent-specific instructions (semi-static)
+4. Task context            ← Plan path, working directory, task details (dynamic)
+```
+
+**Why**: The API caches prompt prefixes. By loading AgentBase as the first ~180 tokens of every agent prompt, all agents after the first get that prefix cached. Subsequent agents in the same session benefit from reduced input billing.
+
+**Batch component loading**: If an agent's spec has `requires_components` in its frontmatter, read ALL listed components before starting execution. This batches file reads into a single turn rather than discovering components mid-execution (saves ~50-100 tokens of tool overhead per component).
+
+---
+
+## Context Longevity
+
+### When to Start a Fresh Conversation
+
+| Signal | Action |
+|--------|--------|
+| 3+ agent spawns in one conversation | Consider fresh conversation |
+| 50+ turns in conversation | Start fresh — history compounds costs |
+| After `/jdi:implement-plan` completes | Fresh conversation for PR/commit (state persisted to YAML) |
+| Context budget at Orange/Red | Complete current task, then fresh conversation |
+
+**Why**: Each turn re-sends the full conversation history. Later turns cost progressively more tokens. Since JDI persists all state to YAML files, a fresh conversation loses nothing.
+
+---
+
+## Token Budget Reference
+
+### Per-Artefact Estimates
+
+| Artefact | Tokens |
+|----------|--------|
+| AgentBase (core) | ~180 |
+| AgentBase (core + sandbox) | ~320 |
+| Average agent spec | ~180 |
+| Component section | ~100-200 |
+| Full component | ~400-600 |
+| Template section | ~50-100 |
+| State read | ~200 |
+
+### Per-Workflow Estimates
+
+| Workflow | Main Context | Agent Context |
+|----------|-------------|---------------|
+| `/jdi:quick` | ~200 tokens | — (direct) |
+| `/jdi:commit` | ~500 tokens | ~400 (haiku) |
+| `/jdi:create-plan` | ~800 tokens | ~2,000 |
+| `/jdi:implement-plan` (simple) | ~800 tokens | ~3,000 |
+| `/jdi:implement-plan` (teams) | ~800 tokens | ~2,000 × N |
+
+**If approaching limits**: Switch to `budget` model profile and use section-specific component loading (`<JDI:Component:Section />`).
+
+---
+
+*Jedi - Context-efficient development through agent delegation.*

package/framework/learnings/backend.md

@@ -0,0 +1,3 @@
+# Backend Rules
+
+<!-- Learnings from PR reviews will be captured here automatically -->

package/framework/learnings/devops.md

@@ -0,0 +1,3 @@
+# DevOps Learnings
+
+<!-- Rules extracted from PR reviews about infrastructure, CI/CD, Docker, and deployment patterns -->

package/framework/learnings/frontend.md

@@ -0,0 +1,3 @@
+# Frontend Rules
+
+<!-- Learnings from PR reviews will be captured here automatically -->

package/framework/learnings/general.md

@@ -0,0 +1,3 @@
+# General Learnings
+
+<!-- Rules extracted from PR reviews about cross-cutting concerns, process, and conventions -->

package/framework/learnings/testing.md

@@ -0,0 +1,3 @@
+# Testing Learnings
+
+<!-- Rules extracted from PR reviews about testing patterns, quality standards, and test conventions -->

package/framework/rules/commit-rules.md

@@ -0,0 +1,24 @@
+---
+name: commit-rules
+description: Standards for creating commits within JDI workflow
+---
+
+# Commit Rules
+
+For full commit instructions, see `<JDI:Commit />` component at `.jdi/framework/components/execution/Commit.md`.
+
+---
+
+## Quick Reference
+
+**Format:** `{type}({scope}): {description}` — imperative mood, no period, max 72 chars.
+
+**Types:** `feat` | `fix` | `refactor` | `docs` | `test` | `chore` | `perf` | `style`
+
+**Scope:** Plan tasks use `{phase}-{plan}-T{n}`. Standalone commits use feature area (e.g., `auth`, `api`).
+
+**Staging:** Always stage files individually. NEVER use `git add .`, `git add -A`, or glob patterns.
+
+**Atomic:** One task = one commit. Each commit must represent a shippable state.
+
+**Pre-commit:** Verify staged files (`git diff --cached --name-only`), run quality checks before committing.

package/framework/rules/deviation-rules.md

@@ -0,0 +1,221 @@
+---
+name: deviation-rules
+description: How to handle deviations from plans during execution
+---
+
+# Deviation Rules
+
+How to handle unexpected situations during plan execution.
+
+---
+
+## Core Principle
+
+Plans are guides, not rigid scripts. Real-world execution reveals new information.
+Handle deviations systematically, not randomly.
+
+---
+
+## The Four Rules
+
+### Rule 1: Auto-Fix Bugs
+
+**Trigger:** Bug discovered during implementation
+
+**Action:**
+1. Fix the bug immediately
+2. Track in deviation log
+3. Continue execution
+
+**Example:**
+```
+Found: TypeError in existing code while adding new feature
+Action: Fixed the TypeError
+Track: Added to deviations with Rule 1 tag
+Continue: Resumed task execution
+```
+
+**What qualifies:**
+- Type errors
+- Null pointer issues
+- Logic errors in existing code
+- Broken imports
+
+### Rule 2: Auto-Add Critical Functionality
+
+**Trigger:** Missing functionality that's essential for task completion
+
+**Action:**
+1. Add the missing piece
+2. Track in deviation log
+3. Continue execution
+
+**Example:**
+```
+Found: Form component needs validation that doesn't exist
+Action: Added validation utility
+Track: Added to deviations with Rule 2 tag
+Continue: Used validation in form, completed task
+```
+
+**What qualifies:**
+- Missing utility functions
+- Required helper components
+- Essential type definitions
+- Necessary API helpers
+
+### Rule 3: Auto-Fix Blocking Issues
+
+**Trigger:** Issue that prevents task completion
+
+**Action:**
+1. Fix the blocking issue
+2. Track in deviation log
+3. Continue execution
+
+**Example:**
+```
+Found: Test failing due to outdated mock
+Action: Updated mock to match current API
+Track: Added to deviations with Rule 3 tag
+Continue: Tests pass, completed task
+```
+
+**What qualifies:**
+- Configuration issues
+- Environment problems
+- Dependency conflicts
+- Test infrastructure issues
+
+### Rule 4: STOP for Architectural Changes
+
+**Trigger:** Proposed change would alter system architecture
+
+**Action:**
+1. **STOP** execution immediately
+2. Present the situation to user
+3. Await decision before continuing
+
+**Example:**
+```
+Found: Task requires changing database schema
+Action: STOPPED execution
+Present: "This requires a database migration that affects X tables"
+Await: User decision on how to proceed
+```
+
+**What qualifies:**
+- Database schema changes
+- API contract changes
+- Authentication/authorisation changes
+- Significant refactoring
+- New external dependencies
+- Infrastructure changes
+
+---
+
+## Decision Flow
+
+```
+Deviation detected
+       │
+       ├─► Is it a bug? ────────────► Rule 1: Fix, track, continue
+       │
+       ├─► Is it missing critical? ──► Rule 2: Add, track, continue
+       │
+       ├─► Is it blocking? ──────────► Rule 3: Fix, track, continue
+       │
+       └─► Does it change architecture? ► Rule 4: STOP, ask, await
+```
+
+---
+
+## Tracking Format
+
+When a deviation occurs, record:
+
+```json
+{
+  "deviations": [
+    {
+      "task_id": "{task where found}",
+      "rule": 1,
+      "title": "{brief description}",
+      "description": "{what was found}",
+      "action": "{what was done}",
+      "files_affected": ["{list}"],
+      "commit_hash": "{if committed separately}"
+    }
+  ]
+}
+```
+
+---
+
+## SUMMARY.md Section
+
+In plan summary, include:
+
+```markdown
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1] {title}**
+- Found during: Task {X}
+- Issue: {description}
+- Fix: {what was done}
+- Files: {affected files}
+- Commit: {hash}
+
+**2. [Rule 2] {title}**
+- Found during: Task {Y}
+- Missing: {what was needed}
+- Added: {what was created}
+- Files: {new files}
+- Commit: {hash}
+
+{Or: "None - plan executed as written."}
+```
+
+---
+
+## Escalation
+
+If unsure which rule applies:
+- Default to Rule 4 (ask)
+- It's better to ask than to make unwanted changes
+- User can always say "jedi" to proceed
+
+---
+
+## Context for User Decisions (Rule 4)
+
+When presenting an architectural decision:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ JDI ► DEVIATION: Architectural Change Detected
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Task:** {current task}
+**Issue:** {what was encountered}
+
+## What's Needed
+
+{Description of the architectural change required}
+
+## Impact
+
+- {Impact 1}
+- {Impact 2}
+
+## Options
+
+1. **Proceed** — Make the change as described
+2. **Modify** — Suggest alternative approach
+3. **Skip** — Skip this task, continue with others
+4. **Stop** — Halt execution entirely
+
+───────────────────────────────────────────────────────────────
+```

package/framework/teams/devops.md

@@ -0,0 +1,26 @@
+---
+name: devops
+description: Helps with Docker, AWS, CLI and other infrastructure-related tasks
+members: [jdi-devops]
+---
+
+# DevOps Team
+
+## Purpose
+
+Infrastructure tasks — Docker, AWS, CI/CD, git worktrees, bash scripting, Laravel Horizon, and development environment management.
+
+## Members
+
+| Role | Agent | Spec Path |
+|------|-------|-----------|
+| DevOps Engineer | `jdi-devops` | `.jdi/framework/agents/jdi-devops.md` |
+
+## Coordination
+
+Single-member team. Lead mode for infrastructure architecture, senior mode for tooling and scripts.
+
+## Boundaries
+
+**Will:** Docker/K8s config, AWS services, CI/CD pipelines, worktree management, bash scripts, Horizon config, troubleshoot infra.
+**Won't:** Write application/test code, gather requirements, make app architectural decisions, access production databases.

package/framework/teams/engineering.md

@@ -0,0 +1,29 @@
+---
+name: engineering
+description: Performs all engineering and coding tasks across backend and frontend
+members: [jdi-backend, jdi-frontend, jdi-architect, jdi-executor]
+---
+
+# Engineering Team
+
+## Purpose
+
+All coding and engineering — implementing features, fixing bugs, refactoring, and delivering shippable increments across full stack (PHP/Laravel + React/TypeScript).
+
+## Members
+
+| Role | Agent | Spec Path |
+|------|-------|-----------|
+| Backend Engineer | `jdi-backend` | `.jdi/framework/agents/jdi-backend.md` |
+| Frontend Engineer | `jdi-frontend` | `.jdi/framework/agents/jdi-frontend.md` |
+| Systems Architect | `jdi-architect` | `.jdi/framework/agents/jdi-architect.md` |
+| Senior Fullstack Engineer | `jdi-executor` | `.jdi/framework/agents/jdi-executor.md` |
+
+## Coordination
+
+Architect confirms approach → engineers implement within their stack → executor manages commits and deviation handling. All follow established project patterns.
+
+## Boundaries
+
+**Will:** Implement per plan, write production code, fix bugs, refactor, atomic commits, run lint/type/test gates, handle deviations.
+**Won't:** Gather requirements, write tests (QA team), make architectural changes without architect, deploy, skip verification.

package/framework/teams/micro-management.md

@@ -0,0 +1,26 @@
+---
+name: micro-management
+description: Engineering oversight — opt-in only via --oversight flag
+members: [jdi-product-lead, jdi-head-engineering]
+opt_in: true
+---
+
+# Micro-Management Team (Opt-In)
+
+**Opt-in only** — spawned when `/jdi:implement-plan --oversight` is used. Not spawned by default.
+
+## Members
+
+| Role | Agent |
+|------|-------|
+| Product Lead | `jdi-product-lead` |
+| Head of Engineering | `jdi-head-engineering` |
+
+## Coordination
+
+Product Lead validates output against requirements. Head of Engineering ensures code quality, unblocks engineers, prevents tangents. Both flag concerns immediately.
+
+## Boundaries
+
+**Will:** Validate task understanding, monitor acceptance criteria, review approach, prevent scope creep.
+**Won't:** Write code, override architect, make product decisions, block without actionable feedback.