# 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

```text
                        ┌──────────────────────────────────────────────┐
                        │                  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) |