# Job Orchestrator
> Use when a GitHub issue or complex intent needs to be analyzed, planned, and implemented end-to-end with sub-agents.
- Skill: `mrciphersmith/job-orchestrator-2` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add mrciphersmith/job-orchestrator-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mrciphersmith/job-orchestrator-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: MrCipherSmith (https://skillmd.com/u/mrciphersmith)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mrciphersmith/job-orchestrator-2
---
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.
# 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//` + optional PR
## When to Use
- Implementing a complete GitHub issue from start to finish
- Analyzing an issue and proposing a solution before implementing
- Running any multi-step orchestrated workflow
- Running a comprehensive code review with persistent documentation
- When the AGENTS.md routing rule (Step 1.5) determines the user wants orchestrated execution and the user confirms
- User says "implement issue #N", "analyze issue #N", provides an issue URL, or asks for orchestrated work
- User says "full review", "полное ревью", or any request that implies orchestration
## Architecture: 4 Dynamic Phases
```
Phase 0: CONTEXT COLLECTION → Gather info, determine intent
Phase 1: PLAN BUILDING → Build dynamic plan, init job docs
Phase 2: EXECUTION → Execute plan steps, document each result
Phase 3: COMPLETION → Final report, optional PR, tell user where docs are
```
---
## Phase 0: CONTEXT COLLECTION
### 0.0 State Resumption Check
Before asking any questions, check if an interrupted job exists:
1. Look in `$JOBS_ROOT` for any directory containing an incomplete `state.json`.
2. If found, ASK the user: "Found paused job ''. Do you want to resume it or start a new orchestrated job?"
3. If resume → Parse `state.json`, restore `JOB_STATE`, and jump directly to the first uncompleted step in Phase 2.
4. If new → Proceed to 0.1.
### 0.1 Determine User Intent
Parse the user's request to identify the intent:
| 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 |
| "Spec then implement" / "BRD first" / "Write spec" | `spec_then_implement` | spec-orchestrator → analyze → implement → review → PR |
| 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
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:
goal: "job-orchestrator — build execution plan"
context:
codebase_summary:
existing_analysis:
```
**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:
```bash
# Detect default branch
git -C 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 |
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---`
- Issue analysis: `analysis--issue-`
- Code review: `review--`
- Custom: `task--`
### 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": ,
"context": ,
"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:
context:
```
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/.../
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"] }
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:**
- `spec`: triggered by 0.1.6 Spec-Orchestrator Gate (user chose A or B, or `run_spec_orchestrator` auto-selects)
- `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: ",
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:
JOBS_ROOT:
DATA:
TITLE:
DESCRIPTION:
INTENT:
SOURCE:
PROJECT:
BRANCH: TBD
BASE_BRANCH:
PLAN:
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 — steps:
Step 0 spec spec-orchestrator → BRD/PRD/FSD/TRD [conditional: run_spec_orchestrator]
Step 1 analyze issue-analyzer → issue #
Step 2 context context-collector → project context + test framework
Step 3 prepare orchestrator → feature branch
Step 4 tests-creator tests-creator × → RED test stubs per task (MANDATORY)
Step 5 implement task-implementer × → 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 '' 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: ",
subagent_type: "general",
prompt: |
Load skill: skills/spec-orchestrator/SKILL.md
request: ""
job_name: "-spec"
jobs_root: ""
codebase_path: ""
skip_stages:
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: /-spec/brd.md (or null if skipped)
prd_path: /-spec/prd.md
fsd_path: /-spec/fsd.md (or null if skipped)
trd_path: /-spec/trd.md (or null if skipped)
log_path: /-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 —
CONTENT:
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: #",
subagent_type: "general",
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 — #
CONTENT:
AGENT: issue-analyzer
TASK: Analyze issue #
```
**For `analyze` intent:** After documenting, present analysis to user. Ask:
```
Analysis complete. Found 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: ",
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:
JOBS_ROOT:
PROJECT_DIR:
DATA:
TASK_DESCRIPTION:
FOCUS_AREAS:
ANALYSIS_RESULT: