Task Execution Engine

Relevant source files

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

• internal/engine/workflow/execute.go
• internal/engine/workflow/prompts/execute-task.md
• internal/engine/workflow/prompts/base.md
• internal/engine/workflow/prompts/tool-use.md
• internal/engine/workflow/prompts/plan-format.md
• internal/engine/workflow/plan.go

The Task Execution Engine is the core component of the M31A autonomous agent responsible for implementing the implementation plan generated during the Plan Phase. It operates primarily in the Execute phase of the seven-phase workflow, where it orchestrates the sequential or parallel implementation of tasks using a suite of specialized tools.

The engine manages task dependencies, tool dispatching, and a robust self-healing mechanism to recover from implementation failures. It ensures that every code change is intentional, verified against acceptance criteria, and atomically committed to the project's version control system.

Sources: internal/engine/workflow/prompts/base.md:14-22, internal/engine/workflow/execute.go:21-30

Architecture and Core Logic

The execution engine follows a topological execution order, ensuring that tasks are only started once their dependencies have successfully completed. It utilizes a taskrunner to schedule and execute groups of tasks, while the Engine provides the high-level orchestration, including context building and tool dispatching.

Execution Workflow

1. Task Loading: Retrieves the structured task list from the session manager.
2. Scheduling: Uses Kahn's algorithm to sort tasks by dependency depth.
3. Parallel Dispatch: Executes independent tasks in groups, adhering to a configurable MaxParallelTasks limit.
4. Tool Execution: For each task, the engine builds a context and interacts with an LLM to generate tool calls (e.g., FileWrite, Edit, Bash).
5. Quality Gates: Validates task output against predefined acceptance criteria before committing.

Sources: internal/engine/workflow/execute.go:34-110, README.md:120-130

Logic Flow Diagram

The following diagram illustrates the lifecycle of a single task within the execution engine.

Task Specification and Data Model

Tasks are defined in the Plan phase as a structured JSON array. Each task represents an atomic unit of work that can ideally be completed in a single LLM call.

Field	Type	Description
id	Integer	Unique sequential identifier starting from 1.
action	String	Type of operation: Create, Add, Modify, Delete.
description	String	Narrative of what the task accomplishes.
dependencies	Array[Int]	IDs of tasks that must complete before this one.
files	Array[String]	File paths the task is expected to create or modify.
acceptance_criteria	Array[String]	Conditions used for verification (e.g., "npm test succeeds").

Sources: internal/engine/workflow/prompts/plan-format.md:65-90, internal/engine/workflow/execute.go:42-55

Tool Dispatching and Interaction

The engine communicates with the filesystem and external environments through a Dispatcher. Before any tool call, the agent is required to produce a "pre-flight" reasoning block to ensure deterministic tool usage.

Primary Tools

• FileWrite/Edit: Atomically creates or modifies files. Edit is preferred for modifications to preserve existing content.
• Bash: Runs shell commands for building, testing, or git operations.
• FileRead/Grep/Glob: Used to discover and understand project structure before writing.
• TodoWrite: Synchronizes a structured TODO.md to track progress.

Sources: internal/engine/workflow/prompts/base.md:58-75, internal/engine/workflow/prompts/tool-use.md:10-45

Tool Execution Sequence

This sequence diagram shows the interaction between the Engine, the Dispatcher, and the LLM.

Self-Healing Mechanism

M31A implements a "Self-Heal" loop to handle errors such as LLM parsing failures, tool errors (e.g., a failing test in Bash), or quality gate rejections.

• Trigger: A tool returns an error or a quality gate fails.
• Context Injection: The engine captures the failure reason, current file states, and git diffs.
• Retry: The agent attempts a "heal" using a fresh LLM call with the error context.
• Budget: A task can be healed up to a maximum defined by MaxHealAttempts (default is 3).

Sources: internal/engine/workflow/execute.go:235-300, internal/engine/workflow/prompts/execute-task.md:75-85

Verification and Quality Gates

The ExecuteQualityGate is an optional feature that runs after task completion. It checks the task results against the acceptance_criteria. If the gate fails, the engine triggers the self-heal loop rather than committing the changes.

Pre-Write Checklist

The engine enforces a "Read-Before-Write" rule. The agent must:

1. Read the target file and its direct imports.
2. Identify exact type signatures for called functions.
3. Confirm consistency with existing project patterns.

Sources: internal/engine/workflow/prompts/base.md:44-55, internal/engine/workflow/execute.go:485-510

Summary

The Task Execution Engine provides the operational backbone for M31A, transforming high-level plans into verified code changes. By combining dependency-aware scheduling, a strictly gated tool dispatcher, and a self-healing implementation loop, the engine ensures that autonomous actions are both safe and accurate.