Initial commit: AirCoding V1.0.0 Alpha architecture baseline
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
344
AirPlan/plan.md
Executable file
344
AirPlan/plan.md
Executable file
@@ -0,0 +1,344 @@
|
||||
# Implementation Plan
|
||||
|
||||
Date: 2026-05-27
|
||||
Status: Formal architecture-to-V1.0.0 Alpha plan
|
||||
|
||||
## Read First
|
||||
|
||||
1. `AirPlan/AGENTS.md`
|
||||
2. `AirPlan/docs/analysis/requirements.md`
|
||||
3. `AirPlan/docs/architecture/solution-architecture.md`
|
||||
4. `AirPlan/docs/architecture/c4/module.md`
|
||||
5. `AirPlan/docs/architecture/baselineV1.md`
|
||||
6. `AirPlan/docs/architecture/多模型三视角审查联合评估.md`
|
||||
7. `AirPlan/docs/architecture/adr/`
|
||||
8. `AirPlan/todo.md`
|
||||
|
||||
## Goal
|
||||
|
||||
Build AirCoding V1.0.0 Alpha: a Linux-first Bun/TypeScript local AI coding runtime with project-local `.air` state, SQLite session persistence, event/domain store, scheduler/worker IPC, ToolRegistry/PermissionEngine, provider adapter boundary, complete C++ development workflow, usable plugin/capability foundation, OpenTUI/Solid ProjectionStore UI, Doctor, and release validation gates.
|
||||
|
||||
## Architecture Baseline
|
||||
|
||||
Implementation must follow these canonical V1 documents:
|
||||
|
||||
| Area | Document |
|
||||
|---|---|
|
||||
| Requirements | `AirPlan/docs/analysis/requirements.md` |
|
||||
| Solution architecture | `AirPlan/docs/architecture/solution-architecture.md` |
|
||||
| C4/module view | `AirPlan/docs/architecture/c4/module.md` |
|
||||
| Baseline | `AirPlan/docs/architecture/baselineV1.md` |
|
||||
| DB schema | `AirPlan/docs/architecture/db-schema-v1.md` |
|
||||
| Event registry | `AirPlan/docs/architecture/event-registry-v1.md` |
|
||||
| Tool registry | `AirPlan/docs/architecture/tool-registry-v1.md` |
|
||||
| Scheduler state machine | `AirPlan/docs/architecture/scheduler-state-machine-v1.md` |
|
||||
| Prompt layering | `AirPlan/docs/architecture/prompt-layering-v1.md` |
|
||||
| Provider matrix | `AirPlan/docs/architecture/provider-capability-matrix-v1.md` |
|
||||
| Error taxonomy | `AirPlan/docs/architecture/error-taxonomy-v1.md` |
|
||||
| Artifact naming | `AirPlan/docs/architecture/artifact-naming-v1.md` |
|
||||
| Scope escalation | `AirPlan/docs/architecture/scope-escalation-v1.md` |
|
||||
| Security model | `AirPlan/docs/architecture/security-model-v1.md` |
|
||||
| Capability trust | `AirPlan/docs/architecture/capability-trust-v1.md` |
|
||||
| Platform matrix | `AirPlan/docs/architecture/cross-platform-matrix-v1.md` |
|
||||
| Multi-model phase-gate assessment | `AirPlan/docs/architecture/多模型三视角审查联合评估.md` |
|
||||
|
||||
## Phase Gate Status
|
||||
|
||||
The P0/P1/P2 remediation and UX scope gate from `AirPlan/docs/architecture/多模型三视角审查联合评估.md` are complete:
|
||||
|
||||
1. source-of-truth and V1.0.0 Alpha vocabulary cleanup — DONE (T-000A)
|
||||
2. public contract freeze repair — DONE (T-000B)
|
||||
3. persistence/runtime invariant repair — DONE (T-000C)
|
||||
4. UX scope decision — DONE (T-000D): all features scheduled as Alpha; VibeBox removed from main plan
|
||||
|
||||
System overview design and detailed design may proceed. `packages/contracts` implementation may proceed after overview design is consistent.
|
||||
|
||||
## Constraints
|
||||
|
||||
1. Runtime: TypeScript on Bun.
|
||||
2. Monorepo: Bun workspaces + Turborepo.
|
||||
3. TUI: `@opentui/solid`, `@opentui/core`, `@opentui/keymap`.
|
||||
4. IPC: NDJSON over stdio.
|
||||
5. DB: project-local SQLite per session.
|
||||
6. Internal message format: Anthropic canonical content blocks.
|
||||
7. Workers: independent Bun child processes.
|
||||
8. V1.0.0 Alpha platform: Linux x86_64 tier 1, Linux arm64/WSL2 tier 2.
|
||||
9. Execution layer must follow Claude Code-style edit/verification discipline.
|
||||
10. All side effects must pass through ToolRegistry and PermissionEngine.
|
||||
|
||||
## Phases
|
||||
|
||||
### Phase 0: Repository Skeleton and Contracts
|
||||
|
||||
Objective: create a compileable monorepo foundation and shared contract package.
|
||||
|
||||
Deliverables:
|
||||
|
||||
- Bun workspace and Turborepo config
|
||||
- `packages/contracts`
|
||||
- core types for runtime, events, IPC, task, worker result, tool, artifact, provider, project, UI, error
|
||||
- baseline test/lint/typecheck commands
|
||||
|
||||
Validation:
|
||||
|
||||
```bash
|
||||
bun install
|
||||
bun run typecheck
|
||||
bun test
|
||||
```
|
||||
|
||||
### Phase 1: Project and Session Storage Foundation
|
||||
|
||||
Objective: implement project-local `.air` initialization and SQLite V1 session store.
|
||||
|
||||
Deliverables:
|
||||
|
||||
- project `.air/shared` and `.air/local` initializer
|
||||
- session ID/project ID creation
|
||||
- SQLite schema/migration V1
|
||||
- SessionStore repositories
|
||||
- EventStore transactional durable event application
|
||||
- ArtifactStore temp-write/rename/hash/DB insert
|
||||
|
||||
Validation:
|
||||
|
||||
```bash
|
||||
bun test packages/runtime
|
||||
bun run air -- doctor --read-only --project <fixture>
|
||||
bun run air -- init <fixture>
|
||||
```
|
||||
|
||||
### Phase 2: ToolRegistry, PermissionEngine, Core Tools, and Capability Foundation
|
||||
|
||||
Objective: provide safe side-effect execution primitives and a usable plugin/capability foundation for V1.0.0 Alpha.
|
||||
|
||||
Deliverables:
|
||||
|
||||
- ToolRegistry
|
||||
- ToolResult envelopes and tool lifecycle events
|
||||
- realpath path classifier
|
||||
- command risk analyzer
|
||||
- PermissionEngine decision records
|
||||
- filesystem, shell, git, project, artifact, context, permission, doctor core tools
|
||||
- CapabilityRegistry manifest loading/validation
|
||||
- local and built-in capability enable/disable config
|
||||
- namespaced capability tool registration
|
||||
- Doctor dependency check path for capabilities
|
||||
|
||||
Validation:
|
||||
|
||||
```bash
|
||||
bun test packages/runtime --filter tool
|
||||
bun test packages/runtime --filter permission
|
||||
```
|
||||
|
||||
### Phase 3: Provider and Context Layer
|
||||
|
||||
Objective: support model calls through canonical context assembly and provider capability validation.
|
||||
|
||||
Deliverables:
|
||||
|
||||
- provider config loader
|
||||
- ProviderCapabilityMatrix implementation
|
||||
- ProviderAdapter interface
|
||||
- one Anthropic-compatible or OpenAI-compatible adapter path
|
||||
- ContextAssembler L0-L9 layering
|
||||
- omission/conflict reporting
|
||||
- provider conversion report
|
||||
|
||||
Validation:
|
||||
|
||||
```bash
|
||||
bun test packages/llm
|
||||
bun test packages/runtime --filter context
|
||||
```
|
||||
|
||||
Real-provider smoke gated by local config:
|
||||
|
||||
```bash
|
||||
bun run air -- provider doctor
|
||||
bun run air -- provider smoke
|
||||
```
|
||||
|
||||
### Phase 4: Worker IPC and Scheduler V1.0.0 Alpha
|
||||
|
||||
Objective: run independent child workers with Scheduler state machine.
|
||||
|
||||
Deliverables:
|
||||
|
||||
- WorkerManager process spawn/monitor
|
||||
- NDJSON IPC framing
|
||||
- Executor/Reviewer/Debugger/Compactor/ExperienceMiner process foundations
|
||||
- heartbeat and timeout handling
|
||||
- TaskGraph load/plan/dispatch/collect
|
||||
- retry budget/failure signature tracking
|
||||
- workspace create/merge events
|
||||
- restart recovery for lost/running agents
|
||||
|
||||
Validation:
|
||||
|
||||
```bash
|
||||
bun test packages/runtime --filter ipc
|
||||
bun test packages/runtime --filter scheduler
|
||||
bun run air -- e2e worker-fixture
|
||||
```
|
||||
|
||||
### Phase 5: Complete C++ Development Workflow
|
||||
|
||||
Objective: deliver the first complete language workflow, not just build/test smoke coverage.
|
||||
|
||||
Deliverables:
|
||||
|
||||
- `packages/toolchain-cpp`
|
||||
- `cpp.detect`
|
||||
- `cpp.cmake.configure`
|
||||
- `cpp.build`
|
||||
- `cpp.test`
|
||||
- `cpp.static.cppcheck`
|
||||
- `cpp.clangd.query`
|
||||
- compiler/linker/test diagnostic parser and semantic signatures
|
||||
- compile_commands generation/discovery
|
||||
- build-system conflict reporting
|
||||
- Debugger integration for failed build/test/debug evidence
|
||||
- Reviewer integration for C++ changes
|
||||
- automatic scoped repair loop for representative C++ failures
|
||||
- C++ fixture projects covering configure/build/test/static-analysis/debug/fix/review
|
||||
|
||||
Validation:
|
||||
|
||||
```bash
|
||||
bun test packages/toolchain-cpp
|
||||
bun run air -- fixture cpp-build-test
|
||||
bun run air -- e2e cpp-fix-fixture
|
||||
bun run air -- e2e cpp-debug-review-fixture
|
||||
```
|
||||
|
||||
### Phase 6: TUI/HUD Projection
|
||||
|
||||
Objective: expose runtime state through OpenTUI/Solid UI without coupling UI to DB/EventBus.
|
||||
|
||||
Deliverables:
|
||||
|
||||
- ProjectionStore hydrate/apply APIs
|
||||
- TUI startup shell
|
||||
- session/task/agent/tool/command/artifact views
|
||||
- permission prompt UI
|
||||
- blocker report UI
|
||||
- basic HUD/statusline projection
|
||||
|
||||
Validation:
|
||||
|
||||
```bash
|
||||
bun test packages/tui
|
||||
bun run air -- tui-smoke --project <fixture>
|
||||
```
|
||||
|
||||
### Phase 7: Agent Prompt Integration and End-to-End Loop
|
||||
|
||||
Objective: connect Main Agent, Architecture Designer, Scheduler, workers, tools, context, and provider call path.
|
||||
|
||||
Deliverables:
|
||||
|
||||
- built-in prompt resources
|
||||
- Main Agent request classification
|
||||
- Architecture Designer impact assessment flow
|
||||
- Executor WorkerResult loop
|
||||
- Reviewer report loop
|
||||
- Debugger failure evidence loop
|
||||
- Compactor summary loop
|
||||
- scope escalation integration
|
||||
|
||||
Validation:
|
||||
|
||||
```bash
|
||||
bun run air -- e2e simple-edit-fixture
|
||||
bun run air -- e2e cpp-fix-fixture
|
||||
```
|
||||
|
||||
### Phase 8: Release Gate and Packaging
|
||||
|
||||
Objective: make V1.0.0 Alpha foundation reproducible and releasable for tier-1 Linux.
|
||||
|
||||
Deliverables:
|
||||
|
||||
- binary tarball packaging
|
||||
- resource bundle
|
||||
- release gate script
|
||||
- doctor report bundle generation
|
||||
- documentation of skipped gates/known limitations
|
||||
|
||||
Validation:
|
||||
|
||||
```bash
|
||||
bun run release:check
|
||||
bun run release:package
|
||||
```
|
||||
|
||||
## Parallelization Boundaries
|
||||
|
||||
Can parallelize after contracts stabilize:
|
||||
|
||||
- storage/EventStore and provider/context adapter work
|
||||
- ToolRegistry/PermissionEngine and ArtifactStore
|
||||
- C++ workflow tools/debug/review fixtures and TUI ProjectionStore
|
||||
- worker foundation and Scheduler tests
|
||||
- capability manifest validation and built-in capability registration
|
||||
|
||||
Must serialize:
|
||||
|
||||
1. `packages/contracts` before package implementations.
|
||||
2. DB schema before EventStore/SessionStore tests.
|
||||
3. ToolRegistry/PermissionEngine before tools and workers rely on side effects.
|
||||
4. Provider/context contract before agent prompt integration.
|
||||
5. Scheduler IPC before real worker E2E.
|
||||
|
||||
## Validation Strategy
|
||||
|
||||
Minimum per-task validation appears in `AirPlan/todo.md`.
|
||||
|
||||
Release-level validation:
|
||||
|
||||
```bash
|
||||
bun install
|
||||
bun run typecheck
|
||||
bun test
|
||||
bun run lint
|
||||
bun run air -- doctor --read-only
|
||||
bun run air -- e2e worker-fixture
|
||||
bun run air -- fixture cpp-build-test
|
||||
bun run air -- e2e cpp-fix-fixture
|
||||
bun run air -- e2e cpp-debug-review-fixture
|
||||
bun run air -- capability validate --all
|
||||
bun run release:check
|
||||
```
|
||||
|
||||
If a validation gate cannot run, record:
|
||||
|
||||
```text
|
||||
why skipped
|
||||
evidence available
|
||||
risk
|
||||
follow-up task
|
||||
```
|
||||
|
||||
## Static Analysis Strategy
|
||||
|
||||
V1.0.0 Alpha static analysis:
|
||||
|
||||
- TypeScript typecheck for all packages.
|
||||
- ESLint or equivalent once repo config exists.
|
||||
- `cppcheck` for C++ fixture/toolchain validation.
|
||||
- Architecture/static consistency reviewed through ADR/C4 updates.
|
||||
|
||||
## Risk Controls
|
||||
|
||||
| Risk | Control |
|
||||
|---|---|
|
||||
| contract churn | implement contracts first and version event/tool schemas |
|
||||
| unsafe edits | enforce read-before-edit and exact edit tools |
|
||||
| hidden side effects | all tools through PermissionEngine |
|
||||
| context overflow | ContextAssembler budgets and Compactor |
|
||||
| worker loss | heartbeat, timeouts, task_attempts, restart recovery |
|
||||
| provider mismatch | capability matrix and conversion reports |
|
||||
| evidence gaps | artifact/evidence refs required in WorkerResult |
|
||||
| platform surprises | Doctor platform report and Linux tier-1 release gates |
|
||||
Reference in New Issue
Block a user