Implementation Mapping

This document maps the (12 logical stages, Part B contracts) to the current eve-based runtime in this repository (11 stage-gated execution steps).

For the high-level public specification, see .

Summary

LLM spec	Runtime	Notes
12 logical stages (B.4)	11 runtime stages	Spec stages 1–2 combine into runtime `research`
Parallel stages 4 & 5 from 3	Sequential `assumptions` then `hmw`	Runtime runs both after `problems`; order is linear
Parallel stages 8 & 9 from 7	Sequential `content` then `ux`	Runtime runs both after `stories`; order is linear
ProblemAgent (stages 3–5)	`problems`, `assumptions`, `hmw` subagents	Logical agent split across three eve subagents
GovernanceAgent (cross-cutting)	Root orchestrator	Not a declared subagent
PrototypeAgent (stage 12)	Built-in `agent` tool	Declared `prototype` subagent exists but root uses built-in tool
B.2 Metadata / B.6 assertions	Partial	Enforced via prompts and conversational gates; not yet full structured schema

Stage mapping

Spec stage	Spec name	Agent (B.5)	Runtime key	Subagent / tool	Output
1	Research Analysis	ResearchAgent	`research`	`research`	`01-research.md`
2	Insight Generation	ResearchAgent	`research` (combined)	`research`	`01-research.md`
3	Problem Definition	ProblemAgent	`problems`	`problems`	`02-problems.md`
4	Assumption Mapping	ProblemAgent	`assumptions`	`assumptions`	`03-assumptions.md`
5	How Might We	ProblemAgent	`hmw`	`hmw`	`04-hmw.md`
6	Hypothesis Creation	HypothesisAgent	`hypotheses`	`hypotheses`	`05-hypotheses.md`
7	User Story Generation	StoryAgent	`stories`	`stories`	`06-stories.md`
8	UX Content	ContentAgent	`content`	`content`	`07-content.md`
9	User Journeys	JourneyAgent	`ux`	`ux`	`08-ux.md`
10	UI Planning	DesignAgent	`ui`	`ui`	`09-ui.md`
11	Design System Mapping	DesignSystemAgent	`designsystem`	`designsystem`	`10-designsystem.md`
12	Prototype Generation	PrototypeAgent	prototype	built-in `agent` tool	`outputs/<run-id>/prototype/`

Research stages 1–2

The LLM spec keeps Research Analysis (what is in the evidence) and Insight Generation (what it means) as separate governed steps. The runtime research subagent produces both in one artefact (01-research.md). The public site merges them into a single "Research synthesis" skill — do not assert a fixed skill count in user-facing copy.

Parallel branches (spec vs runtime)

The LLM spec defines:

Stages 4 and 5 as parallel branches from Stage 3 (requires_approved: [3])
Stages 8 and 9 as parallel branches from Stage 7 (requires_approved: [7])

The runtime executes these as sequential gated steps (assumptions → hmw, content → ux). Both branches still run; order is fixed for simplicity.

Agent registry mapping (B.5)

Spec agent	Stages	Runtime implementation
ResearchAgent	1, 2	`agent/subagents/research/`
ProblemAgent	3, 4, 5	`problems/`, `assumptions/`, `hmw/`
HypothesisAgent	6	`agent/subagents/hypotheses/`
StoryAgent	7	`agent/subagents/stories/`
ContentAgent	8	`agent/subagents/content/`
JourneyAgent	9	`agent/subagents/ux/`
DesignAgent	10	`agent/subagents/ui/`
DesignSystemAgent	11	`agent/subagents/designsystem/`
PrototypeAgent	12	Built-in `agent` tool
GovernanceAgent	all	Root orchestrator

Governance implementation (B.3)

Spec capability	Runtime location
State machine (`draft` → `review` → `approved` / `rejected`)	Conversational gate via `ask_question`; Markdown artefacts do not yet carry B.2 Metadata blocks
Approval before progression	`agent/instructions.md` — stage-gate rule
Audit trail	Markdown artefacts in `outputs/<run-id>/` with evidence citations
Traceability (B.1)	Subagent instructions require citing upstream artefacts and source quotes
GlobalRules (B.6)	Enforced in prompts; future: validate in `agent/lib/pipeline-artefact.ts`

Code references

Concern	File
LLM Operating Spec (canonical)	`spec/ucdops-agent-llm-spec-v1.0.md`
Drop-in system prompt (Part A)	`spec/llm/08-system-prompt.md`
Schema appendix (Part B)	`spec/llm/09-schema-appendix.md`
Root orchestrator prompt	`agent/instructions.md`
Stage → filename map	`agent/lib/outputs.ts`
Artefact schemas and recovery	`agent/lib/pipeline-artefact.ts`
Subagent persistence hook	`agent/hooks/persist-subagent-artefacts.ts`
Per-stage LLM prompts	`agent/subagents/*/instructions.md`

Known deltas

Structured metadata — B.2 Metadata and B.1 TraceabilityChain are normative in the LLM spec but not yet emitted as structured fields in runtime Markdown artefacts.
Stage count — Public marketing avoids fixed skill counts; the LLM spec defines 12 logical stages; runtime executes 11 gated steps.
Prototype path — Root instructions use the built-in agent tool, not the declared prototype subagent.
Subagent sandboxes — Stages 1–10 use isolated sandboxes with hook-based persistence to the parent sandbox.
Naming — Subagent keys differ from documentation and information slugs. See lib/documentation.ts and lib/information.ts.

Stage count policy

The skill set grows over time. Public surfaces present a curated subset under phase names (Discovery, Definition, Delivery, Prototype) and must not assert a fixed total skill count. When changing the pipeline, update the LLM spec, this mapping, agent/instructions.md, and affected subagent instructions together. *