@benzotti/jedi 0.1.0

package/framework/components/meta/StateUpdate.md

@@ -0,0 +1,191 @@
+---
+name: StateUpdate
+category: meta
+description: Update state.yaml and STATE.md with current progress and position
+params:
+  - name: phase
+    type: string
+    required: false
+    description: Phase number to set
+  - name: plan
+    type: string
+    required: false
+    description: Plan number to set
+  - name: task
+    type: string
+    required: false
+    description: Task number to set
+  - name: status
+    type: string
+    required: false
+    options: ["idle", "planning", "executing", "verifying", "complete", "blocked", "error"]
+    description: Current status to set
+  - name: fields
+    type: array
+    required: false
+    description: Specific YAML paths to update (e.g. ["position.status", "session.last_activity"])
+---
+
+# StateUpdate
+
+Update JDI state files to track current progress and position.
+
+## Update Pattern (applies to ALL sections)
+
+1. **Read** the target file with the Read tool
+2. **Modify** only the specified fields (preserve everything else)
+3. **Write** the complete file back with the Write tool
+
+---
+
+## File Paths
+
+| File | Purpose |
+|------|---------|
+| `.jdi/config/state.yaml` | Runtime state (position, session, decisions, blockers) |
+| `.jdi/config/variables.yaml` | Runtime variables (feature metadata, implementation tracking) |
+
+> These are RUNTIME files in `.jdi/`, NOT templates in `.jdi/framework/config/`. If `.jdi/config/` does not exist, create it and copy templates.
+
+---
+
+## Default Behaviour
+
+When invoked as `<JDI:StateUpdate />`: update `session.last_activity` to current ISO timestamp.
+
+---
+
+<section name="Position">
+
+## Position Update
+
+Update fields in `.jdi/config/state.yaml`:
+
+```json
+{
+  "position": {
+    "phase": "{phase}",
+    "phase_name": "{from ROADMAP.yaml}",
+    "plan": "{plan}",
+    "plan_name": "{from PLAN.md}",
+    "task": "{task}",
+    "task_name": "{from plan}",
+    "status": "{status}"
+  }
+}
+```
+
+Names are resolved from ROADMAP.yaml and current plan index file.
+
+### Task Entry Schema
+
+Each task in `current_plan.tasks` supports these fields:
+
+```yaml
+- id: "{phase}-{plan}-T{n}"
+  name: "{Task Name}"
+  type: auto | checkpoint:human-verify | checkpoint:decision | checkpoint:human-action
+  wave: 1
+  status: pending | in_progress | complete | blocked
+  file: ".jdi/plans/{phase}-{plan}-{slug}.T{n}.md"  # optional — present for split plans only
+```
+
+The `file:` field points to the individual task file. When present, agents read task details from this file instead of the monolithic plan. When absent (legacy plans), task details are inline in the plan file.
+
+</section>
+
+---
+
+<section name="Decisions">
+
+## Record Decision
+
+Append to `decisions` array in `state.yaml`:
+
+```json
+{
+  "timestamp": "{ISO}",
+  "phase": "{phase}",
+  "decision": "{description}",
+  "rationale": "{why}",
+  "impact": "{what it affects}"
+}
+```
+
+Also append to STATE.md decisions table: `| {date} | {phase} | {decision} | {rationale} |`
+
+</section>
+
+---
+
+<section name="Blocker">
+
+## Record Blocker
+
+Append to `blockers` array in `state.yaml`:
+
+```json
+{
+  "timestamp": "{ISO}",
+  "type": "technical|external|decision",
+  "description": "{what's blocked}",
+  "impact": "{what can't proceed}",
+  "resolution": null
+}
+```
+
+STATE.md: Add `- [ ] **{type}**: {description}` with impact and date. When resolved: `- [x]` with resolution.
+
+</section>
+
+---
+
+<section name="Deviation">
+
+## Record Deviation
+
+Append to `deviations` array in `state.yaml`:
+
+```json
+{
+  "timestamp": "{ISO}",
+  "rule": "Rule 1|Rule 2|Rule 3|Rule 4",
+  "description": "{what deviated}",
+  "reason": "{why}",
+  "task": "{task context}",
+  "files": ["{affected files}"]
+}
+```
+
+Deviation rules: 1=Auto-fixed bug, 2=Auto-added critical functionality, 3=Auto-fixed blocking issue, 4=Asked about architectural change.
+
+</section>
+
+---
+
+<section name="QuickUpdate">
+
+## Quick Field Update
+
+For single-field or few-field updates, use targeted access instead of full-file read-modify-write:
+
+1. Read only the relevant YAML block from state.yaml (e.g., `position:` block)
+2. Update the specific field(s)
+3. Write back only the changed block using Edit tool
+
+Examples:
+- `<JDI:StateUpdate fields="position.status" />` — read position block, update status
+- `<JDI:StateUpdate fields="session.last_activity" />` — update timestamp only
+- `<JDI:StateUpdate fields="progress.tasks_completed,progress.plans_completed" />` — batch update counters
+
+This avoids reading/writing the full state file (~110 lines) for trivial updates.
+
+</section>
+
+---
+
+<section name="Session">
+
+> **Session Management**: Update `session.last_activity` to current ISO timestamp.
+
+</section>

package/framework/components/meta/TeamRouter.md

@@ -0,0 +1,86 @@
+---
+name: TeamRouter
+category: meta
+description: Resolve which team(s) to spawn for a given command
+params:
+  - { name: command, type: string, required: false, description: "Command to route (e.g. create-plan, implement-plan)" }
+---
+
+# TeamRouter
+
+## Routing Table
+
+| Command | Primary Team | Supporting | Pattern | Agent Loop |
+|---------|-------------|------------|---------|------------|
+| `create-plan` | Product & Research | — | Sequential | Yes |
+| `implement-plan` | Engineering | Micro-Management | Parallel (oversight) | Yes |
+| `research-phase` | Product & Research | — | Sequential | Yes |
+| `pr-feedback` | Engineering | — | Sequential | Yes |
+| `pr-review` | QA | Engineering | Parallel (context) | Yes |
+| `commit` | Engineering | — | Direct | No |
+| `generate-pr` | Engineering | — | Direct | No |
+| `map-codebase` | Product & Research | — | Sequential | Yes |
+| `resume` | (from state) | (from state) | Resumes previous | Yes |
+
+## Team Specs
+
+| Team | Path |
+|------|------|
+| Engineering | `.jdi/framework/teams/engineering.md` |
+| Product & Research | `.jdi/framework/teams/product-research.md` |
+| Quality Assurance | `.jdi/framework/teams/quality-assurance.md` |
+| DevOps | `.jdi/framework/teams/devops.md` |
+| Micro-Management | `.jdi/framework/teams/micro-management.md` |
+
+## Resolution Algorithm
+
+1. Strip `/jdi:` prefix, normalise command
+2. Look up in routing table (skill names map to same command)
+3. Resolve primary + supporting team specs
+4. Determine collaboration pattern and agent loop flag
+5. Activate members based on task context
+
+---
+
+<section name="MemberActivation">
+
+## Member Activation
+
+Activate members based on file types in the task:
+
+| Context | Detection | Active Members |
+|---------|-----------|----------------|
+| Backend | `.php` files | jdi-backend |
+| Frontend | `.tsx`/`.ts` files | jdi-frontend |
+| Full-stack | Both PHP + TS | jdi-backend, jdi-frontend, jdi-executor |
+| Commit | Any | jdi-committer |
+| PR generation | Any | jdi-pr-generator |
+| Plan creation | — | jdi-planner, jdi-product-lead |
+| Research | — | jdi-researcher, jdi-planner |
+| PR review | — | jdi-quality, jdi-verifier |
+| Oversight | During implementation | jdi-head-engineering, jdi-product-lead |
+
+</section>
+
+<section name="ResumeRouting">
+
+## Resume Routing
+
+1. Read `.jdi/config/state.yaml`
+2. Map status: planning→create-plan, executing→implement-plan, verifying→pr-review
+3. Route as resolved command with `resume=true, resume_from_task={position.task}`
+
+</section>
+
+<section name="CollaborationPatterns">
+
+## Collaboration Patterns
+
+| Pattern | Used By | Description |
+|---------|---------|-------------|
+| Sequential | create-plan, research-phase, pr-feedback, map-codebase | Primary team executes, writes state, next team reads state to continue |
+| Parallel (Oversight) | implement-plan | Engineering executes tasks; Micro-Management monitors state.yaml, flags concerns |
+| Parallel (Context) | pr-review | QA reviews code; Engineering provides context and addresses findings |
+| Direct | commit, generate-pr | Single agent, single Task invocation, no team coordination |
+
+</section>

package/framework/components/planning/TaskBreakdown.md

@@ -0,0 +1,83 @@
+---
+name: TaskBreakdown
+category: planning
+description: Break requirements or features into executable tasks
+params:
+  - name: source
+    type: string
+    options: ["requirements", "feature", "ticket", "freeform"]
+    default: "freeform"
+  - name: depth
+    type: string
+    options: ["shallow", "standard", "deep"]
+    default: "standard"
+  - name: mode
+    type: string
+    options: ["default", "dependencies"]
+    default: "default"
+---
+
+# TaskBreakdown
+
+## Default Behaviour
+
+1. **Understand the input** — what is being built, acceptance criteria, constraints
+2. **Identify components** — subsystems involved, files to touch, dependencies
+3. **Create task list** — each task is atomic (one commit), verifiable, ordered by dependency
+4. **Output structured tasks** using the format below
+
+---
+
+## Task Format
+
+```markdown
+<task id="{N}" type="auto|checkpoint:*" tdd="true|false" wave="{W}">
+
+## Task {N}: {Name}
+
+**Objective:** {What this task accomplishes}
+
+**Files:**
+- `path/to/file1.ts` - {what changes}
+
+**Implementation:**
+1. {Step 1}
+2. {Step 2}
+
+**Verification:**
+- [ ] {Verification check}
+
+**Done when:**
+- {Specific, observable completion criteria}
+
+</task>
+```
+
+Task types: `auto` (execute without stopping), `checkpoint:human-verify`, `checkpoint:decision`, `checkpoint:human-action`
+
+---
+
+## Dependency Analysis (mode="dependencies")
+
+For each task, identify:
+- **Hard dependencies**: Must complete in order (e.g., types needed by implementation)
+- **Soft dependencies**: Prefer order but can parallelise
+- **External dependencies**: May require checkpoint
+
+### Wave Assignment
+
+Tasks with no dependencies → Wave 1. Tasks depending on Wave N → Wave N+1.
+
+---
+
+## From Requirements (source="requirements")
+
+When breaking down from REQUIREMENTS.yaml: map REQ-IDs to tasks, track which tasks satisfy which requirements, ensure every in-scope requirement has at least one task.
+
+---
+
+## Granularity
+
+- **shallow**: 4-6 high-level tasks per feature
+- **standard**: 6-10 balanced tasks (default)
+- **deep**: 10-20 fine-grained tasks for complex/unfamiliar work

package/framework/components/planning/WaveComputation.md

@@ -0,0 +1,59 @@
+---
+name: WaveComputation
+category: planning
+description: Compute execution waves for parallel plan processing
+params:
+  - name: plans
+    type: array
+    required: true
+  - name: output
+    type: string
+    default: inline
+    description: Output format (inline|json)
+---
+
+# Wave Computation
+
+Analyses plan dependencies and groups plans into execution waves for parallel processing.
+
+## Algorithm
+
+```
+1. Build dependency graph:
+   For each plan P, for each requirement R in P.requires:
+     Find plan Q where Q.provides contains R → edge Q → P
+
+2. Topological sort with wave assignment:
+   Wave 1: Plans with no dependencies
+   Wave N: Plans whose dependencies are all in waves < N
+
+3. Output wave assignments
+```
+
+## Execution
+
+### Step 1: Extract Frontmatter
+
+For each plan file, parse `requires`, `provides`, and current `wave` from YAML frontmatter.
+
+### Step 2: Build Dependency Graph
+
+Map which plans depend on which based on requires/provides matching.
+
+### Step 3: Compute Waves
+
+Assign waves based on dependency resolution. Plans in the same wave can execute in parallel.
+
+### Step 4: Output
+
+**Inline**: Update each plan's frontmatter `wave` field.
+**JSON**: Return wave structure for executor with wave number, plan IDs, and parallelism flag.
+
+## Cross-Phase Dependencies
+
+Dependencies from previous phases (`requires.phase < current`) are assumed satisfied if that phase is complete. Verify via `.jdi/phases/{required-phase}/VERIFICATION.md`.
+
+## Error Handling
+
+- **Circular dependencies**: Report error with cycle path, suggest splitting a plan
+- **Missing provides**: Check if cross-phase; if not, report and suggest adding plan

package/framework/components/quality/PRReview.md

@@ -0,0 +1,196 @@
+---
+name: PRReview
+category: quality
+description: Review pull request changes and post line comments to GitHub
+params:
+  - name: pr_number
+    type: string
+    required: false
+    description: PR number to review (auto-detected if not provided)
+  - name: context
+    type: string
+    required: false
+    description: Extra context - ClickUp URL, focus areas, or specific instructions
+  - name: depth
+    type: string
+    required: false
+    options: ["quick", "standard", "thorough"]
+    default: "standard"
+    description: How deeply to analyse the changes
+  - name: post
+    type: boolean
+    required: false
+    default: true
+    description: Whether to post comments to GitHub (false = local review only)
+---
+
+# PRReview
+
+Review pull request changes with structured analysis and post line comments to GitHub.
+
+## Default Behaviour
+
+When invoked as `<JDI:PRReview />`, execute steps in order:
+
+### Step 1: Identify PR (REQUIRED)
+
+If PR number provided, use it. Otherwise detect:
+
+```bash
+gh pr view --json number,url,title,headRefName,baseRefName,author --jq '.'
+```
+
+If no PR found: report and **STOP completely**.
+
+### Step 2: Checkout PR Branch (REQUIRED)
+
+```bash
+git fetch origin
+gh pr checkout [pr_number]
+git branch --show-current
+```
+
+### Step 3: Gather PR Context
+
+```bash
+gh pr view [pr_number] --json title,body,additions,deletions,changedFiles,commits,labels
+gh pr view [pr_number] --json files --jq '.files[].path'
+gh pr diff [pr_number]
+gh pr view [pr_number] --json commits --jq '.commits[-1].oid'
+```
+
+### Step 4: Understand PR Intent
+
+1. Read PR description — what problem is being solved?
+2. Read commit messages — what approach was taken?
+3. Identify scope — what should/shouldn't be reviewed?
+
+If context provided:
+- ClickUp URL (`app.clickup.com`): Note for requirements checking
+- Focus keywords: Prioritise these areas
+- Instructions: Follow during review
+
+### Step 5: Read Changed Files FULLY
+
+Read each changed file in its entirety (not just the diff). **NEVER** use limit/offset.
+
+### Step 6: Perform Code Review
+
+Apply <JDI:PRReview:Checklist /> to analyse each change.
+
+### Step 7: Categorise Findings (Internal)
+
+Categorise using <JDI:PRReview:SeverityGuide />. Build internal list with: file path, line number, severity, title, explanation, suggested fix. Do NOT output detailed findings yet.
+
+### Step 8: Review Checkpoint
+
+Output finding counts by severity, total line comments, and review state (APPROVE | REQUEST_CHANGES).
+
+If `post="false"`: note output will go to `.jdi/reviews/PR-[number]-review.md`.
+
+**CHECKPOINT** — Wait for user: "continue" | "list" | "cancel"
+
+### Step 8a: After "continue":
+- `post="true"` (default): Continue to Step 9
+- `post="false"`: Execute `<JDI:PRReviewLocal />`, skip to Step 11
+
+### Steps 9-10: Build & Submit Review (post=true only)
+
+Use <JDI:PRReview:PostComments /> to build and submit the atomic review.
+
+### Step 11: Cleanup (MANDATORY)
+
+```bash
+git checkout master && git branch --show-current
+```
+
+Verify on `master`. Output: PR number, title, state, line comment count, URL, confirmed branch. If not on master, retry.
+
+---
+
+<section name="Checklist">
+
+## Review Checklist
+
+Apply during Step 6.
+
+| Category | Checks |
+|----------|--------|
+| **Correctness** | Logic sound, edge cases handled, error handling, type safety, null/undefined, async |
+| **Security** | No hardcoded secrets, input validated, injection prevented, XSS prevented, auth checks, no sensitive data logged |
+| **Performance** | No N+1 queries, large datasets efficient, no unnecessary re-renders, caching considered, no memory leaks |
+| **Architecture** | Follows patterns, separation of concerns, no circular deps, consistent APIs, appropriate scope |
+| **Style** | Clear naming, readable, no dead code, comments explain "why", consistent formatting |
+| **Testing** | New functionality tested, edge cases tested, meaningful tests, no flaky tests |
+| **Type Safety** | Types defined, no unnecessary `any`, null/undefined typed, generics appropriate |
+
+</section>
+
+---
+
+<section name="SeverityGuide">
+
+## Severity Classification
+
+Use during Step 7.
+
+| Emoji | Severity | Description | Action |
+|-------|----------|-------------|--------|
+| blocker | **Blocker** | Bugs, security issues, data loss risk | Must fix before merge |
+| major | **Major** | Significant issues, performance problems | Should fix before merge |
+| minor | **Minor** | Code quality, maintainability | Should fix, not blocking |
+| suggestion | **Suggestion** | Optional improvements | Consider for future |
+| question | **Question** | Clarification needed | Needs response |
+| praise | **Praise** | Good patterns worth highlighting | Positive feedback |
+
+### Event Logic
+
+- Any blockers, major, or minor findings: `REQUEST_CHANGES`
+- Suggestions only or no issues: `APPROVE`
+
+</section>
+
+---
+
+<section name="PostComments">
+
+## Post Comments to GitHub
+
+Use during Steps 9-10.
+
+> **CRITICAL**: Each finding MUST be a separate object in the `comments` array. The `body` field is ONLY for the summary table. All code-specific feedback goes in `comments` with exact `path` and `line`. Verify `comments` array has one entry per finding (excluding praise, which goes in summary body).
+
+### Get Repository Info
+
+```bash
+gh repo view --json owner,name --jq '"\(.owner.login)/\(.name)"'
+```
+
+### Comment Object Format
+
+```json
+{
+  "path": "[exact_file_path]",
+  "line": [line_number],
+  "side": "RIGHT",
+  "body": "[severity emoji] **[title]**\n\n[explanation]\n\n**Suggested fix:**\n```[language]\n[code]\n```\n\n- AI Ben"
+}
+```
+
+### Submit Review (SINGLE ATOMIC POST)
+
+```bash
+gh api repos/[owner]/[repo]/pulls/[pr_number]/reviews \
+  --input - <<'EOF'
+{
+  "commit_id": "[latest_commit_sha]",
+  "event": "[APPROVE|REQUEST_CHANGES]",
+  "body": "## Review Summary\n\n[assessment]\n\n| Category | Count |\n|----------|-------|\n| Blockers | [N] |\n| Major | [N] |\n| Minor | [N] |\n| Suggestions | [N] |\n\n**[N] line comments below.**\n\n- AI Ben",
+  "comments": [ ...comment objects... ]
+}
+EOF
+```
+
+**CHECKPOINT** — Wait for "post" or "cancel" before posting.
+
+</section>