@benzotti/jedi 0.1.0

package/framework/components/execution/CodebaseContext.md

@@ -0,0 +1,36 @@
+# CodebaseContext Component
+
+Cache-first codebase context loading. Reads existing analysis — never spawns mapper automatically.
+
+---
+
+## Cache-First Loading
+
+1. If `.jdi/codebase/SUMMARY.md` exists → **read it directly** (regardless of age)
+2. If `.jdi/codebase/CONVENTIONS.md` exists → read it when writing code
+3. If neither exists → **inform user** to run `/jdi:map-codebase` first, then proceed without codebase context
+
+**Never spawn codebase mapper automatically.** The mapper is expensive (~30% of session budget). Only run it via explicit `/jdi:map-codebase` command.
+
+**Skip entirely if:** `--skip-codebase` flag is present in command arguments.
+
+---
+
+## Context Files
+
+| File | Purpose | When to Read |
+|------|---------|--------------|
+| `.jdi/codebase/SUMMARY.md` | Architecture overview, file locations, tech stack | Always (if exists) |
+| `.jdi/codebase/CONVENTIONS.md` | Coding standards (mapper output only) | When writing code (if exists) |
+| `.claude/rules/*.md` | Auto-loaded patterns (no explicit read needed) | Automatic |
+| `.jdi/config/state.yaml` | Current phase, plan, position | Always |
+
+---
+
+## Usage in Commands
+
+```
+<JDI:CodebaseContext />
+```
+
+This component reads cached context files. If no codebase analysis exists, it proceeds without it — agents can still analyse relevant source files directly.

package/framework/components/execution/Commit.md

@@ -0,0 +1,121 @@
+---
+name: Commit
+category: execution
+description: Create atomic commits with proper formatting and state tracking
+params:
+  - name: scope
+    type: string
+    required: false
+    default: "task"
+    options: ["task", "plan", "phase", "docs", "fix"]
+    description: What level of work is being committed
+  - name: type
+    type: string
+    required: false
+    default: null
+    options: ["feat", "fix", "refactor", "docs", "test", "chore", "perf", "style"]
+    description: Override commit type (auto-detected if not provided)
+  - name: files
+    type: array
+    required: false
+    default: null
+    description: Specific files to stage (auto-detected if not provided)
+---
+
+# Commit
+
+Create an atomic commit with proper formatting, staging, and state tracking.
+
+---
+
+## Default Behaviour
+
+When invoked as `<JDI:Commit />`:
+
+1. **Check for changes** — `git status --porcelain`. If none, skip.
+
+2. **Identify modified files** — Parse git status, group by change type.
+
+3. **Determine commit type** — `feat` (new), `fix` (bug), `refactor` (cleanup), `docs` (documentation), `test` (tests). Override with `type` param.
+
+4. **Stage files individually**
+   ```bash
+   git add path/to/file1
+   git add path/to/file2
+   ```
+   **NEVER** use `git add .` or `git add -A`
+
+   **EXCLUDED DIRECTORIES** (never stage):
+   - `.worktrees/**` — Git worktrees
+   - `.jdi/**` — JDI runtime state
+
+   ```bash
+   if [[ "$file" == .worktrees/* ]] || [[ "$file" == .jdi/* ]]; then
+     echo "SKIP (excluded): $file"
+     continue
+   fi
+   ```
+
+5. **Create commit message** — Use <JDI:Commit:MessageFormat />
+
+6. **Execute commit**
+   ```bash
+   git commit -m "$(cat <<'EOF'
+   {message}
+   EOF
+   )"
+   ```
+
+7. **Record commit hash** — `git rev-parse --short HEAD`
+
+8. **Update state** — Add commit to `state.yaml` session_commits array.
+
+---
+
+<section name="MessageFormat">
+
+## Message Format
+
+```
+{type}({scope}): {description}
+
+- {change 1}
+- {change 2}
+- {change 3}
+```
+
+### Type Selection
+
+| Type | When to Use |
+|------|-------------|
+| `feat` | New feature, endpoint, component |
+| `fix` | Bug fix, error correction |
+| `test` | Test-only changes |
+| `refactor` | Code cleanup, no behaviour change |
+| `perf` | Performance improvement |
+| `docs` | Documentation changes |
+| `style` | Formatting, linting fixes |
+| `chore` | Config, tooling, dependencies |
+
+### Rules
+- **Scope**: In a plan: `{phase}-{plan}` (e.g., `01-02`). Standalone: feature name or file area.
+- **Description**: Imperative mood, no capital start, no period, max 72 chars.
+- **Body**: 3-5 bullet points of WHAT changed.
+
+</section>
+
+---
+
+## Scope Reference
+
+| Scope | Message Format |
+|-------|----------------|
+| `task` | `{type}({phase}-{plan}): task {N} - {desc}` |
+| `plan` | `docs({phase}-{plan}): complete {plan-name}` |
+| `phase` | `docs({phase}): complete {phase-name}` |
+| `docs` | `docs: {description}` |
+| `fix` | `fix: {description}` |
+
+## State Updates
+
+After commit: append to `commits.session_commits` in state.yaml, update `last_commit_hash`. Append to `implementation.files_modified` in variables.yaml.

package/framework/components/execution/Verify.md

@@ -0,0 +1,140 @@
+---
+name: Verify
+category: execution
+description: Verify completion of tasks, plans, phases, or requirements
+params:
+  - name: scope
+    type: string
+    required: false
+    options: ["task", "plan", "phase", "requirements"]
+    default: "task"
+    description: What level to verify
+  - name: strict
+    type: boolean
+    required: false
+    default: false
+    description: Fail on any unmet criteria (vs warn)
+  - name: include_tests
+    type: boolean
+    required: false
+    default: true
+    description: Run tests as part of verification
+---
+
+# Verify
+
+Verify completion of work at various levels of granularity.
+
+---
+
+## Default Behaviour
+
+When invoked as `<JDI:Verify />`:
+
+1. **Determine scope** — Check current position from state.yaml, default to task-level
+2. **Load verification criteria** — task: PLAN.md verification section; plan: PLAN.md success_criteria; phase: ROADMAP.yaml must_haves
+3. **Execute verification** — Run each check, record pass/fail
+4. **Report results** — Output summary, update state
+
+---
+
+<section name="Task">
+
+## Task Verification (`scope="task"`)
+
+1. **Load task verification criteria** from PLAN.md `**Verification:**` checklist
+2. **Execute each check**: file existence, code patterns, test gates (see TestRunner), manual inspection
+3. **Load done criteria** from `**Done when:**`
+4. **Report result**:
+   ```markdown
+   ## Task Verification: Task {N}
+   **Status:** PASS | FAIL
+
+   ### Verification Checks
+   - [x] {check 1} - PASS
+   - [ ] {check 2} - FAIL: {reason}
+
+   ### Done Criteria
+   - [x] {criterion} - Met
+
+   ### Issues
+   - {issue description if any}
+   ```
+
+</section>
+
+---
+
+<section name="Plan">
+
+## Plan Verification (`scope="plan"`)
+
+1. **Verify all tasks complete** — check status and commits
+2. **Load plan success criteria** from `<success_criteria>` block
+3. **Execute plan-level checks** — test suite, lint/type errors, integration points
+4. **Generate SUMMARY.md preview** — draft with deviations
+5. **Report result**:
+   ```markdown
+   ## Plan Verification: {phase}-{plan}
+   **Status:** PASS | FAIL
+
+   ### Task Completion
+   - [x] Task 1: {name} - {commit}
+
+   ### Success Criteria
+   - [x] {criterion 1} - Met
+   - [ ] {criterion 2} - NOT MET: {reason}
+
+   ### Tests
+   - Suite: {test suite} | Result: {pass/fail} | Coverage: {percentage}
+
+   ### Ready for SUMMARY.md: YES | NO
+   ```
+
+</section>
+
+---
+
+## Advanced Verification (Phase & Requirements)
+
+For `scope="phase"` or `scope="requirements"`, load `<JDI:VerifyAdvanced />`.
+
+---
+
+<section name="TestRunner">
+
+## Test Execution (`include_tests="true"`)
+
+1. **Detect changed files**
+   ```bash
+   # Task-level
+   git diff --cached --name-only
+   git diff --name-only
+   # Plan-level
+   git diff master --name-only
+   ```
+
+2. **Backend test gate (MANDATORY if ANY `*.php` files changed)**
+   ```bash
+   composer test
+   ```
+   If fails: verification FAILS. Do not proceed. Fix tests first.
+
+3. **Frontend tests (if `*.ts`, `*.tsx`, `*.js`, `*.jsx` changed)**
+   ```bash
+   bun run test:vitest
+   ```
+
+4. **Parse results** — total, passed, failed, skipped, coverage
+
+5. **Report**: For each stack (Backend/Frontend), include: ran (yes/no), command, result, counts, and any failed test details.
+
+</section>
+
+---
+
+## State Updates
+
+After verification, set `position.status` to `verified` or `verification_failed`. If gaps found, add to `blockers` array with `type: verification_gap`.
+
+Gap severity: Critical (goal blocked → closure plan), High (requirement unmet → targeted fix), Medium (partially met → note), Low (enhancement → document).

package/framework/components/execution/VerifyAdvanced.md

@@ -0,0 +1,43 @@
+---
+name: VerifyAdvanced
+category: execution
+description: Advanced verification for phase and requirements scope
+---
+
+# VerifyAdvanced
+
+Lazy-loaded verification for `scope="phase"` and `scope="requirements"`. See `<JDI:Verify />` for task and plan verification.
+
+---
+
+<section name="Phase">
+
+## Phase Verification
+
+When `scope="phase"`:
+
+1. **Verify all plans complete** — Check SUMMARY.md exists for each plan, verify success criteria met
+2. **Load phase must_haves from ROADMAP.yaml**
+3. **Verify against codebase (not claims)** — Actually check the codebase, run the functionality
+4. **Create VERIFICATION.md** with must-haves status table, plans completed, gaps found, human verification needed
+5. **Route by status:**
+   - `PASSED` → Continue to next phase
+   - `GAPS_FOUND` → Create gap closure plans
+   - `HUMAN_NEEDED` → Present checklist to user
+
+</section>
+
+---
+
+<section name="Requirements">
+
+## Requirements Verification
+
+When `scope="requirements"`:
+
+1. **Load REQUIREMENTS.yaml** — Get all v1 requirements with REQ-IDs
+2. **For each requirement** — Find which phase/plan claimed to implement it, verify implementation exists, check acceptance criteria
+3. **Cross-reference evidence** — Link to test files, code implementing the requirement, note partial implementations
+4. **Generate report** with total/verified/failed/not-implemented counts, verification results table, failed requirements details, recommendations
+
+</section>

package/framework/components/meta/AgentBase.md

@@ -0,0 +1,108 @@
+# AgentBase Component
+
+Standards inherited by all JDI agents via `<JDI:AgentBase />`. Default loads Core only.
+
+## Standards
+
+- Use **Australian English** spelling in all outputs.
+- Follow `CLAUDE.md` and `.claude/rules/` conventions.
+- Read `.jdi/config/state.yaml` once at task start — update `position`, `progress`, `current_plan` fields via `<JDI:StateUpdate />`.
+- Use the Read tool before editing any file.
+- Batch file reads: issue all Read calls in a single turn rather than sequentially.
+- Batch git operations: combine related commands into a single Bash call where possible.
+
+## Component Resolution
+
+When a spec contains `<JDI:*>` tags:
+1. Read the file from `.jdi/framework/components/` (execution/, planning/, quality/, meta/).
+2. If a section is specified (`<JDI:X:Section />`), execute only that section.
+3. Apply tag parameters as constraints. Return to agent spec and continue.
+
+If your spec has a `requires_components` frontmatter field, read ALL listed components before starting execution.
+
+Do NOT skip `<JDI:*>` tags — they contain essential instructions.
+
+## Activation Protocol
+
+On activation, announce and begin immediately:
+```
+You are now active as {agent-name}. {Action verb} as requested.
+```
+
+## Structured Returns
+
+Return a YAML block with `status`, agent-specific fields, and `next_action` after all work is complete.
+
+## Boundaries
+
+- **Will Do**: Actions within agent responsibility. Prioritise these.
+- **Will Not**: Actions outside scope. Delegate or escalate, never attempt.
+
+---
+
+<section name="Sandbox">
+
+## Sandbox Awareness
+
+You run in a sandboxed environment. Key constraints:
+
+| Operation | Tool / Method | Persists? | Notes |
+|-----------|--------------|-----------|-------|
+| Edit existing files | Edit tool | **Yes** | Primary way to modify code |
+| Delete files | Bash `rm` | **Yes** | Destructive — use with care |
+| Create new files | Write tool / Bash `cat >` | **No** | Silently fails — report in `files_to_create` |
+| Git commits | Bash `git commit` | **No** | Silently fails — report in `commits_pending` |
+| Read files | Read tool | **Yes** | Works reliably |
+| Run commands | Bash tool | **Yes** | Output is real; side-effects vary |
+
+**Key Rules:**
+1. **NEVER attempt `git commit`** — it will appear to succeed but produces no real commit.
+2. **NEVER create new files** via Write tool or Bash redirection — they will not persist.
+3. **ALWAYS use the Edit tool** to modify existing files.
+4. **Report pending work** in structured returns using `files_to_create` and `commits_pending`.
+
+### Structured Returns for Sandbox-Limited Operations
+
+```yaml
+files_to_create:
+  - path: "path/to/new/file.md"
+    content: |
+      Full file content here...
+files_modified:
+  - path/to/edited/file1.ts
+commits_pending:
+  - message: |
+      feat(01-01-T1): implement feature X
+    files:
+      - path/to/modified/file1.ts
+```
+
+### Orchestrator Post-Agent Handling
+
+After a sandboxed agent completes, the orchestrator must:
+1. Create files from `files_to_create` using Write tool
+2. Execute commits from `commits_pending` via `git add` + `git commit`
+3. Record real commit hashes in `.jdi/config/state.yaml`
+
+</section>
+
+---
+
+<section name="TeamMode">
+
+## Communication (Team Mode)
+
+When operating within an Agent Team (spawned by coordinator):
+
+1. **Claim tasks**: Call TaskList, find tasks assigned to you
+2. **Execute**: Read task description, implement using Edit tool
+3. **Report**: SendMessage to coordinator with structured return (include `files_modified`, `files_to_create`, `commits_pending`)
+4. **Complete**: TaskUpdate(status: "completed") AFTER sending results
+5. **Next**: Check TaskList for more assigned tasks. If none, go idle.
+
+**Team Mode Rules:**
+- NEVER write to state.yaml (coordinator handles this)
+- ALWAYS SendMessage results to coordinator before TaskUpdate(completed)
+- Use **SendMessage** to communicate — plain text is not visible to teammates.
+
+</section>

package/framework/components/meta/AgentTeamsOrchestration.md

@@ -0,0 +1,71 @@
+---
+name: AgentTeamsOrchestration
+category: meta
+description: Agent Teams orchestration quick-reference
+---
+
+# AgentTeamsOrchestration
+
+## Core Pattern (6 Steps)
+
+1. **Pre-flight** — Read command spec, `<JDI:CodebaseContext />`, read state.yaml, set status to "executing"
+2. **Create Team** — `TeamCreate(team_name: "{team-name}")`
+3. **Create Tasks** — TaskCreate per work unit, set `addBlockedBy` dependencies
+4. **Spawn Teammates** — Task tool with `subagent_type: "general-purpose"`. Include in prompt: agent spec path, team context, task assignments
+5. **Coordinate** — Automatic message delivery for results, TaskList to monitor, SendMessage to guide/unblock
+6. **Cleanup** — shutdown_request to all → TeamDelete → set status "complete" → report
+
+---
+
+## Task Routing Table
+
+| Task Stack | Agent(s) | Spawn Count |
+|-----------|----------|-------------|
+| PHP only | jdi-backend | 1 |
+| TS/React only | jdi-frontend | 1 |
+| Full-stack | jdi-backend + jdi-frontend | 2 |
+| Config/docs | jdi-backend (default) | 1 |
+
+---
+
+## Specialist Spawn Prompt Template (~200 tokens)
+
+```
+You are {agent-name}. Read .jdi/framework/agents/{spec}.md and .jdi/framework/components/meta/AgentBase.md.
+
+TEAM: {team-name}
+PLAN: {plan-path}
+TASK_FILE: {task-file-path}
+WORKING_DIR: {working-directory}
+
+Read your TASK_FILE for task details (objective, files, steps, verification).
+If TASK_FILE is not provided (legacy plan), claim tasks from TaskList and read task details from the PLAN file.
+
+1. Implement using Edit tool
+2. SendMessage to coordinator with structured return
+3. Mark task completed via TaskUpdate
+
+Report: files_modified, files_to_create, commits_pending.
+No git commit (use commits_pending).
+```
+
+---
+
+## Deferred Operations Checklist
+
+After all specialist tasks complete:
+
+1. **Collect** — Aggregate `files_modified`, `files_to_create`, `commits_pending` from all SendMessage results
+2. **Create files** — Write tool for each `files_to_create` entry
+3. **Execute commits** — `git add` + `git commit` for each `commits_pending` entry
+4. **Record hashes** — Store real commit hashes in state.yaml
+5. **Verify** — Confirm all `files_modified` are present in working tree
+
+---
+
+## Team Lifecycle
+
+```
+TeamCreate → Spawn agents → Monitor (auto message delivery) →
+Collect results → Deferred ops → shutdown_request → TeamDelete
+```

package/framework/components/meta/ComplexityRouter.md

@@ -0,0 +1,80 @@
+# ComplexityRouter Component
+
+Evaluates plan complexity and returns the routing decision for implement-plan.
+
+---
+
+## Decision Matrix
+
+Read the plan index file (frontmatter + task manifest table) and extract these signals:
+
+| Signal | Simple | Complex |
+|--------|--------|---------|
+| Task count | ≤3 | >3 |
+| Tech stacks | Single (PHP-only OR TS-only) | Mixed (PHP + TS/React) |
+| Wave count | 1 (all tasks parallel or sequential) | >1 (multi-wave dependencies) |
+
+**Routing rule:** If ANY signal is "Complex" → use Agent Teams mode. All signals must be "Simple" for single-agent mode.
+
+**Override flags:**
+- `--team` in command arguments → force Agent Teams mode
+- `--single` in command arguments → force single-agent mode
+
+---
+
+## Output
+
+After evaluation, set the routing decision:
+
+```yaml
+mode: single-agent | agent-teams
+primary_agent: jdi-backend | jdi-frontend  # based on tech stack
+secondary_agents: []  # only populated in agent-teams mode
+reasoning: "{why this mode was chosen}"
+```
+
+---
+
+## Single-Agent Mode
+
+Spawn one specialist agent directly via Task tool. Follow cache-optimised load order (AgentBase first):
+
+```
+Task(
+  subagent_type: "general-purpose",
+  name: "{primary_agent}",
+  prompt: "Read .jdi/framework/components/meta/AgentBase.md for the base protocol.
+You are {primary_agent}. Read .jdi/framework/agents/{primary_agent}.md for your spec.
+If your spec has requires_components in frontmatter, batch-read all listed components before starting.
+
+## Project Context
+- Type: {project_type}
+- Tech stack: {tech_stack}
+- Quality gates: {quality_gates}
+- Working directory: {cwd}
+
+## Task
+Execute all tasks in the plan sequentially. PLAN: {plan-path}.
+For split plans (task_files in frontmatter), read each task file one at a time from the file: field in state.yaml.
+Report: files_modified, files_to_create, commits_pending."
+)
+```
+
+No TeamCreate, no TaskCreate, no cross-agent coordination.
+
+---
+
+## Agent Teams Mode
+
+Follow full orchestration from `.jdi/framework/components/meta/AgentTeamsOrchestration.md`:
+TeamCreate → TaskCreate per plan task → spawn specialists per tech-stack routing → wave-based coordination → collect deferred ops → shutdown → TeamDelete.
+
+---
+
+## Usage
+
+```
+<JDI:ComplexityRouter />
+```
+
+Referenced by implement-plan command stub. Evaluates at orchestration time, before any agents are spawned.