Workflow System
Relevant source files
The following files were used as context for generating this wiki page:
The Workflow System in MCB (Memory Context Browser) is a Finite State Machine (FSM) based task orchestration framework designed to manage session state, task execution, and high-level project operations. It serves as the backbone for complex multi-step processes such as semantic code search, repository indexing, and architectural validation.
The system is architected to support AI coding agents by providing persistent session tracking, state transitions, and context injection. It integrates deeply with the project management entities to coordinate between different phases of a software development lifecycle, ensuring policy enforcement and consistent task progression.
Sources: README.md:120-123, AGENTS.md:143-145, crates/mcb-domain/src/entities/workflow.rs
Core Architecture and State Management
The workflow system operates through a structured state machine where WorkflowSession objects track the current status of a task. Progression through a workflow is handled via Transition entities that respond to specific TransitionTrigger events and optional TransitionInput.
Workflow Components
The system defines several key data structures to manage the lifecycle of a process:
| Component | Description |
|---|---|
WorkflowSession | Represents an active instance of a workflow, containing current state and metadata. |
WorkflowState | Defines the specific status of a session (e.g., Idle, Running, Complete). |
Transition | Encapsulates the logic and path for moving from one state to another. |
TransitionTrigger | The event or condition that initiates a state change. |
Sources: crates/mcb-domain/src/entities/workflow.rs:10-25, crates/mcb-domain/src/entities/mod.rs:77-80
State Transition Flow
The following diagram illustrates the high-level logic of the Workflow State Machine:
The state machine ensures that tasks move through validated paths, preventing illegal operations like completing a task that hasn't started.
Sources: crates/mcb-domain/src/entities/workflow.rs, tests/e2e/admin-functional.spec.ts:31-33
Project and Task Orchestration
The Workflow System is closely tied to the ProjectHandler, which manages the high-level orchestration of project phases, issues, and decisions. This allows workflows to be contextualized within specific project boundaries.
Project Resource Management
Workflows operate on various project resources to achieve a goal:
- Phases: Distinct stages of a project (e.g., Discovery, Implementation).
- Issues: Specific tasks or bugs that the workflow aims to resolve.
- Decisions: Documented outcomes of workflow steps that affect project direction.
- Dependencies: Requirements that must be met before a workflow state can transition.
Sources: crates/mcb-server/src/handlers/project.rs:46-52, crates/mcb-domain/src/entities/project.rs
Semantic Search Workflow Example
A concrete implementation of the workflow system is found in the semantic code search process, which follows a defined multi-phase pipeline.
This workflow ensures that natural language queries are accurately mapped to code segments through a series of state-managed transitions.
Sources: crates/mcb-domain/tests/integration/semantic_search_workflow.rs:14-60
Implementation and Integration
The system leverages the linkme crate for distributed registry of tools and handlers, allowing the workflow system to remain modular while exposing its capabilities through the Model Context Protocol (MCP).
Tool Registration
Workflow-related operations are exposed as MCP tools. The ProjectHandler routes these calls based on the ProjectAction and ProjectResource provided in the arguments.
| Action | Supported Resources |
|---|---|
Create | Project, Phase, Issue, Dependency, Decision |
List | Project, Phase, Issue, Dependency, Decision |
Get | Project, Phase, Issue, Decision |
Update | Project, Phase, Issue, Decision |
Delete | Project, Phase, Issue, Dependency, Decision |
Sources: crates/mcb-server/src/handlers/project.rs:79-160, README.md:90-100
Session Monitoring
Administrators can monitor the status of workflows through the system's management UI and API endpoints.
/health: Provides system-wide metrics including workflow engine status./jobs: Displays current indexing and task orchestration status, indicating whether the system is idle, running, or has completed recent workflows./config: Shows active providers (embedding, vector store) that workflows utilize.
Sources: tests/e2e/admin-functional.spec.ts:21-50, README.md:95
Conclusion
The MCB Workflow System provides a robust framework for managing complex, asynchronous tasks within a Clean Architecture environment. By utilizing a formal FSM for sessions and integrating with a rich project management domain, it enables AI agents to perform structured operations over codebases with high reliability and persistent state tracking.
Sources: README.md:110-115, AGENTS.md:143-146