ucx-sdd-bridge

What this skill does

# UCX SDD Bridge Skill

## Changelog

| Version | Date (EST) | Changes |
|---------|------------|---------|
| 1.3.0 | 2026-05-06 | Aligned to UCX plan taxonomy and required development flow: initialization (`sdd_init`/`sdd_preflight`), planning package review, gap fixing, plan approval, implementation start. |
| 1.2.0 | 2026-05-06 | Added planning-first governance gate: roadmap, planning index, changelog planning, gap review, and per-document IPLAN approval before lifecycle creation. |
| 1.1.2 | 2026-05-05 | Added UCX V3 KB integration guidance and cross-skill references for `ucx-kb-context` and `ucx-kb-maintenance`. |
| 1.1.1 | 2026-05-05 | Added known-good executor policy snippet, executor troubleshooting table, and fan-out/fan-in (`saga_parallel`) operational guidance. |
| 1.1.0 | 2026-05-05 | Updated skill to API-only executor runtime model for LLM stages; removed legacy patched/no-executor guidance. |

## Purpose

This skill makes Hermes the interactive orchestrator for UCX SDD lifecycle
workflows. UCX provides deterministic validation and structural enforcement.
Hermes provides conversational reasoning, memory, and policy-gated decision
support.

## Core Principle

> **UCX enforces lifecycle contracts. Hermes orchestrates. Human or LLM-as-judge approvers validate policy-gated outcomes.**

Planning-first rule:

- Before any layer document creation, Hermes completes planning-first artifacts (layer roadmap, planning index, changelog plan), runs a gap review pass, fixes or explicitly defers gaps, creates required plan artifacts (document-layer IPLAN and/or permanent development plan), and records approval.
- Before BRD `sdd_create_build`, Hermes confirms runtime startup gate: `sdd-lifecycle` is running, and in KB-enabled mode `project-knowledge` is running with `kb_status`/`kb_graph_status` success.
- Environment bootstrap and required framework tool availability are mandatory before any document creation stage starts.
- No document/test/code implementation starts without approved plans.

Use API executors for LLM stages (`sdd_review`, `sdd_remediate`).
Do not use legacy CLI executor names such as `claude`, `codex`, or `gemini`.

## UCX V3 Invocation Boundary

For `framework` document-layer lifecycle work, use UCX MCP tools only.

- Scope: BRD through IPLAN document layers in `framework/`.
- Allowed: `sdd_*` MCP tool calls for create/validate/review/remediate/advance.
- Not allowed for document layers: CLI lifecycle invocation patterns (for example `python -m mcp_server.cli.main validate ...`).
- CLI is allowed only after approved IPLAN for implementation execution tasks (tests, source code changes, and implementation documentation updates).

## UCX KB Integration (Optional)

`ucx_hermes` is the SDD runtime (`sdd-lifecycle`). UCX Knowledge Base (`kb` / `project-knowledge`) is a separate sub-framework.

Use KB as contextual enrichment, not as a replacement for lifecycle gates.

- Source of truth for document-layer progression remains UCX V3 stage artifacts and MCP gate outputs.
- Use KB for retrieval tasks such as prior decisions, glossary reuse, domain constraints, and historical issue context.
- If KB is unavailable, continue with SDD lifecycle flow; do not block BRD->IPLAN progression.
- Treat KB write/update operations as governance-controlled actions, typically after approved implementation evidence.

Recommended Hermes sequence when KB is available:

1. Pre-create context fetch from KB before `sdd_create_build`.
2. Review-time context fetch from KB before `sdd_review` (especially in `saga_parallel`).
3. Post-implementation knowledge update after IPLAN execution evidence is validated.

## Safe UCX Tools (Deterministic)

Call these freely. They are 100% rule-based, no AI delegation:

| Tool | Purpose |
|------|---------|
| `sdd_validate` | Structural validation: sections, tags, IDs, scores, traceability |
| `sdd_validate_chg` | CHG governance: change levels, gate routing, approval reqs |
| `sdd_consistency` | Artifact lineage and stage consistency |
| `sdd_validate_links` | Markdown link existence and anchor resolution |
| `sdd_preflight` | Environment readiness before create/review/remediate |
| `sdd_scan` | Extract category counts from validation/remediation reports |
| `sdd_score_show` | Compute quality score from report |
| `sdd_score_validate` | Pass/fail against threshold |
| `sdd_score_compare` | Delta between baseline and candidate reports |
| `sdd_next_action` | Inspect folder and recommend next lifecycle stage |
| `sdd_run_lifecycle` | Pipeline orchestration (use API executor names for LLM stages) |
| `sdd_clean` | Remove obsolete stage artifacts |
| `sdd_init` | Scaffold UCX assets for a project |
| `sdd_personas_show/set/diff` | Manage persona mappings |
| `sdd_env_show` | List `.env` keys without exposing values |
| `sdd_prescreen` | Identify high-priority remediation candidates |
| `sdd_list_executors` / `sdd_register_executor` | API executor registry management |

## Dangerous Patterns (Never Do)

| Pattern | Why It Is Dangerous | Correct Alternative |
|---------|---------------------|---------------------|
| Pass CLI executor names (for example `executor=claude`) | Unsupported in API-only runtime; returns UnknownExecutor | Use API executor names (`api/claude-sonnet`, `api/openrouter`) |
| Pass `executor` to `sdd_validate` | Unsupported parameter/path | Call `sdd_validate` without executor |
| Omit executor policy for LLM stages | Runtime default may differ from project governance policy | Set `executor` explicitly for `sdd_review` and `sdd_remediate` |
| Treat `sdd_review`/`sdd_remediate` as deterministic-only | Misses API executor output and stage status | Capture both deterministic artifacts and executor result fields |
| Auto-run full pipeline without round gates | Can skip human escalation policy at merge decision points | Keep round-based validate/review/remediate gates with escalation checks |

## Standard SDD Workflow with Hermes + UCX

### Stage 0: Planning-First Governance Gate

```
Hermes: Analyze provided source information and constraints
Hermes: Create layer roadmap + planning index + changelog plan
Hermes: Review planning artifacts for dependency and traceability gaps
Hermes: Resolve gaps or record explicit deferrals with rationale
Hermes: Create required plan artifacts (document-layer IPLAN and/or permanent development plan)
Hermes: Review plan artifacts for acceptance-criteria mapping completeness
Hermes: Block lifecycle creation until planning approval exists
```

### Stage 1: Scaffold

```
Hermes: Confirm runtime startup gate before BRD creation (`sdd-lifecycle`, optional `project-knowledge`)
Hermes: Call sdd_init for project /opt/data/b-local/b-local-telegram-ui
UCX: Creates UCX/ directory with templates, personas, schemas
Hermes: Confirm scaffold created, show persona mappings
Hermes: Run sdd_preflight and proceed only when readiness criteria are met
```

### Stage 2: Create Document (Policy-Gated)

```
Human: "Draft a BRD for BEE-001"
Hermes: Call sdd_create_build to see the creation prompt and template
UCX: Returns prompt_text, template, inspection metadata
Hermes: Uses prompt_text + project context + memory to draft BRD sections
Hermes: Writes draft to framework/01_BRD/BEE-001.md
Hermes: Call sdd_validate on the draft
UCX: Returns errors/warnings/passes (deterministic)
Hermes: Present findings; route to approver (human reviewer or independent LLM-as-judge session) for approve/revise decision
```

### Stage 3: Validate (Deterministic Gate)

```
Human: "Validate this BRD"
Hermes: Call sdd_validate with `doc_type=brd`, `layer=01_BRD`, `document=BEE-001.md`
UCX: Runs cross_section, brd_rules, template checks
UCX: Returns structured report with errors/warnings/passes
Hermes: Interpret report for human. If errors → revise. If clean → proceed.
```

### Stage 4: Review (Hermes + API Executor)

```
Human: "Review this BRD for testability and security"
Hermes: Call sdd_review with `doc_type=brd`, `document=BEE-001