aiox-core 5.0.0

package/docs/aiox-workflows/story-development-cycle-workflow.md

@@ -0,0 +1,843 @@
+# Workflow: Story Development Cycle
+
+**Versão:** 1.0
+**Tipo:** Workflow Generico
+**Autor:** Orion (AIOX Master)
+**Data de Criação:** 2025-01-30
+**Tags:** story, development-cycle, quality-gate, agile, generic
+
+---
+
+## Visão Geral
+
+O **Story Development Cycle** e o workflow central do AIOX para desenvolvimento de stories. Ele automatiza o fluxo completo desde a criacao ate a entrega com quality gate integrado, seguindo a sequencia: **criar -> validar -> implementar -> QA review**.
+
+### Objetivo
+
+Garantir que cada story passe por um processo estruturado e rastreavel, com pontos de validação em cada fase, reduzindo retrabalho e aumentando a qualidade das entregas.
+
+### Tipos de Projeto Suportados
+
+| Tipo | Descrição |
+|------|-----------|
+| `greenfield` | Projetos novos, do zero |
+| `brownfield` | Projetos existentes, manutenção |
+| `feature-development` | Desenvolvimento de novas funcionalidades |
+| `bug-fix` | Correção de bugs |
+| `enhancement` | Melhorias em funcionalidades existentes |
+
+---
+
+## Diagrama Mermaid do Workflow
+
+### Fluxo Principal
+
+```mermaid
+flowchart TD
+    subgraph PHASE_1["Fase 1: Story Creation"]
+        START([Inicio: Story Development Cycle]) --> SM_CREATE
+        SM_CREATE["@sm: Criar próxima story<br/>Task: create-next-story"]
+    end
+
+    subgraph PHASE_2["Fase 2: Story Validation"]
+        SM_CREATE --> PO_VALIDATE["@po: Validar story<br/>Task: validate-next-story<br/>10 Checks"]
+        PO_VALIDATE --> VALID_DECISION{Validação OK?}
+        VALID_DECISION -->|Não| FEEDBACK_SM["Feedback para SM<br/>Story retorna para ajustes"]
+        FEEDBACK_SM --> SM_CREATE
+        VALID_DECISION -->|Sim| DEV_IMPLEMENT
+    end
+
+    subgraph PHASE_3["Fase 3: Implementation"]
+        DEV_IMPLEMENT["@dev: Implementar story<br/>Task: dev-develop-story<br/>+ CodeRabbit Self-Healing"]
+    end
+
+    subgraph PHASE_4["Fase 4: QA Review"]
+        DEV_IMPLEMENT --> QA_REVIEW["@qa: Review + Quality Gate<br/>Task: qa-gate"]
+        QA_REVIEW --> QA_DECISION{Quality Gate OK?}
+        QA_DECISION -->|Não| FEEDBACK_DEV["Feedback para Dev<br/>Checklist de fixes"]
+        FEEDBACK_DEV --> DEV_IMPLEMENT
+        QA_DECISION -->|Sim| STORY_DONE
+    end
+
+    subgraph COMPLETION["Conclusão"]
+        STORY_DONE([Story Done!])
+        STORY_DONE --> MORE_STORIES{Mais stories?}
+        MORE_STORIES -->|Sim| SM_CREATE
+        MORE_STORIES -->|Não| CYCLE_COMPLETE([Ciclo Completo])
+    end
+
+    style CYCLE_COMPLETE fill:#90EE90
+    style STORY_DONE fill:#90EE90
+    style SM_CREATE fill:#87CEEB
+    style PO_VALIDATE fill:#FFE4B5
+    style DEV_IMPLEMENT fill:#98FB98
+    style QA_REVIEW fill:#DDA0DD
+    style FEEDBACK_SM fill:#FFB6C1
+    style FEEDBACK_DEV fill:#FFB6C1
+```
+
+### Fluxo de Status da Story
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: SM cria story
+    Draft --> Ready: PO valida (10 checks)
+    Ready --> InProgress: Dev inicia implementação
+    InProgress --> InReview: Dev conclui + CodeRabbit
+    InReview --> Done: QA aprova
+    InReview --> InProgress: QA rejeita
+    Draft --> Draft: PO rejeita validação
+    Done --> [*]
+
+    note right of Draft : Status inicial
+    note right of Ready : Pronta para dev
+    note right of InProgress : Em desenvolvimento
+    note right of InReview : Aguardando QA
+    note right of Done : Concluida
+```
+
+### Diagrama de Interação entre Agentes
+
+```mermaid
+sequenceDiagram
+    participant U as Usuario
+    participant SM as @sm (River)
+    participant PO as @po (Pax)
+    participant DEV as @dev (Dex)
+    participant QA as @qa (Quinn)
+    participant CR as CodeRabbit
+
+    U->>SM: *workflow story-development-cycle
+
+    rect rgb(135, 206, 235)
+        Note over SM: Fase 1: Criacao
+        SM->>SM: Identifica próxima story
+        SM->>SM: Extrai requisitos do epic
+        SM->>SM: Popula template
+        SM-->>U: Story criada (status: Draft)
+    end
+
+    rect rgb(255, 228, 181)
+        Note over PO: Fase 2: Validação
+        SM->>PO: Handoff para validação
+        PO->>PO: Executa 10 checks
+        alt Validação falhou
+            PO-->>SM: Feedback com issues
+            SM->>SM: Ajusta story
+        else Validação OK
+            PO-->>U: Story validada (status: Ready)
+        end
+    end
+
+    rect rgb(152, 251, 152)
+        Note over DEV: Fase 3: Implementação
+        PO->>DEV: Handoff para implementação
+        DEV->>DEV: Implementa tasks
+        DEV->>DEV: Escreve testes
+        DEV->>CR: Pre-commit review
+        CR-->>DEV: Feedback (CRITICAL/HIGH)
+        DEV->>DEV: Self-healing loop
+        DEV-->>U: Story implementada (status: In Review)
+    end
+
+    rect rgb(221, 160, 221)
+        Note over QA: Fase 4: QA Review
+        DEV->>QA: Handoff para review
+        QA->>CR: Review automatizado
+        CR-->>QA: Scan de qualidade
+        QA->>QA: Review manual
+        alt Quality Gate falhou
+            QA-->>DEV: Feedback com fixes
+            DEV->>DEV: Aplica correções
+        else Quality Gate OK
+            QA-->>U: Story aprovada (status: Done)
+        end
+    end
+```
+
+---
+
+## Steps Detalhados
+
+### Step 1: Create Story (Fase 1)
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | `create` |
+| **Agente** | @sm (River - Scrum Master) |
+| **Ação** | Criar próxima story |
+| **Task** | `create-next-story.md` |
+
+#### Descrição
+
+O Scrum Master (River) identifica e cria a próxima story do backlog utilizando o PRD shardado ou documentação do projeto como fonte.
+
+#### Inputs
+
+| Input | Tipo | Origem | Obrigatório |
+|-------|------|--------|-------------|
+| `name` | string | User Input | Sim |
+| `options` | object | User Input | Não |
+| `force` | boolean | User Input | Não |
+| PRD shardado | arquivo | Sistema de arquivos | Sim |
+| Contexto do epic | documento | docs/stories/epic-X/ | Sim |
+
+#### Outputs
+
+| Output | Tipo | Destino |
+|--------|------|---------|
+| `story_file` | arquivo | `{devStoryLocation}/{epicNum}.{storyNum}.story.md` |
+| `story_id` | string | Contexto do workflow |
+| `validation_report` | object | Memória |
+
+#### Critérios de Sucesso
+
+- [ ] Story criada com titulo descritivo
+- [ ] Acceptance criteria definidos
+- [ ] Escopo claro e delimitado
+- [ ] Dependencias identificadas
+
+#### Status da Story
+
+- **Antes:** N/A
+- **Depois:** `Draft`
+
+---
+
+### Step 2: Validate Story (Fase 2)
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | `validate` |
+| **Agente** | @po (Pax - Product Owner) |
+| **Ação** | Validar story (10 checks) |
+| **Task** | `validate-next-story.md` |
+| **Requer** | `create` |
+
+#### Descrição
+
+O Product Owner (Pax) valida a story criada usando um checklist rigoroso de 10 pontos, garantindo que a story esta pronta para implementação.
+
+#### Inputs
+
+| Input | Tipo | Origem | Obrigatório |
+|-------|------|--------|-------------|
+| `story_file` | arquivo | Output do step anterior | Sim |
+| `target` | string | User Input | Sim |
+| `criteria` | array | Config | Sim |
+| `strict` | boolean | User Input | Não (default: true) |
+
+#### Outputs
+
+| Output | Tipo | Destino |
+|--------|------|---------|
+| `validation_report` | object | Arquivo (.ai/*.json) |
+| `validation_result` | boolean | Return value |
+| `errors` | array | Memória |
+| `story_status` | string | Story file |
+
+#### Checklist de Validação (10 Pontos)
+
+| # | Check | Descrição |
+|---|-------|-----------|
+| 1 | Titulo claro e objetivo | O titulo descreve precisamente o que sera feito |
+| 2 | Descrição completa | Problema/necessidade claramente explicado |
+| 3 | Acceptance criteria testaveis | Formato Given/When/Then preferido |
+| 4 | Escopo bem definido | O que esta IN e OUT claramente listado |
+| 5 | Dependencias mapeadas | Stories ou recursos prerequisitos identificados |
+| 6 | Estimativa de complexidade | Pontos de complexidade ou T-shirt sizing |
+| 7 | Valor de negocio | Beneficio para o usuario/negocio claro |
+| 8 | Riscos documentados | Potenciais problemas identificados |
+| 9 | Critérios de Done | Definicao clara de quando esta completa |
+| 10 | Alinhamento com PRD/Epic | Consistencia com documentos fonte |
+
+#### Resultado
+
+| Resultado | Ação |
+|-----------|------|
+| **Aprovada** | Status muda para `Ready`, prossegue para implementação |
+| **Rejeitada** | Retorna para SM com feedback detalhado |
+
+#### Status da Story
+
+- **Antes:** `Draft`
+- **Depois (Sucesso):** `Ready`
+- **Depois (Falha):** `Draft` (retorna para SM)
+
+---
+
+### Step 3: Implement Story (Fase 3)
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | `implement` |
+| **Agente** | @dev (Dex - Full Stack Developer) |
+| **Ação** | Implementar story |
+| **Task** | `dev-develop-story.md` |
+| **Requer** | `validate` |
+
+#### Descrição
+
+O Dev Agent (Dex) implementa a story validada, seguindo os acceptance criteria e as tarefas definidas. Inclui o CodeRabbit Self-Healing Loop para garantir qualidade do codigo.
+
+#### Modos de Execução
+
+| Modo | Descrição | Prompts ao Usuario |
+|------|-----------|-------------------|
+| **YOLO** | Execução autônoma com logging de decisões | 0-1 |
+| **Interactive** | Checkpoints de decisao e feedback educacional (DEFAULT) | 5-10 |
+| **Pre-Flight** | Planejamento completo antes da execucao | 10-15 (upfront) |
+
+#### Inputs
+
+| Input | Tipo | Origem | Obrigatório |
+|-------|------|--------|-------------|
+| `story_file` | arquivo | Output do step anterior | Sim |
+| `task` | string | User Input | Sim |
+| `parameters` | object | User Input | Não |
+| `mode` | string | User Input | Não (default: interactive) |
+
+#### Outputs
+
+| Output | Tipo | Destino |
+|--------|------|---------|
+| `implementation_files` | array | Sistema de arquivos |
+| `test_results` | object | Console/logs |
+| `commit_hash` | string | Git |
+| `execution_result` | object | Memória |
+| `logs` | array | `.ai/logs/*` |
+| `decision_log` | arquivo | `.ai/decision-log-{story-id}.md` (modo YOLO) |
+
+#### Fluxo de Execução
+
+```mermaid
+flowchart LR
+    A[Ler task] --> B[Implementar task + subtasks]
+    B --> C[Escrever testes]
+    C --> D[Executar validacoes]
+    D --> E{Todas passaram?}
+    E -->|Sim| F[Marcar checkbox [x]]
+    E -->|Não| B
+    F --> G[Atualizar File List]
+    G --> H{Mais tasks?}
+    H -->|Sim| A
+    H -->|Não| I[CodeRabbit Self-Healing]
+    I --> J[Story DOD Checklist]
+    J --> K[Status: In Review]
+```
+
+#### CodeRabbit Self-Healing Loop
+
+```mermaid
+flowchart TD
+    START[Iniciar Self-Healing] --> RUN[Executar CodeRabbit CLI]
+    RUN --> PARSE[Analisar resultados]
+    PARSE --> CHECK{Issues CRITICAL?}
+    CHECK -->|Não| DOC[Documentar HIGH issues]
+    DOC --> PASS[PASSED - Prosseguir]
+    CHECK -->|Sim| ITER{iteration < 2?}
+    ITER -->|Sim| FIX[Tentar auto-fix]
+    FIX --> INCREMENT[iteration++]
+    INCREMENT --> RUN
+    ITER -->|Não| FAIL[FAILED - HALT]
+    FAIL --> MANUAL[Requer intervencao manual]
+```
+
+#### Critérios de Sucesso
+
+- [ ] Todos os acceptance criteria implementados
+- [ ] Testes passando
+- [ ] File List atualizada
+- [ ] Codigo commitado
+- [ ] CodeRabbit Self-Healing passou
+
+#### Status da Story
+
+- **Antes:** `Ready`
+- **Durante:** `In Progress`
+- **Depois:** `In Review`
+
+---
+
+### Step 4: QA Review (Fase 4)
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | `review` |
+| **Agente** | @qa (Quinn - Test Architect) |
+| **Ação** | Review final + Quality Gate |
+| **Task** | `qa-gate.md` |
+| **Requer** | `implement` |
+
+#### Descrição
+
+O QA Agent (Quinn) executa o review final com quality gate, validando codigo, testes, e aderencia aos acceptance criteria.
+
+#### Inputs
+
+| Input | Tipo | Origem | Obrigatório |
+|-------|------|--------|-------------|
+| `story_file` | arquivo | Output do step anterior | Sim |
+| `target` | string | User Input | Sim |
+| `criteria` | array | Config | Sim |
+| `strict` | boolean | User Input | Não (default: true) |
+
+#### Outputs
+
+| Output | Tipo | Destino |
+|--------|------|---------|
+| `qa_report` | arquivo | `{qaLocation}/gates/{epic}.{story}-{slug}.yml` |
+| `quality_gate_status` | string | PASS/CONCERNS/FAIL/WAIVED |
+| `story_final_status` | string | Story file |
+| `validation_result` | boolean | Return value |
+| `errors` | array | Memória |
+
+#### Quality Gate Checks
+
+| # | Check | Descrição |
+|---|-------|-----------|
+| 1 | Code review | Padroes, legibilidade, manutenibilidade |
+| 2 | Testes unitarios | Adequados e passando |
+| 3 | Acceptance criteria | Todos atendidos |
+| 4 | Sem regressoes | Funcionalidades existentes preservadas |
+| 5 | Performance | Dentro dos limites aceitaveis |
+| 6 | Seguranca | OWASP basics verificados |
+| 7 | Documentação | Atualizada se necessario |
+
+#### Decisões do Quality Gate
+
+| Decisão | Critérios | Ação |
+|---------|-----------|------|
+| **PASS** | Todos os checks passaram, sem issues HIGH | Aprovar story |
+| **CONCERNS** | Issues nao-bloqueantes presentes | Aprovar com observacoes |
+| **FAIL** | Issues HIGH/CRITICAL presentes | Retornar para Dev |
+| **WAIVED** | Issues explicitamente aceitas | Aprovar com waiver documentado |
+
+#### Severidade de Issues
+
+| Severidade | Descrição | Ação |
+|------------|-----------|------|
+| `low` | Issues menores, cosmeticos | Documentar |
+| `medium` | Deveria corrigir em breve | Criar tech debt |
+| `high` | Critico, deveria bloquear release | Retornar para Dev |
+
+#### Resultado
+
+| Resultado | Ação |
+|-----------|------|
+| **Aprovada** | Status muda para `Done` |
+| **Rejeitada** | Retorna para Dev com checklist de fixes |
+
+#### Status da Story
+
+- **Antes:** `In Review`
+- **Depois (Sucesso):** `Done`
+- **Depois (Falha):** `In Progress` (retorna para Dev)
+
+---
+
+## Agentes Participantes
+
+### @sm - River (Scrum Master)
+
+| Aspecto | Descrição |
+|---------|-----------|
+| **Icone** | 🌊 |
+| **Arquetipo** | Facilitator |
+| **Papel** | Technical Scrum Master - Story Preparation Specialist |
+| **Foco** | Criar stories claras e acionaveis para agentes de desenvolvimento |
+| **Responsabilidades** | Story creation, epic management, sprint planning, local branch management |
+
+**Comandos Relevantes:**
+- `*draft` - Criar próxima story
+- `*story-checklist` - Executar checklist de story
+
+---
+
+### @po - Pax (Product Owner)
+
+| Aspecto | Descrição |
+|---------|-----------|
+| **Icone** | 🎯 |
+| **Arquetipo** | Balancer |
+| **Papel** | Technical Product Owner & Process Steward |
+| **Foco** | Validar coesao de artefatos e garantir qualidade de documentação |
+| **Responsabilidades** | Backlog management, story validation, prioritization, PM tool sync |
+
+**Comandos Relevantes:**
+- `*validate-story-draft {story}` - Validar qualidade da story
+- `*backlog-review` - Review para sprint planning
+
+---
+
+### @dev - Dex (Full Stack Developer)
+
+| Aspecto | Descrição |
+|---------|-----------|
+| **Icone** | 💻 |
+| **Arquetipo** | Builder |
+| **Papel** | Expert Senior Software Engineer & Implementation Specialist |
+| **Foco** | Executar tarefas de story com precisao e testes abrangentes |
+| **Responsabilidades** | Code implementation, testing, debugging, refactoring |
+
+**Comandos Relevantes:**
+- `*develop {story-id}` - Implementar story
+- `*run-tests` - Executar linting e testes
+- `*apply-qa-fixes` - Aplicar correções do QA
+
+---
+
+### @qa - Quinn (Test Architect)
+
+| Aspecto | Descrição |
+|---------|-----------|
+| **Icone** | ✅ |
+| **Arquetipo** | Guardian |
+| **Papel** | Test Architect with Quality Advisory Authority |
+| **Foco** | Análise de qualidade abrangente atraves de arquitetura de testes |
+| **Responsabilidades** | Code review, quality gates, test strategy, risk assessment |
+
+**Comandos Relevantes:**
+- `*review {story}` - Review abrangente de story
+- `*gate {story}` - Criar decisao de quality gate
+- `*code-review {scope}` - Review automatizado
+
+---
+
+## Tasks Executadas
+
+### Mapa de Tasks por Fase
+
+```mermaid
+graph TD
+    subgraph "Fase 1: Criacao"
+        T1[create-next-story.md]
+    end
+
+    subgraph "Fase 2: Validação"
+        T2[validate-next-story.md]
+    end
+
+    subgraph "Fase 3: Implementação"
+        T3[dev-develop-story.md]
+        T3a[story-dod-checklist.md]
+    end
+
+    subgraph "Fase 4: QA Review"
+        T4[qa-gate.md]
+    end
+
+    T1 --> T2
+    T2 --> T3
+    T3 --> T3a
+    T3a --> T4
+```
+
+### Detalhamento das Tasks
+
+| Task | Arquivo | Agente | Propósito |
+|------|---------|--------|-----------|
+| Create Next Story | `create-next-story.md` | @sm | Criar story a partir do PRD/epic |
+| Validate Next Story | `validate-next-story.md` | @po | Validar completude e qualidade |
+| Develop Story | `dev-develop-story.md` | @dev | Implementar codigo e testes |
+| Story DOD Checklist | `story-dod-checklist.md` | @dev | Verificar Definition of Done |
+| QA Gate | `qa-gate.md` | @qa | Criar decisao de quality gate |
+
+---
+
+## Pré-requisitos
+
+### Configuração do Projeto
+
+1. **core-config.yaml** - Arquivo de configuracao AIOX obrigatorio
+   - `devStoryLocation` - Local das stories
+   - `prd.*` - Configuração do PRD
+   - `architecture.*` - Configuração da arquitetura
+   - `qa.qaLocation` - Local dos artefatos de QA
+
+2. **Story Template** - `story-tmpl.yaml` disponivel em `.aiox-core/development/templates/`
+
+3. **Checklists** - Checklists obrigatorios disponiveis:
+   - `story-draft-checklist.md`
+   - `story-dod-checklist.md`
+   - `po-master-checklist.md`
+
+### Documentação Prerequisita
+
+| Documento | Local | Obrigatório |
+|-----------|-------|-------------|
+| PRD (shardado ou monolitico) | Conforme `prd.*` config | Sim |
+| Epic file | `docs/stories/epic-X/` | Sim |
+| Architecture docs | Conforme `architecture.*` config | Sim |
+
+### Ferramentas Integradas
+
+| Ferramenta | Propósito | Agentes |
+|------------|-----------|---------|
+| `git` | Controle de versao | @sm, @dev, @qa |
+| `coderabbit` | Review automatizado | @dev, @qa |
+| `clickup` | Tracking de stories | @sm, @po |
+| `context7` | Documentação de libs | Todos |
+| `github-cli` | Operacoes GitHub | @po, @qa |
+
+---
+
+## Entradas e Saidas
+
+### Entradas do Workflow
+
+| Entrada | Tipo | Fonte | Descrição |
+|---------|------|-------|-----------|
+| Epic requirements | Documento | `docs/stories/epic-X/` | Requisitos do epic |
+| PRD | Documento | Conforme config | Product Requirements |
+| Architecture docs | Documentos | `docs/architecture/` | Especificacoes tecnicas |
+| Story template | YAML | `.aiox-core/development/templates/` | Template padrao |
+
+### Saidas do Workflow
+
+| Saida | Tipo | Destino | Descrição |
+|-------|------|---------|-----------|
+| Story file | Markdown | `{devStoryLocation}/{epic}.{story}.story.md` | Story completa |
+| Implementation files | Codigo | Conforme story tasks | Codigo implementado |
+| Test files | Codigo | Conforme padrao do projeto | Testes unitarios |
+| QA Gate file | YAML | `{qaLocation}/gates/{epic}.{story}-{slug}.yml` | Decisão de QA |
+| Decision log | Markdown | `.ai/decision-log-{story-id}.md` | Log de decisões (modo YOLO) |
+
+---
+
+## Pontos de Decisão
+
+### Diagrama de Decisões
+
+```mermaid
+graph TD
+    D1{Validação PO<br/>10 checks passaram?}
+    D1 -->|Sim| CONTINUE1[Prosseguir para Dev]
+    D1 -->|Não| RETURN1[Retornar para SM]
+
+    D2{Quality Gate<br/>Issues CRITICAL/HIGH?}
+    D2 -->|Não| CONTINUE2[Aprovar Story]
+    D2 -->|Sim| RETURN2[Retornar para Dev]
+
+    D3{Self-Healing<br/>Issues CRITICAL?}
+    D3 -->|Não| CONTINUE3[Prosseguir para DOD]
+    D3 -->|Sim| D4{iteration < 2?}
+    D4 -->|Sim| FIX[Tentar auto-fix]
+    D4 -->|Não| HALT[HALT - Manual]
+```
+
+### Pontos de Decisão Detalhados
+
+| Ponto | Fase | Decisor | Criterio | Resultado Positivo | Resultado Negativo |
+|-------|------|---------|----------|-------------------|-------------------|
+| Validação PO | 2 | @po | 10 checks passam | Status: Ready | Retorna para SM |
+| Self-Healing | 3 | Sistema | Sem CRITICAL issues | Prossegue para DOD | Halt ou auto-fix |
+| Quality Gate | 4 | @qa | Sem HIGH/CRITICAL | Status: Done | Retorna para Dev |
+
+### Condições de Bloqueio
+
+O workflow deve HALT e solicitar intervencao do usuario quando:
+
+1. **Dependencias nao aprovadas necessarias** - Nova lib ou recurso requerido
+2. **Ambiguidade apos verificar story** - Requisitos nao claros
+3. **3 falhas consecutivas** - Tentativas de implementação ou correção
+4. **Configuração faltando** - core-config.yaml ou templates ausentes
+5. **Regressao falhando** - Testes existentes quebraram
+
+---
+
+## Modos de Execução
+
+O workflow suporta tres modos de execucao que afetam todos os steps:
+
+### 1. YOLO Mode (Autônomo)
+
+```yaml
+mode: yolo
+prompts: 0-1
+best_for: Tarefas simples e deterministicas
+```
+
+- Decisões autônomas com logging automatico
+- Mínima interação com usuario
+- Gera `decision-log-{story-id}.md` com todas as decisões
+
+### 2. Interactive Mode (Balanceado) [DEFAULT]
+
+```yaml
+mode: interactive
+prompts: 5-10
+best_for: Aprendizado e decisões complexas
+```
+
+- Checkpoints de decisao explícitos
+- Explicacoes educacionais em cada passo
+- Confirma entendimento com usuario
+
+### 3. Pre-Flight Mode (Planejamento)
+
+```yaml
+mode: preflight
+prompts: 10-15 (upfront)
+best_for: Requisitos ambiguos e trabalho critico
+```
+
+- Análise completa de ambiguidades antes de iniciar
+- Questionário abrangente upfront
+- Execução sem ambiguidades apos planejamento
+
+---
+
+## Troubleshooting
+
+### Problemas Comuns
+
+#### 1. Story nao pode ser criada
+
+**Sintoma:** Erro ao executar `create-next-story`
+
+**Possíveis Causas:**
+- `core-config.yaml` nao encontrado
+- Epic file nao existe
+- PRD nao disponivel
+
+**Solução:**
+```bash
+# Verificar se core-config.yaml existe
+cat .aiox-core/core-config.yaml
+
+# Verificar estrutura de epics
+ls docs/stories/epic-*/
+
+# Verificar PRD
+cat docs/prd/PRD.md  # ou localizado conforme config
+```
+
+#### 2. Validação PO falha repetidamente
+
+**Sintoma:** Story retorna para SM multiplas vezes
+
+**Possíveis Causas:**
+- Acceptance criteria mal definidos
+- Falta de informações no Dev Notes
+- Escopo nao claro
+
+**Solução:**
+1. Revisar os 10 checks do checklist
+2. Garantir formato Given/When/Then nos ACs
+3. Preencher Dev Notes com referencias de arquitetura
+
+#### 3. CodeRabbit Self-Healing falha
+
+**Sintoma:** CRITICAL issues persistem apos 2 iteracoes
+
+**Possíveis Causas:**
+- Issues que requerem refatoração significativa
+- Problemas de segurança complexos
+- Codigo que viola padroes de arquitetura
+
+**Solução:**
+```bash
+# Verificar output do CodeRabbit
+wsl bash -c 'cd /mnt/c/.../aiox-core && ~/.local/bin/coderabbit --prompt-only -t uncommitted'
+
+# Corrigir issues manualmente
+# Depois re-executar *develop
+```
+
+#### 4. Quality Gate retorna FAIL
+
+**Sintoma:** QA rejeita story com HIGH issues
+
+**Possíveis Causas:**
+- Acceptance criteria nao atendidos
+- Cobertura de testes insuficiente
+- Problemas de segurança
+
+**Solução:**
+1. Revisar `qa-gate.yml` gerado
+2. Executar `*apply-qa-fixes` no @dev
+3. Re-submeter para review
+
+#### 5. Workflow trava em handoff
+
+**Sintoma:** Transição entre agentes nao acontece
+
+**Possíveis Causas:**
+- Outputs nao gerados corretamente
+- Status da story inconsistente
+- Dependencia de step anterior nao satisfeita
+
+**Solução:**
+```bash
+# Verificar status da story
+cat docs/stories/{story-file}.md | grep "status:"
+
+# Forcar transição manual
+@{next-agent}
+*{comando-apropriado}
+```
+
+### Logs e Diagnóstico
+
+| Arquivo | Local | Conteudo |
+|---------|-------|----------|
+| Decision Log | `.ai/decision-log-{story-id}.md` | Decisões autônomas (modo YOLO) |
+| QA Gate | `{qaLocation}/gates/{epic}.{story}-{slug}.yml` | Decisão do quality gate |
+| Story File | `{devStoryLocation}/{epic}.{story}.story.md` | Historia completa com logs |
+
+---
+
+## Quando Usar e Quando Não Usar
+
+### Quando Usar Este Workflow
+
+- Desenvolvimento de qualquer story (greenfield ou brownfield)
+- Quando precisa de ciclo completo com validação e quality gate
+- Quando precisa de rastreabilidade do processo
+- Equipes que seguem processo agil estruturado
+
+### Quando NAO Usar Este Workflow
+
+| Situacao | Alternativa |
+|----------|-------------|
+| Hotfixes urgentes | Fluxo simplificado sem QA gate |
+| Spikes/POCs exploratorios | Desenvolvimento ad-hoc |
+| Tasks puramente tecnicas sem story | Tarefas diretas com @dev |
+
+---
+
+## Referências
+
+### Arquivos Relacionados
+
+| Arquivo | Caminho |
+|---------|---------|
+| Workflow Definition | `.aiox-core/development/workflows/story-development-cycle.yaml` |
+| SM Agent | `.aiox-core/development/agents/sm.md` |
+| PO Agent | `.aiox-core/development/agents/po.md` |
+| Dev Agent | `.aiox-core/development/agents/dev.md` |
+| QA Agent | `.aiox-core/development/agents/qa.md` |
+| Create Story Task | `.aiox-core/development/tasks/create-next-story.md` |
+| Validate Story Task | `.aiox-core/development/tasks/validate-next-story.md` |
+| Develop Story Task | `.aiox-core/development/tasks/dev-develop-story.md` |
+| QA Gate Task | `.aiox-core/development/tasks/qa-gate.md` |
+| Story Template | `.aiox-core/development/templates/story-tmpl.yaml` |
+
+### Documentação Adicional
+
+- [Guia de Workflows YAML](../workflows-yaml-guide.md)
+- [Guia de Squads](../squads-user-guide.md)
+- [Framework de Priorizacao](../PRIORITIZATION-FRAMEWORK.md)
+
+---
+
+## Changelog
+
+| Versao | Data | Mudancas |
+|--------|------|----------|
+| 1.0 | 2025-01-30 | Versao inicial do workflow |
+
+---
+
+*Documentação gerada automaticamente baseada no arquivo `story-development-cycle.yaml`*