Referência

Referência técnica para configuração, agentes, estrutura de arquivos e códigos de status do Synkra AIOS.

Referência de Configuração

O AIOS utiliza um sistema de configuração em camadas baseado em arquivos YAML.

Configuração Central (`core-config.yaml`)

O arquivo principal de configuração em .aios-core/core-config.yaml define as configurações do projeto:

Seção	Chave	Descrição
`project`	`type`	Tipo de projeto: `NEW_PROJECT`, `EXISTING_AIOS`
`project`	`version`	Versão do AIOS instalada
`project`	`installedAt`	Data de instalação
`user_profile`	—	Nível do usuário: `beginner`, `intermediate`, `advanced`
`qa`	`qaLocation`	Diretório de artefatos de QA
`prd`	`prdFile`	Caminho para o arquivo PRD
`prd`	`prdSharded`	Se o PRD está fragmentado em arquivos menores
`prd`	`prdShardedLocation`	Diretório para arquivos PRD fragmentados
`architecture`	`architectureFile`	Caminho para o documento de arquitetura
`architecture`	`architectureSharded`	Se a arquitetura está fragmentada
`devLoadAlwaysFiles`	—	Arquivos carregados automaticamente para o agente @dev
`devStoryLocation`	—	Diretório para arquivos de story
`slashPrefix`	—	Identificador do prefixo de comando
`toolsLocation`	—	Caminho para ferramentas do AIOS
`scriptsLocation`	`core`	Caminho dos scripts core
`scriptsLocation`	`development`	Caminho dos scripts de desenvolvimento
`scriptsLocation`	`infrastructure`	Caminho dos scripts de infraestrutura
`dataLocation`	—	Caminho de armazenamento de dados
`ide`	`selected`	Integrações de IDE habilitadas
`mcp`	`enabled`	Integração MCP habilitada
`mcp`	`configLocation`	Caminho do arquivo de configuração MCP

Configuração do Projeto (`.aios/config.yaml`)

Sobrescritas específicas do projeto que ficam no diretório do projeto. Este arquivo é criado durante a inicialização do AIOS e contém configurações locais.

Definições de Agentes (`.aios-core/agents/`)

Cada agente é definido por um arquivo YAML contendo:

Nome da persona e arquétipo
Descrição do papel e responsabilidades
Capacidades e restrições
Permissões de acesso a ferramentas
Regras constitucionais

Definições de Tarefas (`.aios-core/development/tasks/`)

Tarefas são definidas como arquivos Markdown especificando:

Requisitos de entrada e parâmetros
Pré-condições e pós-condições
Etapas de execução
Formato de saída e validação
Atribuição de agente

Referência de Agentes

O AIOS inclui 12 agentes especializados, cada um com uma persona única e responsabilidades definidas.

ID do Agente	Persona	Arquétipo	Papel Principal
`@aios-master`	Orion	Orquestrador	Governança do framework, coordenação de agentes, aplicação constitucional
`@analyst`	Atlas	Pesquisador	Pesquisa aprofundada, análise de dados, análise competitiva
`@architect`	Aria	Visionário	Arquitetura de sistemas, seleção de tecnologia, decisões de design
`@data-engineer`	Dara	Sábio de Dados	Design de schema, otimização de queries, políticas RLS, migrações
`@dev`	Dex	Construtor	Implementação de código, operações git (local), desenvolvimento de stories
`@devops`	Gage	Guardião	Git push, gestão de PRs, CI/CD, gestão de MCP, deploy
`@pm`	Morgan	Estrategista	Criação/execução de epics, levantamento de requisitos, escrita de specs
`@po`	Pax	Validador	Validação de stories (checklist de 10 pontos), priorização do backlog
`@qa`	Quinn	Guardião	Quality gates, revisão de código, loops de QA, verificação de testes
`@sm`	River	Facilitador	Criação de stories, seleção de templates, facilitação de sprints
`@squad-creator`	Nova	Criador	Criação de squads, composição de times, mapeamento de capacidades
`@ux-design-expert`	Uma	Designer	Pesquisa de UX, specs de frontend, design system, acessibilidade

Relacionamento entre Agentes

Os agentes colaboram em uma hierarquia definida:


@aios-master (orquestração)
  ├── @analyst (pesquisa) → @pm (planejamento)
  ├── @pm → @architect (design) → @data-engineer (banco de dados)
  ├── @architect → @ux-design-expert (UX)
  ├── @po (validação) → @sm (criação de stories)
  └── @dev (implementação) → @qa (qualidade) → @devops (deploy)

Matriz de Autoridade

Operação	Agente Exclusivo	Outros
`git push` / `git push --force`	@devops	Bloqueado
`gh pr create` / `gh pr merge`	@devops	Bloqueado
MCP adicionar/remover/configurar	@devops	Bloqueado
Validação de story (GO/NO-GO)	@po	Bloqueado
Criação de story a partir do epic	@sm	Bloqueado
Orquestração de epic	@pm	Bloqueado
Governança do framework	@aios-master	Bloqueado

Referência de Estrutura de Arquivos

O diretório .aios-core/ contém todos os arquivos do framework:


.aios-core/
├── agents/                     # Definições de persona de agentes (YAML)
│   ├── aios-master.yaml
│   ├── analyst.yaml
│   ├── architect.yaml
│   ├── data-engineer.yaml
│   ├── dev.yaml
│   ├── devops.yaml
│   ├── pm.yaml
│   ├── po.yaml
│   ├── qa.yaml
│   ├── sm.yaml
│   ├── squad-creator.yaml
│   └── ux-design-expert.yaml
├── cli/                        # Ponto de entrada CLI e comandos
│   └── index.js
├── core/                       # Lógica core do framework
├── core-config.yaml            # Arquivo principal de configuração
├── data/                       # Armazenamento de dados em runtime
├── development/
│   ├── scripts/                # Scripts de automação de desenvolvimento
│   ├── tasks/                  # Definições de tarefas (Markdown)
│   └── templates/              # Templates de story, epic e documentos
├── docs/                       # Documentação do framework
├── elicitation/                # Dados do motor de elicitação
├── infrastructure/
│   └── scripts/                # Automação de infraestrutura
├── scripts/                    # Scripts legados
└── tools/                      # Definições de ferramentas AIOS

Diretório do Projeto (`.aios/`)

O diretório .aios/ armazena dados específicos do projeto:


.aios/
├── config.yaml                 # Configuração específica do projeto
├── data/                       # Dados de runtime do projeto
│   ├── usage-stats.json        # Estatísticas de uso
│   └── telemetry/              # Dados de telemetria
└── backups/                    # Backups do projeto

Códigos de Status e Vereditos

Status da Story

Status	Descrição	Acionado Por
`Draft`	Story criada, ainda não validada	@sm cria a story
`Ready`	Story validada, pronta para implementação	@po valida (veredito GO)
`InProgress`	Implementação iniciada	@dev inicia o trabalho
`InReview`	Implementação completa, em revisão de QA	@qa inicia revisão
`Done`	QA aprovado, alterações enviadas	@devops envia alterações

Vereditos de Validação (Validação de Story)

Veredito	Pontuação	Ação
`GO`	≥ 7/10 no checklist	Story marcada como Ready, prosseguir para implementação
`NO-GO`	< 7/10 no checklist	Story retornada com correções obrigatórias

Vereditos do QA Gate

Veredito	Condição	Ação
`PASS`	Todas as 7 verificações OK	Aprovar, prosseguir para deploy
`CONCERNS`	Problemas menores encontrados	Aprovar com observações documentadas
`FAIL`	Problemas HIGH/CRITICAL encontrados	Retornar ao @dev com feedback específico
`WAIVED`	Problemas aceitos (raro)	Aprovar com waiver documentado

Vereditos do QA Loop

Veredito	Ação
`APPROVE`	Loop completo, marcar story como Done
`REJECT`	@dev aplica correções, nova revisão
`BLOCKED`	Escalar imediatamente

Gatilhos de Escalação do QA Loop

Gatilho	Descrição
`max_iterations_reached`	5 iterações sem resolução
`verdict_blocked`	QA retornou veredito BLOCKED
`fix_failure`	Tentativas de correção falharam após retentativas
`manual_escalate`	Usuário acionou `*escalate-qa-loop`

Vereditos do Spec Pipeline (Fase de Crítica)

Veredito	Pontuação Média	Ação
`APPROVED`	≥ 4.0	Prosseguir para planejamento de implementação
`NEEDS_REVISION`	3.0 - 3.9	Revisar spec e re-criticar
`BLOCKED`	< 3.0	Escalar para @architect

Classes de Complexidade (Spec Pipeline)

Pontuação	Classe	Fases Executadas
≤ 8	`SIMPLE`	gather, spec, critique (3 fases)
9 - 15	`STANDARD`	Todas as 6 fases
≥ 16	`COMPLEX`	6 fases + ciclo de revisão

Níveis de Severidade do CodeRabbit

Severidade	Fase Dev	Fase QA
`CRITICAL`	Auto-correção, bloquear se persistir	Auto-correção, bloquear se persistir
`HIGH`	Auto-correção, documentar se falhar	Auto-correção, documentar se falhar
`MEDIUM`	Documentar como dívida técnica	Documentar como dívida técnica
`LOW`	Ignorar	Ignorar

Referência de Schemas YAML

Schema de Arquivo de Story


storyId: "STORY-{número}"
title: "Título da story"
status: Draft | Ready | InProgress | InReview | Done
epic: "EPIC-{número}"
description: "Descrição do problema/necessidade"
acceptanceCriteria:
  - "Dado... Quando... Então..."
scope:
  in:
    - "O que está incluído"
  out:
    - "O que está excluído"
dependencies: []
complexity: "S | M | L | XL"
risks: []

Schema de Arquivo do QA Gate


storyId: "STORY-{número}"
verdict: PASS | CONCERNS | FAIL | WAIVED
issues:
  - severity: low | medium | high
    category: code | tests | requirements | performance | security | docs
    description: "Descrição do problema"
    recommendation: "Correção sugerida"

Schema de Execução de Epic


epicId: "EPIC-{número}"
status: Planning | InProgress | Complete
stories:
  - storyId: "STORY-{número}"
    status: Draft | Ready | InProgress | InReview | Done
    assignedAgent: "@dev"