Workflow: Greenfield Service/API Development

Documento: GREENFIELD-SERVICE-WORKFLOW.md Versão: 1.0 Criado: 2026-02-04 Fonte: .aiox-core/development/workflows/greenfield-service.yaml

Visão Geral

O workflow Greenfield Service/API Development e um fluxo orquestrado de agentes para desenvolvimento de servicos backend, desde a concepcao ate a implementacao completa. Suporta tanto planejamento abrangente para servicos complexos quanto prototipagem rapida para APIs simples.

Tipos de Projeto Suportados

| Tipo | Descricao | |------|-----------| | rest-api | API RESTful tradicional | | graphql-api | API GraphQL | | microservice | Microservico independente | | backend-service | Servico backend generico | | api-prototype | Prototipo rapido de API | | simple-service | Servico simples com escopo reduzido |

Quando Usar Este Workflow

Construcao de APIs ou microservicos de producao
Multiplos endpoints e logica de negocio complexa
Necessidade de documentacao e testes abrangentes
Multiplos membros da equipe envolvidos
Expectativa de manutencao a longo prazo
APIs empresariais ou voltadas para externos

Diagrama do Workflow

graph TD
    subgraph FASE_1["Fase 1: Descoberta e Planejamento"]
        A[Inicio: Desenvolvimento de Servico] --> B[analyst: project-brief.md]
        B -.-> B1[Opcional: brainstorming]
        B -.-> B2[Opcional: market research]
        B --> C[pm: prd.md]
    end

    subgraph FASE_2["Fase 2: Arquitetura"]
        C --> D[architect: architecture.md]
        D -.-> D1[Opcional: technical research]
        D --> E{Arquitetura sugere mudancas no PRD?}
        E -->|Sim| F[pm: atualizar prd.md]
        E -->|Nao| G[po: validar todos artefatos]
        F --> G
    end

    subgraph FASE_3["Fase 3: Validacao"]
        G --> H{PO encontrou problemas?}
        H -->|Sim| I[Retornar ao agente relevante para correcoes]
        H -->|Nao| J[po: fragmentar documentos]
        I --> G
    end

    subgraph FASE_4["Fase 4: Ciclo de Desenvolvimento"]
        J --> K[sm: criar story]
        K --> L{Revisar story draft?}
        L -->|Sim| M[analyst/pm: revisar e aprovar story]
        L -->|Nao| N[dev: implementar story]
        M --> N
        N --> O{Revisao QA?}
        O -->|Sim| P[qa: revisar implementacao]
        O -->|Nao| Q{Mais stories?}
        P --> R{QA encontrou problemas?}
        R -->|Sim| S[dev: enderear feedback QA]
        R -->|Nao| Q
        S --> P
        Q -->|Sim| K
        Q -->|Nao| T{Retrospectiva do Epic?}
    end

    subgraph FASE_5["Fase 5: Conclusao"]
        T -->|Sim| U[po: retrospectiva do epic]
        T -->|Nao| V[Projeto Completo]
        U --> V
    end

    style V fill:#90EE90
    style J fill:#ADD8E6
    style K fill:#ADD8E6
    style N fill:#ADD8E6
    style B fill:#FFE4B5
    style C fill:#FFE4B5
    style D fill:#FFE4B5
    style M fill:#F0E68C
    style P fill:#F0E68C
    style U fill:#F0E68C

Diagrama de Sequencia

sequenceDiagram
    autonumber
    participant U as Usuario
    participant AN as Analyst (Atlas)
    participant PM as PM (Morgan)
    participant AR as Architect (Aria)
    participant PO as PO (Pax)
    participant SM as SM (River)
    participant DEV as Dev (Dex)
    participant QA as QA (Quinn)

    rect rgb(255, 228, 181)
        Note over U,AN: Fase 1 - Descoberta
        U->>AN: Iniciar projeto
        AN->>AN: Brainstorming (opcional)
        AN->>AN: Market Research (opcional)
        AN->>PM: project-brief.md
    end

    rect rgb(255, 228, 181)
        Note over PM,AR: Fase 2 - Planejamento
        PM->>AR: prd.md
        AR->>AR: Technical Research (opcional)
        AR->>PM: architecture.md
        alt Arquitetura sugere mudancas
            AR-->>PM: Sugestoes de mudanca
            PM->>AR: prd.md atualizado
        end
    end

    rect rgb(173, 216, 230)
        Note over PO: Fase 3 - Validacao
        PM->>PO: Todos artefatos
        PO->>PO: Validar com po-master-checklist
        alt Problemas encontrados
            PO-->>AN: Correcoes necessarias
            PO-->>PM: Correcoes necessarias
            PO-->>AR: Correcoes necessarias
        end
        PO->>PO: Fragmentar documentos (shard)
    end

    rect rgb(144, 238, 144)
        Note over SM,QA: Fase 4 - Ciclo de Desenvolvimento
        loop Para cada story do epic
            PO->>SM: Documentos fragmentados
            SM->>SM: Criar story
            opt Review do draft
                SM->>AN: Story draft
                AN->>SM: Story aprovada
            end
            SM->>DEV: story.md
            DEV->>DEV: Implementar
            DEV->>DEV: Atualizar File List
            DEV->>QA: Story: "Review"
            opt Review QA
                QA->>QA: Revisar implementacao
                alt Problemas encontrados
                    QA-->>DEV: Feedback
                    DEV->>QA: Correcoes
                end
            end
            QA->>SM: Story: "Done"
        end
    end

    rect rgb(240, 230, 140)
        Note over PO: Fase 5 - Conclusao
        SM->>PO: Epic completo
        opt Retrospectiva
            PO->>PO: epic-retrospective.md
        end
        PO->>U: Projeto Completo
    end

Steps Detalhados

Step 1: Criar Project Brief

| Campo | Valor | |-------|-------| | Agente | @analyst (Atlas) | | Task | Criar project-brief.md | | Input | Conceito/ideia do projeto, requisitos iniciais | | Output | docs/project-brief.md | | Steps Opcionais | brainstorming_session, market_research_prompt |

Descricao: O analista conduz sessao de brainstorming (opcional), pesquisa de mercado (opcional) e cria o brief do projeto que estabelece o escopo, objetivos e contexto inicial.

Nota: Salvar output final em docs/project-brief.md do projeto.

Step 2: Criar PRD

| Campo | Valor | |-------|-------| | Agente | @pm (Morgan) | | Task | Criar prd.md | | Input | project-brief.md | | Output | docs/prd.md | | Template | prd-tmpl |

Descricao: O Product Manager cria o documento de requisitos do produto (PRD) focado em requisitos de API/servico a partir do brief do projeto.

Nota: Salvar output final em docs/prd.md do projeto.

Step 3: Criar Arquitetura

| Campo | Valor | |-------|-------| | Agente | @architect (Aria) | | Task | Criar architecture.md | | Input | prd.md | | Output | docs/architecture.md | | Template | architecture-tmpl | | Steps Opcionais | technical_research_prompt |

Descricao: O Arquiteto cria a arquitetura do backend/servico. Pode sugerir mudancas nas stories do PRD ou novas stories.

Nota: Salvar output final em docs/architecture.md do projeto.

Step 4: Atualizar PRD (Condicional)

| Campo | Valor | |-------|-------| | Agente | @pm (Morgan) | | Task | Atualizar prd.md | | Condicao | architecture_suggests_prd_changes | | Input | architecture.md com sugestoes | | Output | docs/prd.md (atualizado) |

Descricao: Se o arquiteto sugerir mudancas nas stories, o PM atualiza o PRD e re-exporta o documento completo nao-reduzido.

Step 5: Validar Artefatos

| Campo | Valor | |-------|-------| | Agente | @po (Pax) | | Task | Validar todos artefatos | | Input | Todos os documentos (project-brief.md, prd.md, architecture.md) | | Output | Validacao aprovada ou lista de problemas | | Checklist | po-master-checklist |

Descricao: O Product Owner valida todos os documentos quanto a consistencia e completude. Pode exigir atualizacoes em qualquer documento.

Step 6: Corrigir Problemas (Condicional)

| Campo | Valor | |-------|-------| | Agente | Variavel (depende do problema) | | Task | Corrigir documentos sinalizados | | Condicao | po_checklist_issues | | Input | Lista de problemas do PO | | Output | Documentos corrigidos |

Descricao: Se o PO encontrar problemas, retornar ao agente relevante para correcao e re-exportar documentos atualizados para a pasta docs/.

Step 7: Fragmentar Documentos

| Campo | Valor | |-------|-------| | Agente | @po (Pax) | | Task | Fragmentar documentos | | Input | Todos artefatos validados | | Output | docs/prd/, docs/architecture/ (fragmentados) |

Descricao: Fragmentar documentos para desenvolvimento no IDE:

Opcao A: Usar agente PO para fragmentar: @po e pedir para fragmentar docs/prd.md
Opcao B: Manual: Arrastar task shard-doc + docs/prd.md para o chat

Step 8: Criar Story (Loop)

| Campo | Valor | |-------|-------| | Agente | @sm (River) | | Task | Criar story | | Input | Documentos fragmentados | | Output | story.md | | Repete | Para cada epic |

Descricao: Ciclo de criacao de stories:

SM Agent (Nova Sessao): @sm -> *create
Cria proxima story a partir dos documentos fragmentados
Story inicia em status "Draft"

Step 9: Revisar Story Draft (Opcional)

| Campo | Valor | |-------|-------| | Agente | @analyst ou @pm | | Task | Revisar story draft | | Condicao | user_wants_story_review | | Input | story.md em draft | | Output | Story aprovada (Draft -> Approved) |

Descricao: Revisao opcional para aprovar story draft:

Revisar completude e alinhamento da story
Atualizar status: Draft -> Approved

Step 10: Implementar Story

| Campo | Valor | |-------|-------| | Agente | @dev (Dex) | | Task | Implementar story | | Input | story.md aprovada | | Output | Arquivos de implementacao |

Descricao: Dev Agent (Nova Sessao): @dev

Implementa story aprovada
Atualiza File List com todas as mudancas
Marca story como "Review" quando completo

Step 11: Revisar Implementacao (Opcional)

| Campo | Valor | |-------|-------| | Agente | @qa (Quinn) | | Task | Revisar implementacao | | Condicao | Opcional | | Input | Arquivos de implementacao | | Output | Implementacao aprovada ou feedback |

Descricao: QA Agent (Nova Sessao): @qa -> *review-story

Revisao senior dev com capacidade de refatoracao
Corrige problemas pequenos diretamente
Deixa checklist para itens restantes
Atualiza status da story (Review -> Done ou permanece Review)

Step 12: Enderezar Feedback QA (Condicional)

| Campo | Valor | |-------|-------| | Agente | @dev (Dex) | | Task | Enderezar feedback QA | | Condicao | qa_left_unchecked_items | | Input | Checklist QA com itens pendentes | | Output | Implementacao corrigida |

Descricao: Se QA deixou itens nao marcados:

Dev Agent (Nova Sessao): Enderezar itens restantes
Retornar ao QA para aprovacao final

Step 13: Continuar Ciclo

| Campo | Valor | |-------|-------| | Acao | Continuar para todas as stories | | Condicao | Ate que todas as stories do PRD estejam completas |

Descricao: Repetir ciclo de stories (SM -> Dev -> QA) para todas as stories do epic.

Step 14: Retrospectiva do Epic (Opcional)

| Campo | Valor | |-------|-------| | Agente | @po (Pax) | | Task | Retrospectiva do epic | | Condicao | epic_complete | | Output | epic-retrospective.md |

Descricao: Apos conclusao do epic:

Validar que o epic foi concluido corretamente
Documentar aprendizados e melhorias

Step 15: Projeto Completo

| Campo | Valor | |-------|-------| | Acao | Projeto completo | | Estado Final | Todas stories implementadas e revisadas |

Descricao: Todas as stories implementadas e revisadas! Fase de desenvolvimento do servico completa.

Referencia: .aiox-core/data/aiox-kb.md#IDE Development Workflow

Agentes Participantes

graph LR
    subgraph Planejamento
        AN[Analyst<br/>Atlas]
        PM[PM<br/>Morgan]
        AR[Architect<br/>Aria]
    end

    subgraph Validacao
        PO[PO<br/>Pax]
    end

    subgraph Desenvolvimento
        SM[SM<br/>River]
        DEV[Dev<br/>Dex]
        QA[QA<br/>Quinn]
    end

    AN -->|project-brief| PM
    PM -->|prd| AR
    AR -->|architecture| PM
    PM -->|artefatos| PO
    AR -->|artefatos| PO
    PO -->|docs fragmentados| SM
    SM -->|story| DEV
    DEV -->|implementacao| QA
    QA -->|feedback| DEV

Tabela de Agentes

| ID | Nome | Titulo | Icone | Responsabilidade no Workflow | |----|------|--------|-------|------------------------------| | analyst | Atlas | Business Analyst | analise | Criar project brief, brainstorming, market research | | pm | Morgan | Product Manager | estrategia | Criar e atualizar PRD | | architect | Aria | Architect | arquitetura | Criar arquitetura do servico | | po | Pax | Product Owner | validacao | Validar artefatos, fragmentar docs, retrospectiva | | sm | River | Scrum Master | facilitacao | Criar stories do epic | | dev | Dex | Full Stack Developer | implementacao | Implementar stories | | qa | Quinn | Test Architect | qualidade | Revisar implementacao |

Tasks Executadas

| Step | Task | Agente | Obrigatoria | |------|------|--------|-------------| | 1 | create-project-brief | analyst | Sim | | 1a | brainstorming_session | analyst | Nao | | 1b | market_research_prompt | analyst | Nao | | 2 | create-prd | pm | Sim | | 3 | create-full-stack-architecture | architect | Sim | | 3a | technical_research_prompt | architect | Nao | | 4 | update-prd | pm | Condicional | | 5 | execute-checklist (po-master-checklist) | po | Sim | | 6 | fix-documents | varios | Condicional | | 7 | shard-doc | po | Sim | | 8 | create-next-story | sm | Sim (loop) | | 9 | review-story-draft | analyst/pm | Nao | | 10 | develop-story | dev | Sim (loop) | | 11 | review-story | qa | Nao | | 12 | apply-qa-fixes | dev | Condicional | | 14 | epic-retrospective | po | Nao |

Pre-requisitos

Ferramentas Necessarias

| Ferramenta | Proposito | |------------|-----------| | Node.js 18+ | Runtime de desenvolvimento | | Git | Controle de versao | | GitHub CLI (gh) | Integracao GitHub | | Supabase CLI | Operacoes de banco de dados |

Arquivos de Configuracao

| Arquivo | Descricao | |---------|-----------| | .aiox-core/core-config.yaml | Configuracao do framework | | .env | Variaveis de ambiente | | projects/{Name}/.project.yaml | Configuracoes especificas do projeto |

Templates Necessarios

| Template | Localizacao | Agente | |----------|-------------|--------| | project-brief-tmpl.yaml | .aiox-core/development/templates/ | analyst | | prd-tmpl.yaml | .aiox-core/development/templates/ | pm | | architecture-tmpl.yaml | .aiox-core/development/templates/ | architect | | story-tmpl.yaml | .aiox-core/development/templates/ | sm | | qa-gate-tmpl.yaml | .aiox-core/development/templates/ | qa |

Checklists

| Checklist | Agente | Uso | |-----------|--------|-----| | po-master-checklist.md | po | Validacao de artefatos | | story-draft-checklist.md | sm | Validacao de story | | story-dod-checklist.md | dev | Definition of Done |

Entradas e Saidas

Entradas do Workflow

| Entrada | Descricao | Fornecido Por | |---------|-----------|---------------| | Conceito do projeto | Ideia inicial, objetivos, escopo | Usuario | | Requisitos de negocio | Necessidades do cliente/stakeholder | Usuario | | Restricoes tecnicas | Limitacoes conhecidas | Usuario | | Preferencias de stack | Tecnologias preferidas | Usuario |

Saidas do Workflow

| Saida | Localizacao | Criado Por | |-------|-------------|------------| | project-brief.md | docs/project-brief.md | analyst | | prd.md | docs/prd.md | pm | | architecture.md | docs/architecture.md | architect | | PRD fragmentado | docs/prd/ | po | | Arquitetura fragmentada | docs/architecture/ | po | | Stories | docs/stories/epic-X/ | sm | | Codigo implementado | apps/, packages/, infrastructure/ | dev | | QA Gates | docs/qa/gates/ | qa | | Retrospectiva | docs/epic-retrospective.md | po |

Pontos de Decisao

flowchart TD
    D1{Arquitetura sugere<br/>mudancas no PRD?}
    D2{PO encontrou<br/>problemas?}
    D3{Revisar story<br/>draft?}
    D4{Revisao QA?}
    D5{QA encontrou<br/>problemas?}
    D6{Mais stories?}
    D7{Retrospectiva<br/>do epic?}

    D1 -->|Sim| A1[PM atualiza PRD]
    D1 -->|Nao| A2[Continuar para validacao]

    D2 -->|Sim| A3[Retornar ao agente relevante]
    D2 -->|Nao| A4[Fragmentar documentos]

    D3 -->|Sim| A5[Analyst/PM revisa]
    D3 -->|Nao| A6[Dev implementa]

    D4 -->|Sim| A7[QA revisa]
    D4 -->|Nao| A8[Verificar mais stories]

    D5 -->|Sim| A9[Dev endereza feedback]
    D5 -->|Nao| A10[Verificar mais stories]

    D6 -->|Sim| A11[Criar proxima story]
    D6 -->|Nao| A12[Verificar retrospectiva]

    D7 -->|Sim| A13[PO faz retrospectiva]
    D7 -->|Nao| A14[Projeto completo]

Tabela de Decisoes

| Ponto | Condicao | Acao se Verdadeiro | Acao se Falso | |-------|----------|-------------------|---------------| | D1 | architecture_suggests_prd_changes | PM atualiza PRD | Continuar para PO | | D2 | po_checklist_issues | Retornar para correcoes | Fragmentar docs | | D3 | user_wants_story_review | Analyst/PM revisa draft | Dev implementa diretamente | | D4 | Preferencia do usuario | QA revisa implementacao | Verificar mais stories | | D5 | qa_left_unchecked_items | Dev endereza feedback | Story concluida | | D6 | Stories restantes no epic | Criar proxima story | Verificar retrospectiva | | D7 | epic_complete e preferencia | PO faz retrospectiva | Projeto completo |

Handoff Prompts

Mensagens padronizadas para transicoes entre agentes:

| Transicao | Prompt | |-----------|--------| | Analyst -> PM | "Project brief is complete. Save it as docs/project-brief.md in your project, then create the PRD." | | PM -> Architect | "PRD is ready. Save it as docs/prd.md in your project, then create the service architecture." | | Architect (review) | "Architecture complete. Save it as docs/architecture.md. Do you suggest any changes to the PRD stories or need new stories added?" | | Architect -> PM | "Please update the PRD with the suggested story changes, then re-export the complete prd.md to docs/." | | Artefatos -> PO | "All documents ready in docs/ folder. Please validate all artifacts for consistency." | | PO (issues) | "PO found issues with [document]. Please return to [agent] to fix and re-save the updated document." | | Workflow complete | "All planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development." |

Troubleshooting

Problemas Comuns

1. PRD Incompleto

Sintoma: Arquiteto nao consegue criar arquitetura adequada.

Causa: Project brief faltando informacoes cruciais.

Solucao:

Retornar ao analyst
Executar *brainstorm para descobrir requisitos faltantes
Atualizar project-brief.md
PM recriar PRD

2. Arquitetura Incompativel

Sintoma: Stories nao mapeiam para arquitetura.

Causa: PRD e arquitetura desalinhados.

Solucao:

Arquiteto sugere mudancas no PRD
PM atualiza PRD
PO valida consistencia
Re-fragmentar documentos

3. Story Bloqueada em Draft

Sintoma: Story nao progride para implementacao.

Causa: Story draft falhou na validacao.

Solucao:

SM revisar checklist story-draft-checklist
Corrigir itens faltantes
Re-validar com analyst/pm se necessario

4. Implementacao Falha em QA

Sintoma: QA rejeita implementacao repetidamente.

Causa: Requisitos mal interpretados ou codigo de baixa qualidade.

Solucao:

Dev revisar acceptance criteria da story
Executar *apply-qa-fixes com feedback do QA
Rodar CodeRabbit para validacao automatica
Re-submeter para QA

5. Ciclo de Desenvolvimento Infinito

Sintoma: Stories nao sao concluidas.

Causa: Escopo muito grande ou dependencias nao resolvidas.

Solucao:

PO revisar backlog e prioridades
SM fragmentar stories grandes
Identificar e resolver bloqueios
Considerar MVP mais restrito

Logs e Diagnostico

| Tipo | Localizacao | |------|-------------| | Logs do agente | .aiox/logs/agent.log | | Status do projeto | .aiox/project-registry.yaml | | Decision logs | .ai/decision-log-{story-id}.md | | QA reports | docs/qa/gates/ |

Comandos de Debug

# Verificar status do projeto
cat .aiox/project-status.yaml

# Listar stories em progresso
ls docs/stories/epic-*/

# Verificar logs do agente
tail -f .aiox/logs/agent.log

# Habilitar modo debug
export AIOX_DEBUG=true

Referencias

Arquivos do Workflow

| Arquivo | Descricao | |---------|-----------| | .aiox-core/development/workflows/greenfield-service.yaml | Definicao do workflow | | .aiox-core/data/aiox-kb.md | Knowledge base do AIOX |

Agentes

| Arquivo | Agente | |---------|--------| | .aiox-core/development/agents/analyst.md | Atlas (Analyst) | | .aiox-core/development/agents/pm.md | Morgan (PM) | | .aiox-core/development/agents/architect.md | Aria (Architect) | | .aiox-core/development/agents/po.md | Pax (PO) | | .aiox-core/development/agents/sm.md | River (SM) | | .aiox-core/development/agents/dev.md | Dex (Dev) | | .aiox-core/development/agents/qa.md | Quinn (QA) |

Tasks Principais

| Arquivo | Task | |---------|------| | .aiox-core/development/tasks/create-doc.md | Criacao de documentos | | .aiox-core/development/tasks/shard-doc.md | Fragmentacao de documentos | | .aiox-core/development/tasks/sm-create-next-story.md | Criacao de stories | | .aiox-core/development/tasks/dev-develop-story.md | Implementacao de stories | | .aiox-core/development/tasks/qa-review-story.md | Revisao de implementacao | | .aiox-core/development/tasks/execute-checklist.md | Execucao de checklists |

Templates

| Arquivo | Template | |---------|----------| | .aiox-core/development/templates/project-brief-tmpl.yaml | Project Brief | | .aiox-core/development/templates/prd-tmpl.yaml | PRD | | .aiox-core/development/templates/architecture-tmpl.yaml | Arquitetura | | .aiox-core/development/templates/story-tmpl.yaml | User Story | | .aiox-core/development/templates/qa-gate-tmpl.yaml | QA Gate |

Checklists

| Arquivo | Checklist | |---------|-----------| | .aiox-core/development/checklists/po-master-checklist.md | Validacao PO | | .aiox-core/development/checklists/story-draft-checklist.md | Validacao Story Draft | | .aiox-core/development/checklists/story-dod-checklist.md | Definition of Done |

Historico de Alteracoes

| Data | Versao | Descricao | |------|--------|-----------| | 2026-02-04 | 1.0 | Criacao inicial do documento |

Documentacao gerada automaticamente a partir de .aiox-core/development/workflows/greenfield-service.yaml