Architecture

Language: English | 日本語 Last updated: 2026-04-19 Audience: Agent developers

This page describes Aphelion’s architectural design: the three-domain model, session isolation strategy, handoff file schemas, PRODUCT_TYPE branching, and the AGENT_RESULT inter-agent communication protocol.

Three-Domain Model
Session Isolation
Handoff File Schema
PRODUCT_TYPE Branching
AGENT_RESULT Protocol
blocked STATUS
Auto-Approve Mode
Flow Orchestrators
Triage Tiers
Rollback Rules
Sandbox Defense Layers
Related Pages
Canonical Sources

Three-Domain Model

Aphelion divides the software development lifecycle into three independent domains:

flowchart LR
    DR["DISCOVERY_RESULT.md"]
    DLR["DELIVERY_RESULT.md"]
    OPR["OPS_RESULT.md"]

    Discovery["Discovery Flow\n(6 agents)"] -->|generates| DR
    DR -->|input for| Delivery["Delivery Flow\n(12 agents)"]
    Delivery -->|generates| DLR
    DLR -->|input for| Ops["Operations Flow\n(4 agents)\nservice only"]
    Ops -->|generates| OPR

Discovery explores and structures requirements, producing DISCOVERY_RESULT.md.

Delivery designs, implements, tests, and reviews, producing DELIVERY_RESULT.md.

Operations builds infrastructure, database operations, and operations plans, producing OPS_RESULT.md. Only runs for PRODUCT_TYPE: service.

Design Principles

Principle	Description
Domain separation	Each domain runs in an independent Claude Code session
File handoff	Domains connect through `.md` files, not automatic API calls
No automatic chaining	Each domain must be started by the user after reviewing the previous domain’s output
Triage adaptation	Each flow orchestrator assesses project scale and selects a plan tier
Independent invocation	Any agent can be invoked standalone if its input files are available

Agent Flow

flowchart LR
    D["Discovery<br/>(6 agents)<br/>interviewer → ... → scope-planner"]
    DV["Delivery<br/>(12 agents)<br/>spec-designer → ... → releaser"]
    O["Operations<br/>(4 agents)<br/>infra-builder → ... → ops-planner"]
    S["Standalone<br/>analyst / codebase-analyzer / sandbox-runner"]

    D -->|DISCOVERY_RESULT.md| DV
    DV -->|DELIVERY_RESULT.md| O
    S -.optional.-> DV

Per-domain details: Discovery · Delivery · Operations · Standalone

Session Isolation

Each domain runs in a separate Claude Code session. This is a deliberate design choice:

Prevents context window overflow: A full project lifecycle can involve thousands of lines of context. Running everything in one session risks hitting token limits.
Enables specialization: Each orchestrator loads only the rules and agents relevant to its domain.
Forces explicit checkpoints: Users must review each domain’s output before launching the next, ensuring quality gates are not skipped.

The three flow orchestrators — discovery-flow, delivery-flow, operations-flow — are the entry points for each session.

Handoff File Schema

Handoff files are the mechanism by which domains communicate. Each is a structured Markdown document validated by the receiving orchestrator.

flowchart LR
    DR["DISCOVERY_RESULT.md\n---\nPRODUCT_TYPE\nProject overview\nRequirements summary\nScope\nTechnical risks & constraints"]
    DLR["DELIVERY_RESULT.md\n---\nPRODUCT_TYPE\nArtifacts (SPEC/ARCH)\nTech stack\nTest results\nSecurity audit results"]
    OPR["OPS_RESULT.md\n---\nArtifact list\nDeploy readiness\nOpen issues"]

    scope-planner -->|generates| DR
    DR -->|read by| delivery-flow
    delivery-flow -->|generates| DLR
    DLR -->|read by| operations-flow
    operations-flow -->|generates| OPR

DISCOVERY_RESULT.md

Generated by scope-planner (or discovery-flow in Minimal plan). Input for delivery-flow.

Required fields:

PRODUCT_TYPE (one of: service / tool / library / cli)
“プロジェクト概要” section (must not be empty)
“要件サマリー” section (must not be empty)

Structure:

# Discovery Result: {project name}

> 作成日: {YYYY-MM-DD}
> Discovery プラン: {Minimal | Light | Standard | Full}

## プロジェクト概要
## 成果物の性質
PRODUCT_TYPE: {service | tool | library | cli}
## 要件サマリー
## スコープ
## 技術リスク・制約
## 未解決事項

DELIVERY_RESULT.md

Generated by delivery-flow after all phases complete. Input for operations-flow.

Required fields:

PRODUCT_TYPE
“成果物” section (must include SPEC.md and ARCHITECTURE.md status)
“技術スタック” section (must not be empty)
“テスト結果” section
“セキュリティ監査結果” section

OPS_RESULT.md

Generated by ops-planner. Final artifact of the Operations domain.

Required fields:

“成果物一覧” table
“デプロイ準備状態” checklist

PRODUCT_TYPE Branching

The PRODUCT_TYPE field determined during Discovery controls which domains run:

PRODUCT_TYPE	Discovery	Delivery	Operations
`service`	Run	Run	Run
`tool`	Run	Run	Skip
`library`	Run	Run	Skip
`cli`	Run	Run	Skip

Only service products require infrastructure, database operations, and deployment procedures.

AGENT_RESULT Protocol

Every agent must emit an AGENT_RESULT block upon completion. Flow orchestrators parse this block to determine the next action.

stateDiagram-v2
    [*] --> running : agent launched

    running --> success : completed normally
    running --> error : execution failed
    running --> failure : quality issue
    running --> blocked : design ambiguity found
    running --> suspended : session interrupted

    success --> ApprovalGate : proceed to approval gate
    error --> UserDecision : report to user
    failure --> Rollback : trigger rollback flow
    blocked --> LightweightQuery : launch BLOCKED_TARGET agent
    suspended --> [*] : user prompted to resume

    ApprovalGate --> approved : user approves
    ApprovalGate --> conditional : user approves with conditions
    ApprovalGate --> rejected : CRITICAL found

    approved --> [*] : proceed to next phase
    conditional --> [*] : user discretion
    rejected --> Rollback : rollback to developer

    UserDecision --> running : retry
    UserDecision --> [*] : skip or abort

    LightweightQuery --> running : resume with answer
    Rollback --> running : re-run after fix

Block Format

AGENT_RESULT: {agent-name}
STATUS: success | error | failure | suspended | blocked | approved | conditional | rejected
...(agent-specific fields)
NEXT: {next-agent-name | done | suspended}

STATUS Definitions

STATUS	Meaning	Orchestrator Action
`success`	Completed successfully	Proceed to approval gate
`error`	Failed to complete	Report to user, ask for decision
`failure`	Quality issue (e.g., test failure)	Follow domain rollback rules
`suspended`	Session interrupted	Prompt user to resume
`blocked`	Design ambiguity discovered	Launch target agent in lightweight mode
`approved`	Review approved	Proceed
`conditional`	Review approved with conditions	User discretion
`rejected`	Review rejected (CRITICAL found)	Rollback to developer

NEXT Field

The NEXT field tells the orchestrator which agent to launch next. Common values:

A specific agent name (e.g., architect, developer)
done — the domain is complete
suspended — the session should be paused

blocked STATUS

blocked is used when a developer agent discovers a design ambiguity or contradiction that prevents implementation from continuing.

AGENT_RESULT: developer
STATUS: blocked
BLOCKED_REASON: Module X and Y in ARCHITECTURE.md have overlapping responsibilities
BLOCKED_TARGET: architect
CURRENT_TASK: TASK-005
NEXT: suspended

The flow orchestrator launches the agent named in BLOCKED_TARGET in lightweight mode (a short prompt that only asks and answers the specific question), then resumes the original agent with the answer.

Auto-Approve Mode

When a file named .aphelion-auto-approve (or the legacy .telescope-auto-approve) exists in the project root, approval gates are automatically passed. This is designed for automated evaluation systems (e.g., the Ouroboros evaluator).

The file may optionally contain configuration overrides:

# Override triage plan
PLAN: Standard

# Override PRODUCT_TYPE
PRODUCT_TYPE: service

# Override HAS_UI
HAS_UI: true

Safety limits in auto-approve mode:

Maximum 3 retries per agent on error
Maximum 3 rollbacks total

Flow Orchestrators

The three flow orchestrators each manage a domain. They share the following common behavior (defined in .claude/orchestrator-rules.md):

Read orchestrator-rules.md at startup
Perform triage to select a plan tier
Present triage results and request user approval (unless AUTO_APPROVE: true)
Launch agents in sequence using the Agent tool with subagent_type
Execute approval gate after each phase (unless AUTO_APPROVE: true)
Handle errors via AskUserQuestion with retry/skip/abort options

Phase Execution Loop

[Phase N start]
  1. Notify user: "▶ Phase N/M: launching {agent}"
  2. Launch agent with preceding artifact paths
  3. Read AGENT_RESULT from agent output
  4. Handle STATUS: error / blocked / failure
  5. If AUTO_APPROVE: true → auto-select "承認して続行"
     If AUTO_APPROVE: false → show approval gate, wait for user
  6. Proceed to Phase N+1

Triage Tiers

Each flow orchestrator assesses project characteristics at startup and selects one of four plan tiers. See Triage System for full details.

flowchart LR
    subgraph Discovery ["Discovery Flow Triage"]
        direction TB
        DMin["Minimal\n1 agent\nPersonal tool / small script"]
        DLit["Light\n3 agents\nPersonal side project"]
        DStd["Standard\n5 agents\nExternal dependencies"]
        DFul["Full\n6 agents\nLarge-scale / complex"]
    end

    subgraph Delivery ["Delivery Flow Triage"]
        direction TB
        VMin["Minimal\n5 agents\nSingle-function tool"]
        VLit["Light\n+reviewer +test-designer\nPersonal side project"]
        VStd["Standard\n+scaffolder +doc-writer\nMulti-file project"]
        VFul["Full\n+releaser\nPublic / OSS"]
    end

    subgraph Operations ["Operations Flow Triage"]
        direction TB
        OLit["Light\n2 agents\nPaaS / single container"]
        OStd["Standard\n+db-ops\nAPI + DB architecture"]
        OFul["Full\n+observability\nHigh availability"]
    end

Note: security-auditor runs on all Delivery plans. ux-designer runs only when HAS_UI: true.

Rollback Rules

Rollbacks are triggered automatically by test failures and review CRITICAL findings. All rollbacks are limited to 3 times maximum.

Test Failure Rollback (Delivery domain)

tester (failure)
  → test-designer (root cause analysis)
    → developer (fix implementation)
      → tester (re-run)

Review CRITICAL Rollback (Delivery domain)

reviewer (CRITICAL detected)
  → developer (fix)
    → tester (re-run)
      → reviewer (re-review)

Security Audit CRITICAL Rollback (Delivery domain)

security-auditor (CRITICAL detected)
  → developer (fix)
    → tester (re-run)
      → security-auditor (re-audit)

Discovery Rollback: Infeasible Requirements

poc-engineer (blocked, BLOCKED_ITEMS > 0)
  → interviewer (discuss alternatives with user)
    → researcher (re-investigate if needed)
      → poc-engineer (re-verify)

Sandbox Defense Layers

Aphelion uses two complementary layers to protect against dangerous command execution. See Platform Guide for per-platform configuration details.

flowchart TB
    subgraph Advisory ["Advisory Layer"]
        direction LR
        Policy["sandbox-policy.md\n(auto-loaded rule)\nrisk categories:\nrequired / recommended / optional"]
        Permission["Claude Code\nPermission Mode\nallow / ask / deny"]
        Policy --> Permission
    end

    subgraph Enforcement ["Enforcement Layer"]
        direction LR
        Infra["infra-builder\ngenerates devcontainer"]
        Container[".devcontainer/devcontainer.json\ndocker-compose.dev.yml\n(container isolation)"]
        Infra --> Container
    end

    Command["Bash command\nfrom agent"] --> Advisory
    Advisory --> FallbackCheck{"container\navailable?"}

    FallbackCheck -->|Yes| ContainerExec["container\nexecution"]
    FallbackCheck -->|No| PlatformCheck{"platform\ndetected?"}

    PlatformCheck -->|claude_code| PlatformPerm["platform_permission\n(permission mode)"]
    PlatformCheck -->|unknown| CategoryCheck{"required\ncategory?"}

    CategoryCheck -->|No| Advisory2["advisory_only\n(warning only)"]
    CategoryCheck -->|Yes| Blocked["blocked\n(execution denied)"]

    Enforcement -.->|provides| FallbackCheck

Fallback order: container → platform_permission → advisory_only → blocked

Canonical Sources

.claude/CLAUDE.md — Workflow model and design principles
.claude/orchestrator-rules.md — Triage, handoff schema, approval gate, rollback rules
.claude/rules/agent-communication-protocol.md — AGENT_RESULT format and STATUS definitions

Architecture

Table of Contents

Three-Domain Model

Design Principles

Agent Flow

Session Isolation

Handoff File Schema

DISCOVERY_RESULT.md

DELIVERY_RESULT.md

OPS_RESULT.md

PRODUCT_TYPE Branching

AGENT_RESULT Protocol

Block Format

STATUS Definitions

NEXT Field

blocked STATUS

Auto-Approve Mode

Flow Orchestrators

Phase Execution Loop

Triage Tiers

Rollback Rules

Test Failure Rollback (Delivery domain)

Review CRITICAL Rollback (Delivery domain)

Security Audit CRITICAL Rollback (Delivery domain)

Discovery Rollback: Infeasible Requirements

Sandbox Defense Layers

Related Pages

Canonical Sources