ucx-sdd-bridge

name: ucx-sdd-bridge description: | Bridge Hermes conversational reasoning with UCX deterministic SDD tools. Enforces safe SDD workflow: UCX validates structurally, Hermes reviews interactively, human or LLM-as-judge approvers validate policy-gated outcomes. version: 1.3.0 category: spec-driven-development author: UCX Framework Team requires: []

UCX SDD Bridge Skill

Changelog

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:

Dangerous Patterns (Never Do)

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.md`, `executor=api/openrouter`
UCX: Assembles review prompt and runs configured API executor
Hermes: Loads `qa_lead` and `auditor` persona guidance
Hermes: Uses `prompt_text` and executor output as review evidence
Hermes: Presents structured findings and governance recommendation to human

Stage 5: Remediate (Policy-Gated Apply)

Human: "Fix the issues found"
Hermes: Call sdd_remediate with `doc_type=brd`, `layer=01_BRD`, `document=BEE-001.md`, `executor=api/claude-sonnet`
UCX: Produces deterministic findings/fix artifacts and runs API executor apply stage
Hermes: Presents findings, executor status, and recommended actions
Approver: Approves each fix or requests alternative approach (human reviewer or independent LLM-as-judge session)
Hermes: Applies approved edits to document
Hermes: Re-runs sdd_validate to confirm fixes

Stage 6: Advance to Next Layer

Human: "Advance to PRD"
Hermes: Call sdd_next_action on document folder
UCX: Returns current_stage="validated", next_action="create", next_tool="sdd_create"
Hermes: Loads PRD template, uses BRD content + project memory to draft PRD
Hermes: Repeats Stage 2-5 for PRD layer

Hermes Memory Conventions

When working with UCX projects, save to session memory:

Project: BeeLocal
Root: /opt/data/b-local/b-local-telegram-ui
Active document: BEE-001
Current stage: BRD validation
Last validation: 2026-05-02 (3 errors, 1 warning)
Pending: Approver decision for remediation (human reviewer or independent LLM-as-judge session)

This allows Hermes to maintain continuity across the multi-turn SDD workflow that UCX's stateless tools cannot provide.

Tool Calling Rules

1. Use API executors for LLM stages (sdd_review, sdd_remediate), and avoid CLI executor names
2. Always call sdd_validate before advancing stage — structural gate
3. Always enforce planning-first approval before create/test/code work
4. Always present validation reports to the approver authority — do not auto-remediate
5. Use sdd_next_action to confirm stage state — avoid assumptions
6. Save project state to Hermes memory after each significant action

Known-Good Executor Policy

Use an explicit executor policy so review/remediation behavior is deterministic across environments.

Example policy:

review:
  mode: prompt_only
  executor: api/openrouter
remediate:
  executor: api/claude-sonnet
fallback:
  unknown_executor: fail_fast

Operational guidance:

• Set executor explicitly on sdd_review and sdd_remediate calls.
• Keep sdd_validate and sdd_create_build executor-free.
• Use project overrides in UCX/executors.json only for API executors.
• Treat unknown executor names as blocking configuration errors.

Fan-Out/Fan-In Review Guidance

Use review_mode=saga_parallel for multi-persona fan-out/fan-in when persona count or context size makes sequential review costly.

Invocation pattern (MCP tool arguments, not CLI command):

sdd_review:
  doc_type: brd
  document: BEE-001.md
  review_mode: saga_parallel
  executor: api/openrouter
  max_parallel_branches: 4
  branch_timeout_seconds: 120
  max_branch_retries: 1
  retry_backoff_seconds: 2
  saga_branch_llm_enabled: true

Expected behavior:

• Runtime fans out persona branches with bounded concurrency and retry controls.
• Runtime performs deterministic reducer merge at fan-in and returns merged findings.
• Hermes reads review_mode, saga_status, review_run_id, and branch/reducer summaries before gate decisions.
• If saga_status=ESCALATED or passed=false, block merge path and escalate per policy.

When to prefer prompt_only:

• Single persona or low-complexity review.
• No need for branch-level telemetry or retry/compensation controls.

Troubleshooting

Integration with Existing Hermes SDD Skills

This skill works with UCX personas and optional Hermes-native skills:

• business-analyst — Use for BRD gap analysis after sdd_validate
• qa_lead persona — Use for testability review after sdd_review evidence is returned
• auditor persona — Use for compliance reasoning after sdd_review evidence
• ucx-kb-context — Use for retrieval enrichment before create/review/remediate calls when a KB server is available
• ucx-kb-maintenance — Use after approved IPLAN implementation evidence to update project knowledge under governance policy
• If Hermes-native skills exist in your environment (sdd-orchestrator, sdd-cross-validation), use them as optional overlays

Error Handling

If UCX returns an error:

1. Log the tool name and arguments to Hermes memory
2. Present the error clearly to the human
3. Do not retry the same call blindly — ask human for direction
4. If sdd_preflight fails, stop and resolve environment issues before proceeding

Migration Notes

This skill targets UCX Hermes runtime (ucx_hermes/) v2.0.0+ with API-only executor support for LLM stages. If migrating from mixed CLI/API runtimes, replace legacy executor names with API executor names and keep deterministic stages executor-free.