spec-first-copilot 0.4.0 → 0.5.0-beta.1

package/templates/.github/copilot-instructions.md

@@ -1,175 +1,218 @@
-# Copilot Instructions — Projeto
-
-> Regras globais que o agente deve seguir em TODAS as interações neste projeto.
-> Este arquivo é lido automaticamente no início de cada sessão.
-
----
-
-## Inicialização (executar no início de cada sessão)
-
-### 1. Verificar dependências do workflow
-
-| Dependência | Caminho | Se não existir |
-|-------------|---------|----------------|
-| Napkin (memória) | `.ai/memory/napkin.md` | Criar com formato padrão: seções Decisões, Padrões, Armadilhas, Preferências (máx 10 itens/seção) |
-| Templates | `docs/_templates/` | ERRO — projeto não está configurado |
-| Skills | `.github/skills/` | ERRO — projeto não está configurado |
-| Agents | `.github/agents/` | ERRO — projeto não está configurado |
-| Rules | `docs/Desenvolvimento/rules.md` | ERRO — projeto não está configurado |
-| Retomada | `docs/Desenvolvimento/retomada.md` | OK — primeira sessão |
-
-### 2. Validar acesso a todas skills
-
-Verificar que TODAS as 9 skills estão acessíveis:
-
-| Skill | Caminho |
-|-------|---------|
-| `/sf-setup-projeto` | `.github/skills/sf-setup-projeto/SKILL.md` |
-| `/sf-feature` | `.github/skills/sf-feature/SKILL.md` |
-| `/sf-extract` | `.github/skills/sf-extract/SKILL.md` |
-| `/sf-design` | `.github/skills/sf-design/SKILL.md` |
-| `/sf-plan` | `.github/skills/sf-plan/SKILL.md` |
-| `/sf-dev` | `.github/skills/sf-dev/SKILL.md` |
-| `/sf-merge-delta` | `.github/skills/sf-merge-delta/SKILL.md` |
-| `/sf-session-finish` | `.github/skills/sf-session-finish/SKILL.md` |
-| `/sf-discovery` | `.github/skills/sf-discovery/SKILL.md` |
-
-Se alguma skill não for encontrada → avisar o usuário.
-
-### 3. Carregar contexto
-
-1. Ler `.ai/memory/napkin.md` — decisões e padrões acumulados
-2. Ler `docs/Desenvolvimento/retomada.md` (se existir) — ponto de retomada da última sessão
-3. Ler `docs/Estrutura/` (se existir) — contexto global do projeto
-4. Ler `docs/Desenvolvimento/rules.md` — regras de desenvolvimento
-
----
-
-## Identidade do Projeto
-
-Este é um projeto que utiliza desenvolvimento **spec-first** assistido por IA.
-
-### Arquitetura: Projeto-base vs Repos de código
-
-```
-ESTE REPO (projeto-base) = ORQUESTRADOR
-├── docs/          ← specs, PRDs, SDDs, tasks (fonte de verdade)
-├── projetos.yaml  ← manifesto de repos
-└── projetos/      ← repos de código (gitignored, cada um com .git próprio)
-    ├── api/       ← repo: org/projeto-api
-    ├── web/       ← repo: org/projeto-web
-    └── worker/    ← repo: org/projeto-worker
-```
-
-**Regra clara**:
-- **Specs, docs, tasks, progresso** → ficam NESTE repo (projeto-base)
-- **Código, testes, Dockerfiles, CI** → ficam nos repos em `projetos/`
-- **Commits de código** → nos repos do serviço, NUNCA no projeto-base
-- **Git workflow (branches, PRs, merge)** → se aplica aos repos em `projetos/`
-Nenhum código é escrito sem especificação aprovada (SDD).
-
-## Pipeline do Workflow
-
-```
-docs/PM/ (qualquer arquivo)
-    ↓ /sf-setup-projeto (uma vez) ou /sf-feature (por feature)
-/sf-discovery → análise profunda dos insumos (RECOMENDADO, opcional)
-    ↓
-/sf-extract → PRD ou TRD (checkpoint — usuário revisa e aprova)
-    ↓
-/sf-design → SDD + projetos.yaml + docs/Estrutura/ (setup)
-    ↓
-/sf-plan → *_tasks.md + Progresso.md (tasks por fase × área)
-    ↓
-/sf-dev → código nos repos (Security Review pós-dev)
-    → merge-delta automático em features (aplica SDD §11 em docs/Estrutura/)
-```
-
-## Skills disponíveis
-
-| Skill | Tipo | O que faz |
-|-------|------|-----------|
-| `/sf-setup-projeto` | Orquestrador | Bootstrap: cria .context.md, chama /sf-extract, para no checkpoint. Roda UMA vez |
-| `/sf-feature <nome>` | Orquestrador | Feature: cria .context.md tipo PRD, chama /sf-extract, para no checkpoint |
-| `/sf-extract <nome>` | Atômica | Lê docs/PM/{nome}/ → gera PRD ou TRD. Re-executável para novos insumos |
-| `/sf-design <nome>` | Atômica | Pergunta aprovação → gera SDD a partir do PRD/TRD |
-| `/sf-plan <nome>` | Atômica | Lê SDD → gera tasks por área + Progresso.md |
-| `/sf-dev <nome>` | Atômica | Implementa tasks com loop (implement → test → review). Agents por área. Merge-delta automático em features |
-| `/sf-merge-delta <nome>` | Atômica | Aplica SDD §11 Delta Specs em docs/Estrutura/ (chamado automaticamente pelo /sf-dev, re-executável manualmente) |
-| `/sf-session-finish` | Utilitária | Encerra sessão: salva estado, atualiza napkin, gera retomada.md |
-| `/sf-discovery` | Utilitária | Análise profunda de sistemas, arquiteturas e documentações |
-
-## Agents especializados (usados pelo /dev)
-
-| Agent | Área | Stack padrão | Perfil |
-|-------|------|-------------|--------|
-| Backend Coder | BACK | .NET 8 / C# | `.github/agents/backend-coder.md` |
-| Frontend Coder | FRONT | React + Fusion | `.github/agents/frontend-coder.md` |
-| DB Coder | BANCO | PostgreSQL 16 | `.github/agents/db-coder.md` |
-| Infra Coder | INFRA | Docker | `.github/agents/infra-coder.md` |
-| Doc Writer | DOC | — | `.github/agents/doc-writer.md` |
-| Reviewer | Todas | — | `.github/agents/reviewer.md` |
-| Security Reviewer | Todas | — | `.github/agents/security-reviewer.md` |
-
-## Estado da pipeline (`.context.md`)
-
-Cada feature/setup tem um `.context.md` em `docs/Desenvolvimento/{nome}/` que controla o fluxo:
-
-```
-not_started → extract_done → approved → design_done → plan_done → dev_in_progress → dev_done → done
-```
-
-Antes de executar qualquer skill, verificar o status no `.context.md`. Cada skill só avança se o status anterior está correto.
-
-## Regras Invioláveis
-
-1. **Spec-first**: NUNCA gerar código sem SDD aprovado
-2. **PM é sagrado**: NUNCA modificar arquivos em `docs/PM/`
-3. **Extração rígida**: categorias fixas do template, sem texto narrativo, ambiguidades são BLOQUEANTES
-4. **SDD é auto-contido**: coder lê APENAS SDD + task, NUNCA PRD/PM diretamente
-5. **Memória ativa**: ler napkin.md no início, atualizar ao descobrir padrões/armadilhas
-6. **Progresso atualizado**: atualizar Progresso.md ao concluir cada task
-7. **Delta Specs**: todo SDD tem §11 ADDED/MODIFIED/REMOVED — obrigatório
-8. **Testes junto com código**: implementar e testar na mesma task, não separar
-
-## Estrutura de Documentação
-
-```
-docs/
-├── PM/                  ← Insumos brutos (QUALQUER formato — nunca modificar)
-│   ├── setup_projeto/   ← Insumos de bootstrap
-│   └── feat_*/          ← Insumos por feature
-├── _templates/          ← 16 templates (feature/7 + estrutura/8 + global/1)
-├── Estrutura/           ← Retrato global do projeto (gerado por /setup-projeto via tasks DOC)
-└── Desenvolvimento/     ← Artefatos por feature
-    ├── rules.md         ← Regras de desenvolvimento
-    └── {nome}/          ← PRD/TRD, SDD, *_tasks.md, Progresso.md, .context.md, .extract-log.md
-```
-
-## Convenções
-
-- **Pastas**: `feat_nome`, `bug_nome`, `task_nome` (snake_case com prefixo)
-- **Task IDs**: `AREA-NNN` (BANCO-001, BACK-001, FRONT-001)
-- **Regras de negócio**: `RN-NNN` (IDs estáveis, nunca renumerar)
-- **Commits**: `tipo(TASK-ID): descrição` (feat, fix, refactor, test, docs, chore)
-- **Branches**: `feature/feat_nome`, `bugfix/bug_nome`, `task/task_nome`
-
-## Quando Parar e Perguntar
-
-- `docs/PM/{nome}/` vazio ou inexistente → PARAR
-- Ambiguidade na extração → listar como pergunta BLOQUEANTE, PARAR
-- `.context.md` com status incompatível com a skill → PARAR, informar status atual
-- Task com dependência não concluída → avisar, não pular
-- Dúvida sobre regra de negócio → perguntar, NUNCA assumir
-- Quality gate reprovado 3x → escalar pro usuário
-
-## Referências
-
-| Doc | Onde |
-|-----|------|
-| Rules de dev | `docs/Desenvolvimento/rules.md` |
-| Memória | `.ai/memory/napkin.md` |
-| Skills | `.github/skills/*.md` |
-| Agents | `.github/agents/*.md` |
-| Templates | `docs/_templates/` |
-| Estrutura do sistema | `docs/Estrutura/*.md` (após setup) |
+# Copilot Instructions — Projeto
+
+> Regras globais que o agente deve seguir em TODAS as interações neste projeto.
+> Este arquivo é lido automaticamente no início de cada sessão.
+
+---
+
+## Inicialização (executar no início de cada sessão)
+
+### 1. Verificar dependências do workflow
+
+| Dependência | Caminho | Se não existir |
+|-------------|---------|----------------|
+| Napkin (memória) | `.ai/memory/napkin.md` | Criar com formato padrão: seções Decisões, Padrões, Armadilhas, Preferências (máx 10 itens/seção) |
+| Templates | `.github/templates/` | ERRO — projeto não está configurado |
+| Skills | `.github/skills/` | ERRO — projeto não está configurado |
+| Agents | `.github/agents/` | ERRO — projeto não está configurado |
+| Rules | `.github/rules.md` | ERRO — projeto não está configurado |
+| Retomada | `workspace/Output/retomada.md` | OK — primeira sessão |
+
+### 2. Validar acesso a todas skills
+
+Verificar que TODAS as 9 skills estão acessíveis:
+
+| Skill | Caminho |
+|-------|---------|
+| `/sf-setup-projeto` | `.github/skills/sf-setup-projeto/SKILL.md` |
+| `/sf-feature` | `.github/skills/sf-feature/SKILL.md` |
+| `/sf-extract` | `.github/skills/sf-extract/SKILL.md` |
+| `/sf-design` | `.github/skills/sf-design/SKILL.md` |
+| `/sf-plan` | `.github/skills/sf-plan/SKILL.md` |
+| `/sf-dev` | `.github/skills/sf-dev/SKILL.md` |
+| `/sf-merge-delta` | `.github/skills/sf-merge-delta/SKILL.md` |
+| `/sf-session-finish` | `.github/skills/sf-session-finish/SKILL.md` |
+| `/sf-discovery` | `.github/skills/sf-discovery/SKILL.md` |
+
+Se alguma skill não for encontrada → avisar o usuário.
+
+### 3. Carregar contexto
+
+1. Ler `.ai/memory/napkin.md` — decisões e padrões acumulados
+2. Ler `workspace/Output/retomada.md` (se existir) — ponto de retomada da última sessão
+3. Ler `docs/` (se existir) — contexto global do projeto (architecture, domain, conventions, apiContracts, decisions)
+4. Ler `.github/rules.md` — regras de desenvolvimento
+
+---
+
+## Identidade do Projeto
+
+Este é um projeto que utiliza desenvolvimento **spec-first** assistido por IA.
+
+### Arquitetura: Projeto-base vs Repos de código
+
+```
+ESTE REPO (projeto-base) = ORQUESTRADOR
+├── .github/        ← AI operational config (rules, templates, skills, agents)
+├── docs/           ← estado do sistema (architecture, domain, conventions, apiContracts, decisions)
+├── workspace/     ← content compartilhável
+│   ├── Input/      ← insumos brutos do time
+│   └── Output/     ← outputs por feature (PRD, TRD, SDD, tasks, progresso)
+├── projetos.yaml   ← manifesto de repos
+└── projetos/       ← repos de código (gitignored, cada um com .git próprio)
+    ├── api/        ← repo: org/projeto-api
+    ├── web/        ← repo: org/projeto-web
+    └── worker/     ← repo: org/projeto-worker
+```
+
+**Três zonas, zero ambiguidade:**
+- **`.github/` + `.ai/`** → AI operational config (rules, templates, skills, agents, memória) — time edita raro
+- **`docs/`** → estado do sistema (gerado pelo /sf-design e /sf-merge-delta)
+- **`workspace/`** → content compartilhável (Input = time, Output = workflow)
+- **`projetos/`** → código dos serviços (branches, PRs, commits acontecem aí)
+
+Nenhum código é escrito sem especificação aprovada (SDD).
+
+## Pipeline do Workflow
+
+```
+workspace/Input/ (qualquer arquivo)
+    ↓ /sf-setup-projeto (uma vez) ou /sf-feature (por feature)
+/sf-discovery → análise profunda dos insumos (RECOMENDADO, opcional)
+    ↓
+/sf-extract → PRD ou TRD em workspace/Output/{nome}/ (checkpoint — usuário revisa e aprova)
+    ↓
+/sf-design → SDD + projetos.yaml + docs/ (5 docs de sistema — só setup)
+    ↓
+/sf-plan → docs/specs/{nome}/tasks.md + Progresso.md em workspace/Output/{nome}/ (tasks por fase × área)
+    ↓
+/sf-dev → código nos repos (Security Review pós-dev)
+    → merge-delta automático em features (aplica SDD §11 em docs/)
+```
+
+## Skills disponíveis
+
+| Skill | Tipo | O que faz |
+|-------|------|-----------|
+| `/sf-setup-projeto` | Orquestrador | Bootstrap: cria .context.md, chama /sf-extract, para no checkpoint. Roda UMA vez |
+| `/sf-feature <nome>` | Orquestrador | Feature: cria .context.md tipo PRD, chama /sf-extract, para no checkpoint |
+| `/sf-extract <nome>` | Atômica | Lê workspace/Input/{nome}/ → gera PRD ou TRD. Re-executável para novos insumos |
+| `/sf-design <nome>` | Atômica | Pergunta aprovação → gera SDD a partir do PRD/TRD |
+| `/sf-plan <nome>` | Atômica | Lê SDD → gera tasks por área + Progresso.md |
+| `/sf-dev <nome>` | Atômica | Implementa tasks com loop (implement → test → review). Agents por área. Merge-delta automático em features |
+| `/sf-merge-delta <nome>` | Atômica | Aplica SDD §11 Delta Specs em docs/ (chamado automaticamente pelo /sf-dev, re-executável manualmente) |
+| `/sf-session-finish` | Utilitária | Encerra sessão: salva estado, atualiza napkin, gera retomada.md |
+| `/sf-discovery` | Utilitária | Análise profunda de sistemas, arquiteturas e documentações |
+
+## Agents especializados (usados pelo /dev)
+
+| Agent | Área | Stack padrão | Perfil |
+|-------|------|-------------|--------|
+| Backend Coder | BACK | .NET 8 / C# | `.github/agents/backend-coder.md` |
+| Frontend Coder | FRONT | React + Fusion | `.github/agents/frontend-coder.md` |
+| DB Coder | BANCO | PostgreSQL 16 | `.github/agents/db-coder.md` |
+| Infra Coder | INFRA | Docker | `.github/agents/infra-coder.md` |
+| Doc Writer | DOC | — | `.github/agents/doc-writer.md` |
+| Reviewer | Todas | — | `.github/agents/reviewer.md` |
+| Security Reviewer | Todas | — | `.github/agents/security-reviewer.md` |
+
+## Estado da pipeline (`.context.md`)
+
+Cada feature/setup tem um `.context.md` em `workspace/Output/{nome}/` que controla o fluxo:
+
+```
+not_started → extract_done → approved → design_done → plan_done → dev_in_progress → dev_done → done
+```
+
+Antes de executar qualquer skill, verificar o status no `.context.md`. Cada skill só avança se o status anterior está correto.
+
+## Regras Invioláveis
+
+1. **Spec-first**: NUNCA gerar código sem SDD aprovado
+2. **Input é sagrado**: NUNCA modificar arquivos em `workspace/Input/`
+3. **Extração rígida**: categorias fixas do template, sem texto narrativo, ambiguidades são BLOQUEANTES
+4. **SDD é auto-contido**: coder lê APENAS SDD + task, NUNCA PRD/PM diretamente
+5. **Memória ativa**: ler napkin.md no início, atualizar ao descobrir padrões/armadilhas
+6. **Progresso atualizado**: atualizar Progresso.md ao concluir cada task
+7. **Delta Specs**: todo SDD tem §11 ADDED/MODIFIED/REMOVED — obrigatório
+8. **Testes junto com código**: implementar e testar na mesma task, não separar
+
+## Estrutura de Documentação
+
+```
+.github/                     ← AI OPERATIONAL CONFIG
+├── copilot-instructions.md  ← Regras globais pro agente (este arquivo)
+├── rules.md                 ← Regras de desenvolvimento (lidas pelos coders)
+├── templates/               ← Templates do workflow
+│   ├── feature/             ← PRD, TRD, SDD, context, extract-log, Progresso, backlog-extraido, projetos.yaml
+│   ├── specs/               ← brief, contracts, scenarios, tasks (projeções pro agent)
+│   ├── estrutura/           ← architecture, domain, conventions, apiContracts, decisions (setup)
+│   └── global/              ← progresso_global
+├── skills/                  ← 9 skills atômicas
+├── agents/                  ← 7 perfis de agents especializados
+└── instructions/            ← Instruções por contexto
+
+docs/                        ← SYSTEM KNOWLEDGE (gerado pelo /sf-design)
+├── architecture.md          ← C4 + stack + ambientes + deploy
+├── domain.md                ← Visão de negócio + modelo de dados
+├── conventions.md           ← Auth, authz, LGPD, env vars, monitoramento
+├── apiContracts.md          ← Rotas, paginação, catálogo de endpoints
+├── decisions.md             ← ADRs
+└── specs/                   ← Especificações por feature (projeções do SDD)
+    └── {nome}/
+        ├── brief.md         ← Problema/Solução (projeção de SDD §1+§2+§10)
+        ├── contracts.md     ← Dados/API/Integrações (projeção de SDD §3+§4+§5+§8)
+        ├── scenarios.md     ← Fluxos/UI/CAs (projeção de SDD §6+§7+§9)
+        └── tasks.md         ← Tabela única com coluna Área (gerado pelo /sf-plan)
+
+workspace/                   ← TEAM CONTENT (futuro wiki)
+├── Input/                   ← Insumos brutos (QUALQUER formato — nunca modificar)
+│   ├── setup_projeto/       ← Insumos de bootstrap
+│   └── feat_*/              ← Insumos por feature
+└── Output/                  ← Artefatos humanos gerados pelo workflow
+    └── {nome}/
+        ├── PRD.md ou TRD.md ← Requirements (gerado pelo /sf-extract)
+        ├── sdd.md           ← Especificação técnica narrativa (gerado pelo /sf-design)
+        ├── Progresso.md     ← Tracking de execução (gerado pelo /sf-plan)
+        ├── .context.md      ← Estado da pipeline
+        ├── .extract-log.md  ← Log de hashes
+        ├── discovery.md     ← (opcional) análise do /sf-discovery
+        └── retomada.md      ← (session-finish) ponto de retomada
+```
+
+**Quem lê o quê:**
+- **Humano**: `workspace/Output/` (PRD/TRD/SDD narrativos + tracking)
+- **Coder agent**: `docs/specs/{nome}/` (projeções estruturadas) — NUNCA lê SDD direto
+- **Reviewer**: `docs/specs/{nome}/scenarios.md` (CAs) + código
+- **Security Reviewer**: `docs/specs/{nome}/contracts.md` + `docs/conventions.md` + código
+- **merge-delta**: `workspace/Output/{nome}/sdd.md` §11 (única leitura do SDD pelo pipeline)
+
+## Convenções
+
+- **Pastas**: `feat_nome`, `bug_nome`, `task_nome` (snake_case com prefixo)
+- **Task IDs**: `AREA-NNN` (BANCO-001, BACK-001, FRONT-001)
+- **Regras de negócio**: `RN-NNN` (IDs estáveis, nunca renumerar)
+- **Commits**: `tipo(TASK-ID): descrição` (feat, fix, refactor, test, docs, chore)
+- **Branches**: `feature/feat_nome`, `bugfix/bug_nome`, `task/task_nome`
+
+## Quando Parar e Perguntar
+
+- `workspace/Input/{nome}/` vazio ou inexistente → PARAR
+- Ambiguidade na extração → listar como pergunta BLOQUEANTE, PARAR
+- `.context.md` com status incompatível com a skill → PARAR, informar status atual
+- Task com dependência não concluída → avisar, não pular
+- Dúvida sobre regra de negócio → perguntar, NUNCA assumir
+- Quality gate reprovado 3x → escalar pro usuário
+
+## Referências
+
+| Doc | Onde |
+|-----|------|
+| Rules de dev | `.github/rules.md` |
+| Memória | `.ai/memory/napkin.md` |
+| Skills | `.github/skills/*.md` |
+| Agents | `.github/agents/*.md` |
+| Templates | `.github/templates/` |
+| Estado do sistema | `docs/*.md` (após setup) |
+| Insumos brutos | `workspace/Input/` |
+| Outputs do workflow | `workspace/Output/` |