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
176
AirPlan/docs/analysis/requirements.md
Executable file
176
AirPlan/docs/analysis/requirements.md
Executable file
@@ -0,0 +1,176 @@
|
||||
# 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-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.
|
||||
Reference in New Issue
Block a user