Skip to main content
Every sub-agent in Agent Teams Lite returns a structured result envelope to the orchestrator. This contract ensures consistent communication and enables the orchestrator to make informed decisions about next steps.

​
Result Envelope Format

Sub-agents return results in this Markdown format: 
## {Phase Name} Complete

**Change**: {change-name}
**Status**: {success | warning | failure}

### Summary
{1-3 sentence executive summary for the orchestrator}

### Artifacts
{List of created/updated artifacts with paths or observation IDs}

### Next Recommended
{What the orchestrator should do next — be specific}

### Risks
{Any issues, warnings, or blockers discovered}

​
Fields

​
Phase Name
string
required
The phase name (e.g., “Proposal Created”, “Design Complete”, “Verification Report”)
​
Change
string
The change name this result relates to (e.g., “add-dark-mode”). Omitted for sdd-init.
​
Status
enum
required
Result status:
  • success — Phase completed without issues
  • warning — Phase completed but with non-blocking concerns
  • failure — Phase failed or blocked
​
Summary
string
required
A concise executive summary (1-3 sentences) that the orchestrator can parse to understand what happened.
​
Artifacts
list
required
List of artifacts created or updated:
  • engram mode: Observation IDs (e.g., #obs_12345)
  • openspec mode: File paths (e.g., openspec/changes/add-dark-mode/proposal.md)
  • none mode: “None (ephemeral)” or inline artifact description
​
Next Recommended
string
required
What the orchestrator should do next. Be specific:
  • “Ready for specs (sdd-spec)”
  • “Ready for implementation (sdd-apply)”
  • “Blocked: resolve open questions in design before proceeding”
​
Risks
list
Any issues, warnings, or concerns discovered during the phase:
  • CRITICAL: Must be resolved before proceeding
  • WARNING: Should be addressed but won’t block
  • SUGGESTION: Nice-to-have improvements
If none, say “None.”

​
Example: Proposal Created (openspec mode)

## Proposal Created

**Change**: add-dark-mode
**Status**: success

### Summary
Proposal defines UI theme switching with localStorage persistence. Scope includes 3 core deliverables (theme toggle, CSS variables, persistence). Risk level: Low.

### Artifacts
- openspec/changes/add-dark-mode/proposal.md

### Next Recommended
Ready for specs (sdd-spec) or design (sdd-design). Recommend running both in parallel.

### Risks
None.

​
Example: Verification Failed

## Verification Report

**Change**: add-dark-mode
**Status**: failure

### Summary
Verification failed: 3 of 8 spec scenarios are UNTESTED. Build passed, but 2 tests failed. Cannot archive until tests are fixed.

### Artifacts
- openspec/changes/add-dark-mode/verify-report.md

### Next Recommended
Fix failing tests in `src/theme/__tests__/toggle.test.ts`, then re-verify. Do NOT proceed to archive.

### Risks
- **CRITICAL**: `ThemeToggle` component throws error when localStorage is unavailable (scenario "Graceful fallback" UNTESTED)
- **CRITICAL**: Test "persists theme choice" expects 'dark' but got 'light'
- **WARNING**: Coverage is 67%, below recommended 80% threshold

​
Example: Init with Engram

## SDD Initialized

**Project**: my-app
**Status**: success

### Summary
Project context detected (React 19 + TypeScript + Vitest). Persistence mode: engram. Project context saved to Engram.

### Artifacts
- Engram observation: #obs_abc123 (topic_key: sdd-init/my-app)

### Next Recommended
Ready for /sdd-explore <topic> or /sdd-new <change-name>.

### Risks
None.

​
Why This Contract Exists

​
Consistency

Every sub-agent speaks the same language. The orchestrator doesn’t need custom parsers for each phase.

​
Decision Making

The orchestrator uses Status and Next Recommended to decide whether to:
  • Proceed to the next phase automatically
  • Ask the user for input
  • Stop and report an error

​
Traceability

The Artifacts field creates a clear audit trail:
  • In engram mode: observation IDs enable retrieval via mem_get_observation
  • In openspec mode: file paths enable filesystem inspection
  • In none mode: inline results are logged in the conversation

​
Error Handling

The Risks field ensures issues don’t get silently lost. The orchestrator surfaces CRITICAL risks to the user immediately.

​
Sub-Agent Responsibilities

Each sub-agent MUST:
  • Return a result envelope in this exact format
  • Set Status accurately (don’t return success if there are CRITICAL risks)
  • Be specific in Next Recommended (don’t just say “continue”)
  • List ALL artifacts created or updated
  • Flag risks with severity levels (CRITICAL / WARNING / SUGGESTION)
The orchestrator relies on this contract to make autonomous decisions about workflow progression.

Build docs developers (and LLMs) love

Get started for freeTalk to us