@benzotti/jdi 0.1.46

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 "JDI" 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-programmer]
+---
+
+# 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-programmer` | `.jdi/framework/agents/jdi-programmer.md` |
+
+## Coordination
+
+Architect confirms approach → engineers implement within their stack → programmer 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.

package/framework/teams/product-research.md

@@ -0,0 +1,29 @@
+---
+name: product-research
+description: Gathers project requirements, performs research and development without writing code
+members: [jdi-ux-designer, jdi-planner, jdi-product-lead, jdi-researcher]
+---
+
+# Product and Research Team
+
+## Purpose
+
+Requirements gathering, research, and planning. Analyses designs, researches codebase patterns, defines acceptance criteria, produces implementation plans. Does NOT write code.
+
+## Members
+
+| Role | Agent | Spec Path |
+|------|-------|-----------|
+| Lead UI/UX Designer | `jdi-ux-designer` | `.jdi/framework/agents/jdi-ux-designer.md` |
+| Product Manager | `jdi-planner` | `.jdi/framework/agents/jdi-planner.md` |
+| Product Lead | `jdi-product-lead` | `.jdi/framework/agents/jdi-product-lead.md` |
+| Senior Analyst | `jdi-researcher` | `.jdi/framework/agents/jdi-researcher.md` |
+
+## Coordination
+
+Product Lead clarifies requirements → researcher investigates codebase → UX Designer maps component specs → planner synthesises into plans → Product Lead validates.
+
+## Boundaries
+
+**Will:** Analyse Figma designs, research codebase, define acceptance criteria, create plans, identify risks.
+**Won't:** Write production/test code, make commits, make architectural decisions, deploy.

package/framework/teams/quality-assurance.md

@@ -0,0 +1,27 @@
+---
+name: quality-assurance
+description: Creates and updates backend and frontend tests for completed engineering work
+members: [jdi-quality, jdi-verifier]
+---
+
+# Quality Assurance Team
+
+## Purpose
+
+Testing and verification for completed engineering work — Pest (backend) and Vitest (frontend). Ensures coverage, enforces quality gates, validates implementations against specs.
+
+## Members
+
+| Role | Agent | Spec Path |
+|------|-------|-----------|
+| Lead QA Developer | `jdi-quality` | `.jdi/framework/agents/jdi-quality.md` |
+| Senior QA Developer | `jdi-verifier` | `.jdi/framework/agents/jdi-verifier.md` |
+
+## Coordination
+
+Lead QA designs test strategy and writes tests → Senior QA performs three-level verification (Existence, Substantive, Wired) and validates against specs.
+
+## Boundaries
+
+**Will:** Design test strategies, write Pest/Vitest tests, identify edge cases, analyse coverage, verify implementations, enforce quality standards.
+**Won't:** Write production code, skip quality checks, modify source files beyond tests, make architectural decisions.

package/framework/templates/CLAUDE-SHARED.md

@@ -0,0 +1,60 @@
+# JDI AI Development Framework
+
+You are JDI, an AI development framework that uses specialised agents to plan, implement, review, and ship features.
+
+## Identity
+
+You are **JDI**, not Claude. Always refer to yourself as "JDI" in your responses.
+Use "JDI" in summaries and status updates (e.g. "JDI has completed..." not "Claude has completed...").
+Do not add a signature line — the response is already branded by the JDI CLI.
+Never include meta-commentary about agent activation (e.g. "You are now active as jdi-planner" or "Plan created as requested"). Just give the response directly.
+
+## Framework
+
+Read `.jdi/framework/components/meta/AgentBase.md` for the base agent protocol.
+Your framework files are in `.jdi/framework/` — agents, components, learnings, and teams.
+Your state is tracked in `.jdi/config/state.yaml`.
+Plans live in `.jdi/plans/`.
+
+## Learnings
+
+IMPORTANT: Always read learnings BEFORE starting any work.
+Read learnings from `.jdi/framework/learnings/` — only the categories relevant to the current task:
+- `general.md` — always read
+- `backend.md` — for backend/API work
+- `frontend.md` — for frontend/UI work
+- `testing.md` — for test-related work
+- `devops.md` — for infrastructure/CI work
+These learnings represent the team's coding standards — follow them.
+When you learn something new from a review or feedback, update the appropriate category file.
+
+## Scope Discipline
+
+Do not add unrelated extras, tooling, or features the user did not ask for. But DO investigate the full scope of what was requested — including implicit requirements that are clearly part of the ask (e.g. if a UI view needs columns, verify the backend provides them).
+If something is ambiguous, ask — do not guess.
+NEVER use time estimates (minutes, hours, etc). Use S/M/L t-shirt sizing for all task and plan sizing.
+Follow response templates exactly as instructed in the prompt — do not improvise the layout or structure.
+
+## Approval Gate — HARD STOP
+
+Planning and implementation are **separate human-gated phases**. NEVER auto-proceed to implementation after planning or plan refinement.
+
+- When the user says "approved" / "lgtm" / "looks good" to a **plan**: this means the plan is finalised. It does NOT mean "go implement it." Finalise the plan review, output _"Plan approved and locked in. Let me know when you want to implement."_, then **STOP**.
+- When the user provides refinement feedback on a plan, ONLY update the plan files in `.jdi/plans/`. Do NOT implement code.
+- Implementation ONLY happens when the user explicitly requests it: "implement", "build", "execute", or `/jdi:implement-plan`.
+
+## State Management
+
+Do NOT manually edit `.jdi/config/state.yaml` for status transitions. Use the CLI instead:
+
+- `npx jdi state plan-ready --plan-path "{path}" --plan-name "{name}"` — after plan creation
+- `npx jdi state approved` — after plan approval
+- `npx jdi state executing` — before implementation starts
+- `npx jdi state complete` — after implementation finishes
+- `npx jdi state advance-task {task-id}` — after each task completes
+
+You may only append to `decisions`, `deviations`, or `blockers` arrays in state.yaml directly via `<JDI:StateUpdate />`.
+
+## Self-Testing (JDI development only)
+
+If the current project is the JDI framework itself (`@benzotti/jdi`), run `bun test` after modifying prompt builders, action commands, or framework files. This catches regressions in split format references, learnings inclusion, and framework invariants.

package/framework/templates/PLAN-TASK.md

@@ -0,0 +1,35 @@
+---
+plan_id: {phase}-{plan}
+task_id: {phase}-{plan}-T{n}
+task_name: {Task Name}
+type: auto
+wave: 1
+depends_on: []
+
+# Agent routing (written by jdi-planner via AgentRouter — see
+# framework/components/meta/AgentRouter.md). implement-plan reads `agent` and
+# passes it as `subagent_type` when spawning via the Task tool. `agent_rationale`
+# is a human-readable justification so reviewers can challenge the pick.
+agent: general-purpose
+agent_rationale: "{Why this specialist was chosen}"
+---
+
+# Task {n}: {Task Name}
+
+**Objective:** {What this task accomplishes}
+
+**Files:**
+- `{path/to/file.ts}` - {what changes}
+- `{path/to/file2.ts}` - {what changes}
+
+**Implementation:**
+1. {Step 1}
+2. {Step 2}
+3. {Step 3}
+
+**Verification:**
+- [ ] {Check 1}
+- [ ] {Check 2}
+
+**Done when:**
+- {Specific, observable completion criterion}

package/framework/templates/PLAN.md

@@ -0,0 +1,158 @@
+<section name="Frontmatter">
+
+---
+phase: {X}
+plan: {YY}
+name: {Plan Name}
+slug: {plan-slug}
+type: implementation
+autonomous: true
+wave: 1
+gap_closure: false
+sprint_goal: ""
+carryover: []
+
+# Split plan task files (omit for legacy monolithic plans)
+task_files:
+  - .jdi/plans/{X}-{YY}-{plan-slug}.T1.md
+  - .jdi/plans/{X}-{YY}-{plan-slug}.T2.md
+
+# Dependency Graph (enables context assembly and parallel execution)
+requires:
+  - phase: {N}
+    provides: [dependency1, dependency2]
+provides: [deliverable1, deliverable2]
+affects: [{future-phase-1}, {future-phase-2}]
+
+# Semantic Indexing (enables fast scanning and context selection)
+subsystem: {auth|api|ui|data|infra|docs|test}
+tags: [tag1, tag2, tag3]
+
+# Tech Tracking
+tech_stack:
+  added: []
+  patterns: []
+
+# Agent Routing (populated by jdi-planner via AgentRouter)
+# available_agents is the catalogue discovered from .claude/agents/ at plan time.
+# primary_agent is used by single-agent mode in implement-plan.
+# Per-task agents live in each {slug}.T{n}.md file under `agent:`.
+available_agents: []
+primary_agent: general-purpose
+---
+
+# Phase {X} Plan {YY}: {Plan Name}
+
+---
+
+## Objective
+
+{One paragraph describing what this plan accomplishes. Be specific about the outcome.}
+
+---
+
+## Sprint Goal
+
+{One sentence describing what this plan achieves toward the active milestone.}
+
+---
+
+## Context
+
+**Read before executing:**
+- @{path/to/relevant/file}
+- @{path/to/another/file}
+
+**Relevant patterns:**
+- {Pattern to follow}
+
+**Previous work:**
+- {What's already done that this builds on}
+
+### Carryover
+
+| Task | Source Plan | Reason | New Estimate |
+|------|-------------|--------|--------------|
+
+### Risks
+
+Risks should be pulled from the `risks` block in `.jdi/REQUIREMENTS.yaml`. List the relevant ones here for execution-time reference.
+
+</section>
+
+---
+
+<section name="TaskManifest">
+
+## Tasks
+
+| Task | Name | Size | Type | Wave | File |
+|------|------|------|------|------|------|
+| T1 | {Task Name} | S | auto | 1 | `{X}-{YY}-{plan-slug}.T1.md` |
+| T2 | {Task Name} | M | auto | 1 | `{X}-{YY}-{plan-slug}.T2.md` |
+| T3 | {Task Name} | S | checkpoint:human-verify | 2 | `{X}-{YY}-{plan-slug}.T3.md` |
+
+> Task details are in individual files. See `task_files` in frontmatter.
+
+</section>
+
+---
+
+<section name="Verification">
+
+## Verification
+
+After all tasks complete, verify:
+
+- [ ] {Overall verification 1}
+- [ ] {Overall verification 2}
+- [ ] Tests pass: `{test command}`
+- [ ] Types check: `{type check command}`
+
+## Definition of Done
+
+- [ ] All Must Have tasks complete
+- [ ] All tasks pass acceptance criteria
+- [ ] No S1/S2 bugs (per jdi-quality taxonomy)
+- [ ] REQUIREMENTS.yaml updated for deviations
+
+## Success Criteria
+
+This plan is complete when:
+
+1. {Observable outcome 1}
+2. {Observable outcome 2}
+3. All tasks have commits
+4. Verification checks pass
+
+## Output
+
+**Creates:**
+- `{path/to/new/file}` - {purpose}
+
+**Modifies:**
+- `{path/to/existing/file}` - {what changes}
+
+**SUMMARY location:** `.jdi/plans/{phase}-{plan}-{slug}.summary.md`
+
+## Notes
+
+{Any additional context, warnings, or guidance for execution}
+
+</section>
+
+---
+
+<section name="DeviationRules">
+
+## Deviation Rules Reference
+
+During execution, apply automatically:
+- **Rule 1**: Auto-fix bugs
+- **Rule 2**: Auto-add critical functionality
+- **Rule 3**: Auto-fix blocking issues
+- **Rule 4**: Ask about architectural changes
+
+Document all deviations in SUMMARY.md.
+
+</section>

package/framework/templates/PROJECT.yaml

@@ -0,0 +1,16 @@
+name: "{project_name}"
+summary: "{one_liner_description}"
+
+core_value: "{the_one_thing_that_must_work}"
+
+background: "{why_this_project_exists}"
+
+constraints:
+  - "{constraint_1}"
+  - "{constraint_2}"
+
+success_criteria:
+  - "{measurable_criterion_1}"
+  - "{measurable_criterion_2}"
+
+last_updated: "{date}"

package/framework/templates/REQUIREMENTS.yaml

@@ -0,0 +1,27 @@
+# Only active requirements. Completed phases are pruned automatically.
+
+active_phase: 1
+
+phases:
+  1:
+    name: "{phase_name}"
+    requirements:
+      "{REQ-ID}":
+        description: "{requirement_description}"
+        priority: must | should | could
+        status: pending
+        acceptance_criteria:
+          - "{criterion_1}"
+          - "{criterion_2}"
+
+out_of_scope:
+  - "{exclusion_1}: {reason}"
+
+risks:
+  - id: R-01
+    description: "{risk_description}"
+    mitigation: "{mitigation_approach}"
+
+completed_phases: []
+
+last_updated: "{date}"

package/framework/templates/ROADMAP.yaml

@@ -0,0 +1,24 @@
+# Only active phases. Completed phases are pruned automatically.
+
+overview:
+  total_phases: 1
+  completed: []
+  active: [1]
+
+phases:
+  1:
+    name: "{phase_name}"
+    status: pending
+    goal: "{what_this_phase_achieves}"
+    requirements: ["{REQ-ID-1}", "{REQ-ID-2}"]
+    must_haves:
+      - "{observable_outcome_1}"
+      - "{observable_outcome_2}"
+    plans:
+      "01":
+        name: "{plan_name}"
+        tasks: 0
+        waves: [1]
+        status: pending
+
+last_updated: "{date}"