Spec Pipeline Workflow - Documentação Completa

Versão: 1.0 Criado: 2026-01-28 Autor: @architect (Aria) Epic: Epic 3 - Spec Pipeline Status: Ativo

1. Visão Geral

O Spec Pipeline e um workflow orquestrado que transforma requisitos informais em especificações executaveis. Ele e parte da infraestrutura Auto-Claude ADE (Autonomous Development Engine) e implementa um fluxo de 5 fases principais que se adaptam dinamicamente baseado na complexidade do requisito.

1.1 Propósito

• Transformar descricoes informais de usuarios em especificações formais e estruturadas
• Garantir qualidade e consistencia atraves de gates de validação
• Adaptar o nivel de profundidade baseado na complexidade detectada
• Produzir artefatos rastreavies desde requisitos ate implementação

1.2 Principios Fundamentais

| Principio | Descrição | |-----------|-----------| | No Invention | Nenhuma informação inventada - apenas derivação dos inputs | | Traceability | Todo statement deve rastrear para um requisito ou pesquisa | | Adaptive Phases | Fases ajustadas automaticamente pela complexidade | | Quality Gates | Validacao obrigatoria antes de avancar |

2. Diagrama do Workflow

2.1 Fluxo Principal

flowchart TB
    subgraph TRIGGER["Gatilhos"]
        T1["*create-spec STORY-ID"]
        T2["story_created<br/>(autoSpec.enabled)"]
    end

    subgraph PREFLIGHT["Pre-Flight Checks"]
        PF1["story_exists<br/>Verificar/criar diretorio"]
        PF2["no_existing_spec<br/>Evitar sobrescrita"]
        PF3["agents_available<br/>Verificar configuracao"]
    end

    subgraph PHASE1["Fase 1: Gather Requirements"]
        direction TB
        G1["@pm (Morgan)"]
        G2["Elicitação Interativa<br/>9 categorias de perguntas"]
        G3["requirements.json"]
        G1 --> G2 --> G3
    end

    subgraph PHASE2["Fase 2: Assess Complexity"]
        direction TB
        A1["@architect (Aria)"]
        A2["Avaliar 5 dimensoes:<br/>Scope, Integration, Infra,<br/>Knowledge, Risk"]
        A3["complexity.json<br/>SIMPLE | STANDARD | COMPLEX"]
        A1 --> A2 --> A3
    end

    subgraph PHASE3["Fase 3: Research Dependencies"]
        direction TB
        R1["@analyst (Atlas)"]
        R2["Context7 + EXA<br/>Validar dependencias"]
        R3["research.json"]
        R1 --> R2 --> R3
    end

    subgraph PHASE4["Fase 4: Write Specification"]
        direction TB
        W1["@pm (Morgan)"]
        W2["Gerar spec.md<br/>Sem invencao"]
        W3["spec.md"]
        W1 --> W2 --> W3
    end

    subgraph PHASE5["Fase 5: Critique Specification"]
        direction TB
        C1["@qa (Quinn)"]
        C2["Avaliar 5 dimensoes:<br/>Accuracy, Completeness,<br/>Consistency, Feasibility,<br/>Alignment"]
        C3{"Verdict"}
        C4["APPROVED"]
        C5["NEEDS_REVISION"]
        C6["BLOCKED"]
        C1 --> C2 --> C3
        C3 --> C4
        C3 --> C5
        C3 --> C6
    end

    subgraph PHASE5B["Fase 5b: Revise (COMPLEX)"]
        REV1["@pm (Morgan)"]
        REV2["Aplicar feedback<br/>e auto-fixes"]
    end

    subgraph PHASE6["Fase 6: Create Plan"]
        direction TB
        P1["@architect (Aria)"]
        P2["Gerar implementation.yaml<br/>Subtasks atomicas"]
        P3["plan.json"]
        P1 --> P2 --> P3
    end

    subgraph COMPLETION["Conclusão"]
        DONE["Pipeline Complete"]
        ARTIFACTS["Artefatos Gerados"]
    end

    T1 --> PREFLIGHT
    T2 --> PREFLIGHT
    PREFLIGHT --> PHASE1
    PHASE1 --> PHASE2
    PHASE2 --> PHASE3
    PHASE3 --> PHASE4
    PHASE4 --> PHASE5
    C4 --> PHASE6
    C5 --> PHASE5B
    PHASE5B --> PHASE5
    C6 -.-> |"Escalar para @architect"| HALT["HALT"]
    PHASE6 --> COMPLETION

    style TRIGGER fill:#e1f5fe
    style PREFLIGHT fill:#fff3e0
    style PHASE1 fill:#e8f5e9
    style PHASE2 fill:#fce4ec
    style PHASE3 fill:#f3e5f5
    style PHASE4 fill:#e8f5e9
    style PHASE5 fill:#fff8e1
    style PHASE5B fill:#ffebee
    style PHASE6 fill:#e0f2f1
    style COMPLETION fill:#c8e6c9

2.2 Fluxo por Complexidade

flowchart LR
    subgraph SIMPLE["SIMPLE (score <= 8)"]
        S1["Gather"] --> S2["Spec"] --> S3["Critique"]
    end

    subgraph STANDARD["STANDARD (score 9-15)"]
        ST1["Gather"] --> ST2["Assess"] --> ST3["Research"] --> ST4["Spec"] --> ST5["Critique"] --> ST6["Plan"]
    end

    subgraph COMPLEX["COMPLEX (score >= 16)"]
        C1["Gather"] --> C2["Assess"] --> C3["Research"] --> C4["Spec"] --> C5["Critique 1"] --> C6["Revise"] --> C7["Critique 2"] --> C8["Plan"]
    end

    style SIMPLE fill:#c8e6c9
    style STANDARD fill:#fff9c4
    style COMPLEX fill:#ffcdd2

2.3 Diagrama de Sequência

sequenceDiagram
    autonumber
    participant U as Usuario
    participant PM as @pm (Morgan)
    participant AR as @architect (Aria)
    participant AN as @analyst (Atlas)
    participant QA as @qa (Quinn)
    participant FS as File System

    U->>PM: *create-spec STORY-42

    Note over PM: Fase 1: Gather
    PM->>U: Perguntas de elicitacao (9 categorias)
    U->>PM: Respostas dos requisitos
    PM->>FS: Salvar requirements.json

    Note over AR: Fase 2: Assess
    AR->>FS: Ler requirements.json
    AR->>AR: Avaliar 5 dimensoes de complexidade
    AR->>FS: Salvar complexity.json

    alt Complexidade != SIMPLE
        Note over AN: Fase 3: Research
        AN->>FS: Ler requirements + complexity
        AN->>AN: Pesquisar via Context7 + EXA
        AN->>FS: Salvar research.json
    end

    Note over PM: Fase 4: Write Spec
    PM->>FS: Ler todos os artefatos
    PM->>PM: Gerar spec.md (sem invencao)
    PM->>FS: Salvar spec.md

    Note over QA: Fase 5: Critique
    QA->>FS: Ler spec + requirements
    QA->>QA: Avaliar 5 dimensoes de qualidade
    QA->>FS: Salvar critique.json

    alt Verdict = APPROVED
        Note over AR: Fase 6: Plan
        AR->>FS: Ler spec aprovado
        AR->>AR: Gerar plano de implementação
        AR->>FS: Salvar plan.json
        AR->>U: Pipeline Complete!
    else Verdict = NEEDS_REVISION
        QA->>PM: Retornar com feedback
        PM->>PM: Aplicar correcoes
        PM->>QA: Submeter revisao
    else Verdict = BLOCKED
        QA->>AR: Escalar para revisao arquitetural
    end

3. Steps Detalhados

3.1 Fase 1: Gather Requirements

| Atributo | Valor | |----------|-------| | Step ID | gather | | Phase Number | 1 | | Agente | @pm (Morgan) | | Task | spec-gather-requirements.md | | Elicit | Sim - requer interação do usuario |

Inputs

| Input | Tipo | Obrigatório | Descrição | |-------|------|-------------|-----------| | storyId | string | Sim | ID da story sendo especificada | | source | enum | Não | Fonte: prd, user, existing | | prdPath | string | Não | Caminho para PRD se source=prd |

Outputs

| Output | Localização | |--------|-------------| | requirements.json | docs/stories/{storyId}/spec/requirements.json |

Processo de Elicitação (9 Categorias)

mindmap
  root((Elicitação))
    Funcionais
      Q1: O que o sistema deve FAZER?
      Follow-ups sobre usuarios e triggers
    Restrições
      Q2: Restrições tecnicas/negocio?
      Tempo, integrações, stack
    NFR
      Q3: Requisitos nao-funcionais?
      Performance, seguranca, escala
    Aceite
      Q4: Criterios de aceite?
      Formato Given-When-Then
    Suposições
      Q5: Suposições assumidas?
      Riscos se estiverem erradas
    Dominio
      Q6: Entidades e relacionamentos?
      Modelo de dominio
    Interação
      Q7: Como usuario interage?
      Fluxos UX, estados
    Edge Cases
      Q8: O que pode dar errado?
      Tratamento de erros
    Terminologia
      Q9: Glossario do dominio?
      Termos especificos

Estrutura do Output (requirements.json)

{
  "storyId": "STORY-42",
  "gatheredAt": "2026-01-28T10:00:00Z",
  "source": "user",
  "gatheredBy": "@pm",
  "elicitationVersion": "2.0",
  "functional": [
    {
      "id": "FR-1",
      "description": "Permitir login com Google OAuth",
      "priority": "P0",
      "rationale": "Principal metodo de autenticação",
      "acceptance": ["AC-1"]
    }
  ],
  "nonFunctional": [...],
  "constraints": [...],
  "assumptions": [...],
  "domainModel": [...],
  "interactions": [...],
  "edgeCases": [...],
  "terminology": [...],
  "openQuestions": [...]
}

3.2 Fase 2: Assess Complexity

| Atributo | Valor | |----------|-------| | Step ID | assess | | Phase Number | 2 | | Agente | @architect (Aria) | | Task | spec-assess-complexity.md | | Skip Condition | source === 'simple' OR overrideComplexity === 'SIMPLE' |

Inputs

| Input | Tipo | Obrigatório | Descrição | |-------|------|-------------|-----------| | storyId | string | Sim | ID da story | | requirements | file | Sim | requirements.json | | overrideComplexity | enum | Não | Override manual: SIMPLE, STANDARD, COMPLEX |

Outputs

| Output | Localização | |--------|-------------| | complexity.json | docs/stories/{storyId}/spec/complexity.json |

5 Dimensões de Complexidade

radar
    title Dimensões de Complexidade (1-5)
    "Scope" : 3
    "Integration" : 4
    "Infrastructure" : 2
    "Knowledge" : 3
    "Risk" : 3

| Dimensão | Score 1 | Score 3 | Score 5 | |----------|---------|---------|---------| | Scope | 1-2 arquivos | 6-10 arquivos | 20+ arquivos | | Integration | Nenhuma externa | 1-2 APIs externas | Orquestração multipla | | Infrastructure | Nenhuma mudança | Nova dependencia | Nova infraestrutura | | Knowledge | Padroes existentes | Nova biblioteca | Dominio desconhecido | | Risk | Baixo, isolado | Medio, importante | Critico, core do sistema |

Thresholds de Classificação

| Classificação | Score Total | Fases Ativadas | Tempo Estimado | |---------------|-------------|----------------|----------------| | SIMPLE | <= 8 | gather, spec, critique | 30-60 min | | STANDARD | 9-15 | gather, assess, research, spec, critique, plan | 2-4 horas | | COMPLEX | >= 16 | + revise, critique_2 | 4-8 horas |

3.3 Fase 3: Research Dependencies

| Atributo | Valor | |----------|-------| | Step ID | research | | Phase Number | 3 | | Agente | @analyst (Atlas) | | Task | spec-research-dependencies.md | | Skip Condition | complexity.result === 'SIMPLE' | | Tools | Context7, EXA |

Inputs

| Input | Tipo | Obrigatório | Descrição | |-------|------|-------------|-----------| | storyId | string | Sim | ID da story | | requirements | file | Sim | requirements.json | | complexity | file | Sim | complexity.json |

Outputs

| Output | Localização | |--------|-------------| | research.json | docs/stories/{storyId}/spec/research.json |

Fluxo de Pesquisa

flowchart LR
    subgraph Extract["1. Extrair Alvos"]
        E1["Libraries<br/>APIs<br/>Concepts<br/>Infrastructure"]
    end

    subgraph Check["2. Verificar Codebase"]
        C1["package.json"]
        C2["imports existentes"]
        C3["padroes similares"]
    end

    subgraph Research["3. Pesquisar"]
        R1["Context7<br/>(Primario)"]
        R2["EXA<br/>(Fallback)"]
    end

    subgraph Validate["4. Validar"]
        V1["technical-preferences.md"]
        V2["Conflitos?<br/>Alternativas?"]
    end

    subgraph Output["5. Output"]
        O1["research.json"]
    end

    Extract --> Check --> Research --> Validate --> Output

    style Research fill:#e3f2fd

Prioridade de Ferramentas

| Ferramenta | Prioridade | Timeout | Uso | |------------|------------|---------|-----| | Context7 | 1 (primaria) | 30s | Documentação de bibliotecas | | EXA | 2 (fallback) | - | Pesquisa web geral | | Codebase | - | - | Verificar implementações existentes |

3.4 Fase 4: Write Specification

| Atributo | Valor | |----------|-------| | Step ID | spec | | Phase Number | 4 | | Agente | @pm (Morgan) | | Task | spec-write-spec.md | | Constitutional Gate | Article IV - No Invention |

Inputs

| Input | Tipo | Obrigatório | Descrição | |-------|------|-------------|-----------| | storyId | string | Sim | ID da story | | requirements | file | Sim | requirements.json | | complexity | file | Não | complexity.json | | research | file | Não | research.json |

Outputs

| Output | Localização | |--------|-------------| | spec.md | docs/stories/{storyId}/spec/spec.md |

Constitutional Gate: No Invention

flowchart TB
    subgraph RULE["Regra Article IV - No Invention"]
        direction TB
        R1["Todo statement DEVE rastrear para:"]
        R2["FR-* (Requisito Funcional)"]
        R3["NFR-* (Requisito Não-Funcional)"]
        R4["CON-* (Restrição)"]
        R5["Research finding verificado"]
    end

    subgraph VIOLATION["Violações"]
        V1["Adicionar features nao listadas"]
        V2["Assumir detalhes nao pesquisados"]
        V3["Especificar tech nao validada"]
        V4["Criar criterios de aceite inventados"]
    end

    subgraph ACTION["Ação em Violacao"]
        A1["BLOCK"]
        A2["Remover conteudo inventado"]
        A3["OU adicionar a Open Questions"]
    end

    RULE --> |"Se violado"| VIOLATION
    VIOLATION --> ACTION

    style RULE fill:#c8e6c9
    style VIOLATION fill:#ffcdd2
    style ACTION fill:#fff9c4

Estrutura do spec.md

1. Overview
   1.1 Goals
   1.2 Non-Goals
2. Requirements Summary
   2.1 Functional Requirements
   2.2 Non-Functional Requirements
   2.3 Constraints
3. Technical Approach
   3.1 Architecture Overview
   3.2 Component Design
   3.3 Data Flow
4. Dependencies
   4.1 External Dependencies
   4.2 Internal Dependencies
5. Files to Modify/Create
   5.1 New Files
   5.2 Modified Files
6. Testing Strategy
   6.1 Unit Tests
   6.2 Integration Tests
   6.3 Acceptance Tests (Given-When-Then)
7. Risks & Mitigations
8. Open Questions
9. Implementation Checklist

3.5 Fase 5: Critique Specification

| Atributo | Valor | |----------|-------| | Step ID | critique | | Phase Number | 5 | | Agente | @qa (Quinn) | | Task | spec-critique.md | | Gate | Blocking (APPROVED/NEEDS_REVISION/BLOCKED) |

Inputs

| Input | Tipo | Obrigatório | Descrição | |-------|------|-------------|-----------| | storyId | string | Sim | ID da story | | spec | file | Sim | spec.md | | requirements | file | Sim | requirements.json | | complexity | file | Não | complexity.json | | research | file | Não | research.json |

Outputs

| Output | Localização | |--------|-------------| | critique.json | docs/stories/{storyId}/spec/critique.json |

5 Dimensões de Qualidade

pie showData
    title Peso das Dimensões
    "Accuracy" : 25
    "Completeness" : 25
    "Consistency" : 20
    "Feasibility" : 15
    "Alignment" : 15

| Dimensão | Peso | Verifica | |----------|------|----------| | Accuracy | 25% | Spec reflete requisitos corretamente? | | Completeness | 25% | Todas secoes preenchidas? Tests cobrem FRs? | | Consistency | 20% | IDs validos? Sem contradicoes? | | Feasibility | 15% | Tecnicamente possivel? Dependencias existem? | | Alignment | 15% | Alinhado com stack e padroes do projeto? |

Lógica de Verdict

flowchart TB
    START["Iniciar Avaliacao"] --> EVAL["Avaliar 5 Dimensões"]

    EVAL --> CHECK1{"HIGH severity<br/>issues?"}
    CHECK1 -->|Sim| BLOCKED["BLOCKED"]
    CHECK1 -->|Não| CHECK2{"Average<br/>score >= 4.0?"}

    CHECK2 -->|Sim| CHECK3{"Todas dimensoes<br/>>= 3?"}
    CHECK3 -->|Sim| APPROVED["APPROVED"]
    CHECK3 -->|Não| NEEDS["NEEDS_REVISION"]

    CHECK2 -->|Não| CHECK4{"Average<br/>score >= 3.0?"}
    CHECK4 -->|Sim| NEEDS
    CHECK4 -->|Não| BLOCKED

    APPROVED --> PLAN["Ir para Fase 6: Plan"]
    NEEDS --> REVISE["Retornar para Fase 4"]
    BLOCKED --> HALT["HALT + Escalar @architect"]

    style APPROVED fill:#c8e6c9
    style NEEDS fill:#fff9c4
    style BLOCKED fill:#ffcdd2

| Verdict | Condição | Próxima Ação | |---------|----------|--------------| | APPROVED | No HIGH issues, avg >= 4.0, all >= 3 | Ir para Plan | | NEEDS_REVISION | MEDIUM issues OR avg 3.0-3.9 | Retornar para Spec Write | | BLOCKED | HIGH issues OR avg < 3.0 OR any <= 1 | Escalar para @architect |

3.6 Fase 5b: Revise Specification

| Atributo | Valor | |----------|-------| | Step ID | revise | | Phase Number | 5b | | Agente | @pm (Morgan) | | Condition | complexity.result === 'COMPLEX' OR critique.verdict === 'NEEDS_REVISION' |

Inputs

| Input | Tipo | Obrigatório | Descrição | |-------|------|-------------|-----------| | storyId | string | Sim | ID da story | | spec | file | Sim | spec.md atual | | critique | file | Sim | critique.json com feedback |

Outputs

| Output | Localização | |--------|-------------| | spec.md (updated) | docs/stories/{storyId}/spec/spec.md |

3.7 Fase 5c: Second Critique

| Atributo | Valor | |----------|-------| | Step ID | critique_2 | | Phase Number | 5c | | Agente | @qa (Quinn) | | Task | spec-critique.md | | Condition | complexity.result === 'COMPLEX' |

Nota: Segunda critica e mais leniente em issues MEDIUM se houver melhoria demonstrada.

3.8 Fase 6: Create Implementation Plan

| Atributo | Valor | |----------|-------| | Step ID | plan | | Phase Number | 6 | | Agente | @architect (Aria) | | Task | plan-create-implementation.md | | Condition | critique.verdict === 'APPROVED' |

Inputs

| Input | Tipo | Obrigatório | Descrição | |-------|------|-------------|-----------| | storyId | string | Sim | ID da story | | spec | file | Sim | spec.md aprovado | | complexity | file | Não | complexity.json |

Outputs

| Output | Localização | |--------|-------------| | plan.json | docs/stories/{storyId}/plan/implementation.yaml |

Regras de Subtasks

| Regra | Descrição | |-------|-----------| | Single Service | 1 servico por subtask (frontend, backend, database, infra) | | File Limit | Maximo 3 arquivos por subtask | | Verification Required | Cada subtask DEVE ter verificacao definida | | Dependency Order | Database > Backend > Frontend > Integration |

4. Agentes Participantes

graph LR
    subgraph AGENTS["Agentes do Spec Pipeline"]
        PM["@pm<br/>Morgan<br/>Product Manager"]
        AR["@architect<br/>Aria<br/>Architect"]
        AN["@analyst<br/>Atlas<br/>Business Analyst"]
        QA["@qa<br/>Quinn<br/>Test Architect"]
    end

    PM --> |"Fase 1, 4, 5b"| G1["Gather<br/>Write Spec<br/>Revise"]
    AR --> |"Fase 2, 6"| G2["Assess<br/>Plan"]
    AN --> |"Fase 3"| G3["Research"]
    QA --> |"Fase 5, 5c"| G4["Critique"]

    style PM fill:#e8f5e9
    style AR fill:#fce4ec
    style AN fill:#f3e5f5
    style QA fill:#fff8e1

| Agente | ID | Nome | Papel no Pipeline | Fases | |--------|-----|------|-------------------|-------| | @pm | pm | Morgan | Product Manager | 1 (Gather), 4 (Spec), 5b (Revise) | | @architect | architect | Aria | System Architect | 2 (Assess), 6 (Plan) | | @analyst | analyst | Atlas | Business Analyst | 3 (Research) | | @qa | qa | Quinn | Test Architect | 5 (Critique), 5c (Critique 2) |

4.1 Perfil: @pm (Morgan)

• Arquetipo: Strategist
• Foco: Coleta de requisitos, criação de especificações, documentação
• Principios: User-focused, data-informed, clarity & precision
• Ferramentas: Templates de PRD, elicitacao estruturada

4.2 Perfil: @architect (Aria)

• Arquetipo: Visionary
• Foco: Arquitetura de sistemas, avaliação tecnica, planejamento
• Principios: Holistic thinking, pragmatic selection, security at every layer
• Ferramentas: Context7, EXA, análise de codebase

4.3 Perfil: @analyst (Atlas)

• Arquetipo: Decoder
• Foco: Pesquisa, análise de mercado, validação de dependencias
• Principios: Curiosity-driven, evidence-based, action-oriented
• Ferramentas: EXA, Context7, Google Workspace

4.4 Perfil: @qa (Quinn)

• Arquetipo: Guardian
• Foco: Validacao de qualidade, gates de aprovacao, rastreabilidade
• Principios: Requirements traceability, risk-based testing, advisory excellence
• Ferramentas: CodeRabbit, Browser testing, análise de spec

5. Tasks Executadas

| Task | Fase | Agente | Arquivo | |------|------|--------|---------| | Gather Requirements | 1 | @pm | .aiox-core/development/tasks/spec-gather-requirements.md | | Assess Complexity | 2 | @architect | .aiox-core/development/tasks/spec-assess-complexity.md | | Research Dependencies | 3 | @analyst | .aiox-core/development/tasks/spec-research-dependencies.md | | Write Specification | 4 | @pm | .aiox-core/development/tasks/spec-write-spec.md | | Critique Specification | 5, 5c | @qa | .aiox-core/development/tasks/spec-critique.md | | Create Implementation Plan | 6 | @architect | .aiox-core/development/tasks/plan-create-implementation.md |

6. Pré-requisitos

6.1 Pre-Flight Checks

| Check | Descrição | Blocking | |-------|-----------|----------| | story_exists | Diretorio da story existe ou pode ser criado | Sim | | no_existing_spec | Verificar spec existente (evitar sobrescrita) | Não (warning) | | agents_available | Agentes do pipeline estao configurados | Sim |

6.2 Configuração Necessaria

config:
  autoSpec:
    enabled: false        # Ativar auto-spec quando story criada
  showProgress: true      # Mostrar progresso
  verbose: true           # Logs detalhados
  maxRetries: 2           # Tentativas em caso de falha
  retryDelay: 1000        # Delay entre retries (ms)
  strictGate: true        # BLOCKED halts pipeline
  outputDir: docs/stories/{storyId}/spec/

7. Entradas e Saidas

7.1 Entradas do Pipeline

| Entrada | Tipo | Descrição | Fornecido Por | |---------|------|-----------|---------------| | storyId | string | ID único da story | Usuario | | source | enum | prd, user, existing | Usuario (opcional) | | prdPath | string | Caminho para PRD existente | Usuario (opcional) | | overrideComplexity | enum | Override manual de complexidade | Usuario (opcional) |

7.2 Saidas do Pipeline

flowchart LR
    subgraph OUTPUT["Artefatos Gerados"]
        direction TB
        O1["requirements.json"]
        O2["complexity.json"]
        O3["research.json"]
        O4["spec.md"]
        O5["critique.json"]
        O6["plan.json"]
    end

    subgraph LOCATION["Localização"]
        L["docs/stories/{storyId}/spec/"]
        LP["docs/stories/{storyId}/plan/"]
    end

    O1 --> L
    O2 --> L
    O3 --> L
    O4 --> L
    O5 --> L
    O6 --> LP

| Artefato | Fase | Descrição | |----------|------|-----------| | requirements.json | 1 | Requisitos estruturados (9 categorias) | | complexity.json | 2 | Avaliacao de complexidade (5 dimensoes) | | research.json | 3 | Dependencias pesquisadas e validadas | | spec.md | 4 | Especificacao completa executavel | | critique.json | 5 | Resultado da avaliação de qualidade | | plan.json | 6 | Plano de implementação com subtasks |

8. Pontos de Decisão

8.1 Decisão: Pular Assess?

flowchart TB
    D1{"source === 'simple'<br/>OR<br/>overrideComplexity === 'SIMPLE'?"}
    D1 -->|Sim| SKIP["Pular para Spec<br/>(assume SIMPLE)"]
    D1 -->|Não| RUN["Executar Assess"]

8.2 Decisão: Pular Research?

flowchart TB
    D2{"complexity.result === 'SIMPLE'<br/>OR<br/>no external dependencies?"}
    D2 -->|Sim| SKIP["Pular Research<br/>Gerar minimal research.json"]
    D2 -->|Não| RUN["Executar Research"]

8.3 Decisão: Verdict da Critique

flowchart TB
    START["Critique Complete"] --> C1{"HIGH issues?"}
    C1 -->|Sim| BLOCKED["BLOCKED"]
    C1 -->|Não| C2{"avg >= 4.0?"}
    C2 -->|Sim| C3{"all dims >= 3?"}
    C3 -->|Sim| APPROVED["APPROVED"]
    C3 -->|Não| NEEDS["NEEDS_REVISION"]
    C2 -->|Não| C4{"avg >= 3.0?"}
    C4 -->|Sim| NEEDS
    C4 -->|Não| BLOCKED

8.4 Decisão: Executar Revise?

flowchart TB
    D4{"complexity === 'COMPLEX'<br/>OR<br/>verdict === 'NEEDS_REVISION'?"}
    D4 -->|Sim| RUN["Executar Revise<br/>(Fase 5b)"]
    D4 -->|Não| SKIP["Pular Revise"]

8.5 Decisão: Segunda Critique?

flowchart TB
    D5{"complexity === 'COMPLEX'?"}
    D5 -->|Sim| RUN["Executar Critique 2<br/>(Fase 5c)"]
    D5 -->|Não| SKIP["Pular Segunda Critique"]

9. Troubleshooting

9.1 Erros Comuns

| Erro | Causa | Solução | |------|-------|---------| | missing_story_id | Story ID nao fornecido | *create-spec STORY-42 | | phase_failed | Fase falhou durante execucao | Verificar logs, usar --resume | | max_iterations_reached | Limite de revisoes atingido | Escalr para @architect | | critique_blocked | Spec bloqueado pelo QA gate | Revisar critique.json, corrigir HIGH issues | | missing-requirements | requirements.json nao encontrado | Executar fase Gather primeiro | | empty-functional | Nenhum requisito funcional | Re-executar elicitacao | | context7-unavailable | Context7 MCP nao responde | Usar EXA como fallback |

9.2 Como Retomar Execucao

O pipeline suporta retomada atraves de checkpoints:

resume:
  enabled: true
  state_file: docs/stories/{storyId}/spec/.pipeline-state.json

  checkpoints:
    - after: gather   -> requirements_gathered
    - after: assess   -> complexity_assessed
    - after: research -> research_complete
    - after: spec     -> spec_written
    - after: critique -> critique_complete

Comando para retomar:

*create-spec STORY-42 --resume

9.3 Árvore de Decisão de Erros

flowchart TB
    E["Erro no Pipeline"] --> E1{"Qual fase?"}

    E1 -->|Gather| G["Verificar elicitacao"]
    G --> G1["Usuario respondeu todas perguntas?"]
    G --> G2["requirements.json valido?"]

    E1 -->|Assess| A["Verificar inputs"]
    A --> A1["requirements.json existe?"]
    A --> A2["Formato JSON valido?"]

    E1 -->|Research| R["Verificar ferramentas"]
    R --> R1["Context7 ativo?"]
    R --> R2["EXA configurado?"]

    E1 -->|Spec| S["Verificar Constitutional Gate"]
    S --> S1["Conteudo inventado detectado?"]
    S --> S2["Traceability ok?"]

    E1 -->|Critique| C["Verificar verdict"]
    C --> C1["Issues HIGH encontrados?"]
    C --> C2["Score medio < 3.0?"]

10. Referências

10.1 Arquivos do Workflow

| Arquivo | Localização | |---------|-------------| | Definicao do Workflow | .aiox-core/development/workflows/spec-pipeline.yaml | | Task: Gather | .aiox-core/development/tasks/spec-gather-requirements.md | | Task: Assess | .aiox-core/development/tasks/spec-assess-complexity.md | | Task: Research | .aiox-core/development/tasks/spec-research-dependencies.md | | Task: Write Spec | .aiox-core/development/tasks/spec-write-spec.md | | Task: Critique | .aiox-core/development/tasks/spec-critique.md | | Task: Create Plan | .aiox-core/development/tasks/plan-create-implementation.md |

10.2 Agentes Relacionados

| Agente | Localização | |--------|-------------| | @pm (Morgan) | .aiox-core/development/agents/pm.md | | @architect (Aria) | .aiox-core/development/agents/architect.md | | @analyst (Atlas) | .aiox-core/development/agents/analyst.md | | @qa (Quinn) | .aiox-core/development/agents/qa.md |

10.3 Documentação Relacionada

• Workflows YAML Guide
• AIOX Documentation Index
• Backlog Management System

10.4 Commands Rapidos

| Comando | Descrição | Agente | |---------|-----------|--------| | *create-spec STORY-ID | Executar pipeline completo | - | | *gather-requirements STORY-ID | Apenas fase Gather | @pm | | *assess-complexity STORY-ID | Apenas fase Assess | @architect | | *research-deps STORY-ID | Apenas fase Research | @analyst | | *write-spec STORY-ID | Apenas fase Write | @pm | | *critique-spec STORY-ID | Apenas fase Critique | @qa |

11. Mensagem de Conclusão

Ao finalizar com sucesso, o pipeline exibe:

+==============================================================+
|  Spec Pipeline Complete                                      |
+==============================================================+

Story:       {storyId}
Complexity:  {SIMPLE|STANDARD|COMPLEX}
Verdict:     APPROVED
Score:       {score}/5

Artifacts:
   - docs/stories/{storyId}/spec/requirements.json
   - docs/stories/{storyId}/spec/complexity.json
   - docs/stories/{storyId}/spec/research.json
   - docs/stories/{storyId}/spec/spec.md
   - docs/stories/{storyId}/spec/critique.json

Next Steps:
   - Review spec.md
   - Run @dev *develop {storyId}

Metadata

metadata:
  documento: SPEC-PIPELINE-WORKFLOW.md
  versao: 1.0
  criado: 2026-02-04
  autor: Technical Documentation Specialist
  baseado_em:
    - .aiox-core/development/workflows/spec-pipeline.yaml
    - .aiox-core/development/tasks/spec-*.md
    - .aiox-core/development/agents/*.md
  tags:
    - spec-pipeline
    - workflow
    - documentação
    - aiox
    - auto-claude