Job Orchestrator

Job Orchestrator

Purpose

Dynamic orchestrator that builds execution plans based on user intent. Unlike a fixed pipeline, the orchestrator adapts its workflow to what the user actually needs — from "just analyze this issue" to "implement, review, and create a PR". It dispatches sub-agents (issue-analyzer, context-collector, task-implementer, review skills) and persists all work via job-documenter.

Execution metrics (opt-in): when a USER runs this orchestrator directly (not as a dispatched subagent), at the start ask "Collect execution statistics for this run? (yes/no)" per .metaproject/rules/core/execution-metrics.md. If yes, append the ## Execution Metrics section at the end and save it under the job dir (jobs/<job>/metrics/). Never ask or emit it when dispatched as a subagent.

Key design principle (from Anthropic's "Building Effective Agents"):

"The key difference from parallelization is its flexibility — subtasks aren't pre-defined, but determined by the orchestrator based on the specific input."

Input: User request (issue URL, analysis request, implementation request, etc.) Output: Executed plan + persistent job documentation in .metaproject/jobs/<job-name>/ + optional PR

When to Use

• Implementing a complete GitHub issue from start to finish
• Analyzing an issue and proposing a solution before implementing
• Running any multi-step orchestrated workflow
• Running a comprehensive code review with persistent documentation
• When the AGENTS.md routing rule (Step 1.5) determines the user wants orchestrated execution and the user confirms
• User says "implement issue #N", "analyze issue #N", provides an issue URL, or asks for orchestrated work
• User says "full review", "полное ревью", or any request that implies orchestration

Architecture: 4 Dynamic Phases

Phase 0: CONTEXT COLLECTION  →  Gather info, determine intent
Phase 1: PLAN BUILDING       →  Build dynamic plan, init job docs
Phase 2: EXECUTION           →  Execute plan steps, document each result
Phase 3: COMPLETION          →  Final report, optional PR, tell user where docs are

Phase 0: CONTEXT COLLECTION

0.0 State Resumption Check

Before asking any questions, check if an interrupted job exists:

1. Look in $JOBS_ROOT for any directory containing an incomplete state.json.
2. If found, ASK the user: "Found paused job ''. Do you want to resume it or start a new orchestrated job?"
3. If resume → Parse state.json, restore JOB_STATE, and jump directly to the first uncompleted step in Phase 2.
4. If new → Proceed to 0.1.

0.1 Determine User Intent

Parse the user's request to identify the intent:

Ambiguity detection: If the request uses vague words ("improve", "fix", "refactor") with no issue number or specific file — trigger the Interactive Approach Selection below.

0.1.1 Interactive Approach Selection (for ambiguous requests)

When intent cannot be determined confidently, present options to the user:

I see several ways to approach this. Which fits best?

  A) 🔍 Analysis only — decompose into tasks, show plan, stop
  B) 🛠 Full implementation — analyze → implement → review → PR
  C) 📋 Analysis + brainstorm — explore approaches before committing
  D) 🔧 Review only — review current branch changes
  E) 📝 Custom — describe what you need, I'll build the plan

> pick a letter or describe your own approach

Mapping:

• A → analyze intent
• B → implement intent
• C → analyze intent + trigger brainstorm after analysis
• D → review intent
• E → custom intent → proceed to 0.1.5 (interviewer gate)

Skip this step when intent is clear (explicit issue number, "implement issue #N", "review my code").

0.1.5 Interviewer Gate (for custom and ambiguous requests)

For custom intent OR any ambiguous request, invoke the interviewer skill before collecting standard context. This replaces the generic "What do you need?" question with a structured critical interview.

Invoke:

Load skill: skills/interviewer/SKILL.md

INPUT:
  topic: <user's original request>
  goal: "job-orchestrator — build execution plan"
  context:
    codebase_summary: <git log --oneline -10 if available>
    existing_analysis: <any issue content already known>

Map output:

• derived_context → INTENT_STATE.task_description
• answers with confidence: "certain" → INTENT_STATE.constraints
• blockers → surface to user (if non-empty, do NOT proceed)

Gate rule:

• ready_to_proceed: false → STOP. Tell user what blockers remain.
• ready_to_proceed: true → continue to 0.2 with enriched context.

Skip for implement/analyze with an issue number — requirements are in the issue.

0.2 Collect Required Context

The orchestrator MUST collect all required context before proceeding:

Always ask (mandatory):

1. What to do — for implement/analyze: from issue. For custom: from interviewer output (0.1.5).

2. Project directory — NEVER assume. Always ask explicitly:

   Which project directory should I use?
   ○ Type the full absolute path to your project
   (No default — always ask, never assume.)
   

3. Base branch — auto-detect from repo:

   # Detect default branch
   git -C <project_dir> symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'
   # Fallback: check for main, master, develop
   

   Present detected branch and ask to confirm. No hardcoded default.

Intent-specific questions:

4. Job name — auto-generate based on context, ask user to confirm:

   Job documentation folder:
   ○ issue-4141--pipeline-validation  (auto-generated, Recommended)
   ○ Type your own name
   

   Naming patterns:

   • Issue implementation: issue-<N>--<slug>
   • Issue analysis: analysis--issue-<N>
   • Code review: review--<slug>
   • Custom: task--<slug>

0.3 Interview for Implement Intent

For implement intent, dispatch interview skill after collecting context to clarify implementation-specific ambiguities (complements 0.1.5 which handles custom intent):

Dispatch interview skill with:
{
  "goal": <issue title>,
  "context": <collected context + issue body>,
  "domain": "implement",
  "caller": "job-orchestrator",
  "known_facts": [project_dir, base_branch, issue details],
  "max_questions": null
}

When to run: implement intent only (if run_interview: true, default). Skip for: analyze (analysis reveals details), review (scoped by diff), custom (covered by 0.1.5).

Output → Phase 1: INTERVIEW_RESULT feeds into plan building — informs task decomposition and architecture.

Brainstorm trigger: If during interview the user answers "not sure" or the interview identifies an unresolved architectural question (high-impact decision with no clear answer), auto-trigger:

Dispatch brainstorm --quick with:
  topic: <the specific architectural question>
  context: <project stack + interview answers so far>

Present brainstorm result as enriched answer options, then continue interview.

Skip if: user says "just do it" / "skip questions", or run_interview: false.

0.3.1 Dependency Check

If the issue or interview reveals the task is primarily about updating dependencies:

IF issue title/body contains "update", "upgrade", "bump", "dependency", "CVE":
  Suggest: "This looks like a dependency update task. Use /dependency-update instead?"
  IF user confirms → delegate to dependency-update skill, skip orchestrator pipeline

0.4 Summarize and Confirm

Before proceeding, present a summary:

Ready to proceed:
  Intent:    implement
  Issue:     #4141 — Pipeline validation improvements
  Project:   /Users/.../<PROJECT>
  Base:      develop-2
  Create PR: yes
  Job name:  issue-4141--pipeline-validation

Proceed? (yes / adjust)

Phase 1: PLAN BUILDING

1.1 Build Execution Plan

Based on intent, construct an ordered list of steps:

For implement intent:

PLAN:
  1.  { id: "analyze",        type: "analyze",   agent: "issue-analyzer",    depends: [] }
  2.  { id: "context",        type: "context",   agent: "context-collector", depends: ["analyze"] }
  3.  { id: "prepare",        type: "prepare",   agent: "orchestrator",      depends: ["context"] }
  4.  { id: "tests-creator",  type: "tests",     agent: "tests-creator",     depends: ["prepare"] }
  5.  { id: "implement",      type: "implement", agent: "task-implementer",  depends: ["tests-creator"] }
  6.  { id: "sanity-check",    type: "check",    agent: "orchestrator",    depends: ["implement"] }
  7.  { id: "verify",          type: "verify",   agent: "code-verifier",   depends: ["sanity-check"] }
  8.  { id: "review",          type: "review",   agent: "code-review",     depends: ["verify"] }
  9.  { id: "security",        type: "security", agent: "security-audit",  depends: ["implement"], conditional: true }
  10. { id: "fix",             type: "fix",      agent: "task-implementer", depends: ["review"], conditional: true }
  11. { id: "verify-post-fix", type: "verify",   agent: "code-verifier",   depends: ["fix"], conditional: true }
  12. { id: "perf-check",      type: "perf",     agent: "perf-check",      depends: ["verify"], conditional: true }
  13. { id: "report",          type: "report",   agent: "orchestrator",    depends: ["verify"] }
  14. { id: "pr",              type: "pr",       agent: "orchestrator",    depends: ["report"], conditional: true }
  15. { id: "deploy",          type: "deploy",   agent: "deploy",          depends: ["pr"], conditional: true }

Conditional step triggers:

• sanity-check: always runs — verifies ≥1 commit was made
• tests-creator: always runs — mandatory TDD step before every task-implementer wave
• verify: always runs — code-verifier is the mandatory quality gate after implementation
• security: diff touches auth/, api/, migrations, schema files, or .env
• fix: review or verify found CRITICAL/HIGH findings
• verify-post-fix: always runs after fix (confirms fix resolved the findings)
• perf-check: diff contains *.tsx, *.jsx, *.css, dist/, build/ files
• security: diff touches auth/, api/, migrations, schema files, or .env
• fix: review found CRITICAL/WARNING findings
• perf-check: diff contains *.tsx, *.jsx, *.css, dist/, build/ files
• pr: create_pr: true
• deploy: user answers "yes" to post-PR staging deploy prompt

Note: security runs in parallel with review (both depend on implement results, no overlap).

For analyze intent:

PLAN:
  1. { id: "analyze",   type: "analyze",  agent: "issue-analyzer",    depends: [] }
  2. { id: "context",   type: "context",  agent: "context-collector", depends: ["analyze"] }
  3. { id: "report",    type: "report",   agent: "orchestrator",      depends: ["context"] }
  4. { id: "proposal",  type: "proposal", agent: "orchestrator",      depends: ["report"] }

Step 4 (proposal) asks the user: "Want me to implement this? If yes, I'll extend the plan."

For review intent:

PLAN:
  1. { id: "context",  type: "context", agent: "context-collector", depends: [] }
  2. { id: "review",   type: "review",  agent: "reviewers",         depends: ["context"] }
  3. { id: "report",   type: "report",  agent: "orchestrator",      depends: ["review"] }

For custom intent: Build plan dynamically. Each step must have: id, type, agent, dependencies.

1.2 Initialize Job Documentation

Dispatch job-documenter with init action:

Task({
  description: "Init job docs: <job-name>",
  subagent_type: "general",
  prompt: |
    You are the job-documenter agent.
    Load skill: skills/job-documenter/SKILL.md
    Follow rules: rules/core/jobs-documentation.mdc

    ACTION: init
    JOB_NAME: <job-name>
    JOBS_ROOT: <JOBS_ROOT>

    DATA:
      TITLE: <job title>
      DESCRIPTION: <description>
      INTENT: <intent>
      SOURCE: <issue URL or description>
      PROJECT: <project path>
      BRANCH: TBD
      BASE_BRANCH: <base branch>
      PLAN: <plan steps>

    Execute and return DOCUMENTER_RESULT.
})

Validate response: status must be success. If error → report to user, ask how to proceed.

1.3 Display Plan + Agent Approval

Show each step with its agent and status, then ask the user to approve or adjust:

Execution plan — <N> steps:

  Step 1   analyze          issue-analyzer              → issue #<N>
  Step 2   context          context-collector           → project context + test framework
  Step 3   prepare          orchestrator                → feature branch
  Step 4   tests-creator    tests-creator × <tasks>     → RED test stubs per task (MANDATORY)
  Step 5   implement        task-implementer × <tasks>  → <N> tasks make tests GREEN (wave-parallel)
  Step 6   sanity-check     orchestrator                → verify commits exist
  Step 7   verify           code-verifier               → lint + type-check + tests + imports (MANDATORY)
  Step 8   review           code-review × 4             → parallel agents
  Step 9   fix              task-implementer            → [conditional: CRITICAL/HIGH findings]
  Step 10  verify-post-fix  code-verifier               → [conditional: after fix]
  Step 11  report           orchestrator                → final summary
  Step 12  pr               orchestrator + gh CLI       → [conditional: create_pr=true]

Optional (not in plan — add if needed):
  + security-audit   auto-detect: auth/API/DB changes
  + perf-check       auto-detect: if frontend/bundle files changed
  + deploy           ask after PR: "Deploy to staging?"

Proceed? (yes / adjust: "skip fix", "add security-audit", "remove pr", etc.)

If user adjusts:

• Parse natural language: "skip fix" → mark fix step as disabled
• "add security-audit" → insert { id: "security-audit", agent: "security-audit", depends: ["review"] } after review
• "remove pr" → set create_pr: false
• Re-display updated plan and ask again

If plan_approval: false (automation setting) → skip this display and proceed directly.

Phase 2: EXECUTION

Execute each step in plan order, documenting results after each step.

2.1 General Execution Loop

FOR step in PLAN:
  IF step.conditional AND condition_not_met:
    SKIP step, mark as "skipped"
    CONTINUE

  2.1.1  Mark step as in-progress (update display)
  2.1.2  Execute step (see step-specific instructions below)
         **CRITICAL RESILIENCE**: If the sub-agent returns a malformed result or fails to follow formatting rules, run an explicit retry:
         "The previous output was malformed. Fix these errors: [errors] and try again." (Max 2 retries before counting as critical failure).
  2.1.3  Collect result
  2.1.4  Document result via job-documenter (add-document)
         (Also update job state `state.json`)
  2.1.5  Update job README via job-documenter (update-readme)
  2.1.6  Mark step as completed
  
  IF step failed critically:
    Ask user: "Step '<name>' failed. Continue with remaining steps or abort?"
    IF abort: skip to Phase 3 (COMPLETION) with status "aborted"

2.2 Step: ANALYZE

Dispatch issue-analyzer as a sub-agent.

Prepare prompt: Read skills/issue-analyzer/orchestrator-prompt.md (if it exists) and fill in:

• Issue URL or repo+number
• Codebase paths with roles
• Automation settings (skip_confirmation: true, search_depth: focused)

Launch:

Task({
  description: "Issue analysis: #<N>",
  subagent_type: "general",
  prompt: <constructed prompt>
})

Parse result: Extract JSON analysis object:

ANALYSIS_RESULT:
  issue_type:     from issue.type
  total_tasks:    from issue.total_tasks (= tasks.length)
  tasks: [{task_id, task_name, task_type, complexity, dependencies,
           description, target_files, acceptance_criteria, context,
           existing_tests, existing_stories, module_patterns}]
  dependency_order: from dependency_order array (already topologically sorted)

Validate: At least 1 task, no circular dependencies, all dependency references valid. Dependency_order array must contain all task_ids exactly once.

Document: Send to job-documenter:

ACTION: add-document
DATA:
  DOC_TYPE: analysis
  TARGET: both
  TITLE: Issue Analysis — #<N>
  CONTENT: <human-readable summary for man/, raw JSON for ai/>
  AGENT: issue-analyzer
  TASK: Analyze issue #<N>

For analyze intent: After documenting, present analysis to user. Ask:

Analysis complete. Found <N> tasks.
Want me to implement this? I'll create a feature branch and run the full pipeline.
○ Yes, implement
○ No, analysis is enough

If "Yes" → extend PLAN with context → prepare → implement → review → fix → checks → pr steps. Continue execution. If "No" → skip to Phase 3 (COMPLETION).

2.3 Step: CONTEXT

Dispatch context-collector to build the unified context document.

Prepare prompt: Use the template from skills/context-collector/SKILL.md:

Task({
  description: "Collect context: <job-name>",
  subagent_type: "general",
  prompt: |
    You are the context-collector agent. Your task is to research and build
    a context document for the current job.

    Load the skill from: skills/context-collector/SKILL.md

    ACTION: collect
    JOB_NAME: <job-name>
    JOBS_ROOT: <JOBS_ROOT>
    PROJECT_DIR: <project_dir>

    DATA:
      TASK_DESCRIPTION: <from issue or user request>
      FOCUS_AREAS: <derived from analysis — affected areas, libraries>
      ANALYSIS_RESULT: <output from issue-analyzer, if available>
      KNOWN_LIBRARIES: <from package.json scan during analysis>

    Execute all phases and return a CONTEXT_RESULT block.
})

Parse result:

CONTEXT_RESULT:
  status:    success | error
  version:   <document version>
  summary:   <what context was collected>

Validate: status must be success. If error → log warning, continue (context is helpful but not blocking).

After context is collected: All subsequent sub-agents receive the versioned context path from state.json:

CONTEXT_LOCATION: <JOBS_ROOT>/<job-name>/ai/context_v<N>.md

Context versioning: Never overwrite context.md — save snapshots as context_v1.md, context_v2.md, etc.

• Version 1 is created during Step 2.3 (first collect)
• Subsequent versions increment on each update
• state.json → context_doc.version always points to the latest version
• Sub-agents always read the path from state.json, not a hardcoded filename

Triggering context updates during execution:

If during later steps (implement, review) a sub-agent reports missing context or a new library is discovered:

Task({
  description: "Update context: <job-name>",
  subagent_type: "general",
  prompt: |
    You are the context-collector agent. Update the existing context.

    Load the skill from: skills/context-collector/SKILL.md

    ACTION: update
    JOB_NAME: <job-name>
    JOBS_ROOT: <JOBS_ROOT>
    PROJECT_DIR: <project_dir>
    CONTEXT_VERSION: <current version + 1>  ← write to context_v<N+1>.md

    DATA:
      TASK_DESCRIPTION: <original task description>
      UPDATE_REASON: <why context needs updating>
      FOCUS_AREAS: <new areas to research>

    Execute update flow and return a CONTEXT_RESULT block.
})

2.4 Step: PREPARE

Create git worktree for feature branch.

CRITICAL: Feature branches MUST be created via git worktree add. NEVER use git checkout -b or git switch -c — this switches the main working directory. The worktree is a sibling directory to the project directory.

Determine branch name:

Format: feature/<custom-slug>
Slug: descriptive, lowercase, alphanumeric+hyphens, from issue title/feature
Examples: feature/pipeline-validation, feature/mirror-step-source-column

Create worktree:

# Fetch latest base branch
git -C <project_dir> fetch origin <base_branch>

# Create worktree as SIBLING directory
git -C <project_dir> worktree add ../<branch-slug> -b feature/<branch-slug> origin/<base_branch>

# Example:
# Project dir: /Users/user/projects/<PROJECT>
# git -C ... worktree add ../pipeline-validation -b feature/pipeline-validation origin/develop-2
# Result worktree: /Users/user/projects/pipeline-validation
# Result branch:   feature/pipeline-validation

# Auto-detect package manager and install dependencies
if [ -f <worktree_path>/bun.lockb ]; then
  PM="bun"; RUNNER="bun run"; bun install --cwd <worktree_path>
elif [ -f <worktree_path>/pnpm-lock.yaml ]; then
  PM="pnpm"; RUNNER="pnpm run"; pnpm install --prefix <worktree_path>
elif [ -f <worktree_path>/yarn.lock ]; then
  PM="yarn"; RUNNER="yarn"; yarn --cwd <worktree_path>
elif [ -f <worktree_path>/package-lock.json ]; then
  PM="npm"; RUNNER="npm run"; npm install --prefix <worktree_path>
elif [ -f <worktree_path>/requirements.txt ]; then
  PM="python"; RUNNER=""; pip install -r <worktree_path>/requirements.txt
elif [ -f <worktree_path>/go.mod ]; then
  PM="go"; RUNNER=""; (cd <worktree_path> && go mod download)
fi

IMPORTANT: After creating the worktree, ALL subsequent operations (implementation, review, lint, test, git) MUST run in the worktree directory, NOT in the original project directory.

Record state:

BRANCH_STATE:
  name: feature/<branch-slug>
  base: <base_branch>
  worktree_path: <absolute path to worktree>
  project_dir: <original project directory — DO NOT modify>
  created_from_commit: <commit hash>
  package_manager: <PM>
  run_command: <RUNNER>

Store package_manager and run_command in JOB_STATE — all subsequent steps use these instead of hardcoded npm.

Document: Update README via job-documenter (update-readme) with branch info.

2.4.1 Step: TESTS-CREATOR + IMPLEMENT — Wave Isolation

IRON LAW: tests-creator MUST run before task-implementer for every task. No exceptions.

CONTEXT BUDGET RULE: Each wave runs as a single isolated sub-agent. The orchestrator never dispatches task-implementers or tests-creator directly. This keeps the orchestrator context bounded to compact wave summaries regardless of job size.

Why wave isolation

When the orchestrator dispatches task-implementers directly, each sub-agent result (STATUS text + verification output) accumulates in the orchestrator's context. After 3–4 waves this context can reach 100k+ tokens, causing the session to freeze during context reload. Wave isolation prevents this: each wave sub-agent runs in its own context and returns only a compact summary.

Execution pattern

WAVES = topological_sort_into_waves(dependency_order, task_dependencies)

FOR wave_index, wave_tasks in enumerate(WAVES):
  Dispatch SINGLE Agent("wave-executor") with all tasks in this wave.
  
  Receive compact WAVE_RESULT:
    STATUS: WAVE_DONE | WAVE_PARTIAL | WAVE_FAILED
    Wave: <index>
    Commits: [hash msg, hash msg, ...]
    Tests: <N passed, M failed>
    Tasks: task-1 ✅, task-2 ✅
    Result files: <JOBS_ROOT>/<job-name>/results/task-*.json
  
  Decision:
    WAVE_DONE    → continue to next wave
    WAVE_PARTIAL → log warnings, continue (read result files for details)
    WAVE_FAILED  → STOP, read result files for failed tasks, ask user

Wave executor prompt template

Task({
  description: "Wave <N>: implement tasks <task_ids>",
  subagent_type: "general",
  prompt: |
    You are a wave executor. Implement all tasks in this wave, then return a compact summary.
    
    ## Wave
    Wave <N> of <total>
    
    ## Tasks
    <JSON array of task objects for this wave>
    
    ## Workspace
    - worktree_path: <absolute path>
    - branch: <branch name>
    - package_manager: <pm>
    - run_command: <runner>
    - issue_number: <N>
    - job_name: <job-name>
    - context_path: <path to context_vN.md>
    
    ## Instructions
    
    **Step A — tests-creator (MANDATORY, run first):**
    For each task in this wave, dispatch tests-creator in parallel:
      Load skill: skills/tests-creator/SKILL.md
      Pass: task object, workspace, context_path
      Collect: TEST_SPECS[task_id] from each response
    Wait for ALL tests-creator agents to finish before Step B.
    
    **Step B — task-implementer (after all test stubs committed):**
    For each task in this wave, dispatch task-implementer in parallel (if no file overlap; sequential otherwise):
      Load skill: skills/task-implementer/SKILL.md
      Pass: task object WITH test_case_specs: TEST_SPECS[task_id], workspace, job_name, context_path
    Wait for ALL task-implementer agents to finish.
    
    **Parallel safety check:** Before Step B, verify no two tasks share target_files.
    If overlap → run sequentially within this wave.
    
    ## Required response format (compact — no inline JSON)
    
    STATUS: WAVE_DONE
    Wave: <N>
    Commits: [abc1234 feat(x): ..., def5678 feat(y): ...]
    Tests: <N passed, M failed>
    Tasks: task-1 ✅, task-2 ✅
    Result files: <JOBS_ROOT>/<job-name>/results/task-1.json, task-2.json
    
    Use WAVE_PARTIAL if any task is DONE_WITH_CONCERNS.
    Use WAVE_FAILED if any task is BLOCKED or failed.
    Do NOT include full task output inline — write details to result files.
})

After all waves, document:

ACTION: add-document
DATA:
  DOC_TYPE: implementation-report
  TARGET: both
  TITLE: Implementation Report
  CONTENT: <summary of all waves, commits, test totals>
  AGENT: wave-executor
  TASK: Implementation phase

2.5.1 Post-Implementation Checkpoint

After all waves complete, check if tests were created. If not, offer test-gen:

# Derive all modified files from wave summaries and result files
ALL_FILES = collect from WAVE_RESULTS (read result files for details if needed)

IF no test files in ALL_FILES:
  Auto-trigger test-gen for new/modified source files
  (skip test files, config files, types-only files)

Then present the implementation summary to user:

Implementation complete:
  - <N>/<M> tasks ✅
  - <X> files modified, <Y> files created
  - Tests: <created by implementer | auto-generated by test-gen | none>

What's next?
  A) 🔍 Review → fix → PR (standard pipeline)
  B) 👀 Show me the diff first — I'll review manually
  C) 🚀 Skip review, go straight to PR
  D) ⏹ Stop here — I'll continue manually

Mapping:

• A → continue to REVIEW step (default if no response in 60s)
• B → run git diff <merge_base>..HEAD --stat and git diff <merge_base>..HEAD, then re-ask
• C → skip REVIEW and FIX steps, go to CHECKS → PR
• D → skip to Phase 3 (COMPLETION) with status "paused"

2.5.5 Step: IMPLEMENT SANITY CHECK

Lightweight verification after all waves complete, before launching review. This catches the case where a wave sub-agent claims WAVE_DONE but made no actual git changes.

# Run in worktree directory
git diff --stat <merge_base>..HEAD
git log <merge_base>..HEAD --oneline

Gate conditions:

If retry also produces no commits → classify as terminal, ABORT with:

"wave-executor returned WAVE_DONE twice but made no git changes.
Please implement manually and re-run from the review step."

Record:

SANITY_CHECK:
  commits: <count>
  files_changed: <count>
  lines_added: <N>
  lines_removed: <N>
  verified: true | false

2.6 Step: REVIEW

2.6.0 Review Strategy Selection

If the user didn't specify a review approach, offer options:

How should I review the implementation?

  A) 🚀 Quick (code-review 4-agent parallel) — ~30 sec
  B) 📋 Thorough (individual reviewers: ai + boss + style + mobx) — ~2 min
  C) 🔒 Security-focused (code-review + security-audit) — ~1 min
  D) ⏭ Skip review entirely

> pick a letter (default: A)

Then ask which optional convention reviewers to include when local convention docs or matching paths are present:

Which project-convention reviewers should I include?

  A) Include all detected convention reviewers (recommended)
  B) Choose individually
  C) Skip convention reviewers

Detected reviewers:
  - review-frontend-conventions: frontend files / stories / local frontend guide
  - review-testing-practices: tests, stories, MSW, or e2e files
  - review-core-boundaries: shared core/infrastructure files
  - review-flow-graph: shared graph/flow abstraction files

Only show detected reviewers. If the user chooses B, ask for the exact skill names to include or exclude, then persist the choice in job state as convention_reviewers.

Auto-select (skip this question) when:

• review_mode is explicitly set in automation settings → use that
• convention_reviewers is explicitly set in automation settings → use that for optional convention reviewers
• User already chose at Post-Implementation Checkpoint (2.5.1 option A) → use default (A)
• Time pressure (total_job_timeout close) → use A (fastest)

2.6.1 Execute Review

Dispatch review skills on the whole branch. Launch all reviewers in parallel for speed.

Strategy A — code-review (4-agent parallel):

Dispatches 4 agents in parallel (correctness, security, performance, style) and produces a unified severity report.

Launch code-review skill with:
  scope: git diff <merge_base>..HEAD
  output: unified report with CRITICAL/HIGH/MEDIUM/LOW findings

Fallback — individual reviewers (if code-review unavailable or user prefers):

Determine and dispatch all reviewers simultaneously (not sequentially):

# Launch ALL applicable reviewers in a SINGLE turn (parallel):
Agent 1: code-ai-review (correctness, security)
Agent 2: code-boss-review (architecture, logic)
Agent 3: code-style-review (naming, patterns)
Agent 4: code-mobx-store-review (if applicable)
Agent 5+: selected convention reviewers (if applicable)

# Wait for all to complete, then merge results

Review-orchestrator mode (preferred when available):

If review-orchestrator exists in the skill catalog, dispatch it with the selected review flags instead of manually launching individual reviewers. Pass selected convention reviewer flags: --project-conventions, --frontend-conventions, --testing-practices, --core-boundaries, and/or --flow-graph.

Pass review orchestration controls:

context_mode: <review_context_mode automation setting; default "light", ask "full" for high-risk PRs>
token_budget: <review_token_budget automation setting or computed scope budget>
model_strategy: <review_model_strategy automation setting; default "current">
output: unified report with findings, review_context, token_policy, and model metadata

Collect and merge findings:

REVIEW_FINDINGS: [{
  reviewer: "<skill-name>",
  findings: [{ file, line, severity: CRITICAL|WARNING|INFO, message }]
}]

Strategy C — Security-focused:

Run code-review (4-agent) AND security-audit in parallel:

Agent group 1: code-review (correctness, security, performance, style)
Agent group 2: security-audit (dependency vulnerabilities, secrets scan, OWASP patterns)

Merge findings from both into unified REVIEW_FINDINGS.

Deduplicate: If multiple reviewers flag the same file:line, merge into a single finding with the highest severity.

Classify:

NEEDS_FIX = count(CRITICAL) > 0 OR count(WARNING) > 0

Document:

ACTION: add-document
DATA:
  DOC_TYPE: review
  TARGET: both
  TITLE: Code Review Results
  CONTENT: <findings summary for man/, structured findings for ai/>

2.6.2 PR Review Report Publication

If this job is reviewing an existing GitHub PR, or if a PR number/URL was resolved before the review step, ask whether to publish the consolidated review report after review findings are documented and before fix decisions. This gives the user a chance to record the current review state before any automatic fix loop changes it.

Ask unless automation settings explicitly set publish_pr_review_report:

Publish the review report to the PR?

  A) Concise PR comment only
  B) Concise PR comment + detailed AI markdown artifact (recommended for follow-up fixes)
  C) Do not publish

> pick a letter (default: C)

Rules:

• The PR comment and AI artifact must be written in English only, regardless of the chat language or reviewer output language.
• Default is C. Never publish to a PR without explicit user confirmation or publish_pr_review_report: comment, publish_pr_review_report: comment-and-ai-artifact, or legacy publish_pr_review_report: true.
• If the job has review findings but no PR number yet, store pending_pr_review_report_comment and pending_review_ai_artifact in job state. If the later PR step creates a PR, ask the same question after PR creation.
• If the user chooses A, delegate concise comment formatting to review-orchestrator's PR Review Report Publication contract when available.
• If the user chooses B, delegate concise comment formatting and generate .metaproject/jobs/<job-name>/ai/review-ai-report.md using review-orchestrator's Detailed AI Markdown Artifact contract.
• If the user chooses B, the PR comment Meta section must include both an AI artifact link/path and an AI artifact description row explaining in human-readable language that the markdown file contains detailed findings, fix guidance, patch guidance, regression coverage, validation plan, and follow-up agent context.
• If using legacy reviewers, normalize findings into the same concise PR comment and AI artifact structures before posting.
• Record the final decision in job state as publication_plan.mode: comment, comment-and-ai-artifact, or none.

Automation values:

• publish_pr_review_report: ask -> ask the question above.
• publish_pr_review_report: comment or legacy true -> publish the concise PR comment only.
• publish_pr_review_report: comment-and-ai-artifact -> publish the concise PR comment and create/link the detailed AI markdown artifact.
• publish_pr_review_report: none or legacy false -> do not publish.

2.6.3 Post-Review Checkpoint

After review completes, present findings and ask user:

Review complete:
  🔴 <N> CRITICAL  🟠 <M> HIGH  🟡 <K> MEDIUM  🔵 <L> LOW

  A) 🔧 Auto-fix and continue (fix CRITICAL + HIGH, skip LOW)
  B) 📋 Show all findings — I'll decide what to fix
  C) ⏭ Skip fixes, proceed to PR as-is
  D) ⏹ Stop — I'll fix manually

Mapping:

• A → proceed to FIX step (default if CRITICAL > 0)
• B → display all findings grouped by file, then re-ask A/C/D
• C → skip FIX step, go to CHECKS (only if 0 CRITICAL — refuse if CRITICAL > 0)
• D → skip to Phase 3 (COMPLETION) with status "paused"

Auto-proceed (skip this question) when:

• 0 findings → skip directly to CHECKS
• Only INFO findings → skip FIX, go to CHECKS
• auto_create_pr: true → auto-select A

2.7 Step: FIX (conditional)

Only runs if NEEDS_FIX is true. Default max: 3 iterations (max_review_iterations).

UNRESOLVED_FINDINGS = all CRITICAL + WARNING findings from step 2.6

FOR iteration in [1, 2, 3]:
  IF NOT NEEDS_FIX: BREAK

  1. Group UNRESOLVED_FINDINGS by file
  2. Construct fix prompt — MUST include unresolved findings from previous attempt:

     task_type: "fix"
     findings: <UNRESOLVED_FINDINGS>
     iteration: <N>
     previously_unresolved: <findings that were in UNRESOLVED_FINDINGS last iteration but still present>
         → Prefix: "These specific findings were NOT fixed in iteration <N-1>: [list]"

  3. Launch task-implementer with fix prompt
  4. Run sanity-check (step 2.5.5 logic) — verify commits were made
  5. Re-run reviewers (step 2.6) — parallel dispatch
  6. Recompute NEEDS_FIX from new findings
  7. Update UNRESOLVED_FINDINGS = remaining CRITICAL + WARNING

IF still NEEDS_FIX after max iterations:
  Log "Unresolved after <N> iterations" with finding list → continue to checks

Fix prompt escalation pattern:

• Iteration 1: "Fix these findings: [list]"
• Iteration 2: "These findings were NOT fixed in iteration 1: [subset]. Fix them now."
• Iteration 3: "FINAL attempt. These findings remain after 2 fix passes: [subset]. This is the last fix iteration."

2.8 Step: VERIFY (code-verifier)

Dispatch code-verifier as a sub-agent. This replaces the orchestrator-internal "checks" step.

Task({
  description: "Quality gate: <job-name>",
  subagent_type: "general",
  prompt: |
    You are code-verifier. Load skill: skills/code-verifier/SKILL.md

    codebase_path: <worktree_path>
    base_branch:   <base_branch>
    scope:         changed
    
    Run all 4 phases and return VERIFICATION_RESULT.
})

Handle result:

IF VERIFICATION_RESULT.gate == "PASS" or "PASS_WITH_WARNINGS":
  → Proceed to review
  → Log findings as informational in job docs

IF VERIFICATION_RESULT.gate == "FAIL":
  → Extract CRITICAL/HIGH findings
  → Check if fix step is already scheduled
    - If not → add fix step to plan (dispatch task-implementer in fix mode)
    - If fix already ran 2× → escalate to user, skip to report

Document result:

ACTION: add-document
DATA:
  DOC_TYPE: verification-report
  TARGET: both
  TITLE: Verification Report — <gate status>
  CONTENT: <VERIFICATION_RESULT formatted>
  AGENT: code-verifier

2.8.1 Step: VERIFY-POST-FIX (code-verifier, conditional)

After fix iterations, dispatch code-verifier again with identical parameters.

IF fix ran:
  Dispatch code-verifier (same params as step 2.8)
  IF gate still FAIL:
    Log "Verification failed after fix" → skip to report with warning
  IF gate PASS:
    Proceed to report

2.8.1 Step: PERF-CHECK (optional)

Auto-trigger perf-check when frontend/bundle files were modified:

IF any modified file matches: *.tsx, *.jsx, *.css, *.scss, webpack.*, vite.*, next.config.*
  AND project has build output (dist/, build/, .next/)
  THEN:
    Dispatch perf-check --bundle
 

…(truncated)