Skip to content
Aphelion

Agents Reference: Orchestrators & Cross-Cutting

Language: English | 日本語 Last updated: 2026-05-30 Update history:

  • 2026-05-30: document analyst chain spawn contract + legacy-resume injection-only mode (#141)
  • 2026-04-30: Add doc-flow as the 5th flow orchestrator (#54)
  • 2026-04-30: Add doc-reviewer (Quality Agents) per #91
  • 2026-04-26: Sync with #62, #66, #72, #74 (issue #77)
  • 2026-04-25: split from Agents-Reference.md; #42 Audience: Agent developers

This page is one of six pages split from the original Agents-Reference.md (#42). It covers Flow Orchestrators, Safety Agents, Quality Agents, and Standalone Agents (cross-cutting agents). See the sibling pages for domain-specific agents: Discovery, Delivery, Operations, Maintenance, Doc.

Table of Contents

Section titled “Table of Contents”

Note: The 6 author agents launched by doc-flow are documented in the Doc Domain page.

Flow Orchestrators

Section titled “Flow Orchestrators”

Flow orchestrators manage entire domains. They are not triage-selected agents but session entry points.

discovery-flow

Section titled “discovery-flow”
  • Canonical: .claude/agents/discovery-flow.md
  • Domain: Orchestrator (Discovery)
  • Responsibility: Manages the entire requirements exploration flow. Performs triage, launches agents in sequence, handles approvals and rollbacks, generates DISCOVERY_RESULT.md.
  • Inputs: User’s project description (via command argument)
  • Outputs: DISCOVERY_RESULT.md (final handoff), INTERVIEW_RESULT.md, RESEARCH_RESULT.md, POC_RESULT.md, CONCEPT_VALIDATION.md, SCOPE_PLAN.md
  • AGENT_RESULT fields: N/A (orchestrators do not emit AGENT_RESULT; they produce handoff files)
  • NEXT conditions: Prompts user to run /delivery-flow after completion

delivery-flow

Section titled “delivery-flow”
  • Canonical: .claude/agents/delivery-flow.md
  • Domain: Orchestrator (Delivery)
  • Responsibility: Manages the entire design, implementation, testing, and review flow. Reads DISCOVERY_RESULT.md, performs triage, handles rollbacks on test/review failures, generates DELIVERY_RESULT.md.
  • Inputs: DISCOVERY_RESULT.md (optional), existing SPEC.md / ARCHITECTURE.md
  • Outputs: DELIVERY_RESULT.md (final handoff), SPEC.md, ARCHITECTURE.md, implementation code, TEST_PLAN.md, SECURITY_AUDIT.md, README.md
  • AGENT_RESULT fields: N/A
  • NEXT conditions: Prompts user to run /operations-flow (if service) after completion

operations-flow

Section titled “operations-flow”
  • Canonical: .claude/agents/operations-flow.md
  • Domain: Orchestrator (Operations)
  • Responsibility: Manages the deploy and operations flow. Only for PRODUCT_TYPE: service. Reads DELIVERY_RESULT.md, performs triage, generates OPS_RESULT.md.
  • Inputs: DELIVERY_RESULT.md (required), ARCHITECTURE.md, SPEC.md
  • Outputs: OPS_RESULT.md, Dockerfile, docker-compose.yml, CI/CD pipeline, DB_OPS.md, OBSERVABILITY.md, OPS_PLAN.md
  • AGENT_RESULT fields: N/A
  • NEXT conditions: Flow complete (user handles deployment)

maintenance-flow

Section titled “maintenance-flow”
  • Canonical: .claude/agents/maintenance-flow.md
  • Domain: Orchestrator (Maintenance — fourth flow)
  • Responsibility: Manages the maintenance lifecycle for existing projects. Receives a trigger (bug / CVE / performance / tech-debt / feature), performs Patch / Minor / Major triage via change-classifier, and launches the appropriate agent sequence. Patch and Minor complete standalone; Major generates MAINTENANCE_RESULT.md and hands off to delivery-flow.
  • Inputs: User-supplied trigger description (log error, CVE notice, feature request, etc.), SPEC.md, ARCHITECTURE.md
  • Outputs: GitHub issue, PR, test results; Major also produces MAINTENANCE_RESULT.md
  • AGENT_RESULT fields: N/A for Patch/Minor (orchestrator reports via PR + issue). For Major: PLAN, MAINTENANCE_RESULT, HANDOFF_TO
  • NEXT conditions:
    • Patch / Minor completion → done
    • Major completion → delivery-flow (user runs /delivery-flow manually after reviewing MAINTENANCE_RESULT.md)

doc-flow

Section titled “doc-flow”
  • Canonical: .claude/agents/doc-flow.md
  • Domain: Orchestrator (Doc — fifth flow)
  • Responsibility: Generates customer-deliverable documents (HLD / LLD / API reference / ops manual / end-user manual / handover) from existing Aphelion artifacts (SPEC.md, ARCHITECTURE.md, etc.). Performs doc-type triage, launches each of the 6 author agents in sequence with user approval gates, and produces DOC_FLOW_RESULT.md. No automatic chaining from other flows — user invokes via /doc-flow at any point after SPEC.md and ARCHITECTURE.md are available.
  • Inputs: SPEC.md, ARCHITECTURE.md (and optionally DISCOVERY_RESULT.md, UI_SPEC.md, infra artifacts, OPS_RESULT.md); arguments --types, --lang, --slug, --target-project
  • Outputs: DOC_FLOW_RESULT.md, docs/deliverables/{slug}/*.md (one file per selected doc type)
  • AGENT_RESULT fields: STATUS, SLUG, OUTPUT_LANG, GENERATED_DELIVERABLES, SKIPPED_TYPES, TEMPLATE_VERSIONS, SUGGEST_DOC_REVIEW
  • NEXT conditions:
    • All selected doc types complete → done
    • Any author agent blocked (template major bump) → AskUserQuestion for overwrite / backup / abort
  • Triage: Doc-type count based (not Minimal/Light/Standard/Full):
    • Minimal: 1–2 doc types selected
    • Light: 3–4 doc types selected
    • Standard: 5–6 doc types selected
    • Full: all 6 types + post-generation template_version verification
  • Author agents: See Agents Reference: Doc Domain for the 6 author agents (hld-author, lld-author, api-reference-author, ops-manual-author, user-manual-author, handover-author)
  • Slash command: /doc-flow (see .claude/commands/doc-flow.md for argument spec)

Safety Agents

Section titled “Safety Agents”

These agents enforce safety policies across other agents. They may be invoked automatically by orchestrators or explicitly delegated from any Bash-owning agent.

sandbox-runner

Section titled “sandbox-runner”
  • Canonical: .claude/agents/sandbox-runner.md
  • Domain: Safety (cross-cutting)
  • Responsibility: Executes high-risk commands using the strongest available isolation. First attempts container mode (devcontainer + Docker); falls back to platform permission controls if unavailable. Re-classifies commands against sandbox-policy.md and returns a complete audit trail including fallback reason.
  • Inputs: command, working_directory, timeout_sec, risk_hint, allow_network, allow_write_paths, dry_run, reason, caller_agent
  • Outputs: stdout, stderr, exit_code, sandbox_mode, detected_risks, decision, fallback_reason, notes
  • Execution path selection (Step 2 of workflow):
    1. Check for .devcontainer/devcontainer.json in the repository
    2. Run docker info with 5-second timeout
    3. Both OK → container mode (mount working directory only; --network=none by default; no host env vars)
    4. Either fails → fallback to platform_permission with FALLBACK_REASON recorded
  • AGENT_RESULT fields: STATUS, SANDBOX_MODE, EXIT_CODE, DETECTED_RISKS, DECISION, CALLER, DURATION_MS, FALLBACK_REASON (omitted when container mode succeeds)
  • NEXT conditions:
    • Called by another agent → returns to caller agent
    • Invoked standalone → done
    • Session interrupted → suspended

Quality Agents

Section titled “Quality Agents”

These agents enforce quality gates across other agents’ outputs. They are auto-inserted by flow orchestrators after specific phases complete; the calling agent does not invoke them directly.

doc-reviewer

Section titled “doc-reviewer”
  • Canonical: .claude/agents/doc-reviewer.md
  • Domain: Quality (cross-cutting)
  • Responsibility: Reviews cross-document consistency for markdown artifacts (SPEC.md / ARCHITECTURE.md / UI_SPEC.md / docs/design-notes/, DISCOVERY_RESULT.md). Auto-inserted by flow orchestrators after spec-designer / architect / ux-designer / scope-planner / analyst complete (post-insert). Runs in an isolated context independent from the producing agent. Read-only — does not generate or modify any files; emits a text report only.
  • Inputs: Target artifact(s) from the preceding phase + upstream artifacts they depend on (e.g., SPEC.md when reviewing ARCHITECTURE.md). TRIGGERED_BY field identifies the upstream agent.
  • Outputs: Text report with severity-tagged findings (🔴 DR / 🟡 DA / 🟢 DI). No file artifacts.
  • Five review axes: coverage / naming / scope / version / acceptance
  • AGENT_RESULT fields: STATUS, DOC_REVIEW_RESULT (pass | fail | conditional), INCONSISTENCY_COUNT, TRIGGERED_BY, REVIEWED_FILES, FINDINGS, NEXT
  • NEXT conditions:
    • DOC_REVIEW_RESULT: pass → next phase
    • DOC_REVIEW_RESULT: fail → rollback to upstream agent (max 3 per Rollback Limit Common in orchestrator-rules.md); on exceeding, approval gate offers “Approve despite findings”
  • Plan tier:
    • delivery-flow: mandatory across all plans (after spec-designer / architect / ux-designer)
    • discovery-flow: mandatory at scope-planner completion. Skipped in Minimal (scope-planner does not run).
    • maintenance-flow: conditional auto — runs after analyst only when analyst.DOCS_UPDATED contains a SPEC.md diff (Patch with no SPEC change skips)

Standalone Agents

Section titled “Standalone Agents”

These agents operate outside the triage system. analyst is invoked directly by the user; codebase-analyzer is also standalone.

The analyst chain consists of three files: the top-level orchestrator (analyst) and two sub-agents (analyst-intake, analyst-core) that are chained internally. Users invoke /analyst only.

analyst (top-level orchestrator)

Section titled “analyst (top-level orchestrator)”
  • Canonical: .claude/agents/analyst.md
  • Domain: Standalone (top-level orchestrator, invoked via /analyst slash command only)
  • Model: Sonnet
  • Responsibility: Top-level orchestrator for the analyst chain. Chains analyst-intake → analyst-core via the Agent tool. Detects existing planning docs for three resume cases (post-Pattern-B resume / legacy resume / fresh). Does not write files or run git; orchestration only.
  • Inputs: User’s issue description (via /analyst command)
  • Outputs: Passthrough of analyst-core AGENT_RESULT (with agent-name rewritten to analyst for backward compatibility)
  • NEXT conditions: architect (default) | developer

Sub-agent spawn contract (IMPORTANT): analyst.md relies on the Agent tool, which is gated to top-level sessions only. Flow orchestrators and main sessions MUST NOT spawn analyst via Agent(subagent_type="analyst"). The correct pattern for programmatic invocation is:

  1. Spawn analyst-intake directly (pass legacy_planning_doc + existing_issue_url + existing_issue_number if resuming a legacy doc).
  2. Receive HANDOFF_PAYLOAD from analyst-intake’s AGENT_RESULT.
  3. Spawn analyst-core with that HANDOFF_PAYLOAD as the prompt.

This pattern applies to all three cases: fresh, post-Pattern-B resume, and legacy resume.

Resume detection (three cases):

  • Post-Pattern-B resume: planning doc exists AND <!-- analyst-handoff --> block present → spawn analyst-core directly with the parsed YAML.
  • Legacy resume: planning doc exists AND no handoff block AND > GitHub Issue: line present → spawn analyst-intake in injection-only mode (see below).
  • Fresh: no matching planning doc → spawn analyst-intake normally.

analyst-intake

Section titled “analyst-intake”
  • Canonical: .claude/agents/analyst-intake.md
  • Domain: Standalone (sub-agent; invoked by analyst orchestrator or flow orchestrators)
  • Model: Sonnet
  • Responsibility: Structured intake phase (Steps A–D). Collects minimum information via AskUserQuestion, writes the planning doc §1-4 stub with embedded <!-- analyst-handoff --> YAML (for resume detection), creates the GitHub issue, and commits the work branch initial state. Emits HANDOFF_PAYLOAD for the caller to forward to analyst-core. Also supports injection-only mode for legacy doc resume (see below).
  • Inputs: User’s issue description, existing SPEC.md / ARCHITECTURE.md / UI_SPEC.md. In injection-only mode: legacy_planning_doc, existing_issue_url, existing_issue_number.
  • Outputs: docs/design-notes/<slug>.md (§1-4 stub with handoff YAML, or injected block for legacy doc), GitHub issue (initial body; skipped in injection-only mode), work branch commit
  • AGENT_RESULT fields: HANDOFF_PAYLOAD (13-field YAML), BRANCH, GITHUB_ISSUE, ARTIFACT_PATHS
  • NEXT conditions: analyst-core (via caller)

Injection-only mode: Triggered when the caller’s prompt contains legacy_planning_doc + existing_issue_url + existing_issue_number. In this mode:

  • Skips: intake AskUserQuestion (Steps A-B), gh issue create (Step D), proposals/ promotion.
  • Runs: reads the existing planning doc, injects the <!-- analyst-handoff --> block (13 fields constructed from existing content + passed issue params), creates a work branch from main (regardless of current branch — B3 fix), commits the injected block, pushes, emits HANDOFF_PAYLOAD.
  • The HANDOFF_PAYLOAD 13-field schema is identical to fresh mode; no schema change.

analyst-core

Section titled “analyst-core”
  • Canonical: .claude/agents/analyst-core.md
  • Domain: Standalone (sub-agent; invoked by analyst orchestrator or flow orchestrators)
  • Model: Opus
  • Responsibility: Deep analysis phase (Steps 1–5). Validates the handoff payload, classifies the issue, performs full analysis, requests user approval, updates SPEC.md / UI_SPEC.md incrementally (when needed), refines the GitHub issue body, writes planning doc §5-8, and commits the final state.
  • Inputs: HANDOFF_PAYLOAD YAML (13 fields from analyst-intake, via spawn prompt)
  • Outputs: docs/design-notes/<slug>.md (§5-8 added), updated SPEC.md / UI_SPEC.md (incremental), GitHub issue body (refined via gh issue edit), final commit
  • AGENT_RESULT fields: ISSUE_TYPE, ISSUE_SUMMARY, DOCS_UPDATED, GITHUB_ISSUE, HANDOFF_TO, ARCHITECT_BRIEF
  • NEXT conditions: architect (default) | developer

codebase-analyzer

Section titled “codebase-analyzer”
  • Canonical: .claude/agents/codebase-analyzer.md
  • Domain: Standalone
  • Responsibility: Reverse-engineers SPEC.md and ARCHITECTURE.md from an existing codebase that lacks documentation. Enables the project to join the standard Aphelion workflow via analyst → delivery-flow.
  • Inputs: Existing codebase (source files in working directory)
  • Outputs: SPEC.md, ARCHITECTURE.md (reverse-engineered)
  • AGENT_RESULT fields: HAS_UI, PRODUCT_TYPE, LANGUAGE, FRAMEWORK, UC_COUNT, ENTITY_COUNT, TBD_COUNT
  • NEXT conditions: done (user then runs /analyst or /delivery-flow)
Section titled “Related Pages”

Canonical Sources

Section titled “Canonical Sources”