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.

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 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 '<job-name>'. 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
  F) 📄 Spec then implement — generate BRD/PRD/FSD/TRD first, then implement

> 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)
• F → spec_then_implement intent → proceed to 0.1.6 (spec 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.1.6 Spec-Orchestrator Gate (for spec_then_implement, custom, and descriptive implement requests)

Auto-trigger when:

• Intent is spec_then_implement (user explicitly requested spec)
• Intent is custom and interviewer output suggests a new feature / no existing issue
• Intent is implement but the request is purely descriptive (no issue number, no file paths) AND run_spec_orchestrator: "ask"
• Request contains keywords: "spec", "BRD", "PRD", "FSD", "TRD", "спецификац", "документ", "вначале"

Skip when:

• run_spec_orchestrator: "no" (automation setting)
• Request has an explicit GitHub issue number
• Intent is analyze or review

If triggered, ask:

This looks like a new feature from description. Should I generate formal spec documents first?

  A) Full spec — BRD + PRD + FSD + TRD, then implement (recommended for complex features)
  B) PRD only — quick product requirements, then implement
  C) No — go straight to implementation

> pick a letter (default: C if no response in 30s)

Mapping:

• A → insert spec step (full) at top of implement plan; passes skip_stages: []
• B → insert spec step (PRD only) at top of implement plan; passes skip_stages: ["gather","expand","brd","fsd","trd"]
• C → skip spec step, proceed with standard implement plan

Auto-select without asking when:

• run_spec_orchestrator: "yes" → choose A
• run_spec_orchestrator: "prd-only" → choose B

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:
  0.  { id: "spec",           type: "spec",      agent: "spec-orchestrator", depends: [],          conditional: true }
  1.  { id: "analyze",        type: "analyze",   agent: "issue-analyzer",    depends: ["spec"] }
  2.  { id: "context",        type: "context",   agent: "context-collector", depends: ["analyze"] }
  3.  { id: "prepare",        type: "prepare",   agent: "orchestrator",      depends: ["context"] }
  3b. { id: "gatekeep",       type: "gatekeep",  agent: "plan-gatekeeper",   depends: ["prepare"], conditional: true }
  4.  { id: "tests-creator",  type: "tests",     agent: "tests-creator",     depends: ["gatekeep"] }
  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:

• spec: triggered by 0.1.6 Spec-Orchestrator Gate (user chose A or B, or run_spec_orchestrator auto-selects)
• gatekeep: triggered if the job is flagged for high complexity or architectural/database/API boundary changes, or explicitly requested by user (enabled by default for implementations)
• 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
• 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 0   spec             spec-orchestrator           → BRD/PRD/FSD/TRD [conditional: run_spec_orchestrator]
  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.1.9 Step: SPEC (conditional — spec-orchestrator)

Runs only when Spec-Orchestrator Gate (0.1.6) was triggered and user chose A or B.

Dispatch spec-orchestrator:

Task({
  description: "Generate spec: <job-name>",
  subagent_type: "general",
  prompt: |
    Load skill: skills/spec-orchestrator/SKILL.md

    request: "<original user request>"
    job_name: "<job-name>-spec"
    jobs_root: "<JOBS_ROOT>"
    codebase_path: "<project_dir or null>"
    skip_stages: <from gate choice — [] for full, ["gather","expand","brd","fsd","trd"] for PRD-only>
    max_review_iterations: 3
})

Parse result:

• STATUS: DONE or STATUS: DONE_WITH_CONCERNS → collect spec artifact paths
• STATUS: BLOCKED → surface to user, offer to skip spec and continue
• STATUS: NEEDS_CONTEXT → re-dispatch with enriched request

Extract produced artifacts (read from job directory):

SPEC_ARTIFACTS:
  brd_path:  <JOBS_ROOT>/<job-name>-spec/brd.md (or null if skipped)
  prd_path:  <JOBS_ROOT>/<job-name>-spec/prd.md
  fsd_path:  <JOBS_ROOT>/<job-name>-spec/fsd.md (or null if skipped)
  trd_path:  <JOBS_ROOT>/<job-name>-spec/trd.md (or null if skipped)
  log_path:  <JOBS_ROOT>/<job-name>-spec/spec-pipeline-log.md

Pass spec artifacts to downstream steps:

• context-collector: include SPEC_ARTIFACTS paths in FOCUS_AREAS so context-collector reads and summarizes the spec docs
• issue-analyzer (if issue number present): include prd.md content as upstream_context
• wave-executor (implement step): pass spec_context_path: prd_path so task-implementer reads the PRD for implementation guidance

Document:

ACTION: add-document
DATA:
  DOC_TYPE: spec
  TARGET: both
  TITLE: Specification — <job-name>
  CONTENT: <summary of spec artifacts produced + their paths>
  AGENT: spec-orchestrator

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.0 Step: GATEKEEP (conditional — plan-gatekeeper)

Runs only when Gatekeep step is enabled in the plan.

Prepare prompt: Use the template from skills/plan-gatekeeper/SKILL.md:

Task({
  description: "Gatekeep plan: <job-name>",
  subagent_type: "general",
  prompt: |
    You are the plan-gatekeeper agent. Your task is to stress-test the proposed
    plan and decisions, and ensure all design contracts are solid.

    Load the skill from: skills/plan-gatekeeper/SKILL.md

    ACTION: gatekeep
    JOB_NAME: <job-name>
    JOBS_ROOT: <JOBS_ROOT>
    PROJECT: <project_dir>

    DATA:
      plan: <current plan/tasks description>
      context: <latest context from context_v<N>.md>
      project: <project_dir>

    Execute the gatekeeping interview and return a STATUS response.
})

Parse result:

• Parses status protocol response (e.g. STATUS: DONE or STATUS: DONE_WITH_CONCERNS).
• Automatically extracts any proposed ADRs from ## Architectural Decisions (ADR) and dispatches job-documenter to register/synchronize them.
• Extracts refined_plan to update/overwrite the current task list in state.json if adjustments were agreed.
• If status is BLOCKED or NEEDS_CONTEXT, follow the standard subagent resolution flows (resolve blocker or request more info from user).

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)
    Apply rules/core/terse-subagent-response.mdc. No preamble, no filler, no restatement.

    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 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
    Add findings to report (informational, not blocking)

Skip if no frontend files changed or no build output exists. Results are advisory — they don't block the PR.

2.9 Step: REPORT

Aggregate all information into a human-readable summary.

Report structure:

# Job Report: <Title>

## Summary
- **Intent:** <implement / analyze / review>
- **Source:** <issue URL or description>
- **Branch:** `<branch_name>`
- **Tasks:** <completed>/<total> completed
- **Review Iterations:** <N>
- **Final Status:** <READY FOR PR | HAS WARNINGS | HAS ISSUES | ANALYSIS ONLY>

## Analysis
<analysis summary>

## Tasks
### task-1: <Name>
- **Status:** success
- **Files:** <list>
- **Commits:** <hashes>

## Review Results
### code-ai-review
- CRITICAL: <N>, WARNING: <N>, INFO: <N>
### code-boss-review
- ...

## Unresolved Issues
- [ ] <file>:<line> — <message> (from <reviewer>)

## Final Checks
- Lint: PASS
- Type Check: PASS
- Tests: 42 passed, 0 failed

## Changes Summary
### Files Modified (<N>)
- `src/...`

### Files Created (<N>)
- `src/...`

### Commits (<N>)
- `abc1234` feat(pipelines): add validation

2.10 Step: PR (conditional)

Only runs if create_pr is true and intent is implement.

Dispatch pr-issue-documenter to generate the PR description:

Pass the following context to pr-issue-documenter:

ACTION: generate-pr-description
JOB_NAME: <job-name>
BRANCH: <feature_branch>
BASE: <base_branch>
ISSUE_NUMBER: <issue_number if available>
CONTEXT_PATH: <JOBS_ROOT>/<job-name>/ai/context.md

pr-issue-documenter will analyze the branch diff and produce a structured PR description (Summary + Changes by area + Key Files table). Use its output as the body for the PR.

Enrich PR with changelog entry:

Dispatch changelog skill to generate a changelog snippet for this branch:

changelog <base_branch>..HEAD --format compact

Append the changelog snippet to the PR body under a ## Changelog section.

Present to user:

Implementation complete. Draft PR proposal:

Title: <type>(#<issue>): <description>
Base: <base> ← <head>

<pr-issue-documenter output>

## Changelog
<changelog snippet>

Create this draft PR? (yes/no/edit)

If user says "edit" → show the full body, let them modify before creating.

If confirmed:

gh pr create --title "<title>" --body "$(cat <<'EOF'
<body>
EOF
)" --base <base_branch> --head <feature_branch> --draft

Phase 3: COMPLETION

3.1 Finalize Job Documentation

Dispatch job-documenter with finalize action:

ACTION: finalize
DATA:
  FINAL_CONTENT: <full report markdown>
  FINAL_STATUS: completed | aborted
  SUMMARY: <1-3 sentence summary>

Validate response: status must be success.

3.2 Present Results

Tell user:

1. What was accomplished (summary)
2. Where documentation is stored: jobs/<job-name>/
3. PR URL (if created)
4. Metrics summary (time, tokens)
5. Any unresolved issues

✅ Job completed successfully.

  Documentation: <JOBS_ROOT>/<job-name>/
  Branch:        feature/<slug> (worktree: <path>)
  PR:            <URL or "not created">
  Metrics:       <total time>, <total tokens>
  
  See jobs/<job-name>/README.md for the full job index.

3.3 Post-Completion Options

After presenting results, offer next steps:

What would you like to do next?

  A) ✅ Done — nothing else needed
  B) 🚀 Deploy to staging — run /deploy staging
  C) 🔄 Start another job
  D) 📝 Update CLAUDE.md with session learnings

• B → dispatch deploy skill with staging environment
• D → dispatch claude-md-management skill

Auto-skip if the job was analyze or review intent (no deploy makes sense).

Plan Extension (Dynamic Planning)

When the orchestrator starts with an analyze intent and the user then says "yes, implement":

1. Keep existing completed steps (analyze, context, report are already done)
2. Extend plan with new steps: prepare → implement → review → fix → checks → report → pr
3. Update job documentation via job-documenter (update-readme with new plan)
4. Continue execution from the first new step

This is the core of dynamic planning — the plan grows based on user decisions.

State Management

The orchestrator maintains state throughout all phases:

JOB_STATE:
  phase: CONTEXT | PLAN | EXECUTION | COMPLETION
  intent: implement | analyze | review | custom
  create_pr: <bool>
  job_name: <string>
  
  context:
    issue: { number, title, url, type }
    project_dir: <path>
    base_branch: <string>
  
  branch:
    name: <string>
    worktree_path: <path>
    merge_base: <commit hash>
  
  plan:
    steps: [{ id, type, agent, depends, status: pending|in_progress|completed|skipped|failed, prompt_chars: <int>, prompt_hash: <sha256 first 8 chars> }]
    current_step: <step_id>
  
  analysis:
    total_tasks: <N>
    tasks: [<task objects>]
    dependency_order: [<task_ids>]
  
  context_doc:
    path: <JOBS_ROOT>/<job-name>/ai/context.md
    version: <current version>
    status: collected | updated | not-collected
  
  implementation:
    task_results: {<task_id>: <result>}
    all_commits: [<hash>]
    all_files: [<path>]
  
  review:
    iteration: <N>
    findings: [<findings>]
    needs_fix: <bool>
    unresolved: [<findings>]
  
  final_checks:
    lint: <result>
    type_check: <result>
    tests: <result>
  
  documentation:
    job_path: <JOBS_ROOT>/<job-name>
    documents_created: [<paths>]

state.json Specification

The orchestrator persists JOB_STATE to jobs/<job-name>/state.json for job resumption.

Location: jobs/<JOB_NAME>/state.json

Schema reference: skills/job-orchestrator/state.schema.json

When to create: During Phase 1.2 (Initialize Job Documentation) — write initial state after job docs are initialized.

When to update: After every step completion in Phase 2 (EXECUTION) — update plan.steps[i].status, plan.steps[i].prompt (store the prompt used), and plan.current_step.

How to write state.json:

# Write state (orchestrator handles this directly, not via job-documenter)
cat > jobs/<JOB_NAME>/state.json << 'EOF'
{
  "phase": "EXECUTION",
  "intent": "<intent>",
  "job_name": "<job-name>",
  ...
}
EOF

Job resumption (Phase 0.0): If state.json exists and phase is not COMPLETION, offer to resume. Parse the file, restore JOB_STATE, jump to the first step with status: "pending" or status: "in_progress".

Interpreting Subagent Results

Rule: rules/core/subagent-status-protocol.md

All subagents dispatched by this orchestrator MUST begin their final response with STATUS: <STATUS>. The orchestrator reads this line first and routes accordingly.

Iron Law

IF A SUBAGENT DOES NOT START WITH STATUS:, TREAT IT AS NEEDS_CONTEXT AND REQUEST A PROPERLY FORMATTED RESPONSE

Do not attempt to infer status from prose. Do not trust a response that "looks fine" but lacks the status line. Run one explicit retry: "Your response did not start with STATUS: <STATUS>. Please reformat using the subagent status protocol (rules/core/subagent-status-protocol.md) and resend your result."

How to handle each status

STATUS: DONE

• Accept result.
• Extract structured payload (JSON result, files changed, commits, verification results).
• Check for and process any proposed ADRs in the ## Architectural Decisions (ADR) section (see ADR Extraction below).
• Mark step as completed in JOB_STATE.
• Continue to next step in the plan.

STATUS: DONE_WITH_CONCERNS

• Accept result as complete.
• Read the ## Concerns for orchestrator section carefully.
• Check for and process any proposed ADRs in the ## Architectural Decisions (ADR) section (see ADR Extraction below).
• Decide: (a) log concern and continue, (b) surface concern to user at next checkpoint, or (c) re-dispatch with adjusted scope if the concern affects correctness.
• Do NOT silently discard concerns. Record them in JOB_STATE and include in the final report.
• Mark step as completed.

Automatic ADR extraction from subagent responses

When a subagent returns STATUS: DONE or STATUS: DONE_WITH_CONCERNS, check if the response contains a ## Architectural Decisions (ADR) section.

If the section is present, parse it to extract one or more ADRs:

1. Parse each ADR block to find:
   • Title: text matching **Title**: <title> (e.g. postgres-for-write-model)
   • Status: text matching **Status**: <status> (e.g. Accepted)
   • Context: text matching **Context**: <context>
   • Decision: text matching **Decision**: <decision>
   • Consequences: text matching **Consequences**: <consequences>
2. Determine the next index for the ADR (e.g., check how many files exist in the project's global docs/adr/ or local man/adr/ and assign <num> as 0001, 0002, etc.).
3. Format the ADR content as a clean Markdown document:

   # ADR: <Title>
   
   ## Status
   <Status>
   
   ## Context
   <Context>
   
   ## Decision
   <Decision>
   
   ## Consequences
   <Consequences>

4. Dispatch job-documenter to save and synchronize the ADR:

   ACTION: add-document
   JOB_NAME: <JOB_NAME>
   JOBS_ROOT: <JOBS_ROOT>
   DATA:
     DOC_TYPE: adr
     DOC_NAME: <num>-<kebab-case-title>
     TARGET: man
     TITLE: ADR <num>: <Title>
     CONTENT: <formatted ADR content>
     AGENT: <Subagent Name>
     TASK: <Current task/step description>
     DOC_STATUS: final
     PROJECT: <PROJECT_DIR>

STATUS: BLOCKED

• Do NOT proceed to any step that depends on this task.
• Read ## Reason and ## What I need from orchestrator.
• Resolve the blocker: provide the missing file, make the decision, fix the dependency, or escalate to the user.
• Re-dispatch the subagent with the resolved context.
• If the blocker cannot be resolved (e.g., missing information requires user input) → surface to user: "Task <id> is blocked: <reason>. What would you like to do?"

STATUS: NEEDS_CONTEXT

• Do NOT mark step as failed.
• Read ## Missing information and ## Where it might be found.
• Locate the missing information (check job context document, issue body, package.json, codebase).
• Re-dispatch the subagent with the enriched task input.
• If the information is not available anywhere → escalate to user with the specific question.

Red Flag

"The subagent didn't use the status protocol, but the result looks fine"

Do not accept this. A subagent that ignores the status protocol is unpredictable — its next failure may not look fine. Enforce the protocol on every response. Run the retry. If the subagent still does not comply after the retry, log it as a critical failure and ask the user how to proceed.

Constructing Subagent Context

Rule: rules/core/subagent-context-construction.md

Every prompt dispatched to a subagent must be explicitly constructed by the orchestrator. Subagents do not inherit session context, job state, or prior agent output — they only know what the orchestrator tells them.

Template dispatch block

Use this structure for every subagent dispatch:

Task({
  description: "<one-line summary for logs>",
  subagent_type: "general",
  prompt: |
    ## Task
    <Exactly what to do — no ambiguity>

    ## Acceptance Criteria
    - <criterion 1>
    - <criterion 2>

    ## Context
    <Only what is relevant for THIS task — decisions, constraints, background>

    ## Files to read
    - <absolute/path/to/file1.ts>
    - <absolute/path/to/file2.ts>

    ## Constraints
    - Do NOT modify <file or pattern>
    - <other hard stops>
})

Minimality principle

Pass only what the subagent needs for this specific task. Do not dump job state, full analysis JSON, or conversation history. Extraneous context fills the subagent's context window with noise and increases hallucination risk.

Each subagent type gets scoped context:

• issue-analyzer — issue data + codebase paths only
• context-collector — focus areas + analysis summary (not full analysis JSON)
• task-implementer — its specific task object + CONTEXT_PATH (not other tasks' data)
• Reviewers — diff range + file list (not implementation details)

Red Flag

"The subagent can read the job state.json if it needs more context"

→ Iron Law: Orchestrator constructs context. Subagents receive, not retrieve.

The subagent must not fetch orchestrator state independently. If the subagent needs information, the orchestrator puts it in the dispatch prompt. A subagent reading state.json on its own is a sign the orchestrator dispatch was incomplete.

Automation Settings

Dry-Run Mode

When dry_run: true is set (or --dry-run is passed):

1. Phase 0 runs fully — context collection, interviewer (if applicable), summary + confirm
2. Phase 1 runs fully — plan is built and displayed with step tree
3. Phase 2 is skipped entirely — no sub-agents dispatched, no git operations
4. Output: Full plan tree with agent names, input data shapes, dependencies:

Dry-run plan for: issue-4141--pipeline-validation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 1: analyze         [issue-analyzer]          → input: issue #4141
Step 2: context         [context-collector]       → input: analysis result, project_dir
Step 3: prepare         [orchestrator]            → creates: feature/pipeline-validation
Step 4: implement       [task-implementer × 3]    → sequential, 3 tasks
Step 5: sanity-check    [orchestrator]            → verifies commits exist
Step 6: review          [code-review × 4]         → parallel
Step 7: fix             [task-implementer]        → conditional: if NEEDS_FIX
Step 8: checks          [orchestrator]            → lint + type-check + test
Step 9: report          [orchestrator]            → aggregates all results
Step 10: pr             [orchestrator + gh CLI]   → conditional: if create_pr
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Estimated sub-agent calls: 11-14 (varies with tasks and review findings)
No changes will be made. Use without --dry-run to execute.

5. Ask user: "Execute this plan? (yes / adjust / abort)"

Budget Guards & Timeouts

The orchestrator enforces resource limits to prevent runaway sub-agents:

Timeout behavior:

• When a step times out → mark as failed, record partial results if any
• Ask user: "Step X timed out after Y minutes. Retry / Skip / Abort?"
• If total job timeout → force transition to Phase 3 (COMPLETION) with status "timeout"

Context passing rules (minimal context principle):

• issue-analyzer: receives only issue data + codebase paths (NOT previous job state)
• context-collector: receives focus areas + analysis summary (NOT full analysis JSON)
• task-implementer: receives only its specific task object + context.md path (NOT other tasks' results)
• Reviewers: receive only the diff range + file list (NOT implementation details)

Error Handling

Each step failure is classified into one of three classes with different recovery paths:

Error Table

Retry Protocol (for retryable errors)

attempt 1: run step normally
→ failure: classify error
→ if retryable: retry with EXACT same prompt + "Fix these errors: [list]"
→ if fails again: escalate to recoverable → ask user
→ if success: continue

Critical: On retry, use the same prompt stored in state.json → step.prompt. Never re-derive it — re-derivation causes drift.

Progress Notifications

The orchestrator must keep the user informed during long-running execution. This is especially important for non-interactive channels (Telegram, Slack, CI).

At each phase transition:

🔄 Phase 0 → Phase 1: Building execution plan...
🔄 Phase 1 → Phase 2: Executing 7 steps...
✅ Phase 2 → Phase 3: Execution complete, generating report...

At each step transition (Phase 2):

📋 Job: issue-4141--pipeline-validation
├─ ✅ Analyze issue — 3 tasks found
├─ ✅ Collect context — context.md ready
├─ ✅ Prepare branch — feature/pipeline-validation
├─ 🔄 Implement (2/3 tasks done)
│  ├─ ✅ task-1: Add validation schema
│  ├─ ✅ task-2: Implement validator
│  └─ 🔄 task-3: Add integration tests...
├─ ⏳ Review
├─ ⏳ Fix (if needed)
├─ ⏳ Final checks
└─ ⏳ PR

Minimum notification interval: Every 30 seconds during long steps (implementation, review). This prevents the user from thinking the process is stuck.

If notification tools are unavailable (no MCP, no Telegram): fall back to inline text output between steps.

Rules of Engagement

1. DO ALWAYS collect context in Phase 0 — project directory is MANDATORY, never assume.
2. DO build plans dynamically based on intent — not a fixed 8-phase pipeline.
3. DO initialize job documentation before executing any step.
4. DO document every step result via job-documenter.
5. DO parallelize independent tasks and reviewers where safe.
6. DO respect dependency order — use wave-based execution for implementation.
7. DO limit review → fix loop to max_review_iterations.
8. DO present PR proposal to user before creating (unless auto_create_pr).
9. DO tell user where documentation is stored at completion.
10. DO ALWAYS use git worktree add for feature branches — NEVER git checkout -b.
11. DO run ALL commands in the worktree directory, never in the original project.
12. DO ask user for confirmation before extending plan (e.g., analyze → implement).
13. DO send progress notifications at phase/step transitions and every 30s during long steps.
14. DO use auto-detected package_manager and run_command — never hardcode npm.
15. DO NOT ask the user anything during execution (after Phase 0) — except for critical failures and plan extension decisions.
16. DO NOT push the branch until user confirms (or auto_create_pr).
17. DO NOT skip job documentation — it's a core feature, not optional.
18. DO NOT create job documentation for sub-agent results directly — orchestrator formats and sends to documenter.
19. DO store the prompt used for each sub-agent step in state.json → step.prompt before dispatching — required for retry and resume.
20. DO classify every step failure as terminal, retryable, or recoverable — never just abort or ask without classifying first.
21. DO show agent-explicit plan in 1.3 and ask approve/adjust — unless plan_approval: false.
22. DO run sanity-check after every implement step before dispatching review.
23. DO auto-trigger test-gen if implementer produced no test files (unless run_test_gen: false).
24. DO auto-trigger security-audit if diff touches auth/API/DB/env files (unless run_security_audit: false).
25. DO include changelog entry in PR body (unless run_changelog: false).
26. DO NOT deploy without user confirmation (unless run_deploy: true explicitly set).

Configurable Jobs Root

The jobs documentation root is configurable, not hardcoded:

Resolution order:

1. JOBS_ROOT passed explicitly by the orchestrator in the sub-agent dispatch prompt
2. GOODAI_JOBS_ROOT environment variable (if set)
3. Default: <PROJECT_DIR>/jobs/ ← project-local (PROJECT_DIR is known by Phase 0.2)

JOBS_ROOT="${GOODAI_JOBS_ROOT:-$PROJECT_DIR/jobs}"

All references to job paths in sub-agent prompts must use the resolved JOBS_ROOT.

Post-Mortem (for failed/aborted jobs)

When a job ends with status aborted, timeout, or has unresolved critical issues:

1. Auto-generate post-mortem document:

# Post-Mortem: <job-name>

## Timeline
- Phase 0 completed: <timestamp>
- Phase 2, step "implement" started: <timestamp>
- Step "task-3" failed after 2 retries: <timestamp>
- Job aborted by user: <timestamp>

## What Went Wrong
- <Step name> failed with: <error class> — <error message>
- Root cause hypothesis: <analysis>

## What Worked
- <N> tasks completed successfully
- Context collection was accurate

## Recommendations for Retry
- Fix <specific issue> before re-running
- Consider splitting task-3 into smaller subtasks
- Increase step_timeout_ms if timeout was the issue

2. Save to jobs/<job-name>/post-mortem.md
3. Include in final user message: "Post-mortem saved to jobs/<job-name>/post-mortem.md"

Metrics Collection

The orchestrator tracks timing and token usage for each step to enable optimization over time.

Collected per step:

{
  "step_id": "implement",
  "started_at": "2024-03-15T10:30:00Z",
  "completed_at": "2024-03-15T10:35:22Z",
  "duration_ms": 322000,
  "total_tokens": 84500,
  "status": "success",
  "retries": 0
}

Saved to: jobs/<job-name>/metrics.json

Aggregated in report:

## Metrics
| Step | Duration | Tokens | Retries |
|------|----------|--------|---------|
| Analyze | 45s | 12K | 0 |
| Context | 30s | 8K | 0 |
| Implement | 5m 22s | 84K | 0 |
| Review | 1m 10s | 25K | 0 |
| **Total** | **7m 47s** | **129K** | **0** |

This data helps identify which steps are bottlenecks and whether budget guards need adjustment.