Skip to main content

​
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)
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

CommandWhat It Does
/sdd-initInitialize 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-continueRun the next dependency-ready phase via sub-agent(s).
/sdd-ff <name>Fast-forward planning with sub-agents (proposal → specs → design → tasks).
/sdd-applyImplement tasks in batches. Checks off items as it goes.
/sdd-verifyValidate implementation against specs. Reports CRITICAL / WARNING / SUGGESTION.
/sdd-archiveClose a change and persist final state in the active artifact store.

​
Example: Complete Workflow

​
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-AgentSkill FileWhat It Does
Initsdd-init/SKILL.mdDetects project stack, creates openspec/ structure
Explorersdd-explore/SKILL.mdReads codebase, compares approaches, identifies risks
Proposersdd-propose/SKILL.mdCreates proposal.md with intent, scope, rollback plan
Spec Writersdd-spec/SKILL.mdWrites delta specs (ADDED/MODIFIED/REMOVED) with Given/When/Then
Designersdd-design/SKILL.mdCreates design.md with architecture decisions and rationale
Task Plannersdd-tasks/SKILL.mdBreaks down into phased, numbered task checklist
Implementersdd-apply/SKILL.mdWrites code following specs and design, marks tasks complete. v2.0: TDD workflow support
Verifiersdd-verify/SKILL.mdValidates implementation against specs with real test execution. v2.0: spec compliance matrix
Archiversdd-archive/SKILL.mdMerges delta specs into main specs, moves to archive

​
Shared Conventions

All 9 skills reference three shared convention files instead of inlining persistence logic:
FilePurpose
persistence-contract.mdMode resolution rules — how engram, openspec, and none modes behave
engram-convention.mdDeterministic artifact naming, two-step recovery protocol
openspec-convention.mdFilesystem 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

Build docs developers (and LLMs) love

Get started for freeTalk to us