Synkra AIOS (aios-core)

Project Overview#

Synkra AIOS (aios-core) is an AI orchestration operating system designed as a core framework for full-stack development. It's not just a toolkit, but a complete development methodology implementation. Through CLI First principles, it transforms LLMs into professional development teams, enabling end-to-end automation of requirements analysis, architecture design, coding implementation, quality assurance, and deployment.

Problems Solved:

• Context Loss: Engineering-Contextualized Development ensures development Stories contain complete architecture guidance and context
• Fragmented Processes: Unified workflow orchestration standardizes PM, Architect, Dev, QA roles as Agent collaboration
• Execution Uncertainty: ADE provides fault recovery, structured review, and memory layers for robust automated execution

Use Cases:

• Greenfield projects: Rapid setup of new projects from scratch
• Brownfield projects: Iteration, extension, and refactoring of existing codebases
• Non-technical domains: Extended to creative writing, business strategy, education via Squads mechanism

Core Architecture Principles#

The project follows a clear priority hierarchy:

• CLI (Highest Priority): Intelligence core, where all execution, decisions, and automation occur
• Observability (Secondary): Real-time observation and monitoring of CLI activities
• UI (Tertiary): On-demand management and visualization

Two Core Innovations#

1. Agentic Planning#

Specialized analyst, PM, and architect agents collaborate to create detailed PRDs and architecture documents.

2. Engineering-Contextualized Development#

Scrum Master agents transform detailed plans into hyper-detailed development stories containing complete context, implementation details, and architecture guidance.

Professional Agent Matrix (11+ Agents)#

Meta Agents:

• aios-master - Main orchestration agent (includes framework development capabilities)
• aios-orchestrator - Workflow orchestration and team coordination

Planning Agents (Web Interface):

• analyst - Business analysis expert and PRD creation
• pm (Product Manager) - Product management and priority management
• architect - System architect and technical design
• ux-expert - User experience design and usability

Development Agents (IDE):

• sm (Scrum Master) - Sprint management and story creation
• dev - Developer and implementation
• qa - Quality assurance and testing
• po (Product Owner) - Backlog and story management
• data-engineer - Database design and data modeling
• devops - CI/CD, infrastructure, and git operations (only agent with push authority)

Autonomous Development Engine (ADE)#

7 Epics supporting autonomous development:

1. Worktree Manager - Git worktrees branch isolation
2. Migration V2→V3 - Migration to autoClaude V3 format
3. Spec Pipeline - Converting requirements to executable specs
4. Execution Engine - 13-step execution + self-criticism
5. Recovery System - Automatic fault recovery
6. QA Evolution - 10-stage structured review
7. Memory Layer - Persistent memory of patterns and insights

Typical Workflow#

1. @pm creates a PRD          → *create-epic
2. @sm drafts stories          → *draft
3. @po validates stories       → *validate-story-draft
4. @dev implements             → (works from story file)
5. @qa reviews                 → *review STORY-ID
6. @devops pushes              → *push (only agent with push authority)
7. @po closes story            → *close-story STORY-ID

Installation & Quick Start#

System Requirements#

• Node.js >= 18.0.0 (v20+ recommended)
• npm >= 9.0.0
• Git: Optional but recommended
• GitHub CLI: Optional, required for team collaboration

Installation#

# Create new project
npx aios-core init my-project

# Install to existing project
cd your-project
npx aios-core install

CLI Command Reference#

# Project management
npx aios-core init <project-name> [options]
  --force              # Force create in non-empty directory
  --skip-install       # Skip npm dependency installation
  --template <name>    # Use specific template

# System commands
npx aios-core --version
npx aios-core --help
npx aios-core info
npx aios-core doctor --fix

Agent Activation and Commands#

# General commands
*help                    # Show available commands
*guide                   # Show detailed usage guide
*session-info            # Show current session details
*exit                    # Exit agent mode

# Agent-specific examples
@dev *help               # Developer agent commands
@qa *review STORY-42     # QA agent review story

Core Component Structure#

The .aios-core/ directory contains all agent capability definitions and resources:

• agents/: Building blocks, each markdown file defines a single AI agent's role, capabilities, and dependencies
• agent-teams/: Team files defining agent collections and workflow bundles
• workflows/: YAML files defining step sequences for specific project types
• templates/: Reusable document templates (PRD, architecture specs, user stories, etc.)
• tasks/: Instructions for specific repeatable operations
• checklists/: Quality assurance checklists
• data/: Core knowledge base and technical preferences

Extension Mechanism: Squads#

The squads/ directory contains pre-built agent team packages, each squad contains: config.yaml, agents/, tasks/, templates/, checklists/, data/, README.md

IDE Compatibility#

Current Version: v4.2.15 Primary Languages: JavaScript (95.7%), TypeScript, Python, Shell