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

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

FilesExpand file tree

spec-pipeline-workflow.md

Latest commit

History

spec-pipeline-workflow.md

File metadata and controls

Spec Pipeline Workflow - Documentação Completa

1. Visão Geral

1.1 Propósito

1.2 Principios Fundamentais

2. Diagrama do Workflow

2.1 Fluxo Principal

2.2 Fluxo por Complexidade

2.3 Diagrama de Sequência

3. Steps Detalhados

3.1 Fase 1: Gather Requirements

Inputs

Outputs

Processo de Elicitação (9 Categorias)

Estrutura do Output (requirements.json)

3.2 Fase 2: Assess Complexity

Inputs

Outputs

5 Dimensões de Complexidade

Thresholds de Classificação

3.3 Fase 3: Research Dependencies

Inputs

Outputs

Fluxo de Pesquisa

Prioridade de Ferramentas

3.4 Fase 4: Write Specification

Inputs

Outputs

Constitutional Gate: No Invention

Estrutura do spec.md

3.5 Fase 5: Critique Specification

Inputs

Outputs

5 Dimensões de Qualidade

Lógica de Verdict

3.6 Fase 5b: Revise Specification

Inputs

Outputs

3.7 Fase 5c: Second Critique

3.8 Fase 6: Create Implementation Plan

Inputs

Outputs

Regras de Subtasks

4. Agentes Participantes

4.1 Perfil: @pm (Morgan)

4.2 Perfil: @architect (Aria)

4.3 Perfil: @analyst (Atlas)

4.4 Perfil: @qa (Quinn)

5. Tasks Executadas

6. Pré-requisitos

6.1 Pre-Flight Checks

6.2 Configuração Necessaria

7. Entradas e Saidas

7.1 Entradas do Pipeline

7.2 Saidas do Pipeline

8. Pontos de Decisão

8.1 Decisão: Pular Assess?

8.2 Decisão: Pular Research?

8.3 Decisão: Verdict da Critique

8.4 Decisão: Executar Revise?

8.5 Decisão: Segunda Critique?

9. Troubleshooting

9.1 Erros Comuns

9.2 Como Retomar Execucao

9.3 Árvore de Decisão de Erros

10. Referências

10.1 Arquivos do Workflow

10.2 Agentes Relacionados

10.3 Documentação Relacionada

10.4 Commands Rapidos

11. Mensagem de Conclusão

Metadata