Ir para o conteúdo

Guia de Workflows — NS Flow Kit

Documentação operacional dos workflows do NS Flow Kit para os times. Cada documento explica o que o workflow faz, quando usá-lo, quais pastas e arquivos ele gera, e como o time aplica na prática — da instalação ao encerramento do ticket.

Filosofia do kit: agentes executam, humanos decidem. Todo workflow tem pontos de parada obrigatórios (checkpoints) onde uma pessoa aprova antes de prosseguir.

Por onde começar

  1. 00 — Instalação e Setup — pré-requisito de todos os workflows. Instale e configure uma vez por repositório antes de rodar qualquer fluxo. Os docs de workflow assumem que esta etapa já foi concluída.

  2. Escolha o workflow conforme a natureza da demanda (tabela abaixo).

Duas esteiras

O kit tem duas esteiras em paralelo que convergem no board:

  • Produto (upstream): o PO parte de uma ideia/texto e cria a demanda já pronta no board — /discover. Ver Product Discovery Flow e o Guia do PO.
  • Sustentação (card-first): a demanda já chega como card → /route → bug/data-fix/feature.

Ambas alimentam a esteira de dev (/feature). Sobre toda a esteira de dev roda a Camada de Qualidade — 4 gates shift-left (cobertura · smoke · E2E · security) que garantem que nada sai sem qualidade. Ver também o Guia do QA Owner.

Catálogo de workflows core

# Workflow Quando usar Trigger inicial Doc
0 Product Discovery 🔬 Ideia de produto sem card no board (esteira upstream) /discover "{texto}" product-discovery-flow.md
1 Feature Nova funcionalidade ou melhoria significativa /feature <ticket> feature-development.md
2 Bug Defeito reportado com root cause única /analyze-bug <ticket> bug-flow.md
3 Small Improvement Ajuste leve sem impacto em lógica de negócio /analyze-bug <ticket> small-improvement-flow.md
4 Data Fix Root cause é puramente de banco (sem código) /analyze-bug → /data-fix <ticket> data-fix-flow.md
5 Vulnerability 🔬 Findings de SAST/DAST/pentest por classe CWE /scan-vuln → /analyze-vuln CWE-NN vulnerability-flow.md
6 Orchestration Coordenar 2+ tickets em paralelo /manage-queue orchestration-flow.md
7 Health Monitor Resiliência proativa / pós-deploy / degradação /health-check <sistema> health-monitor-flow.md

🔬 = experimental — promovido para estável após 2 pilotos em stacks diferentes.

Camada transversal

Camada O que faz Triggers Doc
Quality Layer 🔬 4 gates shift-left (cobertura · smoke · E2E · security) sobre a esteira de dev /qa-plan · /run-regression · /smoke · /validacao-testes · /qa-gate quality-flow.md · qa-owner-guide.md

Como escolher o workflow certo

Chegou uma demanda
        │
        ├── É uma ideia de produto, sem card no board? ─► Product Discovery (/discover)
        │
        ├── É nova funcionalidade (já tem card)? ──► Feature
        │
        ├── É defeito reportado por usuário?
        │       ├── Afeta lógica/integração/banco? ─► Bug
        │       ├── Root cause é só dados/schema? ──► Data Fix
        │       └── Ajuste leve (texto, label, log)? ► Small Improvement
        │
        ├── Veio de auditoria de security (CWE)? ──► Vulnerability
        │
        ├── É sinal de degradação/saúde? ──────────► Health Monitor
        │
        └── São vários tickets concorrendo? ───────► Orchestration (coordena os demais)

Em dúvida entre Bug e Small Improvement, comece pelo /analyze-bug — o agente classifica e, se encontrar um bug real ou risco alto, escala para o Bug Flow completo.

Conceitos transversais (valem para todos os workflows)

Conceito O que significa
Speckit First Antes de investigar, o agente lê .speckit/ (domínio, risk-map, ADRs, known-issues).
Checkpoints humanos Pontos de parada obrigatórios. O agente apresenta um resumo e aguarda aprovação.
Rastreabilidade Todo artifact carrega um identificador rastreável (ex.: {TICKET_ID}, SCAN-{...}, {SISTEMA}).
Minimum Viable Patch Fixes mínimos e dentro do escopo. Nenhum refactoring oportunístico.
RED→GREEN Teste de regressão que falha antes do fix.
Encerramento via learning-agent O ticket só fecha quando o learning-agent atualiza o Speckit pós-deploy.

Estrutura de pastas (compartilhada por todos os workflows)

.speckit/            ← ENTRADA: base de conhecimento (consultada por todos os agentes)
  domain/  architecture/  business-rules/  known-issues/  design-system/  decisions/  incidents/

.ns-flow/            ← SAÍDA: artifacts gerados por ticket (algumas subpastas são criadas sob demanda)
  intake/            ← Routing Decisions (/route)
  analysis/          ← BugReport, ImpactReport, VulnReport
  design/            ← spec, arch-guidance, ux-guidance, tasks, Mini RFC
  discovery/         ← ImprovementScope, VulnInventory
  product/           ← Product Brief, backlog, protótipo (Product Discovery)
  delivery/          ← PatchBundle, CodeReviewReport, ValidationReport, PR, Release
  state/             ← STATE por ticket (entre sessões)
  orchestration/     ← Queue Reports
  monitoring/        ← Health Reports
  templates/         ← templates reutilizáveis

migrations/          ← scripts SQL versionados (Data Fix)
tools/               ← wrappers de scanners SAST (Vulnerability)

A localização exata pode ser configurada por ARTIFACTS_DIR (.ns-flow) e SPECKIT_DIR (.speckit) no CLAUDE.md do projeto. Os comandos do kit já respeitam essas variáveis automaticamente; só ajuste docs/scripts do seu repositório se você tiver paths hardcoded.

Voltar ao topo