Complete Workflow Guide

Understanding the full Agent Teams Lite workflow from initialization to archive

Overview

Agent Teams Lite uses a structured workflow where a lightweight orchestrator delegates all real work to specialized sub-agents. Each sub-agent starts with fresh context, executes one focused task, and returns a structured result.

The orchestrator NEVER does phase work directly. It only coordinates sub-agents, tracks state, and synthesizes summaries. This keeps the main thread small and stable.

The Workflow Pattern

YOU: "I want to add CSV export to the app"

ORCHESTRATOR (delegate-only, minimal context):
  → launches EXPLORER sub-agent     → returns: codebase analysis
  → shows you summary, you approve
  → launches PROPOSER sub-agent     → returns: proposal artifact
  → launches SPEC WRITER sub-agent  → returns: spec artifact
  → launches DESIGNER sub-agent     → returns: design artifact
  → launches TASK PLANNER sub-agent → returns: tasks artifact
  → shows you everything, you approve
  → launches IMPLEMENTER sub-agent  → returns: code written, tasks checked off
  → launches VERIFIER sub-agent     → returns: verification artifact
  → launches ARCHIVER sub-agent     → returns: change closed

Architecture

The orchestrator maintains minimal context while sub-agents handle all heavy lifting:

┌──────────────────────────────────────────────────────────┐
│  ORCHESTRATOR (your main agent — gentleman, default, etc) │
│                                                           │
│  Responsibilities:                                        │
│  • Detect when SDD is needed                              │
│  • Launch sub-agents via Task tool                        │
│  • Show summaries to user                                 │
│  • Ask for approval between phases                        │
│  • Track state: which artifacts exist, what's next        │
│                                                           │
│  Context usage: MINIMAL (only state + summaries)          │
└──────────────┬───────────────────────────────────────────┘
               │
               │ Task(subagent_type: 'general', prompt: 'Read skill...')
               │
    ┌──────────┴──────────────────────────────────────────┐
    │                                                      │
    ▼          ▼          ▼         ▼         ▼           ▼
┌────────┐┌────────┐┌────────┐┌────────┐┌────────┐┌────────┐
│EXPLORE ││PROPOSE ││  SPEC  ││ DESIGN ││ TASKS  ││ APPLY  │ ...
│        ││        ││        ││        ││        ││        │
│ Fresh  ││ Fresh  ││ Fresh  ││ Fresh  ││ Fresh  ││ Fresh  │
│context ││context ││context ││context ││context ││context │
└────────┘└────────┘└────────┘└────────┘└────────┘└────────┘

The Dependency Graph

Phases execute in a directed acyclic graph (DAG) based on dependencies:

                    proposal
                   (root node)
                       │
         ┌─────────────┴─────────────┐
         │                           │
         ▼                           ▼
      specs                       design
   (requirements                (technical
    + scenarios)                 approach)
         │                           │
         └─────────────┬─────────────┘
                       │
                       ▼
                    tasks
                (implementation
                  checklist)
                       │
                       ▼
                    apply
                (write code)
                       │
                       ▼
                    verify
               (quality gate)
                       │
                       ▼
                   archive
              (merge specs,
               close change)

Parallel Phase Execution

Note that specs and design can run in parallel since they both depend only on the proposal. The orchestrator can launch both sub-agents simultaneously for faster execution.

Commands Reference

Command	What It Does
/sdd-init	Initialize SDD context. Detects stack and bootstraps the active persistence backend.
/sdd-explore <topic>	Investigate an idea. Reads codebase, compares approaches. No files created.
/sdd-new <name>	Start a new change by delegating exploration + proposal to sub-agents.
/sdd-continue	Run the next dependency-ready phase via sub-agent(s).
/sdd-ff <name>	Fast-forward planning with sub-agents (proposal → specs → design → tasks).
/sdd-apply	Implement tasks in batches. Checks off items as it goes.
/sdd-verify	Validate implementation against specs. Reports CRITICAL / WARNING / SUGGESTION.
/sdd-archive	Close a change and persist final state in the active artifact store.

Example: Complete Workflow

Step-by-Step: Adding Dark Mode

1. Start the Change

You: /sdd-new add-dark-mode

AI:  Launching explorer sub-agent...
     ✓ Codebase analyzed. React + Tailwind detected.
     ✓ Current theme: hardcoded light mode in globals.css
     
     Launching proposal sub-agent...
     ✓ proposal.md created
       Intent: Add dark mode toggle with system preference detection
       Scope: Theme context, toggle component, CSS variables
     
     Want me to continue with specs and design? (or review the proposal first)

2. Continue to Specs and Design

You: Go ahead

AI:  ✓ specs/ui/spec.md — 3 requirements, 7 scenarios
     ✓ design.md — CSS variables approach, React Context, localStorage
     ✓ tasks.md — 3 phases, 8 tasks
     
     Ready to implement. Run /sdd-apply to start.

3. Implementation

You: /sdd-apply

AI:  Implementing Phase 1 (Foundation)...
     ✓ 1.1 Created ThemeContext
     ✓ 1.2 Added CSS custom properties
     ✓ 1.3 Added localStorage persistence
     
     3/8 tasks complete. Continue with Phase 2?

4. Verification

You: /sdd-verify

AI:  Running verification...
     ✓ All specs scenarios pass
     ✓ Build successful
     ⚠ Warning: No tests for system preference detection
     
     Status: PASS with warnings

5. Archive

You: /sdd-archive

AI:  Archiving change...
     ✓ Delta specs merged into main specs
     ✓ Change moved to archive/2026-03-04-add-dark-mode/
     ✓ Audit trail created
     
     Change complete!

Sub-Agent Result Contract

Each sub-agent returns a structured payload:

{
  "status": "ok | warning | blocked | failed",
  "executive_summary": "short decision-grade summary",
  "detailed_report": "optional long-form analysis when needed",
  "artifacts": [
    {
      "name": "design",
      "store": "engram | openspec | none",
      "ref": "observation-id | file-path | null"
    }
  ],
  "next_recommended": ["tasks"],
  "risks": ["optional risk list"]
}

executive_summary is intentionally short. detailed_report can be as long as needed for complex architecture work.

The Sub-Agents

Each sub-agent is a SKILL.md file — pure Markdown instructions:

Sub-Agent	Skill File	What It Does
Init	sdd-init/SKILL.md	Detects project stack, creates openspec/ structure
Explorer	sdd-explore/SKILL.md	Reads codebase, compares approaches, identifies risks
Proposer	sdd-propose/SKILL.md	Creates proposal.md with intent, scope, rollback plan
Spec Writer	sdd-spec/SKILL.md	Writes delta specs (ADDED/MODIFIED/REMOVED) with Given/When/Then
Designer	sdd-design/SKILL.md	Creates design.md with architecture decisions and rationale
Task Planner	sdd-tasks/SKILL.md	Breaks down into phased, numbered task checklist
Implementer	sdd-apply/SKILL.md	Writes code following specs and design, marks tasks complete. v2.0: TDD workflow support
Verifier	sdd-verify/SKILL.md	Validates implementation against specs with real test execution. v2.0: spec compliance matrix
Archiver	sdd-archive/SKILL.md	Merges delta specs into main specs, moves to archive

Shared Conventions

All 9 skills reference three shared convention files instead of inlining persistence logic:

File	Purpose
persistence-contract.md	Mode resolution rules — how engram, openspec, and none modes behave
engram-convention.md	Deterministic artifact naming, two-step recovery protocol
openspec-convention.md	Filesystem paths for each artifact, directory structure

Why they exist: Previously each skill inlined its own persistence logic (~224 lines of duplication across 9 skills). Now each skill references the shared files for DRY principles and consistent behavior.

v2.0 Skill Upgrades

Two skills received major upgrades:

sdd-apply v2.0

Added TDD workflow support. When enabled, the implementer follows a RED-GREEN-REFACTOR cycle: write a failing test first, implement until it passes, then refactor. Controlled by tdd: true and test_command in config.

sdd-verify v2.0

Now performs real test execution instead of static analysis only. Runs the project’s test suite and build commands, produces a spec compliance matrix mapping each requirement to PASS/FAIL/SKIP, and reports issues at CRITICAL/WARNING/SUGGESTION severity levels.

Next Steps

Persistence Modes

Learn about engram, openspec, and none modes

Delta Specs

Understand delta specifications

TDD Workflow

Master the RED-GREEN-REFACTOR cycle

Commands

Complete command reference