@benzotti/jdi 0.1.46

package/framework/components/meta/StrictnessProtocol.md

@@ -0,0 +1,60 @@
+# StrictnessProtocol Component
+
+The discipline every JDI skill follows. Referenced by user-invocable commands to enforce deterministic, auditable behaviour on every invocation.
+
+When a command references `<JDI:StrictnessProtocol />`, these rules apply to the command's orchestration. They are **not suggestions** — they are the contract Claude honours for that skill.
+
+---
+
+## The Five Rules
+
+1. **Ask before assuming.** Never infer user intent from silence. If the skill requires information not visible on disk or in frontmatter, stop and ask. A missing answer is not permission to guess.
+
+2. **Present options, not mandates.** When multiple paths are valid, surface them as labelled choices (A / B / C) with the trade-off for each. The user picks — you do not pick for them and narrate.
+
+3. **The user decides strategy; you execute tactics.** Architecture, scope, priority, and verdict calls belong to the user. Naming, file placement, and code conventions belong to you. When in doubt which category a decision falls into, ask.
+
+4. **Never auto-run the next skill.** A skill's job ends when the user has a clear next action. Do not invoke downstream commands, spawn implementers after a plan approval, or chain skills silently. Each skill boundary is a human gate.
+
+5. **Adapt when the template doesn't fit.** The numbered workflow in each skill is the default path, not a prison. If the user's situation doesn't match any option, listen and adjust — but do so explicitly ("this doesn't fit option A/B/C/D — let me adapt…"), not by quietly drifting off-script.
+
+---
+
+## Inline Blocker Sentences
+
+Skills that reference this component will include explicit waiting sentences between steps, such as:
+
+- "Wait for the user's answer. Do not proceed until they respond."
+- "Store findings internally. Do NOT print them to the user yet."
+- "Stop here. Do not advance state until the user says `approved`."
+
+These are hard gates. Treat them as you would a `return` statement in code: execution stops until the condition is met.
+
+---
+
+## Silent Discovery Discipline
+
+Skills that also reference `<JDI:SilentDiscovery />` gather context from disk before asking questions. The two components compose:
+
+- `SilentDiscovery` defines **what** to read and how to store it
+- `StrictnessProtocol` defines **how** that discovered state shapes the conversation (never re-ask what's already on disk; surface findings only when relevant to the current step)
+
+---
+
+## Deviation Handling
+
+If you need to deviate from a skill's numbered workflow — because the user's situation doesn't fit, because a required file is missing, or because an edge case isn't covered — announce the deviation explicitly:
+
+> "This situation doesn't match the standard flow: {reason}. I'm going to {adapted approach} instead. Is that okay?"
+
+Then wait for confirmation. Silent deviation is the failure mode this protocol exists to prevent.
+
+---
+
+## Usage
+
+```
+<JDI:StrictnessProtocol />
+```
+
+Referenced in the footer of user-invocable commands (`/jdi:build`, `/jdi:create-plan`, `/jdi:implement-plan`, etc.) as the final reassertion of the non-negotiables before the HARD STOP gate.

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-programmer |
+| 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,95 @@
+---
+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}" priority="must|should|nice">
+
+## Task {N}: {Name}
+
+**Priority:** must | should | nice
+
+**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
+
+---
+
+## Priority Bands
+
+Every task MUST be tagged with one of three priority bands:
+
+- **Must Have** (critical path — plan fails if not delivered)
+- **Should Have** (planned but droppable under pressure)
+- **Nice to Have** (delivered only with surplus capacity)

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 programmer 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,225 @@
+---
+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 5b: Cross-Reference Learnings (MANDATORY)
+
+If learnings files were loaded (via the command stub or agent prompt), cross-reference every changed file against the team's learnings:
+
+1. For each finding from the review checklist, check if a learning exists that addresses it — cite the learning in your comment.
+2. Flag any code that **violates** a documented learning (e.g. a learning says "always use path aliases" but the PR uses relative imports).
+3. **Praise** code that follows learnings the team has documented — this reinforces good patterns.
+4. If no learnings were loaded, skip this step (but note it in your review summary as a gap).
+
+Learnings-based findings should use the same severity classification as other findings. A violation of a documented team convention is at minimum a **minor** finding.
+
+### Step 6: Perform Code Review
+
+Apply <JDI:PRReview:Checklist /> to analyse each change. Include learnings violations alongside standard checklist findings.
+
+### 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 the LocalOutput section below, 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>
+
+---
+
+<section name="LocalOutput">
+
+## Local Review Output
+
+When `post="false"` or invoked with `<JDI:PRReview post="false" />`:
+
+Skip Steps 9-10 (posting to GitHub). Instead, write the full structured review to a file:
+
+1. **Create the directory** if it does not exist: `mkdir -p .jdi/reviews`
+2. **Write** to `.jdi/reviews/PR-{pr_number}-review.md` with frontmatter (pr, title, author, branch, url, reviewed_at, verdict, findings counts) followed by: Summary, Findings (organised by severity highest to lowest), and Checklist.
+3. **Confirm**: Output the file path, finding counts, and verdict.
+
+Then proceed to Step 11 (return to master).
+
+</section>

package/framework/config/jdi-config.yaml

@@ -0,0 +1,159 @@
+# JDI Global Configuration
+# Edit these settings to customise JDI behaviour
+
+version: "1.0.0"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Workflow Settings
+# ─────────────────────────────────────────────────────────────────────────────
+workflow:
+  # Mode: yolo (autonomous) | interactive (confirm gates) | strict (all confirmations)
+  mode: yolo
+
+  # Depth: shallow | standard | deep (affects task granularity)
+  depth: standard
+
+  # Enable parallel plan execution within waves
+  parallelisation: true
+
+  # Commit planning docs to git
+  commit_docs: true
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Agent Toggles
+# ─────────────────────────────────────────────────────────────────────────────
+agents:
+  # Run research phase before planning
+  research: true
+
+  # Validate plans before execution
+  plan_check: true
+
+  # Verify outcomes after execution
+  verifier: true
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Model Routing
+# ─────────────────────────────────────────────────────────────────────────────
+models:
+  # Active profile: quality | balanced | budget
+  profile: balanced
+
+  # Profile definitions (agent -> model mapping)
+  profiles:
+    # Maximum reasoning power, use for critical work (~100% token baseline)
+    quality:
+      planner: opus
+      architect: opus
+      programmer: opus
+      verifier: sonnet
+      researcher: sonnet
+      phase_researcher: sonnet
+      plan_checker: sonnet
+      debugger: opus
+      quality: sonnet
+
+    # Smart allocation for typical development (~40% less than quality)
+    balanced:
+      planner: opus
+      architect: opus
+      programmer: sonnet
+      verifier: sonnet
+      researcher: sonnet
+      phase_researcher: sonnet
+      plan_checker: sonnet
+      debugger: sonnet
+      quality: sonnet
+
+    # Minimal opus usage, conserve quota (~60% less than quality)
+    budget:
+      planner: sonnet
+      architect: sonnet
+      programmer: sonnet
+      verifier: haiku
+      researcher: haiku
+      phase_researcher: haiku
+      plan_checker: haiku
+      debugger: sonnet
+      quality: haiku
+
+  # Override specific agents (null = use profile default)
+  overrides:
+    planner: null
+    programmer: null
+    verifier: null
+    researcher: null
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Default Paths and Values
+# ─────────────────────────────────────────────────────────────────────────────
+defaults:
+  branch_prefix: "feature/"
+  commit_types:
+    - feat
+    - fix
+    - refactor
+    - docs
+    - test
+    - chore
+    - perf
+    - style
+  plan_location: .jdi/plans
+  state_location: .jdi
+  thoughts_location: .jdi/thoughts
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Git Settings
+# ─────────────────────────────────────────────────────────────────────────────
+git:
+  # Automatically stage changes before commit
+  auto_stage: false
+
+  # Require clean worktree before operations
+  require_clean_worktree: false
+
+  # Branches that cannot be directly modified
+  protected_branches:
+    - main
+    - master
+    - develop
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Quality Gates
+# ─────────────────────────────────────────────────────────────────────────────
+quality:
+  # Run linter before each commit
+  run_lint_before_commit: true
+
+  # Run tests before creating PR
+  run_tests_before_pr: true
+
+  # Require verification pass before marking complete
+  require_verification: true
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Context Management
+# ─────────────────────────────────────────────────────────────────────────────
+context:
+  # Maximum files to include per task context
+  max_files_per_task: 5
+
+  # Number of tasks before recommending split
+  split_threshold_tasks: 3
+
+  # Context budget thresholds (0.0 - 1.0)
+  context_budget_warning: 0.5   # Yellow zone
+  context_budget_critical: 0.7  # Red zone
+
+# ─────────────────────────────────────────────────────────────────────────────
+# UI Settings
+# ─────────────────────────────────────────────────────────────────────────────
+ui:
+  # Show progress banners during execution
+  show_progress_banners: true
+
+  # Enable verbose output
+  verbose_mode: false
+
+  # Use emoji in output (disabled for cleaner logs)
+  emoji_enabled: false