Use when a GitHub issue or complex intent needs to be analyzed, planned, and implemented end-to-end with sub-agents.

<SUBAGENT-STOP> If you were dispatched as a subagent to execute a specific task, skip this skill entirely. This skill is for orchestrators and interactive session-level routing only. Proceed directly with your assigned task. </SUBAGENT-STOP>

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:

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

0.1 Determine User Intent

Parse the user's request to identify the intent:

User Says	Intent	Plan Type
"Implement issue #N" / "Issue to PR"	`implement`	Full: analyze → branch → implement → review → fix → checks → PR
"Analyze issue #N" / "Study issue"	`analyze`	Analysis only: analyze → report. Then ask if user wants to implement.
"Review my code" / "Review branch"	`review`	Review only: review → report
"Analyze and implement"	`implement`	Same as implement
Custom request	`custom`	Run `interviewer` skill first, then build plan from output

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):

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

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.)

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:

Intent	Additional Questions
`implement`	Create PR? (default: yes). Skip if user already stated.
`analyze`	None — always produced. After: ask if user wants to implement.
`review`	Which branch to review? (default: current branch)
`custom`	None — covered by interviewer in 0.1.5

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/Presight/Vantage/<PROJECT>
# git -C ... worktree add ../pipeline-validation -b feature/pipeline-validation origin/develop-2
# Result worktree: /Users/user/Presight/Vantage/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:

Check	Pass	Fail action
At least 1 commit exists	≥1 commit	`retryable` — re-dispatch the failed wave-executor with: "No commits were made. Implement the changes and commit them."
At least 1 file modified	≥1 file changed	Same as above
Claimed files actually modified	All files in wave result match diff	Log discrepancy as WARNING, continue

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)

Auto-select (skip this question) when:

review_mode is explicitly set in automation settings → use that
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):

Reviewer	Condition	Launch
`code-ai-review`	Always	Parallel
`code-boss-review`	Always	Parallel
`code-style-review`	Always	Parallel
`code-mobx-store-review`	Only if `*.store.ts` modified	Parallel

# 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)

# Wait for all to complete, then merge results

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 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:

What was accomplished (summary)
Where documentation is stored: jobs/<job-name>/
PR URL (if created)
Metrics summary (time, tokens)
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":

Keep existing completed steps (analyze, context, report are already done)
Extend plan with new steps: prepare → implement → review → fix → checks → report → pr
Update job documentation via job-documenter (update-readme with new plan)
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).
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.
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.

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

Setting	Default	Options	Description
`skip_confirmation`	`true`	true/false	Skip confirmation for sub-agents
`base_branch`	auto-detect	any	Base branch (auto-detect from repo default, or ask user)
`max_review_iterations`	`3`	1-5	Max review → fix iterations
`create_pr`	`true`	true/false	Whether to propose PR at the end
`auto_create_pr`	`false`	true/false	Auto-create PR without asking
`review_mode`	`"code-review"`	`"code-review"` / `"individual"`	Use 4-agent parallel or individual reviewers
`reviewers`	`["code-ai-review", "code-boss-review", "code-style-review"]`	skill names	Individual reviewers (when review_mode=individual)
`conditional_reviewers`	`{"code-mobx-store-review": "*.store.ts"}`	skill→pattern	Conditional reviewers
`run_final_checks`	`true`	true/false	Run lint/type-check/test
`run_interview`	`true`	true/false	Run interview skill in Phase 0
`dry_run`	`false`	true/false	Plan-only mode: full Phase 0+1, no agent dispatch or git ops
`log_prompt_sizes`	`true`	true/false	Store prompt char count per step in state.json for observability
`plan_approval`	`true`	true/false	Show agent plan and ask approve/adjust before execution (1.3)
`run_test_gen`	`true`	true/false	Auto-run test-gen if implementer skips tests
`run_security_audit`	`true`	true/false	Auto-run security-audit if auth/API/DB files touched
`run_perf_check`	`true`	true/false	Auto-run perf-check if frontend/bundle files changed
`run_changelog`	`true`	true/false	Auto-generate changelog entry and include in PR description
`run_deploy`	`ask`	`ask`/`true`/`false`	Post-PR deploy: ask user (ask), always deploy (true), never (false)

Dry-Run Mode

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

Phase 0 runs fully — context collection, interviewer (if applicable), summary + confirm
Phase 1 runs fully — plan is built and displayed with step tree
Phase 2 is skipped entirely — no sub-agents dispatched, no git operations
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.

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

Budget Guards & Timeouts

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

Guard	Default	Description
`step_timeout_ms`	`300000` (5 min)	Max time per step. Kill agent if exceeded.
`implementation_timeout_ms`	`600000` (10 min)	Max time for full implementation phase
`total_job_timeout_ms`	`1800000` (30 min)	Max time for entire job. Abort to Phase 3 if exceeded.
`max_retries_per_step`	`2`	Max retries for a failed step before asking user

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:

Class	Meaning	Action
`terminal`	Unrecoverable — cannot continue	ABORT immediately, surface actionable message
`retryable`	Transient failure (bad output, timeout)	Auto-retry up to 2× with identical prompt. After 2 failures → escalate to `recoverable`
`recoverable`	Partial success or skippable failure	Ask user with specific "continue from here / skip step / abort" options

Error Table

Error	Class	Action
Issue not found (404)	`terminal`	ABORT — issue-analyzer reports 404
Analysis returns 0 tasks	`recoverable`	Try smart fallback: (1) re-read issue with broader scope, (2) ask user to clarify, (3) if still 0 → ABORT
Branch/worktree creation fails	`terminal`	ABORT — report git error. NEVER fall back to `git checkout -b`
Interviewer `ready_to_proceed: false`	`terminal`	STOP — tell user which blockers remain
Sub-agent returns malformed JSON	`retryable`	Retry with: "Output was malformed. Fix: [errors]. Try again." (max 2×)
Sub-agent timeout	`retryable`	Retry with identical prompt (max 2×)
Task implementation fails	`recoverable`	Ask: "Step failed. Continue remaining tasks / skip this task / abort?"
Job-documenter returns error	`recoverable`	Log warning, continue (documentation is non-blocking)
All reviewers fail	`recoverable`	Skip review, add warning to report, continue to checks
Fix loop exceeds max_review_iterations	`recoverable`	Log unresolved findings, continue to checks
Final checks fail	`recoverable`	Include in report, still propose PR (user decides)
gh CLI not available	`recoverable`	Print PR data, user creates manually

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

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

JOBS_ROOT passed explicitly by the orchestrator in the sub-agent dispatch prompt
GOODAI_JOBS_ROOT environment variable (if set)
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:

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

Save to jobs/<job-name>/post-mortem.md
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.

job-orchestrator

Job Orchestrator

Purpose

When to Use

Architecture: 4 Dynamic Phases

Phase 0: CONTEXT COLLECTION

0.0 State Resumption Check

0.1 Determine User Intent

0.1.1 Interactive Approach Selection (for ambiguous requests)

0.1.5 Interviewer Gate (for custom and ambiguous requests)

0.2 Collect Required Context

0.3 Interview for Implement Intent

0.3.1 Dependency Check

0.4 Summarize and Confirm

Phase 1: PLAN BUILDING

1.1 Build Execution Plan

1.2 Initialize Job Documentation

1.3 Display Plan + Agent Approval

Phase 2: EXECUTION

2.1 General Execution Loop

2.2 Step: ANALYZE

2.3 Step: CONTEXT

2.4 Step: PREPARE

2.4.1 Step: TESTS-CREATOR + IMPLEMENT — Wave Isolation

Why wave isolation

Execution pattern

Wave executor prompt template

2.5.1 Post-Implementation Checkpoint

2.5.5 Step: IMPLEMENT SANITY CHECK

2.6 Step: REVIEW

2.6.0 Review Strategy Selection

2.6.1 Execute Review

2.6.2 Post-Review Checkpoint

2.7 Step: FIX (conditional)

2.8 Step: VERIFY (code-verifier)

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

2.8.1 Step: PERF-CHECK (optional)

2.9 Step: REPORT

2.10 Step: PR (conditional)

Phase 3: COMPLETION

3.1 Finalize Job Documentation

3.2 Present Results

3.3 Post-Completion Options

Plan Extension (Dynamic Planning)

State Management

state.json Specification

Interpreting Subagent Results

Iron Law

How to handle each status

Red Flag

Constructing Subagent Context

Template dispatch block

Minimality principle

Red Flag

Automation Settings

Dry-Run Mode

Budget Guards & Timeouts

Error Handling

Error Table

Retry Protocol (for retryable errors)

Progress Notifications

Rules of Engagement

Configurable Jobs Root

Post-Mortem (for failed/aborted jobs)

Metrics Collection

0.1.5 Interviewer Gate (for `custom` and ambiguous requests)

Retry Protocol (for `retryable` errors)