AiosDeck

Less friction. More intelligence.

Status: Implemented — core orchestration, agents, workflows, security, and telemetry are implemented and covered by the test suite (1400+ tests). v1.1 benchmark instrumentation (profiling hooks, bare mode, routing parity) is shipped; see CHANGELOG.

AiosDeck is an intelligent orchestration platform that transforms AI-assisted development from isolated conversations into collaborative software engineering.

Instead of talking to a single language model, you work with a coordinated team of specialized AI agents — each with one responsibility, governed by a kernel that manages context, memory, workflows, and security.

Just as an operating system coordinates CPU, memory, and processes, AiosDeck coordinates context, planning, implementation, review, and documentation.

The result is a development environment that remembers your projects, understands your architecture, and continuously assists your workflow.

Table of Contents

• Core Idea
• Philosophy
• Relationship with ProjDesk
• Roadmaps
• Architecture
• How It Works
• Security
• Agent Ecosystem
• Skills
• Decisions
• Getting Started
• License

Core Idea

Traditional AI tools follow a single conversation loop. The model is the center of everything.

Developer
   │
   ▼
LLM
   │
   ▼
Answer

AiosDeck introduces an execution layer between you and the model. The language model is no longer the center of the system — it becomes an execution engine.

Developer
   │
   ▼
AiosDeck
   │
   ├── Planner       (decomposes intent)
   ├── Context       (enriches with project knowledge)
   ├── Memory        (remembers decisions and conventions)
   ├── Scheduler     (orchestrates task queue)
   ├── Agents        (execute with single responsibility)
   ├── Quality Gates (validate every output)
   └── Security      (enforces zero-trust policies)
   │
   ▼
Runtime (OpenCode via ai-jail)
   │
   ▼
LLMs (Ollama / GPT / Gemini / Claude)

Philosophy

AiosDeck is built around ten principles that guide every architectural decision.

Every abstraction must solve an existing problem. Never an anticipated one.

The full philosophy is documented in philosophy.md.

Relationship with ProjDesk

ProjDesk prepares your development workspace. AiosDeck prepares your intelligence workspace. Together they create an autonomous development environment.

Developer
   │
   ▼
ProjDesk
   │
   ├── Docker
   ├── VS Code
   └── Workspace
   │
   ▼
AiosDeck
   │
   ├── Context
   ├── Agents
   └── OpenCode
   │
   ▼
LLMs

The contract between them is a project manifest (aios/project.yaml) — a single file that describes how the project should be understood, which Skills to load, which Quality Gates to run, and which agents to enable. ProjDesk can generate it. AiosDeck consumes it. It works with or without ProjDesk.

Roadmaps

AiosDeck maintains one active roadmap: post-1.0 instrumentation and stability. Everything else is directional context.

Stabilization Roadmap — v1.0 (released)

Short, shippable milestones toward a stable, predictable v1.0. Each phase is atomic and verified (pytest tests/ -q + ruff).

Instrumentation Roadmap — v1.1 (released)

Benchmark observability so performance becomes a machine-checkable artifact.

v1.0 core — learning governance (approval pipeline), RuleBasedRouter (deterministic model routing), and the basic console. Everything else is a documented post-1.0 extension, not a v1.0 commitment.

Vision Roadmap — Where We Are Going

The destination. No dates. No versions. Pure direction.

• AI Operating System — A coordinated team of specialized AI agents, each with one responsibility
• Marketplace — Community-contributed Agents, Skills, Workflows, and Plugins
• Distributed Agents — Agents running across machines, coordinated by the Scheduler
• Cloud Sync — Shared memory, shared policies, per-team agents (local-first, cloud-optional)
• IDE Integration — In-editor agent panels, inline reviews, side-by-side context

Implemented Phases

The following phases are shipped and verified by the test suite.

Workflows, the quality pipeline, skills, research, learning governance, and all agents are implemented and tested — not merely specified. The plugin system, advanced TUI widgets, and concurrent execution are post-1.0.

Implementation Roadmap — What We Are Building Now

The full, current roadmap is roadmap.md — milestones M1–M8 plus the parallel design Track D, with every epic explicitly marked implemented / in-progress / planned. The incident driving M1's P0 epics is documented in ADR-0007.

Rule: Every abstraction must solve an existing problem. Never an anticipated one. If a component is not in this table, it has not earned its existence yet.

Design System — "Control Room"

Visual identity, design tokens, and Penpot artifacts live in design/. The submarine control room is the metaphor: depth for context, sonar for scanning, missions for work, control rooms for agents. design/style-guide.md defines the rules; design/tokens.json is the single source of visual truth.

Agent Birth Timeline

v0.2  Developer    ████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
v0.3  Memory       ░░░░░░░░████████░░░░░░░░░░░░░░░░░░░░░░░░░
v0.4  PromptBuilder░░░░░░░░░░░░░░░████████░░░░░░░░░░░░░░░░░░
v0.5  AgentExecutor░░░░░░░░░░░░░░░░░░░░░░░████████░░░░░░░░░░
v0.6  Planner      ░░░░░░░░░░░░░░░░░░░░░░░░░░░░████████░░░░░
v0.7  Reviewer     ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░████████░░
v0.8  Scheduler    ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░██████░░
v0.9  Tester       ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░████
v0.9  Documentation░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░███
v0.9  Git          ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░██
v0.9  Research     ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░██

Architecture

                         User
                          │
                          ▼
                    AiosDeck CLI (aios)
                          │
                          ▼
                        Kernel
                          │
                  Event Dispatcher
                          │
             ┌────────────┼────────────┐
             ▼            ▼            ▼
         Scheduler     Memory      Context
                          │
                          ▼
                     Task Queue
                          │
                  Security Manager
             ┌────────────┼────────────┐
             │ Policy Engine           │
             │ Capability Manager      │
             │ Secret Manager          │
             │ Prompt Firewall         │
             │ Audit Logger            │
             │ Approval Gates          │
             └────────────┼────────────┘
                          │
                  Quality Pipeline
             ┌────────┬───┴───┬────────┬────────┐
             ▼        ▼       ▼        ▼        ▼
          Format    Lint   Tests  Security  AI Arch
                                              │
                                    Documentation Review
                          │
             ┌────────────┼─────────────┐
             ▼            ▼             ▼
           Planner      Developer   Reviewer
             │            │             │
             │    (loads Skills from    │
             │     OpenCode skill       │
             │     tool on-demand)      │
             │            │             │
              └────────────┼─────────────┘
                           ▼
                    AgentExecutor
                           │
                    Runtime Adapter
                           │
                  OpenCode (via ai-jail)
                           │
                Ollama / GPT / Gemini / Claude

Full architecture is documented in architecture.md.

How It Works

Project Detection

aios

AiosDeck detects everything automatically:

• Project language (Python, JS/TS, Rust, Shell, Go, ...)
• Dependency manager (uv, pip, npm, cargo, ...)
• Linter (ruff, eslint, clippy, shellcheck, ...)
• Formatter (black, prettier, cargo fmt, shfmt, ...)
• Test runner (pytest, vitest, jest, bats, cargo test, ...)
• Git repository status
• Docker and Docker Compose presence
• OpenCode configuration and available Skills
• ai-jail sandbox configuration

All of this feeds into the Context Engine, which enriches every agent prompt with project-specific knowledge. No prompts. No configuration files. Just detection.

The Project Manifest

Every project can declare an aios/project.yaml that defines how the project should be understood:

name: my-project
language: python
runtime: opencode
sandbox: ai-jail

quality:
  lint: ruff
  format: black
  tests: pytest

skills:
  - project-dna
  - coding-style

workflows:
  - feature
  - fix
  - review

This manifest is the contract between ProjDesk and AiosDeck — and between any project and its AI agents.

Session Flow

aios
   │
   ├── Detects project characteristics
   ├── Loads project manifest
   ├── Restores memory from previous sessions
   ├── Assembles context (language, tools, conventions, architecture)
   ├── Loads active Skills (project-dna, coding-style)
    ├── Initializes the project scheduler engine (kanban persistence)
   ├── Starts Runtime (OpenCode via ai-jail)
   └── Shows dashboard

──────────────────────────────
 ProjDesk
 Workspace Ready
──────────────────────────────
 Docker        Running
 Git           main
 Skills        12 loaded
 Memory        Loaded
 Scheduler     Ready
 Developer     Ready
 Planner       Ready
 Reviewer      Offline
 Tester        Offline
 Documentation Offline
 OpenCode      Connected
 Runtime       ai-jail
 Status        Healthy
──────────────────────────────
 Welcome back.

Security

Security is not a feature. It is architecture. From the first line of code.

Zero-Trust Model

Every agent is untrusted until explicitly authorized. Instead of giving agents full access, each receives only the capabilities required for its job.

agents:
  planner:
    filesystem: read
    internet: false
    git: false
    shell: false

  developer:
    filesystem: write
    shell: true
    git: false
    internet: false

  reviewer:
    filesystem: read
    shell: false
    internet: false

  researcher:
    internet: true
    filesystem: read

Security Components

• Policy Engine — enforces capability-based access per agent
• Capability Manager — assigns and revokes capabilities at runtime
• Secret Manager — injects secrets into runtime, never into prompts
• Prompt Firewall — removes secrets, blocks injection, limits size before reaching the model
• Audit Logger — records every action with timestamps for debugging and trust
• Approval Gates — requires human confirmation for destructive operations (push, delete, migrate)

Deep Defense

AiosDeck delegates sandbox enforcement to ai-jail (process isolation, filesystem masks, directory restrictions, secret masking, per-project policies). AiosDeck adds orchestration and authorization on top. Even if an agent has permission to execute code, it remains constrained by ai-jail policies. Defense in depth.

runtime:
  command: ai-jail opencode
  # OpenCode is NEVER invoked directly.
  # The runtime adapter always spawns it
  # inside the security sandbox.

Agent Ecosystem

Agents are specialized. One job each. Nothing more.

Each agent is documented in detail under agents/. Every agent has its own ADR (Architecture Decision Record) with In → Process → Out specification, events emitted, events consumed, and a timeline of when each capability is introduced.

Skills

Agents learn by loading Skills — small knowledge fragments that teach them how to work with specific technologies, patterns, or conventions. Skills are an AiosDeck abstraction for modular knowledge; the active runtime's native mechanism loads them. OpenCode's Skill system is the first implementation.

Core Skills (v0.1)

Future Skills

docker-lifecycle, git-workflow, architecture-principles, agent-design, review-checklist, documentation-style, bash-style, semantic-command-tree, modular-architecture, project-philosophy, event-bus, runtime-opencode, ai-jail.

Skills are born when they solve an existing problem — never before.

Decisions

Architecture Decision Records explain why each foundational choice was made — not just what was chosen. These preserve context for future maintainers.

Getting Started

AiosDeck v1.1.0.

# Install
git clone <repository-url> ~/.config/aiosdeck
~/.config/aiosdeck/install.sh

# Start a session (shows dashboard)
aios

# Manage project knowledge
aios memory list
aios memory add convention "Use snake_case"

# Plan and execute on a sprint board
aios plan "add OAuth2 login" --run

# Review code (read-only, deterministic detectors)
aios review
aios review . --level architecture --output json --dry-run
aios review src/aios --level security
aios review --diff            # review the current git diff only
aios review --output file     # write report to reviewer_report.json

# Run diagnostics
aios doctor

# Process a backlog of tasks sequentially
aios backlog run --source=board:backlog
aios backlog list board:backlog
aios backlog add "feat(api): add health endpoint"
aios backlog stats

# Show help
aios help

Requirements

• Linux (primary platform)
• Python 3.12+
• OpenCode (runtime for agent execution)
• ai-jail (security sandbox)
• ProjDesk (workspace manager, optional but recommended)

License

MIT © Gabriel Pablo Garcia

Read next: Vision → Philosophy → Architecture → Decisions