AirCoding/AirPlan/docs/analysis/requirements.md

# Requirements

Date: 2026-05-27
Status: Formal V1.0.0 Alpha requirements

## 1. Product Intent

AirCoding is a self-owned local AI coding agent/runtime for developer workflows. It should combine Claude Code-quality execution discipline, OpenTUI/OpenCode-inspired terminal UX, project-local persistence, multi-agent orchestration, and extensible toolchain capability packages.

The V1.0.0 Alpha target is not a half-finished skeleton. It must deliver a usable Linux-first local coding loop with a complete C++ development workflow and a plugin/capability foundation. C++ is the first deep toolchain profile; the runtime remains extensible for later language profiles.

## 2. Primary Users

| User | Need |
|---|---|
| Developer/operator | Give coding requirements, monitor progress, approve important decisions, receive verified changes |
| AirCoding maintainer | Extend runtime, tools, providers, prompts, and toolchain packages safely |
| Future plugin/capability author | Add tools/capabilities without bypassing core security and event contracts |

## 3. Functional Requirements

### FR-001 CLI Startup and Project Initialization

AirCoding must start from a CLI entrypoint, detect/open a project, initialize `.air/` when needed, load resources/config, run read-only Doctor, and open a session.

### FR-002 Project-Local State

AirCoding must store project source-of-truth workflow state under project `.air/`:

```text
.air/shared/  # shareable project config/rules/plan docs
.air/local/   # private sessions/artifacts/workspaces/backups/local DBs
```

### FR-003 Session Persistence

AirCoding must persist each session in SQLite at:

```text
<project>/.air/local/sessions/<session-id>/session.db
```

It must support messages, drafts, durable events, task graph state, agents, tool/command runs, artifacts, diagnostics, evidence refs, workspaces, summaries, and UI state.

### FR-004 Event-Driven Runtime

AirCoding must publish RuntimeEvents for live behavior and persist durable events transactionally with domain table updates.

### FR-005 Main Agent Conversation

AirCoding must provide a user-facing Main Agent that can receive requests, answer directly when appropriate, classify work, show progress, and present blockers/confirmations.

### FR-006 Architecture Designer

AirCoding must route architecture/interface/product-impacting decisions to an Architecture Designer that updates architecture artifacts and produces impact assessments.

### FR-007 Scheduler and TaskGraph

AirCoding must schedule TaskSpec records with hard/soft dependencies, write-area conflict handling, retry budgets, child worker dispatch, heartbeat monitoring, merge coordination, and restart recovery.

**FR-007.5 ADR 级联失效与架构变更回滚**：当 ADR 发生架构方案变更（如 ffmpeg → gstreamer）时，调度器必须：
1. 通过 TaskNode.adr_refs 溯源所有依赖该 ADR 的任务（含已完成）
2. 级联失效受影响任务（completed→invalidated、running→终止、pending→cancelled）
3. 冻结调度（dispatch_frozen），阻止新任务派发
4. 创建 git 回滚快照（rollback_ref），支持 revert 旧方案代码
5. 接收 ArchitectureDesigner 产出的 PlanDelta 增量重规划
6. apply_delta 吸收新任务后解冻调度
7. 终审时检查 INVALIDATED 任务的旧代码是否已清理

### FR-008 Independent Worker Agents

Executor, Reviewer, Debugger, Compactor, and ExperienceMiner must run as independent Bun child processes communicating through NDJSON IPC.

### FR-009 Claude Code-Quality Execution Primitives

Execution tools must enforce read-before-edit, exact conservative edits, small patches, no unrelated refactors, permission checks, and verification-before-completion discipline.

### FR-010 ToolRegistry and Built-In Tools

AirCoding V1.0.0 Alpha must provide schema-validated built-in tools for filesystem, shell, git, project scanning, full C++ build/test/static-analysis/debug workflows, GUI screenshot evidence, network capture evidence, artifacts, context assembly, permission requests, and Doctor.

### FR-011 Permission and Security Model

AirCoding must classify paths/commands/network/credentials, enforce permission profiles, protect system-sensitive and credential operations, back up project-outside writes, and refuse unsafe requests.

### FR-012 Plugin and Capability Foundation

AirCoding V1.0.0 Alpha must include the plugin/capability foundation: manifest loading, validation, enable/disable config, dependency declaration, Doctor integration, namespaced tool registration, source/trust metadata, and PermissionEngine enforcement. Third-party registry/signing may remain later work, but local and built-in capability packaging must be usable.

### FR-013 Provider Layer

AirCoding must use Anthropic canonical messages internally and route provider calls through adapters with capability matrix validation and conversion reports.

### FR-014 Context Assembly and Compaction

AirCoding must assemble prompts from ordered layers, fit token budgets, record omissions, and use copy-on-write compaction when needed.

### FR-015 Artifact and Evidence Management

AirCoding must write artifacts through temp-file then atomic rename, record URI/path/hash/metadata, and link claims through evidence refs.

### FR-016 TUI and HUD

AirCoding must provide an OpenTUI/Solid-based terminal UI and HUD consuming ProjectionStore, not raw DB/EventBus.

### FR-017 Complete C++ Development Workflow

AirCoding V1.0.0 Alpha must support a complete C++ development workflow: project detection, build-system assessment, CMake configure, Ninja-first/Make-fallback build, compiler/linker diagnostic parsing, clangd code-intelligence queries, cppcheck static analysis, CTest/GoogleTest execution, debug run/log parsing, failure diagnosis, scoped fix execution, review, and evidence-backed verification.

### FR-018 Doctor

AirCoding must run read-only Doctor on startup, report environment/capability issues, and support fix mode under permission policy.

### FR-019 Logging and Diagnostics

AirCoding must write user-readable `air.log` and encrypted developer `air.developer.log`, with seven-day retention by default.

### FR-020 Release Gate

AirCoding must define tier-1 Linux release gates covering unit tests, integration fixture replay, real LLM E2E, project init, C++ build/test flow, SQLite recovery, child IPC, TUI startup, and artifact/event persistence.

## 4. Non-Functional Requirements

### NFR-001 Local-First Operation

Project state, artifacts, logs, and debug knowledge must remain local unless the user explicitly exports/shares/uploads them.

### NFR-002 Recoverability

AirCoding must recover from process/session restart by reading SQLite state, detecting lost agents, preserving workspaces, and rebuilding Scheduler queues.

### NFR-003 Extensibility

Language/toolchain support must be added through `toolchain-*` packages and capability manifests.

### NFR-004 Provider Flexibility

Internal contracts must remain stable across Anthropic, OpenAI, OpenRouter, ollama, and compatible endpoints.

### NFR-005 UI Responsiveness

Main Agent and TUI must remain responsive while background workers run.

### NFR-006 Evidence-Based Completion

Tasks must not be marked completed without appropriate build/test/debug/review evidence or an explicit skipped-gate report.

### NFR-007 Linux-First Platform Support

Linux x86_64 is tier 1. Linux arm64 and WSL2 are tier 2. macOS is experimental. Windows native is post-MVP/experimental.

### NFR-008 Security Boundary Preservation

LLM output, tool results, plugins, and external content are untrusted data until validated by runtime contracts and policy.

## 5. Constraints

1. Runtime: TypeScript on Bun.
2. Monorepo: Bun workspaces + Turborepo.
3. TUI: OpenTUI/Solid.
4. IPC: NDJSON over stdio.
5. DB: SQLite per session with WAL/NORMAL/foreign_keys OFF.
6. Internal message format: Anthropic canonical content blocks.
7. C++ is first deep toolchain; runtime remains language-agnostic.
8. Python is subprocess-only helper layer, not core runtime.
9. Early distribution uses binary tarball, not public package channels.
10. Architecture docs and workflow state live under `AirPlan/` for this repository.

## 6. Acceptance Notes

V1.0.0 Alpha is acceptable when it can demonstrate:

1. CLI starts and initializes/opens a project `.air/` tree.
2. Session DB schema initializes and persists messages/events/tasks/tool runs/artifacts.
3. EventStore transactionally applies core durable events to domain tables and safely records schema-only registered events.
4. ProjectionStore hydrates and updates a usable TUI/HUD view.
5. Scheduler dispatches worker child processes via NDJSON IPC, supports tool calls through the parent runtime, and receives WorkerResult.
6. ToolRegistry executes filesystem/shell/git/artifact/context/doctor/C++/debug/GUI/network evidence tools through PermissionEngine.
7. C++ workflow can detect, configure, build, statically analyze, test, debug, fix, review, and re-verify a representative fixture project.
8. Failed build/test/debug commands produce diagnostics/artifacts/evidence refs and can trigger Debugger repair.
9. ContextAssembler produces Anthropic canonical messages with omissions where needed.
10. Provider adapter path can perform model calls under capability validation and conversion reporting.
11. Capability manifests can be loaded, validated, enabled, and registered as namespaced tools.
12. Doctor reports platform/provider/toolchain/capability/display/network status and supports permissioned fix mode.
13. Release gate commands are documented and runnable on tier-1 Linux.