/eshanized/M31A

Wiki directory

Browse AI-generated documentation for any repository.

Overview

Relevant source files

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

M31 Autonomous (M31A) is a terminal-native AI coding agent designed to handle the end-to-end software development lifecycle. Unlike traditional autocomplete assistants, M31A operates through a structured seven-phase workflow, utilizing a suite of 18 built-in tools to interact directly with the filesystem, shell, and external resources. It prioritizes code correctness through strict "Read-Before-Write" rules and a comprehensive verification system.

Sources: README.md:12-25, internal/engine/workflow/prompts/base.md:7-12

Core Workflow Architecture

The system operates on a sequential pipeline of seven phases, ensuring that every task is properly initialized, planned, executed, and verified before being committed to the version control system.

The Seven-Phase Pipeline

Initialize: Detects the project type (e.g., Go, Node, Rust, Python) and builds a code intelligence index including import graphs and symbol lookups.
Discuss: Facilitates understanding requirements through clarifying questions within the TUI.
Plan: Generates a detailed implementation plan featuring file predictions, task lists, and dependency mapping.
Execute: Performs the actual coding using 18 specialized tools, following a topological sort to handle task dependencies.
Verify: Validates the output by running build commands and test suites, with a self-healing mechanism for automatic fixes.
Runtime: Manages the development server lifecycle and performs HTTP smoke tests.
Ship: Finalizes the session by generating walkthroughs, updating the ledger, and performing the final git commit.

Sources: README.md:104-142, internal/engine/workflow/prompts/base.md:14-23

Workflow Flow Diagram

This diagram illustrates the transition between phases and the integration of quality gates.

Generating architecture diagram...

Sources: README.md:88-102, internal/engine/workflow/plan.go:53-150

Code Intelligence and Context Awareness

M31A utilizes a codeintel package to build a mental model of the codebase. This system parses source files (supporting Go, TypeScript, Python, and Rust) to create an import graph and symbol index.

Technical Components of CodeIntel

Indexer: The central orchestrator for codebase parsing and relevance scoring.
ImportGraph: Tracks upstream and downstream dependencies between files.
SymbolIndex: Maps symbols to their definitions and locations.
RelevanceScorer: Ranks files based on their relationship to the current task and target files.

Sources: internal/integrations/codeintel/codeintel.go:17-30, README.md:145-150

Read-Before-Write Rule

A critical principle of M31A is the "Read-Before-Write" rule. Before any modification, the agent must read:

The target file in its entirety.
All imported files (types, interfaces, constants).
All files that depend on the target (callers, consumers).
Configuration files governing the target's behavior.

Sources: internal/engine/workflow/prompts/base.md:33-51, internal/engine/workflow/prompts/context-awareness.md:10-25

Planning and Execution

The transition from planning to execution is governed by a structured Plan format and a task runner that implements Kahn's algorithm for topological sorting.

Implementation Plan Structure

A plan generated by M31A must contain specific sections to be valid:

Section	Purpose
Summary	High-level narrative of the approach and tech choices.
Proposed Changes	Categorized list of files marked as `[NEW]` or `[MODIFY]`.
Task List	A JSON array of tasks with IDs, actions, and dependencies.
Verification Plan	Both automated (build/test) and manual validation steps.

Sources: internal/engine/workflow/prompts/plan-format.md:14-75, internal/engine/workflow/plan.go:210-230

Execution Logic

Execution follows a strict process to maintain stability:

Topological Sort: Tasks are executed in an order that satisfies all dependencies.
Tool Usage: Employs tools like Edit for targeted string/line-range replacement and FileWrite for new files.
Atomic Commits: Every successful task results in exactly one git commit.

Sources: internal/engine/workflow/prompts/execute-task.md:19-45, internal/engine/workflow/prompts/tool-use.md:31-50

Tooling System

M31A provides 18 built-in tools, gated by a permission system that requires user approval for dangerous operations.

Key Tools and Descriptions

Tool	Primary Function
`Bash`	Executes shell commands (builds, tests, git ops).
`FileRead`	Reads file content up to a 5MB limit.
`Edit`	Performs targeted replacements using exact, trimmed, or fuzzy matching.
`FileWrite`	Writes complete files atomically via temporary files.
`Glob` / `Grep`	High-performance filesystem searching and content matching.
`WebFetch`	Retrieves external documentation or API references.

Sources: internal/engine/workflow/prompts/tool-use.md:7-90, README.md:162-171

Safety and Privacy Features

The system is designed with a "zero telemetry" philosophy and multiple layers of security:

Commit Rollback Chain: Every task-level commit can be rolled back; git bisect is integrated to find breaking changes.
OS Keychain Integration: API keys for providers (OpenRouter, Zen, Nvidia) are stored in the OS-native keychain (e.g., macOS Keychain, Windows Credential Manager) rather than plaintext files.
SSRF Protection: WebFetch blocks private, loopback, and link-local IP addresses.
Permission Modals: Bash commands are individually gated with "Allow", "Allow Always", or "Deny" options.

Sources: README.md:200-220, README.md:345-365

Conclusion

M31 Autonomous provides a highly structured environment for AI-driven development. By enforcing a strict seven-phase workflow and a "read-before-write" context gathering phase, it minimizes the risk of broken imports and inconsistent naming common in simpler AI coding assistants. Its reliance on a local static binary and OS keychain ensures privacy and security for professional development environments.