@nstechhub/corporate-ns-flow-kit

v1.3.0

Published

4 days ago

Agent-Driven Lifecycle Kit para sistemas legados — agentes executam, humanos decidem.

Downloads

375

0High
0Medium
0Low

cleitonborges

mau-ricio

 ███╗   ██╗███████╗    ███████╗██╗      ██████╗ ██╗    ██╗    ██╗  ██╗██╗████████╗
 ████╗  ██║██╔════╝    ██╔════╝██║     ██╔═══██╗██║    ██║    ██║ ██╔╝██║╚══██╔══╝
 ██╔██╗ ██║███████╗    █████╗  ██║     ██║   ██║██║ █╗ ██║    █████╔╝ ██║   ██║
 ██║╚██╗██║╚════██║    ██╔══╝  ██║     ██║   ██║██║███╗██║    ██╔═██╗ ██║   ██║
 ██║ ╚████║███████║    ██║     ███████╗╚██████╔╝╚███╔███╔╝    ██║  ██╗██║   ██║
 ╚═╝  ╚═══╝╚══════╝    ╚═╝     ╚══════╝ ╚═════╝  ╚══╝╚══╝     ╚═╝  ╚═╝╚═╝   ╚═╝

Powered by Claude Code · Speckit · BMAD · TLC Spec-Driven

"Humans Decide. Agents Execute."
Transform legacy engineering from reactive and tribal into structured,
agent-assisted, and measurable — without rewriting a single system.

Quick Start · Como Funciona · Agentes · Speckit · Roadmap

O Problema

Times que mantêm sistemas legados heterogêneos (.NET, Java, Delphi, Oracle, PHP) enfrentam os mesmos problemas repetidos:

| Problema | Impacto | |----------|---------| | Conhecimento tribal | Só quem construiu sabe consertar | | Discovery manual lento | Dev passa horas investigando antes de escrever uma linha | | Blast radius desconhecido | Fix em um sistema quebra três outros | | Processo inconsistente | Cada dev tem seu próprio jeito de resolver bugs | | Zero aprendizado institucional | O mesmo bug ressurge sem que ninguém saiba |

O ns-flow-kit resolve cada um desses problemas com uma abordagem estruturada: agentes de IA especializados executam o trabalho pesado, humanos validam e decidem.

Como Funciona

┌──────────────────────────────────────────────────────────────────────┐
│            AZURE DEVOPS Boards   ou   GITHUB Issues                  │
│         Entrada oficial das demandas (provider escolhido             │
│                 por projeto durante o setup-mcp)                     │
└──────────────────────┬───────────────────────────────────────────────┘
                       │
       ┌───────────────┼───────────────┐
       ▼               ▼               ▼
┌─────────────┐  ┌──────────┐  ┌─────────────────────────────┐
│  BUG FLOW   │  │ FEATURE  │  │   VULNERABILITY FLOW 🔬     │
│             │  │   FLOW   │  │     (v1.2.0-experimental)   │
│ bug-        │  │          │  │                             │
│ investigator│  │ /feature │  │ /scan-vuln                  │
│   ↓         │  │   ↓      │  │   └── vuln-triage           │
│ impact-     │  │ spec +   │  │       (Semgrep + Veracode   │
│ analyzer    │  │ tasks    │  │        + pentest, dedup,    │
│   ↓         │  │   ↓      │  │        FPs auditáveis)      │
│ architecture│  │ builder- │  │   ↓                         │
│ -agent      │  │ agent    │  │ /analyze-vuln CWE-NN        │
│   ↓         │  │          │  │   └── vuln-investigator     │
│ builder-    │  │          │  │       (L1–L4, padrão único) │
│ agent       │  │          │  │                             │
└─────┬───────┘  └────┬─────┘  └──────────────┬──────────────┘
      │               │                       │
      └───────────────┼───────────────────────┘
                      ▼
              ┌───────────────┐
              │ test-validator│  (+ re-scan SAST se vuln-flow)
              │      ↓        │
              │ pr-generator  │  (+ /security-review se vuln-flow)
              │      ↓        │
              │ release-agent │  (consulta release-policy.md)
              │      ↓        │
              │ learning-agent│  (+ cwe-catalog update se vuln-flow)
              └───────┬───────┘
                      │
              Claude Code (executor)
                      │
     ┌────────────────┴────────────────────┐
4–5 checkpoints                     dados gerados
humanos                            automaticamente
     │                                     │
     ▼                                     ▼
┌────────────────┐         ┌──────────────────────────────────┐
│   .ns-flow/    │         │         SPECKIT LAYER            │
│  (Governança)  │         │     (Memória Institucional)      │
│                │         │                                  │
│ analysis/      │         │  Known Issues · Anti-Patterns    │
│ design/        │         │  ADRs · Incidents · Domain       │
│ delivery/      │         │  Context · Risk Maps             │
│ discovery/     │         │  CWE Catalog 🔬                  │
│ state/         │         │                                  │
└────────────────┘         └──────────────────────────────────┘

Quick Start — Repo Legado Existente

Este é o caminho principal do kit: adicionar o NS Flow Kit a um repositório que já existe.

Passo 1 — Escolha sua ferramenta de IA

O kit funciona com qualquer ferramenta de IA, porém está otimizado para uso com o Claude Code.

Pode ser usado também com:

GitHub Copilot
ChatGPT
Gemini

Caminho A — Claude Code CLI (recomendado)

Automação completa: slash commands nativos, encadeamento de agentes automático, bootstrap semântico.

# Node.js 18 ou superior
node --version          # deve retornar v18.x ou superior

# Instalar o Claude Code
npm install -g @anthropic/claude-code

# Login — requer conta Anthropic (plano Max ou API key em platform.anthropic.com)
claude login

# Confirmar instalação
claude --version

Com Claude Code, todos os comandos funcionam nativamente no terminal: /bootstrap-repo, /update-speckit, /analyze-bug, /generate-fix, /run-regression, /open-pr e /release-check.

Caminho B — Cursor ou VS Code com IA (Claude, Copilot, Gemini)

Sem install extra além da IDE que você já usa. O bootstrap roda como script de terminal, e os agentes são acionados via chat da sua IDE.

Pré-requisito: ter Cursor, VS Code + GitHub Copilot, VS Code + Claude, ou VS Code + Gemini Code Assist já instalado e funcionando.

O fluxo de trabalho é semi-manual:

Rodar o bootstrap via terminal (Passo 3)
Para cada ticket, abrir o arquivo do agente em .claude/agents/ e colar o conteúdo no chat da IDE
Salvar os artifacts gerados em .ns-flow/ manualmente

Caminho C — Qualquer IA no browser (claude.ai, ChatGPT, Gemini)

Funciona em ambientes sem acesso à internet no terminal ou com restrições corporativas.

Pré-requisito: acesso a qualquer assistente de IA via browser.

O bootstrap roda como script bash puro (sem precisar do Claude Code). Os prompts dos agentes ficam em .claude/agents/ — você copia, cola no chat e salva os resultados.

Bootstrap sem Claude Code: os Passos 2–3 funcionam em todos os caminhos. O script bootstrap-speckit.sh usa o Claude Code para análise semântica se ele estiver disponível, e cai para modo estático (mais campos [DRAFT]) caso contrário. O kit é funcional nos dois casos.

Passo 2 — Configurar MCPs (recomendado)

MCPs (Model Context Protocol) permitem que os agentes leiam e escrevam tickets diretamente no provider — sem copiar/colar manual. O kit suporta dois providers em paralelo, escolhidos por projeto:

| Provider | MCP usado | Refiner correspondente | Ticket ID padrão | |---|---|---|---| | Azure DevOps (Boards + Repos) | @azure-devops/mcp | azure-card-refiner | ADO-{num} | | GitHub (Issues + Repos) | @modelcontextprotocol/server-github | github-issue-refiner | GH-{num} |

Quando configurado, /analyze-bug <ticket-id> busca o ticket automaticamente no provider escolhido, e o refiner correspondente consegue analisar repositórios remotos sem clonar.

O kit traz dois templates (.mcp.json.template.azure-devops e .mcp.json.template.github) na raiz e um comando setup-mcp que pergunta o provider, coleta os valores específicos e gera o .mcp.json final com valores literais — sem depender de variáveis de ambiente do shell.

Setup interativo (Azure DevOps ou GitHub)

npx @nstechhub/corporate-ns-flow-kit setup-mcp
# ou explicitamente:
npx @nstechhub/corporate-ns-flow-kit setup-mcp --provider azure-devops
npx @nstechhub/corporate-ns-flow-kit setup-mcp --provider github

Backward-compat: projetos com .local-config.json v1 (Azure flat — gerado por versões anteriores do kit) são migrados silenciosamente para v2 ao re-rodar setup-mcp. O .mcp.json resultante é byte-idêntico ao gerado antes da mudança — coberto por snapshot test em tests/init-azure-fixture.test.js.

O que o `setup-mcp` faz

Detecta conflito com user scope. Se você já tem um MCP azure-devops registrado em ~/.claude.json (de um claude mcp add ... -s user anterior), o setup pergunta:
- [1] Remover o user scope e configurar no projeto (recomendado).
- [2] Manter o user scope existente e pular a configuração do MCP no projeto.
User scope tem precedência sobre project scope no Claude Code, então deixar os dois ativos faz o .mcp.json do projeto ficar inativo.
Pergunta o modo de autenticação (apenas se for configurar o MCP do projeto):
Para Azure DevOps:
| Modo | Quando escolher | Pré-requisito | |---|---|---| | az login (padrão, recomendado) | Você tem o Azure CLI e consegue rodar az login | Azure CLI + az login --allow-no-subscriptions | | PAT (Personal Access Token) | Ambientes onde az login interativo é bloqueado (proxy/MITM, máquinas restritas) | Token gerado em https://dev.azure.com/<org>/_usersSettings/tokens |
Para GitHub:
| Modo | Quando escolher | Pré-requisito | |---|---|---| | gh-cli (padrão, recomendado) | Você tem o gh CLI e fez gh auth login | GitHub CLI instalado + autenticado | | PAT (Personal Access Token) | Ambientes sem gh CLI ou para usar token específico | Token criado em https://github.com/settings/tokens com escopos repo, read:org |
Pergunta os valores que afetam o subagent correspondente ao provider:
Azure DevOps — alimenta azure-card-refiner:
| Pergunta | Exemplo | Onde é usado | |---|---|---| | Organização do Azure DevOps | minhaorg (parte da URL https://dev.azure.com/<org>) | Gravado literalmente no .mcp.json | | (modo PAT) Email/UPN | [email protected] | Compõe base64(<email>:<pat>) no .mcp.json | | (modo PAT) Personal Access Token | <token> (em texto claro durante o input) | Mesmo | | Caminho-raiz das aplicações locais | E:\Projetos\NS | azure-card-refiner faz Glob/Grep aqui | | Diretório dos briefings .md | C:\Users\<user>\Documents\cards-briefing | Onde o subagent grava cada refinamento | | Projetos do Azure DevOps em ordem de prioridade | DEV - PROJETO ALBATROZ, Plataformas | Subagent busca aqui quando a aplicação não está no caminho local |
GitHub — alimenta github-issue-refiner:
| Pergunta | Exemplo | Onde é usado | |---|---|---| | Owner do GitHub | nstechhub (parte da URL https://github.com/<owner>) | Gravado em providers.github.owner | | Repositórios em ordem de prioridade | corporate-ns-flow-kit, outro-repo | Subagent prioriza nessa ordem para busca remota | | (modo PAT) Personal Access Token | ghp_<token> (texto claro durante input) | Gravado literalmente no .mcp.json | | (modo gh-cli) — token coletado de gh auth token | (automático) | Mesmo | | Caminho-raiz das aplicações locais | E:\Projetos\NS | github-issue-refiner faz Glob/Grep aqui | | Diretório dos briefings .md | C:\Users\<user>\Documents\cards-briefing | Onde o subagent grava cada refinamento ({data}_gh{num}_{slug}.md) |
Gera os arquivos:
- .mcp.json — com valores literais (sem ${VAR}). Não depende de env vars — qualquer terminal que você abrir lê esse arquivo direto.
- .claude/.local-config.json — config persistida (sem o PAT em si). É a fonte da verdade dos caminhos e projetos para o subagent.
- .gitignore — adiciona .mcp.json e .claude/.local-config.json para evitar commit acidental de credenciais ou caminhos pessoais.
Nota: o subagent azure-card-refiner é versionado direto no kit (sem renderização per-user). Ele lê .claude/.local-config.json em runtime na primeira ação (Etapa 0). Para alterar caminhos depois, edite o JSON direto — sem precisar re-rodar setup-mcp. Se o config estiver ausente ou inválido, o agente aborta e instrui você a rodar setup-mcp.
Verifica az login (no modo azcli) e claude mcp list.
Roda um smoke test das credenciais (v1.1.0+):
- GitHub: gh api user + gh api repos/{owner}/{primeiro_repo} para validar que o token consegue ler.
- Azure DevOps: az account show + az devops project list --org <org>.
- Falha aqui downgrada mcpConfigured: false no config — você descobre o problema antes de tentar o primeiro /analyze-bug, não no meio dele.
- Resultado fica registrado em providers.<p>.mcpSmokeTestStatus (passed | failed | skipped).

Re-executar é seguro. O PAT, por segurança, precisa ser digitado novamente a cada execução (apenas o email é lembrado).

Escopos do PAT GitHub: ver .mcp.json.template.github.README.md para o passo-a-passo de criação (classic e fine-grained) com os escopos exatos: repo, read:org, workflow. Em ambientes com SSO, prefira o modo gh-cli — o token rotaciona automaticamente quando você roda gh auth refresh.

(Opcional) Comentários automáticos nos checkpoints

A partir da v1.1.0, cada um dos 4 checkpoints humanos pode postar um comentário curto na issue/work-item de origem. Desligado por default. Para habilitar, acrescente ao .claude/.local-config.json:

{
  "checkpointNotifications": {
    "enabled": true,
    "postToProvider": true,
    "mentions": ["@reviewer-handle"]
  }
}

Cada checkpoint posta uma linha do tipo [NS Flow Kit] Checkpoint 2 — patch gerado. Aguardando revisão do código. Idempotente (não duplica em re-runs). Suporte a --silent para override pontual no comando. Detalhes do protocolo em .claude/agents/_shared/checkpoint-notify.md.

Modo `az login` — pré-setup

# Instale o Azure CLI uma vez (Windows)
winget install -e --id Microsoft.AzureCLI

# Faça login (se a rede corporativa bloquear o callback do navegador, use --use-device-code)
az login --allow-no-subscriptions
# ou
az login --allow-no-subscriptions --use-device-code

Modo PAT — gerando o token

Acesse https://dev.azure.com/<sua-org>/_usersSettings/tokens → New Token.

Permissões mínimas:

| Escopo | Acesso | |---|---| | Work Items | Read & Write | | Code | Read | | Project and Team | Read | | Identity | Read |

Copie o token (só aparece uma vez) e cole quando o setup-mcp perguntar.

O PAT (em base64) é gravado dentro do .mcp.json gerado, que está no .gitignore. Esse arquivo fica apenas no disco local — não é commitado e não vai para o pacote npm.

Verificar se o MCP está ativo

claude mcp list

A saída deve mostrar azure-devops com status Connected. Se aparecer mas vier de User MCPs ao invés de Project MCPs, é sinal de que existe configuração antiga em user scope — rode setup-mcp de novo e escolha a opção 1, ou remova manualmente:

claude mcp remove azure-devops -s user

Apenas o .mcp.json.template e o subagent .claude/agents/azure-card-refiner.md são versionados no kit. Cada usuário gera o .mcp.json rodando setup-mcp, e os valores per-user ficam em .claude/.local-config.json. Ambos os arquivos gerados são adicionados automaticamente ao .gitignore do projeto. O subagent é o mesmo código para todos — ele lê os valores do JSON em runtime.

Passo 3 — Instalar o kit no seu repo

Via `npx` (recomendado — requer Node 18+)

cd /caminho/do/seu/repo
npx @nstechhub/corporate-ns-flow-kit init

O comando já aplica chmod +x scripts/*.sh automaticamente no Linux/macOS. Re-execute com --force para sobrescrever arquivos já existentes.

Alternativa — `git clone` manual

# Entre na raiz do seu repositório legado
cd /caminho/do/seu/repo

# Baixar o kit numa pasta temporária
git clone https://github.com/nstechhub/corporate-ns-flow-kit.git /tmp/ns-flow-kit

# Copiar as pastas de configuração para o seu repo
cp -r /tmp/ns-flow-kit/.claude .
cp -r /tmp/ns-flow-kit/.ns-flow .
cp -r /tmp/ns-flow-kit/.speckit .
cp -r /tmp/ns-flow-kit/scripts .
cp -r /tmp/ns-flow-kit/migrations .
cp    /tmp/ns-flow-kit/CLAUDE.md .

# Dar permissão de execução aos scripts
chmod +x scripts/*.sh

O que foi copiado e por quê:

| Pasta/Arquivo | Função | |---------------|--------| | .claude/ | Agentes, comandos, políticas e contexto operacional | | .ns-flow/ | Pasta onde os artifacts de cada ticket são salvos | | .speckit/ | Base de conhecimento do sistema (será preenchida no passo 3) | | scripts/ | Bootstrap, update e inicialização de tickets | | docs/ | Guias de onboarding e compatibilidade de IDE | | migrations/ | Templates para scripts de banco versionados | | CLAUDE.md | Instruções que o Claude Code lê automaticamente ao abrir o projeto |

Passo 4 — Bootstrap do Speckit

Com Claude Code instalado, use o slash command diretamente na raiz do repositório:

claude
/bootstrap-repo NOME_SISTEMA --stack dotnet

O comando detecta o stack automaticamente se --stack for omitido, faz análise estática via script + análise semântica com Claude Code, e exibe ao final o número de campos [DRAFT] restantes.

Sem Claude Code instalado — modo script direto:

./scripts/bootstrap-speckit.sh \
  --repo .              \
  --system NOME_SISTEMA \
  --stack dotnet

Flags opcionais para integração com Azure DevOps:

./scripts/bootstrap-speckit.sh \
  --repo .               \
  --system NOME_SISTEMA        \
  --stack dotnet         \
  --ado-org minha-org    \
  --ado-project meu-proj \
  --since "2 years ago"

O que o bootstrap produz (executado em etapas com paradas para revisão):

| Camada | Arquivos | Para quem | |--------|---------|-----------| | Speckit | system-overview, risk-map, architecture-overview, known-issues, anti-patterns | Agentes NS Flow Kit | | CLAUDE.md raiz | Stack, entidades centrais, regras de ouro, glossário, navegação, perguntas em aberto | Devs + agentes | | ARCHITECTURE.md | Visão de componentes + mínimo 5 diagramas Mermaid | Devs + agentes | | PATTERNS.md | Padrões ativos (com path:linha), anti-patterns, zona cinzenta | Devs + agentes | | Context docs | .claude/context/{modulo}-context.md para hotspots — checklist de segurança | Agentes |

Tempo esperado: 20–40 minutos (inclui paradas para revisão humana entre etapas).

Passo 5 — Revisar os DRAFTs gerados

O bootstrap gera arquivos marcados com [DRAFT] onde não conseguiu inferir com certeza. Revisar esses arquivos é necessário antes de usar os agentes — eles são a fonte de contexto.

Arquivos gerados em .speckit/ (ordem de prioridade para revisão):

.speckit/
├── domain/
│   └── system-overview.md          ← REVISAR PRIMEIRO: módulos, criticidade, banco
├── architecture/
│   ├── architecture-overview.md    ← stack, padrão arquitetural, restrições
│   └── risk-map.md                 ← hotspots — validar se os arquivos listados fazem sentido
└── known-issues/
    ├── {sistema}-known-issues.md   ← padrões de bug extraídos dos commits
    └── anti-patterns-detected.md   ← SQL concatenado, credentials, god classes

Para cada arquivo:

Leia e corrija os campos [DRAFT - verificar]
Remova inferências incorretas
Adicione contexto que só quem trabalha no sistema conhece

O bootstrap exibe ao final o número de campos [DRAFT] restantes. Use esse número para decidir se vale acionar o Speckit Amplifier (seção abaixo) antes do primeiro ticket.

O NS Flow Kit já funciona com o Speckit gerado aqui. Quanto mais [DRAFT] resolvidos, mais preciso o bug-investigator — mas a operação não precisa esperar o Speckit estar perfeito.

Speckit Amplifier — captura de conhecimento tácito (opcional)

O bootstrap analisa o que o código mostra. Ele não captura o que está na cabeça de quem mantém o sistema: medos, nomes enganosos, cascatas ocultas, decisões contraintuitivas.

Quando vale usar: quando o bootstrap gerou 15+ campos [DRAFT], ou quando as investigações estão exigindo muito contexto manual por ticket.

Como funciona: uma call de 45–60 min com devs seniores, transcrita e processada pelo Claude Code em 5 etapas. O output vai direto para o Speckit, substituindo os [DRAFT] restantes.

# Ver o template com as perguntas e etapas
cat .speckit/domain/tribal-knowledge-template.md

O que o Amplifier gera além do bootstrap:

| Arquivo | O que captura | |---------|--------------| | system-overview.md (enriquecido) | Medos, pontos de pessoa única, avisos da equipe | | domain/naming-guide.md | "Nomes que mentem" — classes e pastas com nomes enganosos | | known-issues/gray-zones.md | Onde o código faz de dois jeitos sem um padrão definido | | domain/diagnostic-guide.md | Tabela "sintoma → onde investigar" para o bug-investigator | | .claude/context/{modulo}-context.md | Checklist "como modificar com segurança" por pasta quente |

Não é obrigatório, não tem prazo, e pode ser feito a qualquer momento — inclusive depois do primeiro ticket, quando o time já viu o valor do processo.

Passo 6 — Abrir o Claude Code e rodar o primeiro ticket

# Na raiz do seu repo legado
claude

O Claude Code vai ler o CLAUDE.md automaticamente e carregar as instruções operacionais.

Com um ticket do Azure DevOps em mãos, utilize o comando adequado:

/analyze-bug ADO-4821

O agente vai:

Ler o .speckit/ para contexto
Pedir logs ou detalhes adicionais se precisar
Produzir um BugReport + ImpactReport em .ns-flow/analysis/

Você revisa → aprova → continua com /generate-fix ADO-4821.

Ou para novas features:

/feature ADO-4821

Você revisa e continua com "Especifique a tarefa 1" ou "Implemente a tarefa 1"

Passo 6.5 (opcional) — Habilitar o security flow

Se o projeto tem findings de SAST/Pentest a tratar, rode o bootstrap específico de security uma vez:

/bootstrap-security --stack dotnet

Isso popula .speckit/known-issues/cwe-catalog.md com OWASP Top 10 + CWEs do stack, configura o bloco veracode e semgrep no .local-config.json, e prepara tools/{semgrep,veracode}/ (já distribuído pelo init).

Configure as env vars uma vez (não comite):

# Windows
[Environment]::SetEnvironmentVariable('VERACODE_API_ID',  '<id>',  'User')
[Environment]::SetEnvironmentVariable('VERACODE_API_KEY', '<key>', 'User')

# Linux/macOS/WSL
export VERACODE_API_ID='<id>'
export VERACODE_API_KEY='<key>'

Depois:

/scan-vuln                     # consolida Semgrep + Veracode + pentest
/analyze-vuln CWE-79 GH-456    # investiga uma classe específica

Detalhes: ver seção Fluxo de Vulnerabilidade abaixo.

O Squad de Agentes

Dez agentes especializados (8 do ciclo principal + 2 de security). Cada um tem responsabilidade única, limites definidos e output estruturado.

| Agente | Papel | Ativação | |--------|-------|---------| | bug-investigator | Diagnóstica root cause a partir do ticket + logs + codebase | /analyze-bug | | impact-analyzer | Mapeia blast radius em todos os sistemas e clientes afetados | Auto-encadeado | | architecture-agent | Valida abordagem contra ADRs e políticas | Condicional | | builder-agent | Gera o patch mínimo e escopo controlado | /generate-fix | | test-validator | Escreve e planeja validação + regressão | /run-regression | | pr-generator | Monta PR completo com rollback plan | Auto-encadeado | | release-agent | Orquestra release seguro com gates de qualidade (PR aprovado + CI) | /release-check | | learning-agent | Atualiza Speckit, registra métricas e fecha a issue no provider | Auto no fechamento | | vuln-triage 🔬 | Ingestão multi-fonte (Semgrep + Veracode + pentest), dedup, FP filtering, status tracking | /scan-vuln | | vuln-investigator 🔬 | Investigação por classe CWE (todas as instâncias), padrão único de fix, hipóteses L1–L4 | /analyze-vuln |

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

Protocolos compartilhados (v1.1.0+)

A partir da v1.1.0, os agentes do ciclo compartilham dois protocolos canônicos para evitar drift entre implementações:

| Protocolo | Função | Usado por | |---|---|---| | _shared/ticket-fetch.md | Etapa 0 — busca o ticket no provider (MCP do GitHub/Azure ou CLI) e normaliza em .ns-flow/state/<TICKET_ID>-ticket.json | bug-investigator, impact-analyzer, pr-generator, release-agent, learning-agent | | _shared/checkpoint-notify.md | Notificação opt-in nos 4 checkpoints humanos | comandos /analyze-bug, /generate-fix, /open-pr, /release-check | | _shared/refiner-common.md | Protocolo dos refiners | azure-card-refiner, github-issue-refiner |

Comandos Claude Code (slash commands)

# Bug flow / Feature flow
/bootstrap-repo Nome-Sistema --stack dotnet          # onboarding do repo — Speckit + docs
/update-speckit Nome-Sistema --since "2 weeks ago"   # varredura periódica pós-sprint
/analyze-bug <ticket-id>                              # inicia investigação completa (ex: ADO-4821 ou GH-1234)
/generate-fix <ticket-id>                             # gera o patch
/run-regression <ticket-id>                           # valida + escreve testes
/open-pr <ticket-id>                                  # cria PR com contexto completo
/release-check <ticket-id>                            # verifica gates e gera release package
/feature <ticket-id>                                  # inicia workflow de nova feature completa

# Security flow 🔬 (experimental v1.2.0)
/bootstrap-security --stack dotnet                    # popula cwe-catalog + scaffold tools/<scanner>/
/scan-vuln                                            # Semgrep + Veracode + pentest, dedup, FPs auditáveis
/scan-vuln --semgrep-only                             # apenas Semgrep
/scan-vuln --veracode-only --veracode-app=Prod        # Veracode com override de app (Dev vs Prod)
/scan-vuln --include-pentest=audits/2026-Q1.pdf       # adiciona pentest manual ao inventário
/analyze-vuln CWE-79 <ticket-id>                      # investigação por classe — padrão único de fix

Comandos do CLI (`npx @nstechhub/corporate-ns-flow-kit`)

npx @nstechhub/corporate-ns-flow-kit init                                # instala/atualiza o kit no projeto
npx @nstechhub/corporate-ns-flow-kit setup-mcp                           # configura MCP (provider auto-detect ou pergunta)
npx @nstechhub/corporate-ns-flow-kit setup-mcp --provider github         # força provider GitHub
npx @nstechhub/corporate-ns-flow-kit setup-mcp --provider azure-devops   # força provider Azure DevOps
npx @nstechhub/corporate-ns-flow-kit setup-mcp --switch                  # alterna provider preservando configs históricas
npx @nstechhub/corporate-ns-flow-kit setup-workflows                     # copia templates GitHub Actions ou Azure Pipelines

Subagentes especializados (não slash commands — auto-roteados)

| Subagente | Quando é acionado | Provider | |---|---|---| | azure-card-refiner | "Refinar card 1234 do Azure DevOps" | Azure DevOps | | github-issue-refiner | "Refinar issue 42 do GitHub" | GitHub | | expert_<APP_SLUG> | Perguntas sobre uma app específica (criados via /new-app-expert-agent) | Qualquer | | doc-gen | "Gera doc técnica desse projeto" | Agnóstico |

Fluxo do Bug (visão do desenvolvedor)

1. /analyze-bug <ticket-id>            (ex: ADO-4821 ou GH-1234)
   ├── Etapa 0 compartilhada: busca o ticket no provider via MCP/CLI
   │   e normaliza em .ns-flow/state/<TICKET_ID>-ticket.json
   └── Agente investiga, busca no Speckit, produz BugReport + ImpactReport

2. ⚡ Você revisa → aprova a estratégia de fix
   (notificação opcional postada na issue, se habilitada)

3. /generate-fix <ticket-id>
   ├── builder-agent valida nome da branch contra branch-naming.md
   │   e propõe o nome correto se não casar
   └── Agente gera patch mínimo dentro do escopo declarado

4. ⚡ Você revisa o patch → aprova para validação

5. /run-regression <ticket-id>
   └── Agente escreve e executa testes

6. /open-pr <ticket-id>
   ├── Push automático da branch para origin
   ├── Cria o PR via MCP do GitHub (ou az repos pr create para Azure)
   ├── Aplica labels canônicas: ns-flow-kit, needs-review, {bug|improvement|feature}
   └── Acrescenta "Closes #N" automaticamente (GitHub) para auto-fechar a issue

7. ⚡ Reviewer aprova o PR

8. /release-check <ticket-id>
   ├── Consulta status do CI via MCP (gh pr checks / get_pull_request_status)
   ├── Consulta aprovação do PR via MCP (reviewDecision)
   └── Gates determinísticos — bloqueia se CI pendente ou vermelho

9. ⚡ Você aprova o deploy

10. ✅ Confirme o deploy → learning-agent encerra o ticket
    ├── Atualiza Speckit e metrics-feed
    └── Fecha a issue no provider (se Closes #N não fechou) + comentário
        com link do release

4 decisões humanas. Todo o resto: agentes — agora com PR criado, CI verificado e issue fechada automaticamente.

Fluxo de Nova Feature (visão do desenvolvedor)

1. /feature ADO-{id}
   └── Agente consulta Speckit, faz perguntas de clarificação,
       avalia tamanho (Small/Medium/Large/Complex) e captura
       requisitos com IDs rastreáveis (FEAT-01, FEAT-02...)

2. ⚡ Você revisa o escopo e o plano de fases → aprova para continuar

3. "design da feature"   [apenas se Large ou Complex]
   └── Agente valida contra ADRs, mapeia hotspots, propõe arquitetura

4. "quebrar em tasks"    [apenas se Large ou Complex]
   └── Agente cria tasks atômicas com dependências e critérios de conclusão

5. ⚡ Você revisa o plano de implementação → aprova para executar
   (para Small/Medium, os passos 3-5 colapsam em um único checkpoint)

6. "implementar T1" / "executar"
   └── Agente implementa task por task: RED→GREEN → commit atômico → próxima

7. /open-pr ADO-{id}
   └── PR criado com requisitos rastreados, rollback plan e checklist

8. ⚡ Reviewer aprova o PR

9. /release-check ADO-{id}
   └── Gates verificados, release package gerado

10. ⚡ Você aprova o deploy

11. ✅ Confirme o deploy → learning-agent encerra o ticket
    └── Gate obrigatório — Speckit atualizado, métricas registradas

2 checkpoints para features pequenas. 4 para Large/Complex. Todo o resto: agentes.

Fluxo de Vulnerabilidade (🔬 experimental v1.2.0)

Use quando há findings de SAST/Pentest, OWASP Top 10 ou relatório de auditoria de security. Diferente do bug-flow, trata classes inteiras de CWE em vez de root cause única.

1. /scan-vuln                                  (ou --semgrep-only / --veracode-only / --include-pentest)
   ├── vuln-triage consolida Semgrep + Veracode + pentest
   ├── deduplica por (file, line, cwe)
   ├── descarta FPs com justificativa textual (auditável)
   └── propõe waves por alavanca: config → cookies → output → info → design

2. ⚡ Você valida o escopo e ondas (Checkpoint 0)

3. /analyze-vuln CWE-NN <ticket-id>
   ├── vuln-investigator formula hipóteses L1–L4 ANTES de Grep
   ├── confirma instâncias no codebase (verificação humana, não só scanner)
   └── propõe padrão único de fix para TODAS as N instâncias da classe

4. ⚡ Você aprova o padrão único (Checkpoint 1)

5. /generate-fix <ticket-id>
   └── builder-agent valida branch contra branch-naming + aplica padrão
       único em todas as N instâncias

6. ⚡ Você revisa o patch (Checkpoint 2)

7. /run-regression <ticket-id>
   ├── test-validator: testes + re-scan SAST com 0 findings da classe
   └── Falha se Semgrep ainda flagra → builder volta para corrigir

8. /open-pr <ticket-id>
   ├── /security-review (gate adicional built-in do Claude Code)
   ├── PR via MCP/CLI com labels canônicas + Closes #N
   └── Dupla aprovação se mudança em utilitário endurecido

9. ⚡ Reviewer aprova o PR (Checkpoint 3)

10. /release-check <ticket-id>
    ├── release-agent consulta release-policy (fast-track de security disponível)
    ├── CI status + PR approved via MCP
    └── Re-scan SAST final para confirmar 0 findings

11. ⚡ Você aprova o deploy (Checkpoint 4)

12. ✅ Confirme o deploy → learning-agent encerra o ticket
    ├── Cria entrada CWE-NN no cwe-catalog.md se não existe (gap 4.7.2)
    ├── Acrescenta ticket ao Histórico se já existe
    └── Métricas type="vulnerability" no metrics-feed.jsonl

5 checkpoints humanos (Checkpoint 0 extra para validar escopo do triage).

Wave-N — quando o scanner revela residual pós-merge

Veracode tem lag de 24h–7d entre merge e re-scan. Se um novo scan revelar instâncias residuais:

Os artifacts da Wave 1 são renomeados com sufixo -wave1- (preserva linhagem).
Nova rodada de /analyze-vuln CWE-NN gera Wave 2 sob o mesmo ticket guarda-chuva.
PR diferente, mesmo ticket. Sem inflacionar quantidade de tickets.

KPIs do PoC original (CITNET)

| Métrica | Valor | |---|---| | Findings ingeridos | 401 brutos (168 Semgrep + 233 Veracode) | | FPs descartados auditavelmente | 155 (com justificativa em cada um) | | Findings em lag (closed-via-commit-{SHA}) | 45 | | Findings únicos pós-dedup | 192 em 13 classes CWE | | Classes CWE fechadas | 8 (CWE-79/80, 209, 524, 614, 798, 22, A05) | | Commits fix(security): em main | 24 atômicos | | CIAs cobertas | 24/24 | | Regressões pós-deploy | 0 |

Speckit — Memória Institucional

O Speckit é o que impede que o mesmo problema seja resolvido duas vezes do zero.

.speckit/
├── domain/              # mapa de sistemas, clientes, escalação
├── architecture/        # overview arquitetural, risk map, padrões de integração
├── business-rules/      # regras de negócio que afetam decisões técnicas
├── known-issues/        # padrões de bug confirmados + anti-patterns
├── decisions/           # ADR registry (Architecture Decision Records)
└── incidents/           # histórico de P1s, retrospectivas, metrics-feed

Populando o Speckit automaticamente

# Setup inicial — slash command (recomendado com Claude Code)
claude
/bootstrap-repo Nome-Sistema --stack dotnet

# Setup inicial — modo script direto (sem Claude Code)
./scripts/bootstrap-speckit.sh --repo . --system Nome-Sistema --stack dotnet

# Atualização periódica pós-sprint — slash command (recomendado)
/update-speckit Nome-Sistema --since "2 weeks ago"

# Atualização periódica — modo script direto (sem Claude Code)
./scripts/update-speckit.sh --repo . --system Nome-Sistema --stack dotnet --since "2 weeks ago"

O bootstrap analisa:

Estrutura de pastas e stack detectada
Histórico Git: hotspots, commits de bug, autores por área
TODOs, FIXMEs e GAMBIARRAs no código
SQL concatenado, catches vazios, credenciais hardcoded
Connection strings e integrações nas configs

Maturidade do Speckit

| Match Rate | O que significa | |------------|----------------| | 0–10% | Speckit recém-populado — normal no início | | 10–30% | Acumulando padrões — agentes começam a ganhar velocidade | | 30–50% | Maturidade operacional — discovery acelerado | | 50%+ | Alta maturidade — maioria dos bugs tem contexto histórico |

Ns-Flow-Kit - Framework de Governança (Baseado no BMAD-Method)

Todo ticket produz uma cadeia de artifacts rastreáveis:

.ns-flow/
├── analysis/    # BugReport + ImpactReport por ticket
├── design/      # ArchitectureGuidance + Mini RFCs
├── delivery/    # PatchBundle + ValidationReport + PR + ReleasePackage
├── discovery/   # ImprovementScope para melhorias
└── templates/   # Mini RFC · PR Template · Rollback Plan · ADR

Rastreabilidade total: do ticket ADO ao commit de produção, cada decisão tem um artifact.

Políticas (Agents Cannot Override)

| Política | O que governa | |----------|--------------| | db-change-policy | Categorias A/B/C/D para mudanças de banco — DDL bloqueia pipeline até aprovação humana | | production-policy | Nenhum acesso direto à produção — tudo via pipeline | | security-policy | Zero credenciais hardcoded, SQL parametrizado obrigatório, sanitização de inputs | | release-policy | Janelas permitidas, freeze periods, quality gates por severidade | | branch-naming (v1.1.0+) | Formato obrigatório {tipo}/{TICKET_ID}-{slug} — habilita auto-link de issue no GitHub e parsing por CI | | coding-principles | Minimum Viable Patch, hypothesis-first, RED→GREEN obrigatório, commits atômicos | | vulnerability-policy 🔬 (v1.2.0+) | 10 regras hard-stop do vulnerability-flow: onda por classe, FPs auditáveis, /security-review como gate, learning-agent obrigatório no fechamento | | release-policy 🔬 (v1.2.0+) | Janelas, freeze periods, fast-track de security, aprovação dupla para utilitários endurecidos |

Estrutura do Repositório

ns-flow-kit/
│
├── .claude/                    # Camada de execução (Claude Code)
│   ├── agents/                 # 8 agentes do ciclo + 2 de security + refiners + doc-gen
│   │   │                       #   vuln-triage [v1.2.0] · vuln-investigator [v1.2.0]
│   │   └── _shared/            # Protocolos canônicos compartilhados:
│   │                           #   - refiner-common.md (refiners)
│   │                           #   - ticket-fetch.md (Etapa 0 dos 5 agentes do ciclo) [v1.1.0]
│   │                           #   - checkpoint-notify.md (notificação opt-in) [v1.1.0]
│   ├── commands/               # /bootstrap-repo /update-speckit /analyze-bug /generate-fix /run-regression /open-pr /release-check /feature
│   │                           #   + /bootstrap-security /scan-vuln /analyze-vuln [v1.2.0]
│   ├── context/                # Contexto operacional injetado em cada sessão
│   ├── hooks/                  # Automações por evento do pipeline
│   ├── policies/               # Políticas que agentes não podem ignorar:
│   │                           #   coding-principles · db-change · production · security · release · branch-naming [v1.1.0]
│   │                           #   + vulnerability-policy · release-policy [v1.2.0]
│   ├── prompts/                # Master prompts para raciocínio complexo
│   └── workflows/              # bug-flow · feature-development · small-improvement-flow · critical-incident-flow
│                               #   + vulnerability-flow [v1.2.0]
│
├── .ns-flow/                   # Governança e artifacts por ticket
│   ├── analysis/               # BugReport, ImpactReport
│   ├── design/                 # ArchitectureGuidance, Mini RFCs
│   ├── delivery/               # Patches, validações, PRs, releases
│   ├── discovery/              # ImprovementScope
│   ├── state/                  # Estado por ticket entre sessões ({TICKET_ID}-state.md)
│   └── templates/              # Templates reutilizáveis
│
├── .speckit/                   # Memória institucional
│   ├── domain/                 # Sistemas, clientes, escalação
│   │   ├── naming-guide.md     # "Nomes que mentem" — classes com nomes enganosos
│   │   ├── diagnostic-guide.md # Tabela sintoma → onde investigar
│   │   └── tribal-knowledge-template.md  # Guia para Speckit Amplifier (call opcional)
│   ├── architecture/           # Overview, risk map, integrações
│   ├── business-rules/         # Regras de negócio com impacto técnico
│   ├── known-issues/           # Padrões de bug + anti-patterns + gray-zones
│   ├── decisions/              # ADR registry
│   └── incidents/              # Histórico P1, retrospectivas, metrics-feed
│
├── .azure-pipelines/           # Pipeline ADO (provider-aware no projeto consumidor)
├── .github/workflows/          # GitHub Actions (provider-aware no projeto consumidor)
│
├── templates/
│   └── workflows/
│       ├── github/             # pr-checks · speckit-update · release-gates (copiados via setup-workflows)
│       └── azure-pipelines/    # placeholder — projetos Azure já têm pipelines próprios
│
├── docs/
│   ├── onboarding/             # Guia para novos membros do squad
│   ├── architecture/           # Documentação de arquitetura
│   ├── runbooks/               # Runbooks operacionais e rollback plans
│   ├── troubleshooting/        # Guias de diagnóstico
│   └── release-notes/          # Histórico de releases
│
├── scripts/
│   ├── bootstrap-speckit.sh    # Popula Speckit lendo o repositório
│   ├── update-speckit.sh       # Atualização contínua do Speckit (provider-aware)
│   └── init-ticket.sh          # Inicializa workspace por ticket
│
├── migrations/                 # Scripts de banco versionados e idempotentes
├── tools/                      # Wrappers SAST para security flow [v1.2.0]
│   ├── semgrep/                #   Run-SemgrepScan.ps1 + README (local + cloud modes)
│   └── veracode/               #   Get-VeracodeFlaws.ps1 + README (REST API + HMAC, sem Java)
├── tests/                      # Snapshot test de backward-compat (init-azure-fixture)
├── CHANGELOG.md                # Histórico de mudanças (Keep a Changelog) [v1.1.0]
├── .mcp.json.template.github.README.md   # Escopos do PAT GitHub [v1.1.0]
├── .claude/.local-config.example.json    # Schema documentado da config local [v1.2.0]
└── src/                        # Código fonte (ou submodule do repo legado)

Stacks Suportados

| Stack | Bug Flow | Code Generation | Test Generation | Security Flow 🔬 | Notas | |-------|----------|----------------|----------------|-------------------|-------| | .NET Framework 4.8 | ✅ | ✅ | ✅ xUnit/NUnit | ✅ (Semgrep + Veracode validado no PoC CITNET) | Stack primário | | Java 8/11 | ✅ | ✅ | ✅ JUnit 5 | ⏳ Piloto pendente para promoção estável | Spring-aware | | Delphi | ✅ | ✅ | ⚠️ Manual | ⚠️ Apenas modo fallback (catálogo manual) | Sem automação de teste | | Oracle PL/SQL | ✅ | ✅ com policy gate | ✅ PL/SQL blocks | ⚠️ Catálogo CWE limitado | db-change-policy obrigatória | | PHP 5.x–7.x | ✅ | ✅ | ⚠️ PHPUnit se disponível | ⏳ Piloto pendente | Procedural-aware | | Node / TypeScript | ✅ | ✅ | ✅ Jest/Vitest | ⏳ Piloto pendente | — | | Python | ✅ | ✅ | ✅ pytest | ⏳ Piloto pendente | — | | SQL Server | ✅ | ✅ com policy gate | ✅ | n/a (não é stack de aplicação) | db-change-policy obrigatória |

🔬 Security Flow é experimental (v1.2.0) — só .NET tem PoC validado. Stacks marcados como ⏳ funcionam via fallback (varredura por padrões do cwe-catalog.md), mas dependências e utilitários endurecidos precisam ser confirmados num piloto antes de promover para estável.

Métricas

O learning-agent alimenta .speckit/incidents/metrics-feed.jsonl após cada ticket. Cada linha tem type: "bug" | "feature" | "vulnerability" para segregação de KPIs.

Bug flow / Feature flow

| Métrica | Target (maduro) | Fonte | |---------|----------------|-------| | Speckit match rate | > 40% | % de bugs com padrão conhecido | | Discovery time P2 | ≤ 4h | Ticket start → BugReport confirmado | | Cycle time total P2 | ≤ 10h | Ticket start → produção | | Rework rate | < 15% | Patches devolvidos ao builder-agent | | Regression rate | < 5% | Fixes que introduzem novos bugs |

Vulnerability flow 🔬

| Métrica | Target (maduro) | Fonte | |---------|----------------|-------| | FP-rate Semgrep | < 95% (após calibração) | (FPs descartados) / (brutos) — meta caindo a cada wave | | FP-rate Veracode | < 30% (após calibração) | (FPs descartados) / (brutos) | | Findings fechados por wave | varia por classe | Soma de status open → closed | | Cycle time por classe CWE | ≤ 5 dias para classes ≤ 50 findings | start /analyze-vuln → deploy confirmado | | Regressões pós-deploy security | 0 | telemetria + pentest subsequente | | Cobertura de CIAs / tenants | 100% | (CIAs no patch) / (CIAs totais) — multi-tenant projects | | Crescimento do cwe-catalog.md | 1–2 entradas/sprint na fase inicial | Entradas novas via learning-agent |

Benchmark de referência (PoC CITNET): 401 findings brutos → 192 únicos pós-dedup → 8 classes CWE fechadas em 24 commits → 0 regressões reportadas até 2026-05-10.

Compatibilidade de IDEs

O kit roda em qualquer ambiente baseado em VS Code — sem adaptação de conteúdo.

| IDE | Suporte | Como funciona | |-----|---------|--------------| | Claude Code | ✅ Nativo | Slash commands + agentes encadeados automaticamente | | Cursor | ✅ Completo | .cursor/rules/ + Tasks Ctrl+Shift+1..5 | | Antigravity (Google) | ✅ Completo | Baseado em VS Code — lê rules e tasks nativamente | | VS Code + Copilot | ✅ Primeira classe | .github/copilot-instructions.md auto-injetado + Tasks | | VS Code + Gemini | ✅ Suportado | Tasks + #file: references no Gemini Code Assist | | VS Code puro | ⚠️ Manual | Tasks + scripts + AI externo via browser |

Estrutura de compatibilidade incluída

.cursor/
└── rules/
    ├── 00-adlc-context.mdc        # Contexto base — sempre ativo
    ├── 01-bug-investigator.mdc    # Prompts do agente de investigação
    ├── 02-impact-analyzer.mdc     # Prompts do agente de impacto
    ├── 03-agents-build-test-release.mdc  # Builder, Validator, PR, Release, Learning
    ├── 04-policies.mdc            # Políticas sempre ativas no código
    ├── 05-stack-standards.mdc     # Padrões por stack (.NET, Java, Delphi, PHP, Oracle)
    └── 06-speckit-lookup.mdc      # Padrão de consulta ao Speckit

.vscode/
    ├── settings.json              # Contexto de projeto para o AI do editor
    ├── tasks.json                 # Comandos NS Flow Kit como Tasks (Ctrl+Shift+1..5)
    ├── extensions.json            # Extensões recomendadas
    └── keybindings-suggestion.json

Guia completo: docs/onboarding/ide-compatibility-guide.md

Roadmap

✅ v1.0 — Fundação

8 agentes especializados completos para o ciclo bug/feature
3 workflows (bug · improvement · critical incident)
Speckit com bootstrap e update automático
Templates de governança completos (BMAD-inspired)
Pipeline CI/CD (Azure DevOps + GitHub Actions)
Suporte a 5 stacks legados (.NET, Java, Delphi, Oracle PL/SQL, PHP)

✅ v1.1 — Multi-provider (Azure DevOps + GitHub)

v1.1 — fundação multi-provider:

Schema v2 do .local-config.json com migração silenciosa de v1
setup-mcp provider-aware: escolhe azure-devops ou github por projeto, com flag --provider e --switch para alternar
setup-workflows (novo subcomando): distribui templates de GitHub Actions reutilizáveis (pr-checks, speckit-update, release-gates)
github-issue-refiner (agente novo): paralelo ao azure-card-refiner, refina issues do GitHub usando MCP @modelcontextprotocol/server-github
Convenção de ticket ID configurável via ticketIdPattern (default ADO-{num} para Azure, GH-{num} para GitHub) — framework deixa de impor formato
Backward-compat estrita: projetos Azure existentes geram .mcp.json byte-idêntico após migração (snapshot test em tests/init-azure-fixture.test.js)
ADRs 003-006 registrando as decisões estruturais em .speckit/decisions/

v1.1.0 — fluxo GitHub end-to-end (ver CHANGELOG.md):

Policy branch-naming (.claude/policies/branch-naming.md) — formato {tipo}/{TICKET_ID}-{slug} validado pelo workflow pr-checks.yml e pelo builder-agent
Smoke test do setup-mcp — gh api user (GitHub) ou az devops project list (Azure) ao final do setup; falha downgrada mcpConfigured: false
Companion docs (.mcp.json.template.github.README.md) — escopos exatos do PAT GitHub (classic e fine-grained) + modo gh-cli recomendado
Etapa 0 compartilhada (_shared/ticket-fetch.md) — busca de ticket via MCP/CLI normalizada para os 5 agentes do ciclo
Comentários automáticos opt-in nos 4 checkpoints (_shared/checkpoint-notify.md) — habilitado via checkpointNotifications.enabled
/open-pr automatizado — push da branch, mcp__github__create_pull_request (com fallback gh pr create), labels canônicas, Closes #N automático
release-agent determinístico — consulta status do CI e aprovação do PR via MCP/CLI (não mais checklist manual)
learning-agent fecha issue no provider após deploy confirmado, com comentário e link do release
/bootstrap-repo enriquecido via GitHub API (hotspots por commits, issues question/tech-debt, PRs de hotfix → seed do risk-map)

🔬 v1.2.0-experimental — Vulnerability Flow (PoC CITNET validado)

Workflow paralelo ao bug-flow para tratamento estruturado de vulnerabilidades. Decisão registrada em ADR-007. PoC original: 24 commits fix(security): mergeados em main, 8 classes CWE fechadas, 0 regressões.

2 agentes: vuln-triage (ingestão multi-fonte Semgrep + Veracode + pentest, dedup, FP filtering em 3 camadas), vuln-investigator (hipóteses L1–L4, padrão único de fix por classe)
3 comandos: /scan-vuln, /analyze-vuln CWE-NN, /bootstrap-security --stack
2 policies: vulnerability-policy.md (10 regras hard-stop), release-policy.md (gap 4.7.1 fechado — janelas, freeze, fast-track de security)
1 workflow: vulnerability-flow.md com 5 checkpoints humanos (Checkpoint 0 extra para escopo do triage)
1 catálogo seed: cwe-catalog.md com 11 entradas universais (OWASP Top 10) + heurísticas globais de FP
2 wrappers SAST em PowerShell: tools/semgrep/Run-SemgrepScan.ps1 (local + cloud), tools/veracode/Get-VeracodeFlaws.ps1 (REST API + HMAC, sem CLI Java/MSI)
Status expandido de finding: open | closed-via-commit-{SHA} | dismissed-fp | backlog — resolve Veracode lag de 24h–7d
Wave-N pattern: rotina para residual pós-merge sem inflacionar tickets
learning-agent cria entrada CWE automaticamente quando classe nova é encontrada (gap 4.7.2 da PoC)

Status experimental. Promoção para estável (v1.3) após 2º piloto em stack diferente (Java/PHP/Node).

🔮 v2.0 — Multi-repo Intelligence

Speckit compartilhado entre múltiplos repos do mesmo sistema
Cross-repo pattern detection
Org-level engineering intelligence

Onboarding do Squad

Semana 0:  /bootstrap-repo CITWEB         →  revisar DRAFTs  →  validar com o time
Semana 1:  primeiro ticket real no bug-flow  →  debrief com o squad
Semana 2+: learning-agent roda após cada ticket  →  Speckit atualizado por ticket
           /update-speckit CITWEB toda segunda   →  captura o que ficou fora do fluxo
Mês 2:     Speckit match rate > 25%  →  agentes acertando padrões
Mês 3:     Cycle time P2 ≤ 10h  →  pipeline operacional em velocidade de cruzeiro

──────  Security flow 🔬 (opcional, quando houver findings de SAST/Pentest)  ──────

Semana A:  /bootstrap-security --stack <stack>   →  catálogo CWE seed + scaffold tools/
           configurar env vars VERACODE_API_*    →  uma vez por dev
Semana B:  /scan-vuln  →  validar inventário, descartar FPs amostralmente
           /analyze-vuln CWE-XX → fix da Wave 1 (config-level) →  fechar 1ª classe
Semana C+: 1 ticket de vulnerabilidade por sprint  →  cwe-catalog cresce 1–2 entradas
Mês 2:     FP-rate Semgrep < 95%, Veracode < 30%  →  calibração de regras
Mês 3:     Ondas 1–4 fechadas (config → cookies → output → info)
           Wave 5 (design — CSRF, AuthZ, crypto) em planning

Guia completo: docs/onboarding/squad-member-guide.md

AI-Ready Repository Standard

Um repositório é AI-Ready quando os agentes conseguem trabalhar sem precisar de explicações manuais:

| Nível | Critério | |-------|---------| | 1 — Legível | README existe, stack documentado, zero credenciais no repo | | 2 — Navegável | .speckit/domain/ preenchido, 3+ ADRs, known-issues iniciais | | 3 — Agent-Ready | Risk map atualizado, dependency map, smoke tests, runbooks de deploy | | 4 — Intelligence-Ready | Match rate > 40%, metrics-feed ativo, MCP integrado, dashboard de métricas conectado | | 5 — Security-Hardened 🔬 | cwe-catalog.md enriquecido com paths reais, SAST integrado (Semgrep + Veracode/equivalente), 0 findings críticos abertos por > 30 dias, vulnerability-flow executado em pelo menos 3 classes CWE |

Contribuindo

Melhorias são bem-vindas via PR:

Novos anti-patterns → .speckit/known-issues/anti-patterns.md
Suporte a novo stack → atualizar agentes + este README
Correções nos agentes → PR com justificativa
Novos ADRs de referência → .speckit/decisions/

Mudanças em políticas requerem justificativa detalhada no PR.

Licença

MIT — use, adapte e distribua livremente.
Se usar em produção, uma estrela ⭐ no repo ajuda outros times a encontrar.

Built for squads that ship legacy systems at the speed of modern engineering.

nstechhub