rdev/docs/aios-core/info.md

Synkra AIOS-Core Analysis

Repository: 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:

<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:

---
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:

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