admin/AirCoding
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Initial commit: AirCoding V1.0.0 Alpha architecture baseline

Browse Source 
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
This commit is contained in:
AirCoding
2026-05-28 18:45:01 +08:00
commit 82f3140847
366 changed files with 123826 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

148
AirPlan/docs/architecture/main-agent-state-machine.md Normal file
View File

@@ -0,0 +1,148 @@
# 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) |