spec-first-copilot

Kit completo de desenvolvimento spec-first para GitHub Copilot. Pipeline disciplinado do insumo bruto ao código — com checkpoints humanos, agents especializados por área, security review e rastreabilidade ponta a ponta.

v0.7.0 (estável) — TRD ressuscitado como peer do PRD, aprovação por persona, SDD eliminado. Ver CHANGELOG para detalhes da migração v3→v4.

Conteúdo

• Pra quem é isso
• O que você ganha
• Instalação
• Estrutura gerada
• Pipeline passo a passo
• Skills disponíveis
• Agents especializados
• Backends plugáveis (adapters)
• Troubleshooting
• Links

Pra quem é isso

Você gerencia projetos onde PMs/POs entregam requisitos em formatos heterogêneos (docs no Confluence, SQLs de modelagem, wireframes, notas dispersas) e quer que o desenvolvimento assistido por IA siga um processo previsível. Sem "a IA adivinhou" — com specs aprovadas antes de uma linha de código.

Use-cases cobertos:

• Bootstrap de projeto novo (define stack + arquitetura + primeiras features)
• Features novas em projeto existente (merge aditivo em docs cross-feature)
• Bugs e tasks técnicas (mesmo pipeline, escopo menor)
• Times multi-dev (contratos firmes via specs/ + projetos.yaml)

O que você ganha

| Benefício | Como entrega | |-----------|--------------| | Spec-first rígido | Nenhum código sem PRD/TRD aprovados + specs/ gerado | | Dois revisores, dois docs | PM aprova PRD (produto), dev aprova TRD (técnico) | | Rastreabilidade total | Cada RN, ADR, endpoint, task aponta pro insumo-fonte via hash SHA-256 | | Security by default | Security Reviewer audita 6 categorias pós-dev (Auth, AuthZ, Injeção, PII, Headers, Banco) | | Backend-agnóstico | Rode local (filesystem) ou sincronize com Confluence via MCP | | Multi-repo nativo | projetos.yaml mapeia serviços → repos; cada repo com branch/PR próprio | | Entregáveis contínuos | Features obrigatoriamente faseadas (P1/P2/P3) — nunca "tudo ou nada" | | Re-executável | Toda skill pode rodar de novo; hashes detectam incremental |

Instalação

npm i -g spec-first-copilot

Pré-requisitos: Node.js 18+, Git, GitHub Copilot com acesso a Copilot Chat.

Windows (PowerShell) — se o CLI não rodar por política de execução:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Primeiros passos

# 1. Criar o projeto
spec-first-copilot init --name=MeuProjeto
cd MeuProjeto

# 2. Jogar insumos brutos (qualquer formato)
#    em workspace/Input/<nome>/
#    Ex: workspace/Input/app_barbearia/visao.md + modelo.sql + decisoes.md

# 3. Abrir com VS Code + Copilot Chat e iniciar o pipeline
#    /sf-start app_barbearia

Opções do CLI:

| Opção | Descrição | |-------|-----------| | --name | Nome do projeto (obrigatório) | | --target | Diretório destino (default: ./<name>) |

Estrutura gerada

MeuProjeto/
├── .ai/memory/napkin.md              <- Memória persistente (curada continuamente)
├── .github/                          <- AI OPERATIONAL CONFIG
│   ├── copilot-instructions.md       <- Meta-regras pro agente
│   ├── rules.md                      <- Regras invioláveis + quality gate
│   ├── CHANGELOG.md                  <- Histórico do framework
│   ├── instructions/                 <- Regras por contexto (docs, arquivos sensíveis)
│   ├── templates/                    <- 17 templates do workflow
│   │   ├── feature/                  <- PRD, TRD, context, extract-log, Progresso, projetos.yaml
│   │   ├── specs/                    <- brief, contracts, scenarios, tasks (projeções pro coder)
│   │   ├── estrutura/                <- 5 docs cross-feature (architecture, domain, conventions, apiContracts, decisions)
│   │   └── global/                   <- progresso_global
│   ├── adapters/                     <- SourceAdapter interface + 2 implementations built-in
│   ├── skills/                       <- 11 skills do workflow (ver tabela abaixo)
│   └── agents/                       <- 7 perfis especializados (ver tabela abaixo)
├── docs/                             <- SÍNTESE CROSS-FEATURE (atualizada pelo /sf-merge-docs)
│   ├── architecture.md               <- Containers C4 + stack + ambientes + deploy
│   ├── domain.md                     <- Visão de negócio + modelo de dados consolidado
│   ├── conventions.md                <- Auth, authz, LGPD, env vars, códigos de erro, monitoramento
│   ├── apiContracts.md               <- Convenções de API + catálogo de endpoints
│   └── decisions.md                  <- ADRs (append-only)
├── specs/                            <- AGENT CONTRACTS (projeções de PRD+TRD pro coder)
│   └── {scope}/
│       ├── brief.md                  <- Problema/Solução
│       ├── contracts.md              <- Sistema + áreas tocadas (schema, endpoints, integrações, RNs)
│       ├── scenarios.md              <- Jornadas + CAs + estratégia de testes
│       └── tasks.md                  <- Tabela única com coluna Área (gerado pelo /sf-plan)
├── workspace/                        <- TEAM CONTENT
│   ├── Input/                        <- Insumos brutos (QUALQUER formato — nunca modificar)
│   │   └── {scope}/                  <- Nome livre (app_barbearia, feat_login, bug_checkout)
│   └── Output/                       <- Docs narrativos pro humano
│       └── {scope}/
│           ├── PRD.md                <- Requirements de produto (se insumos têm produto)
│           ├── TRD.md                <- Requirements técnicos (se insumos têm técnica)
│           ├── Progresso.md          <- Tracking de execução
│           └── .context.md           <- Estado da pipeline (YAML)
├── projetos/                         <- Repos de código (gitignored, cada um com .git)
├── projetos.yaml                     <- Manifesto de repos (gerado no first-run)
├── sfw.config.yml.example            <- Manifesto de adapters (input/output)
└── .gitignore

Três zonas, zero ambiguidade:

• .github/ + .ai/ → config operacional + memória (time edita raro)
• docs/ → síntese cross-feature (atualizada pelo /sf-merge-docs)
• workspace/ → content compartilhável (Input = time, Output = workflow)

Pipeline passo a passo

workspace/Input/<scope>/ (seus arquivos)
    │
    ▼
/sf-start <scope>  ──▶  /sf-load  ──▶  /sf-discovery  ──▶  /sf-extract
                                                              │
                                                              ▼
                                                     PRD + TRD gerados
                                                              │
                                       ┌──────── CHECKPOINT DUPLO ────────┐
                                       │  PM aprova PRD | dev aprova TRD   │
                                       └──────────────────────────────────┘
                                                              │
                                                              ▼
                                                         /sf-design  ──▶  specs/ (sempre)
                                                                          docs/ + projetos.yaml (first-run)
                                                              │
                                                              ▼
                                                         /sf-plan    ──▶  tasks.md + Progresso.md
                                                              │
                                                              ▼
                                                         /sf-dev     ──▶  código nos repos
                                                                          + Security Review
                                                                          + /sf-merge-docs automático
                                                                            (diff PRD+TRD ↔ docs/)

Mesmo comando pra bootstrap e feature — first_run é derivado da ausência/presença de docs/.

Apresentação visual: abra apresentacao.html pra ver o fluxo completo com personas, artefatos e adapters.

Skills disponíveis

| Skill | Tipo | Função | |-------|------|--------| | /sf-mcp <provider> | Setup | Configura backend externo (Confluence). Cria .mcp.json + sfw.config.yml | | /sf-load <scope> | Utilitária | Puxa Input do backend (incremental via hash) | | /sf-publish <scope> <tipo> | Utilitária | Publica PRD/TRD/Progresso nos targets. Auto-chamada por extract/plan | | /sf-start <scope> | Orquestrador | Entrada única. Cria .context.md, chama /sf-load + /sf-discovery + /sf-extract | | /sf-discovery <path> | Atômica | Análise profunda prévia dos insumos (obrigatório em v4) | | /sf-extract <scope> | Atômica | Gera PRD e/ou TRD conforme conteúdo dos insumos | | /sf-design <scope> | Atômica | PRD+TRD aprovados → specs/. First-run também cria docs/ + projetos.yaml | | /sf-plan <scope> | Atômica | Lê PRD + TRD + specs/ → tasks por área + Progresso.md | | /sf-dev <scope> | Atômica | Implementa tasks com loop (implement → test → review). Merge-docs automático no fim | | /sf-merge-docs <scope> | Atômica | Diff semântico PRD+TRD ↔ docs/ → atualiza síntese cross-feature | | /sf-session-finish | Utilitária | Encerra sessão: salva estado, atualiza napkin, gera retomada.md |

Agents especializados

| Agent | Área | Stack padrão | Modelo | |-------|------|--------------|--------| | Backend Coder | BACK | .NET 8 / C# (editável) | Sonnet (S/M) · Opus (L) | | Frontend Coder | FRONT | React + Fusion (editável) | Sonnet (S/M) · Opus (L) | | DB Coder | DB | PostgreSQL 16 (editável) | Sonnet (S/M) · Opus (L) | | Infra Coder | INFRA | Docker | Sonnet (S/M) · Opus (L) | | Doc Writer | DOC | — | Sonnet | | Reviewer | Todas | — (quality gate) | Sonnet | | Security Reviewer | Todas | — (gate pós-dev) | Opus |

Perfis em .github/agents/ — editáveis pelo time pra ajustar stack específica do projeto (ex: Node.js em vez de .NET, Angular em vez de React).

Backends plugáveis (adapters)

Arquitetura de adapter layer via sfw.config.yml. Skills não conhecem Confluence ou filesystem — chamam uma interface padrão. Novos backends entram como plugins sem tocar o pipeline.

Built-in:

• FilesystemAdapter — zero dependência externa. Ideal pra times offline, testes automatizados (mock natural), ou diretório compartilhado.
• ConfluenceAdapter — via MCP Atlassian. Conflict detection client-side. PM edita Input no Confluence, agent auto-publica Output (PRD/TRD/Progresso) após cada skill.

Roadmap: NotionAdapter, JIRAAdapter, SharePointAdapter, GitHubIssuesAdapter (formalizados quando surgir 3º caso real).

Setup do Confluence:

/sf-mcp confluence

Guia o setup interativo (space key, parent IDs, credenciais gitignored).

Troubleshooting

| Problema | Solução | |----------|---------| | /sf-start reclama que pasta Input está vazia | Verifique que há pelo menos 1 arquivo em workspace/Input/<scope>/ | | Pipeline trava em ambiguidade | PRD §12 ou TRD §10 têm linhas sem resposta. Preencher coluna "Resposta" e rodar /sf-design de novo | | PM quer mudar algo depois do PRD aprovado | Criar workspace/Input/<scope>/ajustes_v1.md e rodar /sf-extract → merge aditivo preserva IDs | | /sf-publish não envia TRD pro Confluence | Verificar publishes: [PRD, TRD, Progresso] no sfw.config.yml | | Coder pede algo que não está nas specs/ | Não é bug — é feature. Significa que spec ficou incompleto. Completar via /sf-extract e re-rodar /sf-design | | Security Review bloqueia merge | CRÍTICO/ALTO são bloqueantes. MÉDIO/BAIXO são recomendações. Ver agents/security-reviewer.md |

Links

• Repositório: gustavomaritan-labs/spec-first-workflow
• Kit Claude (equivalente pra Claude Code): spec-first-claude
• Apresentação do pipeline: apresentacao.html
• Issues: github.com/.../issues

Licença

MIT © Gustavo Maritan