Guia de Workflows do AIOS

Versao: 1.0.0 Ultima Atualizacao: 2026-02-02 Status: Ativo

Visao Geral

Os Workflows do AIOS sao sequencias orquestradas de atividades de agents que automatizam processos de desenvolvimento complexos. Eles fornecem padroes estruturados e repetitivos para cenarios de desenvolvimento comuns.

Conceitos Chave

Tipos de Workflow

Por Tipo de Projeto

Por Escopo

Workflows Disponiveis

Workflows de Desenvolvimento Core

1. Ciclo de Desenvolvimento de Story

ID: story-development-cycle Tipo: Generic Agents: SM → PO → Dev → QA

O workflow mais comum para desenvolvimento iterativo:

┌─────────────────────────────────────────────────────────────┐
│                   Story Development Cycle                    │
│                                                              │
│  @sm: Create Story → @po: Validate → @dev: Implement → @qa  │
│         │                  │               │            │    │
│         ▼                  ▼               ▼            ▼    │
│     Draft Story       10 Checks       Code + Tests    Gate   │
└─────────────────────────────────────────────────────────────┘

Phases:

1. Story Creation - SM cria a proxima story do backlog
2. Story Validation - PO valida com checklist de 10 pontos
3. Implementation - Dev implementa com testes
4. QA Review - QA executa quality gate

Quando usar:

• Qualquer desenvolvimento de story (greenfield ou brownfield)
• Ciclo completo com validacao e quality gate
• Quando voce precisa de rastreabilidade de processo

2. Greenfield Fullstack

ID: greenfield-fullstack Tipo: Greenfield Agents: DevOps → Analyst → PM → UX → Architect → PO → SM → Dev → QA

Workflow completo para novas aplicacoes full-stack:

Phases:

1. Environment Bootstrap - DevOps configura a infraestrutura do projeto
2. Discovery & Planning - Criar project brief, PRD, specs, arquitetura
3. Document Sharding - Desmembrar documentos para desenvolvimento
4. Development Cycle - Implementacao iterativa de stories

Quando usar:

• Construir aplicacoes prontas para producao
• Multiplos membros da equipe envolvidos
• Requisitos de features complexos
• Manutencao de longo prazo esperada

3. Brownfield Discovery

ID: brownfield-discovery Tipo: Brownfield Agents: Architect → Data Engineer → UX → QA → Analyst → PM

Avaliacao completa de divida tecnica para projetos existentes:

Phases:

1. Data Collection - Documentacao de sistema, banco de dados, frontend
2. Initial Consolidation - Rascunho da avaliacao
3. Specialist Validation - Revisoes de DB, UX, QA
4. Final Reports - Avaliacao + Relatorio executivo
5. Planning - Criacao de epic e stories

Quando usar:

• Migrando do Lovable/v0.dev
• Auditoria completa de codebase
• Avaliacao de divida tecnica antes de investimento

Outros Workflows

Como Criar um Workflow

Passo 1: Planeje Seu Workflow

Defina:

• Proposito: Qual problema este workflow resolve?
• Agents: Quais agents participam?
• Sequencia: Qual e a ordem dos steps?
• Condicoes: Ha pontos de decisao ou atividades paralelas?

Passo 2: Use a Task de Criar Workflow

# Ative um agent que pode criar workflows
@architect
 
# Execute a task de criar workflow
*create-workflow

Passo 3: Responda as Perguntas de Elicitacao

A task perguntara:

1. Target Context: core, squad, ou hybrid
2. Workflow Name: ex., feature-development
3. Primary Goal: Qual e o resultado esperado?
4. Stages/Phases: Principais phases do workflow
5. Agent Orchestration: Quais agents em cada stage
6. Resource Requirements: Templates, arquivos de dados necessarios

Passo 4: Estrutura do Workflow

O workflow gerado segue esta estrutura:

workflow:
  id: my-workflow
  name: My Custom Workflow
  version: "1.0"
  description: "Description of what this workflow does"
  type: greenfield | brownfield | generic
  project_types:
    - web-app
    - saas
 
  metadata:
    elicit: true
    confirmation_required: true
 
  phases:
    - phase_1: Phase Name
    - phase_2: Another Phase
 
  sequence:
    - step: step_name
      id: unique-id
      phase: 1
      agent: agent-name
      action: Action description
      creates: output-file.md
      requires: previous-step-id
      optional: false
      notes: |
        Detailed instructions for this step...
      next: next-step-id
 
  flow_diagram: |
    ```mermaid
    graph TD
      A[Start] --> B[Step 1]
      B --> C[Step 2]

decision_guidance: when_to_use:

• Scenario 1
• Scenario 2 when_not_to_use:
• Anti-pattern 1

handoff_prompts: step1_complete: “Step 1 done. Next: @agent for step 2”

### Passo 5: Local de Saida

Workflows sao salvos baseados no contexto:
- **Core**: `.aios-core/development/workflows/[name].yaml`
- **Squad**: `squads/[squad]/workflows/[name].yaml`
- **Hybrid**: `squads/[squad]/workflows/[name].yaml`

---

## Como Executar um Workflow

### Metodo 1: Modo Guiado (Padrao)

```bash
# Iniciar um workflow
*run-workflow story-development-cycle start

# Verificar status
*run-workflow story-development-cycle status

# Continuar para o proximo step
*run-workflow story-development-cycle continue

# Pular step opcional
*run-workflow story-development-cycle skip

# Abortar workflow
*run-workflow story-development-cycle abort

Metodo 2: Modo Engine

# Executar com automacao completa do engine
*run-workflow greenfield-fullstack start --mode engine

State do Workflow

O state e persistido em .aios/[instance-id]-state.yaml:

instance_id: "wf-abc123"
workflow_name: "story-development-cycle"
status: "active"
current_step: 2
total_steps: 4
steps:
  - id: create
    status: completed
    completed_at: "2026-02-02T10:00:00Z"
  - id: validate
    status: in_progress
  - id: implement
    status: pending
  - id: review
    status: pending

Continuidade Multi-Sessao

Workflows persistem entre sessoes do Claude Code:

1. Usuario inicia nova sessao
2. Ativa @aios-master
3. Executa *run-workflow [name] continue
4. Sistema carrega state, mostra step atual
5. Usuario executa step
6. Retorna e executa continue novamente

Padroes de Workflow

O AIOS detecta padroes comuns de workflow baseados no historico de comandos:

Padroes Detectados

Deteccao de Padroes

O sistema usa workflow-patterns.yaml para:

• Detectar em qual workflow voce esta baseado nos comandos usados
• Sugerir proximos steps com scores de confianca
• Fornecer mensagens de handoff contextuais

Melhores Praticas

Design de Workflow

1. Mantenha phases focadas - Cada phase deve ter um proposito claro
2. Defina handoffs claros - Documente o que cada agent passa para o proximo
3. Inclua steps opcionais - Permita flexibilidade para casos simples
4. Adicione orientacao de decisao - Ajude usuarios a saber quando usar/nao usar

Execucao de Workflow

1. Comece com status - Verifique *run-workflow [name] status antes de continuar
2. Siga os prompts de handoff - Eles contem contexto importante
3. Nao pule steps obrigatorios - Apenas steps opcionais podem ser pulados
4. Documente decisoes - Mantenha notas para referencia futura

Criacao de Workflow

1. Teste com casos simples primeiro - Valide que o fluxo funciona
2. Inclua diagramas de fluxo - Representacao visual ajuda no entendimento
3. Adicione notas detalhadas - Usuarios futuros agradecerao
4. Defina tratamento de erros - O que acontece quando as coisas dao errado?

Workflow vs Task

Solucao de Problemas

Problemas Comuns

Workflow nao encontrado:

Error: Workflow '{name}' not found

• Verifique se o nome do workflow corresponde ao ID do arquivo
• Verifique o contexto alvo (core/squad)

Nenhuma instancia ativa:

Error: No active workflow instance found

• Inicie o workflow primeiro com *run-workflow [name] start

Step nao e opcional:

Error: Cannot skip non-optional step

• Complete o step ou aborte o workflow

Obtendo Ajuda

# Listar workflows disponiveis
ls .aios-core/development/workflows/
 
# Validar um workflow
*validate-workflow {name}
 
# Ver detalhes do workflow
cat .aios-core/development/workflows/{name}.yaml

Documentacao Relacionada

• Diagrama de Workflow HybridOps - Padroes de colaboracao humano-agent
• Guia de Referencia de Agents - Agents disponiveis e suas capacidades
• Desenvolvimento Orientado a Story - O workflow de story

Guia de Workflows do AIOS v1.0 - Orquestrando Colaboracao IA-Humano