AirCoding/AirPlan/docs/architecture/main-agent-state-machine.md

Main Agent State Machine

Date: 2026-05-28 Status: V1.0.0 Alpha canonical state machine

This document defines the Main Agent lifecycle for V1.0.0 Alpha. Event names align with event-registry-v1.md. Permission model aligns with interface-contracts-v1.md permission_template.

States

                        ┌──────────────────────────────────────────────┐
                        │                  IDLE                         │
                        │            Waiting for user input             │
                        └──────┬───────────────────────────────────────┘
                               │ user.message.created
                               ▼
                        ┌──────────────────────────────────────────────┐
                        │              CLASSIFYING                      │
                        │       LLM classifies intent                  │
                        └──┬──────────────────┬───────────────────────┘
                           │                  │
              Chat/Q&A     │    Task request   │ /direct command
                           ▼                  ▼                ▼
                    ┌──────────┐    ┌──────────────────┐  ┌──────────────┐
                    │ANSWERING │    │   DELEGATING     │  │ DIRECT_MODE  │
                    │ Direct   │    │ Needs arch check?│  │ Main Agent   │
                    │ reply    │    └──┬───────────┬───┘  │ with executor│
                    │ → IDLE   │       │           │      │ permissions  │
                    └──────────┘  Simple│      Needs│      │ /done → IDLE │
                                  skip  │      plan │      └──────────────┘
                                  plan  │           │
                                  →     ▼           ▼
                              Scheduler┌──────────┐ ┌──────────────────────┐
                                       │SCHEDULING│ │ARCHITECTURE_DESIGNING│
                                       │Create    │ │ Architecture         │
                                       │tasks     │ │ Designer assesses    │
                                       │→ AWAITING│ │ impact               │
                                       └──────────┘ └──────┬───────────────┘
                                                           │ architecture.plan.updated
                                                           ▼
                                                  ┌──────────────────┐
                                                  │   CONFIRMING     │
                                                  │ Present plan to  │
                                                  │ user, await      │
                                                  │ confirm/modify/  │
                                                  │ reject           │
                                                  └──┬───┬───┬──────┘
                                                     │   │   │
                                            Confirm  │   │Mod│  Reject
                                                     ▼   │   │  → IDLE
                                              ┌──────────┐│
                                              │EXECUTING ││
                                              │ Scheduler││
                                              │ monitors ││
                                              │ progress ││
                                              └──┬───┬───┘│
                                                 │   │    │
                            task.progress event  │   │    │
                            → summarize to user  │   │    │
                                                 │   │    │
                            ┌────────────────────┘   │    │
                            │ User requirement change │    │
                            ▼                        │    │
                     ┌──────────────┐                │    │
                     │ INTERRUPTING │                │    │
                     │ Classify     │                │    │
                     │ change level:│                │    │
                     │ execution    │                │    │
                     │ → notify     │                │    │
                     │   Scheduler  │                │    │
                     │ design/      │                │    │
                     │ interface    │                │    │
                     │ → Arch       │                │    │
                     │   Designer   │                │    │
                     │   full       │                │    │
                     │   assessment │                │    │
                     └──┬───────┬───┘                │
                        │       │                    │
                Execution│  Design level             │
                → resume │       ▼                    │
                EXECUTING│  ┌──────────────┐         │
                         │  │ARCHITECTURE  │         │
                         │  │ REVISING     │         │
                         │  │ Update plan  │         │
                         │  │ → CONFIRMING │         │
                         │  └──────────────┘         │
                         │                           │
                         ▼                           ▼
                 ┌──────────────────────────────────────┐
                 │            SUMMARIZING                │
                 │  All tasks complete, summarize to user│
                 │  Trigger ExperienceMiner              │
                 │  → IDLE                              │
                 └──────────────────────────────────────┘

Events (from event-registry-v1.md)

Event	Emitter	Consumer	Notes
user.message.created	TUI/CLI	Main Agent	User input
requirement.changed	Main Agent	Scheduler, Architecture Designer	When user changes scope mid-execution
architecture.plan.updated	Architecture Designer	Main Agent	Plan produced or revised
architecture.impact.completed	Architecture Designer	Main Agent	Impact assessment done
task.created	Scheduler	Main Agent	Tasks created from plan
task.progress	Scheduler/workers	Main Agent	Progress update
task.completed	Scheduler	Main Agent	Task done
task.failed	Scheduler	Main Agent	Task failed
task.blocked	Scheduler	Main Agent	Task blocked
permission.prompt.requested	PermissionEngine	Main Agent/TUI	Needs user decision
permission.prompt.resolved	TUI	PermissionEngine	User decided

Key Internal Events

Event	Meaning
IntentClassified	Main Agent internal: chat vs task vs direct
DirectModeEntered	Main Agent entered /direct mode
DirectModeExited	Main Agent exited /done mode

Confirmation Gating

Change Level	Action
Implementation (no interface/architecture impact)	Silent → EXECUTING
Architecture (interface/constraint/design change)	Architecture Designer assessment → low-permission: user confirm; high-permission: auto-proceed, results displayed

Main Agent Idle Principle

Main Agent must remain idle and responsive. Background tasks (ExperienceMiner, DebugKnowledge indexing) are dispatched to sub-agents via Scheduler, never run on Main Agent's thread/loop.

Direct Mode Rules

1. /direct enters DIRECT_MODE with permission_template: "main_direct".
2. In DIRECT_MODE, Main Agent executes directly without Scheduler dispatch.
3. Main Agent uses Executor-level permissions but remains user-facing.
4. /done exits DIRECT_MODE, triggers evidence collection, returns to IDLE.
5. DIRECT_MODE does not block Scheduler-owned background tasks.
6. All DIRECT_MODE actions are logged with source.kind = "main".

State-to-AgentRuntimeContext Mapping

State	permission_template
IDLE, CLASSIFYING, ANSWERING, CONFIRMING, SUMMARIZING	N/A (no task execution)
DIRECT_MODE	main_direct
EXECUTING	Determined by Scheduler per task
INTERRUPTING, ARCHITECTURE_REVISING	N/A (delegation only)