Skip to content
Aphelion

Architecture: Protocols

Language: English | 日本語 Last updated: 2026-04-25 (split from Architecture.md; #42) Audience: Agent developers

This page is one of three pages split from the original Architecture.md (#42). It covers the handoff file schemas and the AGENT_RESULT inter-agent communication protocol, including the blocked STATUS. See the sibling pages for the domain model and operational rules: Domain Model, Operational Rules.

Table of Contents

Section titled “Table of Contents”

Handoff File Schema

Section titled “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"]
    MR["MAINTENANCE_RESULT.md\n(Major only)\n---\nPRODUCT_TYPE\nImpact summary\nBreaking changes\nRegression risk"]

    scope-planner -->|generates| DR
    DR -->|read by| delivery-flow
    delivery-flow -->|generates| DLR
    DLR -->|read by| operations-flow
    operations-flow -->|generates| OPR
    maintenance-flow -->|Major| MR
    MR -.->|read by| delivery-flow

DISCOVERY_RESULT.md

Section titled “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

Section titled “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

Section titled “OPS_RESULT.md”

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

Required fields:

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

AGENT_RESULT Protocol

Section titled “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

Section titled “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

Section titled “STATUS Definitions”
STATUSMeaningOrchestrator Action
successCompleted successfullyProceed to approval gate
errorFailed to completeReport to user, ask for decision
failureQuality issue (e.g., test failure)Follow domain rollback rules
suspendedSession interruptedPrompt user to resume
blockedDesign ambiguity discoveredLaunch target agent in lightweight mode
approvedReview approvedProceed
conditionalReview approved with conditionsUser discretion
rejectedReview rejected (CRITICAL found)Rollback to developer

NEXT Field

Section titled “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

Section titled “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.

Section titled “Related Pages”

Canonical Sources

Section titled “Canonical Sources”