AirCoding/AirPlan/plan.md

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:

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:

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:

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:

bun test packages/llm
bun test packages/runtime --filter context

Real-provider smoke gated by local config:

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:

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:

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:

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:

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:

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:

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:

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