| id | finite-ape-machine | |||||
|---|---|---|---|---|---|---|
| title | Finite APE Machine — current technical overview | |||||
| date | 2026-04-22 | |||||
| status | active | |||||
| tags |
|
|||||
| author | descartes |
Finite APE Machine is the engineered realization of the Inquiry methodology as a finite-state, signal-aware control system for software work. Inquiry names the cycle-level process. APE names the orchestrating methodology and scheduler. Finite APE Machine names the technical system that operationalizes that methodology through explicit states, governed transitions, artifacts, and phase-specific agent behavior.
The point of the system is not to multiply agents indefinitely. It is to make responsibility, transition conditions, and outputs explicit enough that AI-assisted work becomes inspectable and reproducible instead of improvisational.
The current operational model is a six-state cycle with an optional evolutionary pass:
IDLE → ANALYZE → PLAN → EXECUTE → END → EVOLUTION → IDLE
If evolution is disabled in .inquiry/config.yaml, the cycle returns directly from END to IDLE after PR creation and merge preparation. [2][5]
| State | Operator | Purpose | Primary artifact |
|---|---|---|---|
| IDLE | DEWEY | Triage, issue readiness, and explicit start handoff | .inquiry/state.yaml |
| ANALYZE | SOCRATES | Clarify the problem and produce a rigorous diagnosis | cleanrooms/<issue>/analyze/diagnosis.md |
| PLAN | DESCARTES | Design the execution sequence and verification strategy | cleanrooms/<issue>/plan.md |
| EXECUTE | ADA | Implement phase by phase under the plan's constraints and coding manifesto | code + commits |
| END | APE + human gate | Create and merge the PR through an explicit closure gate | PR |
| EVOLUTION | DARWIN | Propose improvements to the framework itself | issues/comments in the Inquiry repository |
APE is not a peer agent in the roster. It is the orchestrating methodology and dispatch layer that reads state, checks transition conditions, and invokes the appropriate phase behavior. In current repository vocabulary, this is the scheduler/event-loop role. [2][4][5]
The current system uses one primary sub-agent per active work phase:
- DEWEY in IDLE
- SOCRATES in ANALYZE
- DESCARTES in PLAN
- ADA in EXECUTE
- DARWIN in EVOLUTION
APE still orchestrates every state boundary, and END remains the explicit APE + human closure gate. Earlier expanded rosters are historical context, not the active architectural model.
The machine does not rely on implicit conversational drift to change phases. Transitions are checked against a declared contract and executed through the CLI, which is responsible for validating preconditions, applying effects, and updating persisted state. This makes the finite-state structure operational rather than metaphorical. [2][5]
The sub-agent prompt seen by the operator is not an opaque mixture of YAML prose. Inquiry CLI assembles it explicitly as APE identity from assets/apes/<name>.yaml, phase-owned operational contract from assets/fsm/states/<state>.yaml, and runtime inquiry-context. iq ape prompt prints that exact effective prompt. Standard APE YAMLs stay identity-first; DARWIN is the only bounded exception and keeps only abstract-process methodology while EVOLUTION owns repository procedure. [2][4][5]
The system coordinates through persisted artifacts rather than agent-to-agent hidden memory. At minimum, the cycle relies on:
.inquiry/state.yamlfor current phase and task identity.inquiry/config.yamlfor cycle options such as evolution enablement.inquiry/mutations.mdfor human observations relevant to DARWINcleanrooms/<issue>/analyze/diagnosis.mdas the contract between ANALYZE and PLANcleanrooms/<issue>/plan.mdas the contract between PLAN and EXECUTE
This keeps the orchestration inspectable from the repository itself.
Finite APE Machine borrows the RTOS analogy to explain scheduling, waiting, event signaling, and task dispatch. The analogy is architectural, not literal: the system behaves like a scheduler with event-driven coordination, but it is not an operating-system kernel.
Finite APE Machine structures collaboration across three recurring perspectives:
| Perspective | Acronym | Dominant states | Practical meaning |
|---|---|---|---|
| Agent-Aided Design | AAD | ANALYZE | Human intention is clarified with AI assistance |
| Agent-Aided Engineering | AAE | PLAN | The work is decomposed, verified, and ordered |
| Agent-Aided Manufacturing | AAM | EXECUTE + END | The approved plan is carried into implementation and delivery |
DARWIN operates after delivery as the meta-learning layer that evaluates the cycle itself instead of the product alone.
This document is the primary technical overview of the current finite-state system. Supporting documents elaborate particular aspects of that overview:
- agent-lifecycle.md defines the current agent registry and state responsibilities.
- cooperative-multitasking-model.md explains the scheduler/task analogy and two-level FSM model.
- signal-based-coordination.md explains event and signal routing.
- ../architecture.md explains the end-to-end system at repository scale.
- ../roadmap.md explains where the live system should go next.
Earlier repository documents described a larger and more granular roster including MARCOPOLO, VITRUVIUS, SUNZI, GATSBY, ADA, DIJKSTRA, BORGES, and HERMES as active architectural roles. That material remains historical context, but it should not be read as the current active model of the Finite APE Machine. The current model is the sharper scheduler-plus-phase-agent structure described above.