# 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 |