admin/AirCoding
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
8d9c4208fa2ac04df297e2b329838361f68bcaf9
AirCoding/AirPlan/plan.md
AirCoding 8d9c4208fa System overview design: four-model audit, repair, and regression complete 
- system-overview-design.md: repaired with P0/P1/P2 gaps resolved, all 24 frozen baselines listed, error taxonomy, global ~/.air, IPC, TaskSpec/WorkerResult, PromptLayer, PermissionEngine, RuntimeEvent, state machines, capability trust, artifact naming, operations
- Four cross-verification audit reports (GPT-5, MIMO 2.5, Opus 4.7, DeepSeek V4 Pro)
- Three regression reviews (R1: initial repair closure, R2: second pass with PromptLayer L9 wording found, R3: full PromptLayer alignment verified)
- AGENTS.md, plan.md, todo.md synchronized

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-29 15:46:26 +08:00

352 lines
11 KiB
Markdown
Executable File
Raw Blame History

# 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/system-overview-design.md`
5. `AirPlan/docs/architecture/c4/module.md`
6. `AirPlan/docs/architecture/baselineV1.md`
7. `AirPlan/docs/architecture/多模型三视角审查联合评估.md`
8. `AirPlan/docs/architecture/gpt5概要设计审查.md`
9. `AirPlan/docs/architecture/mimo2.5概要设计审查.md`
10. `AirPlan/docs/architecture/Opus4.7概要设计审查.md`
11. `AirPlan/docs/architecture/DeepSeek概要设计审查.md`
12. `AirPlan/docs/architecture/概要设计修复回归审查.md`
13. `AirPlan/docs/architecture/adr/`
14. `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` |
| System overview design | `AirPlan/docs/architecture/system-overview-design.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 has been repaired after the GPT-5, MIMO 2.5, Opus 4.7, and DeepSeek overview audits. All P0/P1 and non-decision alignment gaps were folded into `system-overview-design.md`; `概要设计修复回归审查.md` passed the overview regression gate. Detailed design and `packages/contracts` implementation may proceed.
## 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 View Git Blame Copy Permalink