@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/schemas/agent-state.schema.json

@@ -0,0 +1,273 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/agent-state.schema.json",
+  "title": "Multi-Agent Pipeline — agent-state.json",
+  "description": "Canonical state file for a single pipeline run. Written to $HOME/.claude/logs/multi-agent/{project}/{task-id}/agent-state.json and read by every phase. Versioned so older runs can be migrated or ignored.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "taskId",
+    "shortId",
+    "project",
+    "branch",
+    "baseBranch",
+    "currentPhase",
+    "status",
+    "startedAt",
+    "phases",
+    "identity"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "enum": ["2.0.0", "2.1.0"],
+      "description": "v2.0.0: single-repo only (scalar project/projectRoot/worktreePath). v2.1.0: adds optional projects[] array for multi-repo tasks — single-repo fields remain for backward compat; when projects[] has >1 entries, multi-repo mode is active."
+    },
+    "taskId": {
+      "type": "string",
+      "description": "Canonical task id — Jira key (PROJ-12345), GitHub issue number (#316), or free-text slug.",
+      "minLength": 1
+    },
+    "shortId": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Auto-incremented local short id from .worktrees/.multi-agent-counter — unique per machine, not per project."
+    },
+    "jiraId": {
+      "type": ["string", "null"],
+      "description": "Jira issue key (PROJ-12345) if the task originated from Jira, else null."
+    },
+    "githubIssue": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "owner": { "type": "string" },
+        "repo": { "type": "string" },
+        "number": { "type": "integer", "minimum": 1 }
+      },
+      "required": ["owner", "repo", "number"],
+      "description": "GitHub issue coordinates if the task originated from GitHub, else null."
+    },
+    "project": {
+      "type": "string",
+      "description": "Project slug — used to partition logs and knowledge base."
+    },
+    "projectRoot": {
+      "type": "string",
+      "description": "Absolute path to the main checkout."
+    },
+    "worktreePath": {
+      "type": ["string", "null"],
+      "description": "Absolute path to the task worktree. Null in --local mode."
+    },
+    "branch": { "type": "string", "description": "Working branch for this task." },
+    "baseBranch": { "type": "string", "description": "PR target branch (e.g. develop, main)." },
+    "remoteType": {
+      "type": "string",
+      "enum": ["github", "bitbucket"],
+      "description": "Determines which PR API and reviewer strategy is used."
+    },
+    "currentPhase": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 7,
+      "description": "Last phase the orchestrator entered. Resume re-enters at currentPhase + 1."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["in_progress", "paused", "complete", "failed"],
+      "description": "Overall task status."
+    },
+    "startedAt": { "type": "string", "format": "date-time" },
+    "finishedAt": { "type": ["string", "null"], "format": "date-time" },
+    "autopilot": { "type": "boolean", "default": false },
+    "onlyDevelop": {
+      "type": "boolean",
+      "default": false,
+      "description": "--dev flag — phases 1, 2, 4, 5 are skipped."
+    },
+    "localMode": {
+      "type": "boolean",
+      "default": false,
+      "description": "--local flag — no worktree, direct branch in projectRoot."
+    },
+    "instructionDriven": {
+      "type": "boolean",
+      "default": false,
+      "description": "A Figma / skill instruction file is steering phases 3-6."
+    },
+    "identity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "email"],
+      "properties": {
+        "name": { "type": "string" },
+        "email": { "type": "string", "format": "email" },
+        "username": { "type": "string", "description": "SCM username (GitHub/Bitbucket). Used to filter out PR author from reviewer list." }
+      }
+    },
+    "phases": {
+      "type": "object",
+      "description": "Per-phase status + outputs. Keys are phase numbers as strings (\"0\"..\"7\").",
+      "patternProperties": {
+        "^[0-7]$": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "status": { "type": "string", "enum": ["pending", "in_progress", "done", "skipped", "failed"] },
+            "startedAt": { "type": "string", "format": "date-time" },
+            "finishedAt": { "type": "string", "format": "date-time" },
+            "model": { "type": "string" },
+            "files": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Files produced or modified by this phase. Used for semantic revert."
+            },
+            "retryCount": { "type": "integer", "minimum": 0, "maximum": 3 },
+            "notes": { "type": "string" },
+            "clarificationRounds": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 2,
+              "description": "v5.3.0 Phase 2 Plan Approval Gate — number of clarification question/answer rounds the orchestrator ran before producing the first plan. Cap 2; hitting the cap produces a 'best-effort' plan instead of asking more questions. Only emitted in normal mode (skipped for --dev, autopilot, --dev autopilot)."
+            },
+            "clarificationQuestions": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "v5.3.0 Phase 2 — ordered log of questions the orchestrator asked the user when the issue description was ambiguous (missing acceptance criteria, vague language, missing Figma/endpoint links, unclear scope vs. parent story)."
+            },
+            "clarificationAnswers": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "v5.3.0 Phase 2 — ordered log of user answers aligned with clarificationQuestions (same length)."
+            },
+            "planIterations": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "v5.3.0 Phase 2 Plan Approval Gate — how many plan revisions the user requested before approving. 1 = approved on first show; N = user sent N-1 free-text edit requests and the plan was re-rendered each time."
+            },
+            "planApprovedAt": {
+              "type": ["string", "null"],
+              "format": "date-time",
+              "description": "v5.3.0 Phase 2 Plan Approval Gate — timestamp when the user approved the plan. Null when the gate is not applicable (--dev, autopilot, --dev autopilot) or the task was aborted at the gate."
+            },
+            "planEditRequests": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "v5.3.0 Phase 2 — free-text edit instructions the user typed between plan renders. Preserved verbatim for audit; Opus parses them conversationally to revise the plan."
+            }
+          }
+        }
+      }
+    },
+    "reviewIterations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "iteration": { "type": "integer", "minimum": 1 },
+          "blocking": { "type": "integer", "minimum": 0 },
+          "important": { "type": "integer", "minimum": 0 },
+          "suggestion": { "type": "integer", "minimum": 0 },
+          "decision": { "type": "string", "enum": ["fix", "accept", "escalate"] }
+        }
+      }
+    },
+    "confluenceSpace": {
+      "type": ["string", "null"],
+      "description": "Cached Confluence space key for the project — avoids re-asking on every run."
+    },
+    "confluenceParentId": {
+      "type": ["string", "null"],
+      "description": "Cached Confluence parent page id."
+    },
+    "pr": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "number": { "type": "integer", "minimum": 1 },
+        "url": { "type": "string", "format": "uri" },
+        "version": { "type": "integer", "minimum": 0, "description": "Bitbucket PR version — must increment by 1 per PUT." },
+        "draft": { "type": "boolean" },
+        "reviewers": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "commit": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "sha": { "type": "string", "minLength": 7 },
+        "message": { "type": "string" }
+      }
+    },
+    "projects": {
+      "type": "array",
+      "description": "v2.1.0+. Per-repo state for multi-repo tasks. When present and len > 1, multi-repo mode is active; the scalar project/projectRoot/worktreePath fields at top level refer to the primary (first) repo. Each entry mirrors the top-level single-repo fields plus its own identity and commit.",
+      "minItems": 1,
+      "maxItems": 10,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["project", "projectRoot", "branch", "baseBranch", "identity"],
+        "properties": {
+          "project": { "type": "string" },
+          "projectRoot": { "type": "string" },
+          "worktreePath": { "type": ["string", "null"] },
+          "branch": { "type": "string" },
+          "baseBranch": { "type": "string" },
+          "remoteType": {
+            "type": "string",
+            "enum": ["github", "bitbucket", "gitlab", "generic-git"]
+          },
+          "identity": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "email"],
+            "properties": {
+              "name": { "type": "string" },
+              "email": { "type": "string", "format": "email" },
+              "username": { "type": "string" }
+            }
+          },
+          "platform": {
+            "type": "string",
+            "enum": ["bitbucket", "github", "gitlab", "generic-git"],
+            "description": "Host platform for this repo (derived from origin URL)."
+          },
+          "commit": {
+            "type": ["object", "null"],
+            "additionalProperties": false,
+            "properties": {
+              "sha": { "type": "string", "minLength": 7 },
+              "message": { "type": "string" }
+            }
+          },
+          "pr": {
+            "type": ["object", "null"],
+            "additionalProperties": false,
+            "properties": {
+              "number": { "type": "integer", "minimum": 1 },
+              "url": { "type": "string", "format": "uri" },
+              "draft": { "type": "boolean" }
+            }
+          },
+          "pushAttempts": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "v2.1.0+ push-must-succeed retry counter. Increments per rebase-retry."
+          },
+          "buildStatus": {
+            "type": "string",
+            "enum": ["pending", "passed", "failed"],
+            "description": "Latest Phase 3 build outcome for this repo."
+          }
+        }
+      }
+    }
+  }
+}

package/pipeline/schemas/analysis-output.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/analysis-output.schema.json",
+  "version": "1.0.0",
+  "title": "Multi-Agent Pipeline — Phase 1 analysis output",
+  "description": "Contract for the Explorer subagent's summary in Phase 1. Drives Phase 2 task decomposition and Phase 4 review focus. Explorer must not mutate the codebase; output is read-only research.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["stack", "touchedAreas", "risks", "summary"],
+  "properties": {
+    "stack": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["primary"],
+      "properties": {
+        "primary": {
+          "type": "string",
+          "enum": ["ios", "android", "backend", "frontend", "mobile", "unknown"],
+          "description": "Dominant stack inferred from project markers (.xcodeproj, build.gradle, package.json, etc.)."
+        },
+        "language": { "type": "string", "description": "E.g. 'Swift 6', 'Kotlin 2.1', 'Python 3.13', 'TypeScript 5'." },
+        "framework": { "type": "string", "description": "E.g. 'SwiftUI', 'Jetpack Compose', 'FastAPI', 'Next.js 16'." }
+      }
+    },
+    "touchedAreas": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "why"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1, "description": "File or directory relative to repo root." },
+          "why": { "type": "string", "minLength": 4, "description": "Why the task likely affects this area." }
+        }
+      },
+      "description": "Files / modules the task is most likely to modify. Phase 2 uses this to scope tasks."
+    },
+    "risks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["risk", "severity"],
+        "properties": {
+          "risk": { "type": "string", "minLength": 4 },
+          "severity": { "type": "string", "enum": ["low", "medium", "high"] },
+          "mitigation": { "type": ["string", "null"] }
+        }
+      },
+      "description": "Known hazards surfaced by exploration — concurrency hotspots, deprecated APIs, tech debt, missing tests."
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 20,
+      "description": "≤200 word plain-language summary for Phase 2 planning + user approval."
+    }
+  }
+}

package/pipeline/schemas/clarify-output.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://example.com/pipeline/clarify-output.schema.json",
+  "title": "Clarification Output",
+  "description": "Schema for Phase 0 Step 9 task-clarifier sub-agent output. Source: pipeline/agents/task-clarifier.md. Pattern reference: Devin clarifying-question loop (https://docs.devin.ai/work-with-devin/devin-review) and Cursor Plan Mode (https://cursor.com/docs/agent/planning).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["clarityScore", "questions", "stopAndAsk"],
+  "properties": {
+    "clarityScore": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 10,
+      "description": "How clearly the task is specified — 10 = crystal clear, 0 = title-only. Rubric in task-clarifier.md."
+    },
+    "rationale": {
+      "type": "string",
+      "description": "One-sentence justification for the score, citing the line of the issue body that drove it."
+    },
+    "stopAndAsk": {
+      "type": "boolean",
+      "description": "Orchestrator-facing flag. true → Phase 0 pauses and asks the user (interactive) or follows autopilotMode (autopilot). false → proceed silently to Phase 1."
+    },
+    "questions": {
+      "type": "array",
+      "maxItems": 5,
+      "description": "Clarifying questions to ask. Empty array when stopAndAsk is false.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "text"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^q[0-9]+$",
+            "description": "Stable identifier within this clarification round (q1, q2, …)."
+          },
+          "text": {
+            "type": "string",
+            "description": "Question to display to the user. One sentence, ends with a question mark."
+          },
+          "options": {
+            "type": "array",
+            "minItems": 2,
+            "maxItems": 4,
+            "description": "Discrete answer choices. Omit when the answer is genuinely free-text (an identifier, URL, number).",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["label"],
+              "properties": {
+                "label":       { "type": "string", "description": "The choice text (≤ 60 chars; longer wraps awkwardly in AskUserQuestion)." },
+                "recommended": { "type": "boolean", "default": false, "description": "True for the conventional default. At most one option per question carries this flag." },
+                "reason":      { "type": "string", "description": "One-line tradeoff hint — why this choice would or would not be the right pick." }
+              }
+            }
+          },
+          "reason": {
+            "type": "string",
+            "description": "Why this question is being asked — cite the source of ambiguity, ideally quoting the issue line."
+          }
+        }
+      }
+    },
+    "userAnswers": {
+      "type": "object",
+      "description": "Filled in AFTER the orchestrator runs AskUserQuestion. Keys are question IDs (q1, q2, …) and values are the selected label or free-text response. Empty during the agent's own emission.",
+      "additionalProperties": { "type": "string" }
+    },
+    "tokens_in":   { "type": "integer", "minimum": 0 },
+    "tokens_out":  { "type": "integer", "minimum": 0 },
+    "duration_ms": { "type": "integer", "minimum": 0 }
+  }
+}

package/pipeline/schemas/dev-critic-output.schema.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://example.com/pipeline/dev-critic-output.schema.json",
+  "title": "Dev Critic Output",
+  "description": "Schema for Phase 3.5 evaluator-optimizer (dev-critic) sub-agent output. Source: pipeline/agents/dev-critic.md. Pattern reference: Anthropic 'Building Effective Agents' (Dec 2024) — evaluator-optimizer.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["pass", "iteration", "gates", "findings"],
+  "properties": {
+    "pass": {
+      "type": "boolean",
+      "description": "true if all mandatory gates passed AND no blocking findings remain. false otherwise — generator must iterate."
+    },
+    "iteration": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 3,
+      "description": "1-indexed critic round. 1 = full pass. 2 = re-check round-1 failures only. 3 = NOT recommended (escalate should be true)."
+    },
+    "escalate": {
+      "type": "boolean",
+      "default": false,
+      "description": "true when critic has hit the loop cap (devCritic.maxIterations) and gates still fail. Orchestrator decides next step (pause user / proceed with logged failure / abort)."
+    },
+    "gates": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["build", "lint", "test", "secrets"],
+      "properties": {
+        "build": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status"],
+          "properties": {
+            "status": { "type": "string", "enum": ["pass", "fail", "skipped"] },
+            "skip_reason": { "type": "string", "description": "Required when status == 'skipped'. E.g. 'xcodebuild not installed on this runner'." },
+            "error_summary": { "type": "string", "description": "First failure line + count when status == 'fail'." }
+          }
+        },
+        "lint": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status"],
+          "properties": {
+            "status": { "type": "string", "enum": ["pass", "fail", "skipped"] },
+            "tool": { "type": "string", "description": "swiftlint | ktlint | eslint | ruff | ..." },
+            "errors": { "type": "integer", "minimum": 0 },
+            "warnings": { "type": "integer", "minimum": 0 },
+            "skip_reason": { "type": "string" }
+          }
+        },
+        "test": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status"],
+          "properties": {
+            "status": { "type": "string", "enum": ["pass", "fail", "skipped"] },
+            "passed": { "type": "integer", "minimum": 0 },
+            "failed": { "type": "integer", "minimum": 0 },
+            "skipped_count": { "type": "integer", "minimum": 0 },
+            "skip_reason": { "type": "string" }
+          }
+        },
+        "secrets": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status"],
+          "properties": {
+            "status": { "type": "string", "enum": ["pass", "fail"] },
+            "matched_patterns": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Pattern names that matched (never the actual secret value)."
+            }
+          }
+        }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["severity", "file", "issue"],
+        "properties": {
+          "severity": { "type": "string", "enum": ["blocking", "important", "suggestion"] },
+          "file": { "type": "string", "description": "Repo-relative path. For multi-repo tasks, prefixed with '<repo-name>/'." },
+          "line": { "type": "integer", "minimum": 1 },
+          "rule": { "type": "string", "description": "Citation. Format: 'rules/<file>.md#<anchor>' or 'gate/<name>'." },
+          "issue": { "type": "string", "description": "Short, one-sentence description." },
+          "fix": { "type": "string", "description": "Concrete suggestion the generator can act on without re-reading the rule." }
+        }
+      }
+    },
+    "duration_ms": { "type": "integer", "minimum": 0 },
+    "tokens_in": { "type": "integer", "minimum": 0 },
+    "tokens_out": { "type": "integer", "minimum": 0 },
+    "stack": {
+      "type": "string",
+      "description": "Stack used for checklist selection (echoed from Phase 1 detectedStack).",
+      "enum": ["ios", "android", "backend", "node", "python", "docker", "generic"]
+    }
+  }
+}

package/pipeline/schemas/diff-risk.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/diff-risk.schema.json",
+  "version": "1.0.0",
+  "title": "Multi-Agent Pipeline — Phase 4 diff risk score",
+  "description": "Output contract for diff-risk-score.mjs. Heuristic, deterministic, no LLM. Produced before Phase 4 Step 2 to give reviewer prompts a priority ordering — never used as a gate.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "task", "totals", "files"],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "task": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["base", "head"],
+      "properties": {
+        "id": { "type": ["string", "null"] },
+        "base": { "type": "string", "description": "Base ref (e.g. origin/main)." },
+        "head": { "type": "string", "description": "Head ref (e.g. HEAD or branch name)." },
+        "ts": { "type": "string", "format": "date-time" }
+      }
+    },
+    "totals": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["files", "loc_added", "loc_removed", "max_score"],
+      "properties": {
+        "files": { "type": "integer", "minimum": 0 },
+        "loc_added": { "type": "integer", "minimum": 0 },
+        "loc_removed": { "type": "integer", "minimum": 0 },
+        "max_score": { "type": "number", "minimum": 0 }
+      }
+    },
+    "files": {
+      "type": "array",
+      "description": "One entry per changed file, sorted by score descending. Top-N (caller-controlled, default 5) feeds the reviewer priority hint.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "score", "loc_added", "loc_removed", "signals"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "score": { "type": "number", "minimum": 0 },
+          "loc_added": { "type": "integer", "minimum": 0 },
+          "loc_removed": { "type": "integer", "minimum": 0 },
+          "signals": {
+            "type": "array",
+            "description": "Heuristic signals that contributed to the score. Each entry is a {name, weight, value} triple — name is the rule id (e.g. 'security_path'), weight is its multiplier from rules table, value is the rule's evaluated quantity (loc, count, 1 for booleans).",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["name", "weight", "value"],
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "enum": [
+                    "loc_changed",
+                    "security_path",
+                    "public_api",
+                    "no_test_change",
+                    "complexity_delta",
+                    "ui_critical",
+                    "migration"
+                  ]
+                },
+                "weight": { "type": "number" },
+                "value": { "type": "number" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}