Workflow Engine

The workflow engine is the orchestration hub for multi-step design and implementation workflows. It powers both the MCP advance tool and trurlic design sessions.

The advance loop

Every interaction follows the same pattern:

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

advance() is a pure function — it computes the next step from the current graph state without any side effects. Same inputs always produce the same output.

Task types

`new_component`

Full design workflow for a new component. Steps: define_scope → cover_concerns → pattern_detection → summary_gate → ready.

The developer defines the component’s scope, answers concern questions, reviews detected patterns, and confirms the summary before implementation begins. Multiple steps are gated (require human input).

`feature`

Add functionality to an existing component. Steps: verify_constraints → cover_concerns → pattern_detection → summary_gate → ready.

Starts by verifying that existing decisions still hold for the new feature, then addresses any uncovered concern areas relevant to the task. When a task description is provided, concern coverage is focused on task-relevant gaps via keyword matching.

`fix`

Apply a bugfix within existing constraints. Steps: verify_constraints → [cover_concerns] → impact_check → ready.

Checks that the fix respects existing decisions. The cover_concerns step fires conditionally — only when the component has zero decisions and the task description touches an uncovered concern area, preventing unguarded fixes in areas that have never been designed. impact_check assesses cross-component effects when the component has connections.

`learn`

Study existing decisions before implementing. Steps: user_explains → analyze_code → walk_decisions → summary_gate → ready.

The user first describes the component from memory, then the agent reads source code, reviews decisions, and the user confirms comprehension via the summary gate.

`review`

Challenge decisions for drift or staleness. Steps: walk_decisions → drift_check → coverage_audit → pattern_detection → summary_gate → ready.

Interactive workflow for re-examining whether existing decisions still hold. Stale decisions are flagged during drift check, coverage gaps are audited, patterns are reassessed, and the user confirms findings.

`harden`

Strengthen coverage for uncovered concern areas. Steps: coverage_audit → cover_concerns → pattern_detection → ready.

Identifies gaps in concern coverage, guides the developer through addressing them, and detects patterns in the newly recorded decisions.

`bootstrap`

Autonomous project scan from source code. Steps: scan_project → extract_decisions → project_rules → pattern_detection → ready.

Fully autonomous — no gated steps. The agent reads source code and records what it finds. All decisions attributed as agent.

Task type inference

If task_type is omitted from an advance call, the workflow engine infers it from the graph state:

Component has no decisions → new_component
Component has decisions → feature (default for existing components)

Explicit task_type always overrides inference.

Gated steps

Steps marked requires_user_input: true are gated. The agent must present the step’s prompt to the user, collect a meaningful response (minimum 20 bytes), and pass it back as step_evidence. This is how Trurlic enforces human authorship of architectural decisions.

Evidence is passed as a map: { "step_name": "user's response text" }. The workflow engine validates that gated steps have sufficient evidence before progressing.

Gated steps (require human input): define_scope, analyze_code, cover_concerns, walk_decisions, verify_constraints, impact_check, pattern_detection, summary_gate, drift_check, coverage_audit, user_explains.

Ungated steps (autonomous): register, scan_project, extract_decisions, project_rules, ready.

Step prompts

get_step_prompt returns structured prompts for each step, including system instructions, component context, and step-specific focus areas. Prompts are transport-agnostic — the same prompts are consumed by MCP agents and CLI sessions.

The INTERACTION_PROTOCOL is embedded in every interactive step prompt, instructing the agent on how to facilitate the Socratic conversation.

All workflow steps

Step	Gated	Description
`register`	No	Register a new component in the graph
`define_scope`	Yes	Define what the component is responsible for
`analyze_code`	Yes	Read existing source code for context
`cover_concerns`	Yes	Address uncovered architectural concern areas
`walk_decisions`	Yes	Review existing decisions for a component
`verify_constraints`	Yes	Confirm decisions are consistent with each other
`impact_check`	Yes	Assess impact of changes on connected components
`pattern_detection`	Yes	Identify cross-cutting patterns across decisions
`summary_gate`	Yes	Human confirms the design summary before proceeding
`drift_check`	Yes	Challenge decisions that may be stale or outdated
`coverage_audit`	Yes	Audit which concern areas lack decisions
`scan_project`	No	Scan source code for architectural components
`extract_decisions`	No	Extract decisions from source code analysis
`project_rules`	No	Define project-wide inviolable rules
`user_explains`	Yes	User provides task context or explanation
`ready`	No	Workflow complete — implementation can proceed

Concern tracking

The workflow engine tracks ten architectural concern areas with keyword matching against decision content. During cover_concerns steps, uncovered concerns are surfaced in priority order. The engine determines which concerns are addressed by existing decisions and which need attention.

When a task description is provided (e.g. --task "add caching"), the cover_concerns step filters to concerns whose keywords match the task, focusing the conversation on what’s relevant instead of walking all gaps.