rdev/docs/aios-core/info.md

# Synkra AIOS-Core Analysis

> Repository: [github.com/SynkraAI/aios-core](https://github.com/SynkraAI/aios-core)
> Version: 4.0.4 | Language: JavaScript (ES2022, CommonJS) | Runtime: Node.js 18+

## What Is It?

**AIOS (AI-Orchestrated System)** is a CLI framework that orchestrates specialized AI agents to collaboratively build software using structured methodologies. It eliminates two critical problems in LLM-assisted development: **planning inconsistency** (solved via hierarchical agent roles) and **context loss** (solved via a deterministic 8-layer context injection engine called SYNAPSE).

It implements an **"Agentic Agile"** methodology: hierarchical planning (analyst -> PM -> architect) followed by contextual implementation (scrum master -> developer -> QA). Each agent has exclusive authority over its domain — only `@devops` can push, only `@architect` makes architecture decisions, only `@qa` issues quality verdicts.

**Target audience:** Teams using AI-assisted development who want structured, repeatable workflows with agent specialization rather than a single general-purpose LLM chat.

**Install:** `npx aios-core@latest init my-project` — drops a `.aios-core/` directory into your project and integrates with Claude Code, Cursor, or Windsurf.

## Architecture

```
CLI (bin/aios.js, Commander)
  |
  +-- Master Orchestrator (core/orchestration/)
  |     +-- Agent Invoker          # Activate agents by @name
  |     +-- Workflow Executor       # Multi-step orchestration
  |     +-- SYNAPSE Context Engine  # 8-layer context injection (L0-L7)
  |     +-- Recovery Handler        # Error rollback & retry
  |     +-- Session State Manager   # Cross-session continuity
  |
  +-- Agent System (.aios-core/development/agents/)
  |     12 agents, each with: persona, commands, dependencies, activation flow
  |
  +-- Task System (.aios-core/development/tasks/)
  |     201 executable tasks as Markdown+YAML files
  |
  +-- Execution Engines (core/execution/)
  |     +-- Build Orchestrator      # Autonomous code generation
  |     +-- Semantic Merge Engine   # AST-aware code merging
  |     +-- Subagent Dispatcher     # Parallel task execution
  |     +-- Wave Executor           # Batched operations with deps
  |
  +-- Quality Gates (quality/, hooks/)
  |     Pre-commit, pre-push, CI validation
  |
  +-- Configuration (4-level hierarchy)
        L1 Framework -> L2 Project -> L3 Core -> L4 Local (user)
```

### Directory Structure

```
aios-core/
+-- .aios-core/                   # Framework core (installed into projects)
|   +-- core/                     # Runtime engines (~25 modules)
|   |   +-- orchestration/        # Master orchestrator (16KB)
|   |   +-- execution/            # Build, merge, dispatch (12KB)
|   |   +-- synapse/              # 8-layer context injection
|   |   +-- config/               # Config loaders (L0-L4)
|   |   +-- ids/                  # ID generators
|   |   +-- health-check/         # Diagnostics
|   +-- development/              # Agent definitions & workflows
|   |   +-- agents/               # 12 agent definitions
|   |   +-- tasks/                # 201 executable tasks
|   |   +-- workflows/            # 15 workflow definitions
|   |   +-- templates/            # 9 document templates
|   |   +-- agent-teams/          # 7 bundled agent groups
|   +-- infrastructure/           # Build scripts, CI templates
|   +-- hooks/                    # Git hooks
|   +-- product/                  # Squads, mind contexts
|   +-- quality/                  # Quality gate implementations
|   +-- schemas/                  # JSON Schema validators
|   +-- constitution.md           # Formal principles & gates
+-- bin/                          # CLI executables
+-- packages/                     # Monorepo (aios-install, gemini-ext)
+-- .claude/                      # Claude Code integration
+-- docs/                         # Documentation (~6.8MB)
+-- tests/                        # Test suite (~4MB, 80%+ coverage)
```

### Key Modules by Size

| Module | LOC | Purpose |
|--------|-----|---------|
| master-orchestrator.js | 1,542 | Main orchestration engine |
| semantic-merge-engine.js | 1,180 | AST-aware code merging |
| workflow-executor.js | 1,180 | Multi-step workflow execution |
| terminal-spawner.js | 1,043 | Shell command execution with streaming |
| build-state-manager.js | 948 | Build execution state tracking |
| greenfield-handler.js | 888 | New project initialization |
| session-state.js | 875 | Cross-session continuity |
| recovery-handler.js | 720 | Error recovery & rollback |

## The 12 Agents

| Agent | Persona | Role | Exclusive Authority |
|-------|---------|------|---------------------|
| `@dev` | Dex (Builder) | Senior Developer | Code implementation |
| `@qa` | Quinn (Guardian) | Test Architect | Quality verdicts |
| `@architect` | Aria (Architect) | System Designer | Architecture decisions |
| `@pm` | Morgan (Analyzer) | Product Manager | Requirements & specs |
| `@po` | Pax (Curator) | Product Owner | Story creation & prioritization |
| `@sm` | River (Facilitator) | Scrum Master | Sprint planning & story flow |
| `@analyst` | Alex (Researcher) | Business Analyst | Research & pattern extraction |
| `@data-engineer` | Dara (Data Architect) | DB Designer | Schema design & migrations |
| `@ux-design-expert` | Uma (Designer) | UX/UI Specialist | Design & usability |
| `@devops` | Gage (Operator) | DevOps Engineer | git push, PRs, releases |
| `@aios-master` | Orion (Orchestrator) | Framework Developer | All capabilities |
| `@squad-creator` | Scout (Builder) | Expansion Creator | Build new squads/domains |

Agent authority is non-negotiable. Only `@devops` can `git push`. Only `@architect` makes architecture decisions. Enforced by the Constitution system.

## Typical Workflow

```
1. npx aios-core init my-project
2. @pm: *gather-requirements -> *write-spec
3. Approve spec, activate @architect
4. @architect: *create-plan -> *map-codebase
5. @po: *shard-doc (split large docs) -> *create-next-story
6. @dev: *develop (implement story)
7. @qa: *review-story
8. @devops: *git-push
9. Loop to step 5 for next story
```

## 10 Interesting Things

### 1. SYNAPSE: 8-Layer Deterministic Context Injection

The standout innovation. Rather than stuffing everything into one LLM prompt, SYNAPSE builds context through 8 prioritized layers:

| Layer | Name | What It Injects |
|-------|------|-----------------|
| L0 | Constitution | Non-negotiable principles (CLI-first, agent authority) |
| L1 | Global | Framework-wide coding standards |
| L2 | Agent | Agent-specific rules ("Dev only updates story Dev section") |
| L3 | Workflow | Current phase, expected next step |
| L4 | Task | Acceptance criteria, inputs/outputs |
| L5 | Squad | Domain-specific conventions |
| L6 | Keyword | Triggered by tags like `[LLM: complex]` |
| L7 | Star-Command | Command-specific context for `*develop`, `*review`, etc. |

Output is XML prepended to every LLM prompt:
```xml
<synapse-rules>
  <layer level="0" name="constitution">
    <rule>CLI First: All functionality works 100% via CLI</rule>
    <rule>Agent Authority: Only @devops can git push</rule>
  </layer>
  <layer level="2" name="agent" agent="dev">
    <rule>CRITICAL: ONLY update story Dev Agent Record</rule>
  </layer>
</synapse-rules>
```

### 2. Markdown as Executable Specification

All 201 tasks are Markdown files with YAML front matter that serve as both documentation AND executable specs. The framework parses them into execution plans:

```yaml
---
task: create-next-story()
responsible: River (Scrum Master)
entrada:
  - campo: epic_name
    tipo: string
    required: true
saida:
  - campo: created_file
    tipo: string
acceptance-criteria:
  - [ ] Story has all required sections
---
## Execution Steps
1. Validate epic exists
2. Create story file
3. Update epic index
```

The Markdown tree parser extracts YAML metadata, numbered steps become execution plans, and checkboxes become progress tracking.

### 3. Formal Constitution with Automated Enforcement

A `constitution.md` file defines legally-styled principles with three severity levels enforced by quality gates:

- **NON-NEGOTIABLE**: Gates block execution (CLI-first, agent authority)
- **MUST**: Gates warn but allow (story-driven dev, quality-first)
- **SHOULD**: Gates inform only (absolute imports)

This is unusual — most projects have informal "contributing" docs. AIOS has a formal governance document with automated enforcement.

### 4. Semantic Merge Engine (AST-Aware)

Instead of line-based git merges, the semantic merge engine understands code structure:
- Function-level conflict detection
- Import reorganization
- 3-way merge (ours/theirs/base) with AST awareness
- Eliminates typical merge conflicts in multi-agent workflows where different agents modify the same files

### 5. Session State Machine with Recovery

Agent conversations survive IDE restarts. A `SessionState` tracks current agent, task, story, execution history, and checkpoints. The recovery handler can resume from the last good state after failures — critical for long-running multi-agent workflows that might span hours.

Persisted to `.aios/session-state.yaml`.

### 6. No Database — Git Repository IS the Database

Zero traditional database. All state lives in the filesystem:
- YAML for configuration
- Markdown for stories, tasks, specs
- JSON for metadata
- Git history for audit trail

The repository itself is the single source of truth. This makes the entire system portable and version-controlled by default.

### 7. Wave Executor for Parallel Agent Work

Independent tasks run in parallel, respecting dependency graphs:

```javascript
const wave = [
  { task: 'task-a', deps: [] },
  { task: 'task-b', deps: [] },        // Parallel with A
  { task: 'task-c', deps: ['a', 'b'] } // Waits for A+B
];
await waveExecutor.execute(wave);
```

Enables fast multi-agent workflows without race conditions.

### 8. Squads: Domain-Extensible Agent Teams

The framework isn't locked to software development. "Squads" are pluggable domain-specific agent teams with their own agents, tasks, templates, and knowledge bases. A squad for legal, marketing, healthcare, or education could define 1-5 specialized agents with 20-50 domain tasks.

Structure: `squads/your-squad/{config.yaml, agents/, tasks/, templates/, data/}`.

### 9. Three Execution Modes

Every task can run in one of three modes:
- **YOLO** (0-1 prompts): Fully autonomous with logging. Fast, dangerous.
- **Interactive** (5-10 prompts): Explicit checkpoints at key decision points. Default.
- **Pre-Flight** (comprehensive): Zero-ambiguity upfront planning before any execution.

This is a thoughtful UX choice — developers pick their risk tolerance per task.

### 10. Portuguese-First, Multi-Language

The codebase and task definitions use Portuguese for many field names (`responsavel`, `entrada`, `saida`, `pre-condicoes`). Documentation exists in Portuguese, English, and Spanish. This is unusual for an open-source framework and reflects its origin from Pedro Valerio's hybrid-ops methodology. The English docs are comprehensive but the Portuguese roots show the project's cultural DNA.

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Runtime | Node.js 18+ |
| Language | JavaScript ES2022 (CommonJS, ESM migration planned) |
| Types | TypeScript 5.9.3 (definitions only, not compiled) |
| CLI | Commander 12.1.0 |
| Prompts | @clack/prompts 0.11.0 |
| Templates | Handlebars 4.7.8 |
| Validation | ajv (JSON Schema) + validator |
| YAML | js-yaml 4.1.0 |
| Markdown | @kayvan/markdown-tree-parser 1.5.0 |
| Process | execa 5.1.1 |
| Testing | Jest 30.2.0 (80%+ coverage required) |
| Linting | ESLint 9.38.0 + Prettier 3.5.3 |
| Release | semantic-release 25.0.2 |
| Git Hooks | husky 9.1.7 |

**19 production dependencies** — deliberately minimal for a framework of this scope.

## Scale

| Metric | Count |
|--------|-------|
| Agents | 12 |
| Executable tasks | 201 |
| Workflows | 15 |
| Document templates | 9 |
| Agent teams | 7 |
| SYNAPSE layers | 8 |
| Config levels | 4 |
| Supported IDEs | 3 (Claude Code, Cursor, Windsurf) |
| Test coverage | 80%+ |
| Docs | ~6.8MB |