Workflow Engine

The workflow engine is the orchestration hub. It powers the MCP advance tool: given the graph and a task, it computes the next step. It never calls an LLM and never writes — advance() is a pure function of graph state plus inputs, so the same inputs always produce the same step.

The advance loop

1. advance(component, task_type, mode) → { step, action, requires_user_input, ready }
2. Perform the action (get_step_prompt, add_component, record_decision, …)
3. If requires_user_input: present the prompt, collect the user's response
4. advance again, passing step_evidence
5. Repeat until ready: true
6. get_context → implement, constrained by the brief

If task_type is omitted, the engine infers it from graph state (empty component → new_component/learn/bootstrap by mode; existing component → feature). An explicit task_type always wins. Two combinations are pinned: learn requires interactive mode, bootstrap requires agent mode.

Task types

Each task type walks its own step sequence. The engine picks the next step by checking postconditions against the graph, so it can’t skip ahead.

Task type	Step sequence (happy path)
`new_component`	`register` → `define_scope` → `cover_concerns` → `pattern_detection` → `design_check` → `ready`
`feature`	`verify_constraints` → `cover_concerns` → `pattern_detection` → `design_check` → `ready`
`fix`	`verify_constraints` → [`cover_concerns`] → `impact_check` → `ready`
`learn`	`warm_up` → `analyze_code` → `walk_decisions` → `design_check` → `ready`
`review`	`walk_decisions` → `drift_check` → `coverage_audit` → `pattern_detection` → `design_check` → `ready`
`harden`	`coverage_audit` → `cover_concerns` → `pattern_detection` → `ready`
`bootstrap`	`scan_project` → `extract_decisions`* → `project_rules` → `pattern_detection` → `ready`

Steps in [brackets] are conditional (e.g. fix runs cover_concerns only when the component has no decisions and the task touches an uncovered concern). extract_decisions* repeats once per discovered component. impact_check only fires when the component has connections.

Gated steps

A gated step returns requires_user_input: true. The agent must present its prompt, collect a real response (at least 20 bytes), and pass it back as step_evidence — a map of { "step_name": "user's response" }. The engine refuses to advance past a gated step without sufficient evidence. This is how human authorship is enforced: the agent facilitates, the human decides.

Ungated (autonomous): register, scan_project, extract_decisions, project_rules, ready. Gated (need evidence): everything else.

The 16 steps

Step	Gated	Purpose
`register`	No	Create the component node in the graph
`define_scope`	Yes	Define what the component is responsible for
`analyze_code`	Yes	Read existing source for context
`cover_concerns`	Yes	Address uncovered architectural concern areas
`walk_decisions`	Yes	Review a component’s existing decisions
`verify_constraints`	Yes	Confirm existing decisions still hold for the task
`impact_check`	Yes	Assess effects on connected components
`pattern_detection`	Yes	Identify cross-cutting patterns across decisions
`design_check`	Yes	Practical comprehension check before proceeding
`drift_check`	Yes	Challenge decisions that may be stale
`coverage_audit`	Yes	Audit which concern areas lack decisions
`scan_project`	No	Bootstrap: scan structure, identify components
`extract_decisions`	No	Bootstrap: extract decisions from a component’s code
`project_rules`	No	Bootstrap: record project-wide rules
`warm_up`	Yes	Learn: opener that surfaces the user’s mental model
`ready`	No	Complete — switch to `get_context` and implement

The step names summary_gate and user_explains are accepted as legacy aliases for design_check and warm_up. Use the canonical names.

Step prompts

get_step_prompt returns a transport-agnostic prompt for a step — system instructions, component context, and step-specific focus. In interactive mode the prompt carries the interaction protocol that tells the agent how to facilitate the Socratic conversation. In agent mode the prompts drive autonomous analysis. See Design Conversations and Bootstrap for the two modes in action.

Concern tracking

The engine tracks ten concern areas (security, error handling, concurrency, integrity, performance, external interfaces, storage, serialization, dependencies, migration), matching each against decision content by keyword. During cover_concerns and coverage_audit, uncovered concerns surface in priority order — security before style. When a task description is supplied, coverage is filtered to task-relevant gaps instead of walking every one.