sdd-orchestrator

What this skill does

# SDD Orchestrator — Specification-Driven Development Workflow Engine

## Overview

You orchestrate the SDD v3.2 lifecycle across 8 document layers using 15 expert persona subagents. Unlike the legacy UCX system that concatenated all persona texts into a single prompt, you dispatch personas as **parallel subagents** for concurrent review.

### Mandatory Governance Load (Before Any SDD Work)

Before creating, reviewing, or remediating ANY SDD document, load the governance protocol:

```
skill_view(name='sdd-orchestrator', file_path='references/governance-load-protocol.md')
```

This single file condenses the planning-first rules from GOVERANCE_RULES.md §2b/§3, DEFINITION_OF_DONE.md plan/IPLAN review level, and DEVELOPMENT_WORKFLOW_GUIDE.md §2. **Skip this load step = governance violation.**

If the protocol file is missing or stale (after a UCX framework sync), fall back to loading the three governance docs individually via:

```
skill_view(name='sdd-orchestrator', file_path='governance/GOVERNANCE_RULES.md')
skill_view(name='sdd-orchestrator', file_path='governance/DEFINITION_OF_DONE.md')
skill_view(name='sdd-orchestrator', file_path='governance/DEVELOPMENT_WORKFLOW_GUIDE.md')
```

These docs contain the planning-first gates (§3), Definition of Done for plan/IPLAN review level,
depth model selection, plan types and storage rules (§2b), and the full agent operating model.

Governance docs are read **directly from the repository** (`framework/` tree); per D-0013 (aidoc-flow migration), there is no local sync — re-stale-checks are not needed.

## SDD Layer Sequence (v3.2)

```
BRD (L1) → PRD (L2) → EARS (L3) → BDD (L4) → ADR (L5) → SPEC (L6) → TDD (L7) → IPLAN (L8) → Code
```

### Layer Descriptions

| Layer | Artifact | Purpose | Upstream | Downstream |
|-------|----------|---------|----------|------------|
| L1 | BRD | Business requirements, objectives, scope | — | PRD |
| L2 | PRD | Product features, user stories, ADR topics | BRD | EARS |
| L3 | EARS | Formal requirements (WHEN-THE-SHALL-WITHIN) | BRD, PRD | BDD |
| L4 | BDD | Executable acceptance scenarios with spec_trace | BRD, PRD, EARS | ADR |
| L5 | ADR | Architecture decisions (Context-Decision-Consequences) | BRD, PRD, EARS, BDD | SPEC |
| L6 | SPEC | Component interfaces, data models, behavior contracts | BRD, PRD, EARS, BDD, ADR | TDD |
| L7 | TDD | Test case definitions, BDD-to-test mapping, quality thresholds | BRD through SPEC | IPLAN |
| L8 | IPLAN | Execution plan: file manifest, bash commands, session handoff | BRD through TDD | Code |

### What Was Cut from v2

| Cut | Replaced By |
|-----|-------------|
| SYS (L6) | ADR captures architecture; PRD captures scope |
| REQ (L7) | EARS + BDD spec_trace provide requirement-to-spec links |
| CTR (L8) | SPEC interface contracts handled inline |
| TSPEC (L10) | TDD (L7) with embedded test case definitions |
| TASKS (L11) | IPLAN (L8) execution bridge with session handoff |

## Persona Name Mapping (UCX → Hermes Skill)

| UCX Name | Hermes Skill Name |
|----------|-------------------|
| architect | system-architect |
| auditor | security-auditor |
| tech_lead | technical-lead |
| strategist | business-strategist |
| chaos_engineer | chaos-engineer |
| operator | site-reliability-engineer |
| integration_lead | integration-specialist |
| product_owner | product-owner |
| business_analyst | business-analyst |
| fact_checker | fact-checker |
| chairperson | board-chairperson |
| qa_lead | qa-lead |
| content_strategist | content-strategist |
| requirements_specialist | requirements-specialist |
| ux_strategist | ux-strategist |

---

---

## Hermes Agent as SDD Strategy Execution Runtime

When the SDD pipeline defines an autonomous strategy (trading agent, monitoring system, etc.), Hermes Agent can serve as the runtime orchestrator instead of building a custom execution engine. This replaces the traditional IPLAN→Code execution path with Hermes-native scheduling, MCP integration, and skill-based rule execution.

Pattern documented in: `references/hermes-agent-sdd-runtime-pattern.md`

Key integration points:

- **cronjob**: Schedule check windows at precise times (market hours, daily scans)
- **skills**: Load SDD documents as decision rules — soft updates via skill patches
- **MCP servers**: Register broker/external system MCP servers as Hermes tools
- **memory**: Persist state across sessions (positions, account data, idempotency keys)
- **gateway**: Multi-platform operator alerts (Telegram, Discord, etc.)

Cost comparison: ~1 developer-week + $5-10/month (LLM inference) vs 4-6 developer-weeks + $200/month for custom orchestrator.

See ADR-21 for a complete implementation example (TradeGent CC).

**NO SDD DOCUMENT MAY BE CREATED, REVIEWED, OR REMEDIATED WITHOUT A WRITTEN AND APPROVED PLAN.**

Before any document creation (Phase 1), the following planning package MUST exist and be explicitly approved by the human:

### Required Planning Artifacts

1. **Planning Roadmap** — `plans/ROADMAP.md` or `governance/plans/ROADMAP.md` listing all intended SDD layers and their dependencies
2. **Planning Index** — `governance/plans/README.md` or `.hermes/plans/README.md` listing required plan documents
3. **Changelog Plan** — Document tracking expected changes per layer
4. **IPLAN or Development Plan** — `governance/plans/PLAN-NNN_{slug}.md` (preferred) or `.hermes/plans/YYYY-MM-DD_HHMMSS-{slug}.md` per the `plan` skill

### Planning Gate Checklist (Execute Before Phase 1)

- [ ] Planning roadmap exists for project scope
- [ ] Planning index lists required plan artifacts
- [ ] Changelog plan exists for issue scope
- [ ] Planning gap review completed (resolved or deferred with rationale)
- [ ] IPLAN or development plan exists and is explicitly approved by human
- [ ] Human has explicitly approved proceeding to document creation

**If any checklist item is missing: STOP. Do not proceed to Phase 1. Create the missing artifact or ask the human for direction.**

For a deeper, 10-category audit covering changelog plans, gap reviews, index registration, dependency completeness, roadmap timing, ADR topic coverage, scope boundaries, section outlines, CHG governance, and validation pre-checks, see `references/plan-gap-review-checklist.md`.

### BRD-to-Source Coverage Audit (For BRD Layer Initialization)

When initializing a project's BRD layer from a large source document (rulebook, strategy doc, etc.):

1. **Extract all section headers** from the source document — use `grep -n '^# '` for markdown, or equivalent for the format
2. **Build a coverage matrix**: each source section → proposed BRD assignment + rationale
3. **Identify gaps**: unassigned sections, vague assignments ("folded into BRD-X" without explicit rationale), content blocks between section boundaries not captured by any header
4. **Verify 100% coverage** — every source unit must have an explicit BRD home or a deliberate exclusion with rationale
5. **Check for orphan content** — sections with no natural BRD home may indicate missing BRDs in the architecture

This audit must complete and be approved before any BRD extraction begins. The output is a table in the planning roadmap showing source section → BRD mapping with line spans.

### UCX Governance Compliance

This phase implements the UCX `DEVELOPMENT_WORKFLOW_GUIDE.md` §2 "Planning-First Requirement":
> Before implementation starts, complete this sequence: create planning roadmap → create planning index → define changelog plan → run planning gap review → create and approve IPLAN.

Reference: `governance/templates/PROJECT_KICKOFF_PLAN-TEMPLATE.md` for project-level planning structure.

---

### Batch ADR Generation from BDD

For the complete ADR generation pipeline across 19 documents (9 engine + 10 cross-cutting), see `references/adr-generation-from-bdd.md`. This reference captures:

- Pre-generation checklist (hash fixes, validation verification)
- Subagent timeout workaround (pre-extract upstream data, direct write_file, retry-on-timeout pattern)