Workflow Engine

Relevant source files

The following files were used as context for generating this wiki page:

• internal/engine/workflow/engine.go
• internal/engine/workflow/initialize.go
• internal/engine/workflow/plan.go
• internal/engine/workflow/plan_chunk.go
• internal/engine/workflow/ship_preflight.go
• internal/engine/workflow/prompts/base.md
• README.md

The Workflow Engine is the core orchestration layer of M31 Autonomous, responsible for managing the end-to-end lifecycle of a software development task. It operates as a terminal-native agent that transitions through a structured seven-phase sequence to ensure code is not just generated, but also planned, verified, and shipped with git-backed persistence.

The engine facilitates a "loop-owning" approach where the AI assistant manages everything from initial goal clarification to final demonstration walkthroughs. It integrates codebase intelligence, model arbitrage, and automated quality gates to maintain high standards for code correctness and project consistency.

Sources: internal/engine/workflow/engine.go:62-90, README.md:27-38

Architecture and Core Components

The engine is built around a WorkflowState that tracks mutable session data, and an Engine struct that handles phase dispatching and subsystem coordination.

Engine Structure

The Engine coordinates several specialized subsystems:

• PhaseCoordinator: Manages pre-phase setup, post-phase metrics, and transition side effects.
• StateMachine: Enforces valid phase transitions and tracks the current state.
• ContextBuilder: Dynamically assembles LLM prompts based on the current phase, project intelligence, and conversation history.
• CostTracker: Monitors token usage and enforces budget limits.

Sources: internal/engine/workflow/engine.go:94-140, internal/engine/workflow/engine.go:285-325

Workflow Phases

The engine operates in seven sequential phases:

Phase	Description
Initialize	Detects project type (Go/Node/Rust/Python), initializes Git, and builds code intelligence indexes.
Discuss	Asks clarifying questions to resolve ambiguities in the user's requirements.
Plan	Generates a structured implementation plan, task list, and architectural decisions.
Execute	Implements tasks sequentially using 18 built-in tools (Bash, Edit, FileWrite, etc.).
Verify	Validates outputs via syntax checks, build tests, and self-healing loops.
Runtime	Manages dev server lifecycles and performs HTTP smoke tests.
Ship	Performs final pre-ship checks, generates changelogs, and archives the session.

Sources: internal/engine/workflow/prompts/base.md:18-30, README.md:104-125

Execution Flow

The workflow engine follows a linear progression but includes sophisticated internal logic for plan refinement and task execution.

Phase Transition Logic

Phase transitions are serialized to prevent race conditions during checkpoint saving. The engine uses a StateMachine to ensure that transitions only occur between valid states (e.g., from Plan to Execute).

Sources: internal/engine/workflow/engine.go:65-67, internal/engine/workflow/engine.go:484-492

Planning and Chunking

For complex goals, the engine employs a "Chunked Planning" strategy to maintain reliability in large-scale changes.

Plan Generation Process

1. Research: Identifies patterns and risks in the codebase.
2. Outline: Generates a high-level structure of "waves."
3. Expansion: Fleshes out each wave into concrete tasks with acceptance criteria.
4. Gates: Runs security, granularity, and gap analysis checks.

Sources: internal/engine/workflow/plan.go:23-56, internal/engine/workflow/plan_chunk.go:10-25

Task Schema

Tasks are generated as structured JSON objects within the Plan phase to facilitate automated execution.

{
  "id": 1,
  "action": "Create",
  "description": "Initialize database schema",
  "dependencies": [],
  "files": ["internal/db/schema.go"],
  "acceptance_criteria": ["gofmt passes", "compiles successfully"]
}

Sources: internal/engine/workflow/plan_chunk.go:28-35, internal/engine/workflow/plan.go:134-142

Verification and Shipping

The engine ensures quality through automated checks before finalizing any session.

Ship Preflight Checklist

Before a final commit, the engine scans touched files for:

• Markers: TODO, FIXME, HACK, BROKEN.
• Debug Statements: console.log, fmt.Println, debugger.
• Secrets: API keys (OpenAI, Stripe), tokens (GitHub, Slack), and AWS keys.

Sources: internal/engine/workflow/ship_preflight.go:20-65

Git Integration

The engine maintains a commit rollback chain. Every task results in an atomic commit, allowing the engine to utilize git bisect to identify and revert offending changes if verification fails.

Sources: README.md:162-164, internal/engine/workflow/initialize.go:64-73

Technical Specifications

Data Structures

type PhaseResult struct {
    Phase               m31types.WorkflowPhase
    Success             bool
    Tasks               []m31types.Task
    Error               string
    Usage               *m31types.Usage
    Cost                float64
    ToolCalls           int
    Commits             []git.CommitInfo
}

Sources: internal/engine/workflow/engine_messages.go:76-96

Execution Control

The engine provides mechanisms to pause, resume, or skip tasks during the execution phase, allowing for human-in-the-loop intervention.

• PauseExecution(): Halts the current task group.
• ResumeExecution(): Restarts execution.
• SkipCurrentTask(taskID): Bypasses a specific task.

Sources: internal/engine/workflow/engine.go:158-198

Summary

The M31 Autonomous Workflow Engine serves as a robust orchestrator that converts user requirements into verified code. By enforcing a strict seven-phase process—supported by codebase intelligence, self-healing loops, and pre-ship safety gates—it ensures that the resulting software is architecturally sound and production-ready.