Result Contract

Structured envelope format returned by all sub-agents

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.