82f3140847
Complete architecture document set with multi-model review remediation: - Frozen interface contracts, runtime semantics, DB schemas - Event/tool/error/provider registries - Scheduler and main agent state machines - C4 module/code views, solution architecture, baseline V1 - Multi-model review reports and joint assessment - Phase-gate remediation complete (P0/P1/P2/UX resolved) - Implementation plan with T-000A through T-045 - Reference folders kept as placeholders only
9.5 KiB
9.5 KiB
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
/directenters DIRECT_MODE withpermission_template: "main_direct".- In DIRECT_MODE, Main Agent executes directly without Scheduler dispatch.
- Main Agent uses Executor-level permissions but remains user-facing.
/doneexits DIRECT_MODE, triggers evidence collection, returns to IDLE.- DIRECT_MODE does not block Scheduler-owned background tasks.
- 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) |