spec-first-copilot 0.8.0-beta.2 → 0.8.0-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-first-copilot",
-  "version": "0.8.0-beta.2",
+  "version": "0.8.0-beta.3",
   "description": "Spec-first workflow kit for GitHub Copilot — AI-driven development with specs, not guesswork",
   "bin": {
     "spec-first-copilot": "bin/cli.js"

package/templates/.github/CHANGELOG.md

@@ -8,6 +8,34 @@
 
 ---
 
+## 0.8.0-beta.3 (2026-05-11) — Working directory blindado
+
+Esclarecimento crítico em brownfield (e em qualquer cenário com múltiplos
+repos em `projetos/`): o cwd do agente **nunca muda** — é sempre a raiz SFW.
+Repos clonados são alvo de trabalho, não ambiente de trabalho. Evita conflito
+entre regras SFW e regras do time do repo legado (`CLAUDE.md`, `.cursorrules`,
+`AGENTS.md` etc. internos ao repo).
+
+### Adicionado
+
+- **Regra inviolável #7** em `rules.md`: "Working directory é a raiz SFW"
+- **Seção "Working Directory — raiz SFW é a casa do agente"** em `rules.md`:
+  tabela do que faz/não faz, fronteira clara entre operacional/descritivo/histórico
+- **Bloco "Working Directory"** no topo de `copilot-instructions.md` —
+  antes de qualquer outra seção
+- **Aviso reforçado no Passo 3 do `/sf-onboard`** (logo após clone):
+  usar `git -C projetos/<repo>` em vez de `cd`; não carregar arquivos de
+  instrução internos do repo legado (`CLAUDE.md`, `.cursorrules`, `AGENTS.md`)
+
+### Por quê
+
+Repo legado pode ter próprio `CLAUDE.md` ou `copilot-instructions.md` que
+conflita com SFW. Sem regra explícita, agente pode confundir "padrões
+observados" (descritivos, TRD §1.6) com "regras invioláveis" (prescritivas,
+`rules.md`). Resultado: bagunça. Fronteira agora é explícita.
+
+---
+
 ## 0.8.0-beta.2 (2026-05-11) — Auth check pré-clone
 
 `/sf-onboard` agora verifica autenticação git **antes** de tentar clonar,

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

@@ -49,6 +49,31 @@ Se algum command não for encontrado → avisar o usuário.
 
 ---
 
+## Working Directory — onde o agente trabalha
+
+> ⚠️ **Crítico** — não mude isso.
+
+O cwd do agente é a **raiz deste projeto SFW** (onde estão `.github/`, `docs/`,
+`specs/`, `workspace/`, `projetos.yaml`). Repos clonados em `projetos/<repo>/`
+são **alvo de trabalho**, NUNCA **ambiente de trabalho**.
+
+| Faz | NÃO faz |
+|-----|---------|
+| Lê/escreve código via path relativo: `projetos/api/src/...` | Troca cwd pra `projetos/<repo>/` |
+| Roda git: `git -C projetos/api <comando>` | Lê `copilot-instructions.md` que exista DENTRO de `projetos/<repo>/` |
+| Lê regras de `rules.md` da raiz SFW | Lê `CLAUDE.md` do repo legado |
+| Lê padrões do TRD §1.6 (na raiz SFW) | Carrega `.cursor/`, `AGENTS.md`, `.cursorrules` do repo legado |
+
+**Por quê**: repos legados (`/sf-onboard`) podem ter próprias regras/convenções
+que conflitam com SFW. A verdade operacional é sempre a raiz SFW — código nos
+`projetos/` é objeto de leitura/escrita, não fonte de regras vivas. Padrões do
+repo legado, quando relevantes, foram **descritos** no TRD §1.6 pelo `/sf-onboard`.
+
+Detalhamento completo em `.github/rules.md` (Regra Inviolável #7 + seção
+"Working Directory").
+
+---
+
 ## Identidade do Projeto
 
 Este é um projeto que utiliza desenvolvimento **spec-first** assistido por IA.

package/templates/.github/rules.md

@@ -1,229 +1,266 @@
-# Regras de Desenvolvimento
-
-> Regras que todos os agentes de desenvolvimento devem seguir.
-> Lido pelo Coder/Senior Coder e Reviewer antes de cada task.
-> Aplicado globalmente a todas as features.
-
----
-
-<!--
-=============================================================================
-INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
-=============================================================================
-
-QUANDO LER: Toda vez que /sf-dev executar uma task. Obrigatório.
-QUEM LÊ: Coder, Senior Coder e Reviewer.
-COMO USAR: Regras aqui são LEI — não são sugestões. Violações reprovam a task no quality gate.
-
-PERSONALIZAÇÃO: Este arquivo é editado manualmente pelo time.
-As regras abaixo são o padrão do framework. O time pode:
-- Adicionar regras específicas da stack
-- Remover regras que não se aplicam
-- Ajustar convenções ao projeto
-
-=============================================================================
--->
-
-## Regras Invioláveis
-
-1. **Spec-first**: Nenhuma task pode ser executada sem PRD e/ou TRD aprovados (+ `specs/{nome}/` gerado)
-2. **specs/ é a fonte do coder**: O coder lê APENAS `specs/{nome}/` + task — nunca consulta PRD/TRD ou PM diretamente
-3. **Um commit por task**: Cada task gera exatamente 1 commit
-4. **Sem invenção**: Se `specs/` não especifica, o coder NÃO assume — para e reporta
-5. **Entregáveis contínuos**: Toda feature é faseada em entregáveis incrementais. Cada fase entrega valor ao usuário e pode ir para produção independentemente. Nunca "tudo ou nada" — sempre "pequeno e constante"
-6. **Nunca na main**: Todo código é desenvolvido em branch própria. Merge apenas via PR aprovado pelo usuário
-
-## Convenções de Código
-
-### Padrão geral
-- Todo código segue a stack e convenções de `docs/architecture.md` + `docs/conventions.md`
-- Nomes em inglês (código) — documentação em português
-- Sem código morto (comentado) — se não usa, apaga
-- Sem secrets hardcoded — sempre variáveis de ambiente
-
-### Backend
-- Testes obrigatórios: mínimo happy path + 1 cenário de erro
-- Validação de input na borda (controller/handler) — não no service
-- Erros de negócio: usar códigos definidos em `docs/conventions.md` (seção Códigos de Erro do Domínio)
-- Tipos explícitos (sem `any`, `object`, `dynamic` genéricos)
-
-### Frontend
-- Componentes tipados com props documentadas
-- Estados explícitos: loading, empty, error, success
-- Sem lógica de negócio no componente — delegar para hooks/services
-
-### Banco de dados
-- Toda migration tem rollback testado
-- Execução sequencial — nunca pular migrations
-- Seeds apenas para ambiente de desenvolvimento
-
-## Convenções de Git
-
-> **Escopo**: Estas regras se aplicam aos **repositórios em `projetos/`** (api, web, worker, etc.).
-> O projeto-base em si é o orquestrador — specs e docs ficam aqui, código fica nos repos.
-
-### Commits
-```
-tipo(TASK-ID): descrição curta
-
-Corpo opcional com detalhes.
-
-Refs: feat_cadastro_cliente
-```
-
-| Tipo | Quando usar |
-|------|-------------|
-| `feat` | Nova funcionalidade |
-| `fix` | Correção de bug |
-| `refactor` | Mudança sem alterar comportamento |
-| `test` | Adição/alteração de testes |
-| `docs` | Documentação |
-| `chore` | Configuração, build, CI |
-
-### Branches
-```
-feature/feat_cadastro_cliente
-feature/feat_mvp_fase1
-bugfix/bug_cpf_duplicado
-task/task_otimizar_listagem
-```
-
-| Regra | Descrição |
-|-------|-----------|
-| Base | Sempre a partir de `main` atualizada (origin) |
-| Merge | Via Pull Request aprovado pelo usuário — NUNCA merge automático |
-| Conflitos | Resolver antes de mergear — nunca force push em branch compartilhada |
-
-### Git Workflow (5 passos obrigatórios)
-
-O /sf-dev DEVE seguir este fluxo para CADA fase de entrega:
-
-#### Passo 1 — Antes de codar
-```bash
-# Verificar working tree limpo
-git status
-# Se há mudanças pendentes → sugerir commit ou stash antes de prosseguir
-# NUNCA começar a codar com working tree sujo
-```
-
-#### Passo 2 — Criar branch
-```bash
-# Atualizar main a partir do remote
-git checkout main
-git pull origin main
-
-# Criar branch para a fase
-git checkout -b feature/{nome}_fase{N}
-# Ex: feature/feat_mvp_fase1
-```
-- Branch criada no **repo do serviço** (projetos/api, projetos/web, etc.)
-- Se a fase afeta múltiplos repos → branch com mesmo nome em cada um
-- NUNCA desenvolver direto na main
-
-#### Passo 3 — Ao terminar a fase
-```bash
-# Atualizar Progresso.md com status da fase
-# Push da branch
-git push origin feature/{nome}_fase{N}
-
-# Abrir PR com template detalhado (ver seção abaixo)
-gh pr create --title "..." --body "..."
-```
-- Deixar ambiente local **rodando** (docker compose up + dotnet run + npm run dev)
-- Informar ao usuário que o ambiente está ON para testes manuais
-
-#### Passo 4 — Aguardar aprovação
-```
-⏸️ PARAR e aguardar.
-- O usuário revisa o PR, testa manualmente o ambiente local
-- Merge é MANUAL — o agente NUNCA faz merge
-- Se o usuário pedir ajustes → corrigir na mesma branch, push, atualizar PR
-```
-
-#### Passo 5 — Após merge (quando usuário confirmar)
-```bash
-# Atualizar main local
-git checkout main
-git pull origin main
-
-# Limpar branches mergeadas
-git branch -d feature/{nome}_fase{N}
-git remote prune origin
-```
-
-### Template de Pull Request
-
-Todo PR aberto pelo /sf-dev DEVE seguir este formato:
-
-```markdown
-## Fase {N} — {Nome da fase}
-
-### O que foi entregue
-- [ ] {Entregável 1 da fase}
-- [ ] {Entregável 2 da fase}
-
-### Tasks concluídas
-| Task | Descrição | Testes |
-|------|-----------|--------|
-| BACK-001 | Criar endpoint X | ✅ unit + integration |
-| DB-001 | Migration tabela Y | ✅ rollback testado |
-| FRONT-001 | Tela de cadastro | ✅ unit |
-
-### Testes
-- ✅ Unit tests passando ({N}/{N})
-- ✅ Integration tests passando ({N}/{N})
-- ✅ Security Review aprovado
-- ⬜ E2E (aguardando teste manual do usuário)
-
-### Como testar manualmente
-1. Ambiente já está rodando em:
-   - API: http://localhost:8080
-   - Web: http://localhost:3000
-   - Banco: localhost:5432
-2. Fluxo para testar:
-   - {Passo 1 do teste manual}
-   - {Passo 2 do teste manual}
-   - {Resultado esperado}
-
-### Observações
-- {Decisões tomadas, trade-offs, pontos de atenção}
-```
-
-## Quality Gate (por task)
-
-> Checklist obrigatório. O Reviewer valida TODOS os itens antes de aprovar.
-
-- [ ] Código compila sem erros
-- [ ] Testes passam (se aplicável à task)
-- [ ] Lint limpo (sem warnings não justificados)
-- [ ] Critérios de aceite da task atendidos (ref `specs/{nome}/scenarios.md`)
-- [ ] Sem TODOs no código sem justificativa
-- [ ] Sem secrets hardcoded
-- [ ] Commit segue convenção: `tipo(TASK-ID): descrição`
-- [ ] Arquivos listados na task foram os únicos modificados (sem side effects)
-
-## Regras por Stack
-
-> Seção opcional. Adicionar regras específicas da tecnologia escolhida.
-> Exemplos abaixo — remover/ajustar conforme o projeto.
-
-<!--
-### Node.js / TypeScript
-- ESLint + Prettier como formatador
-- Strict mode no tsconfig
-- Path aliases configurados (@/modules, @/shared)
-
-### Python
-- Ruff como linter/formatter
-- Type hints obrigatórios (mypy strict)
-- Virtual environment (venv ou poetry)
-
-### React / Next.js
-- Server Components por padrão, Client Components só quando necessário
-- Zustand ou Context para estado global (não Redux)
-- Tailwind CSS para estilos
--->
-
----
-
-> **Atualização**: Editado manualmente pelo time. Aplicado globalmente a todas as features.
+# Regras de Desenvolvimento
+
+> Regras que todos os agentes de desenvolvimento devem seguir.
+> Lido pelo Coder/Senior Coder e Reviewer antes de cada task.
+> Aplicado globalmente a todas as features.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+QUANDO LER: Toda vez que /sf-dev executar uma task. Obrigatório.
+QUEM LÊ: Coder, Senior Coder e Reviewer.
+COMO USAR: Regras aqui são LEI — não são sugestões. Violações reprovam a task no quality gate.
+
+PERSONALIZAÇÃO: Este arquivo é editado manualmente pelo time.
+As regras abaixo são o padrão do framework. O time pode:
+- Adicionar regras específicas da stack
+- Remover regras que não se aplicam
+- Ajustar convenções ao projeto
+
+=============================================================================
+-->
+
+## Regras Invioláveis
+
+1. **Spec-first**: Nenhuma task pode ser executada sem PRD e/ou TRD aprovados (+ `specs/{nome}/` gerado)
+2. **specs/ é a fonte do coder**: O coder lê APENAS `specs/{nome}/` + task — nunca consulta PRD/TRD ou PM diretamente
+3. **Um commit por task**: Cada task gera exatamente 1 commit
+4. **Sem invenção**: Se `specs/` não especifica, o coder NÃO assume — para e reporta
+5. **Entregáveis contínuos**: Toda feature é faseada em entregáveis incrementais. Cada fase entrega valor ao usuário e pode ir para produção independentemente. Nunca "tudo ou nada" — sempre "pequeno e constante"
+6. **Nunca na main**: Todo código é desenvolvido em branch própria. Merge apenas via PR aprovado pelo usuário
+7. **Working directory é a raiz SFW**: O agente opera SEMPRE a partir da raiz do projeto SFW (onde estão `.github/`, `docs/`, `specs/`, `workspace/`, `projetos.yaml`). Repos em `projetos/<repo>/` são **alvo de trabalho**, NUNCA **ambiente de trabalho** (ver seção abaixo)
+
+## Working Directory — raiz SFW é a casa do agente
+
+> **Regra crítica em projetos com `/sfw-onboard` ou múltiplos repos**: o cwd
+> da IA não muda. Tudo é referenciado a partir da raiz SFW.
+
+### O que o agente FAZ
+
+- ✅ Trabalha com cwd = raiz SFW (onde rodou `init`)
+- ✅ Lê código com caminho relativo: `projetos/api/src/Controllers/UserController.cs`
+- ✅ Escreve código com caminho relativo: idem
+- ✅ Roda git **dentro** do repo target via `git -C projetos/api <comando>` (não com `cd`)
+- ✅ Consulta `rules.md`, `docs/`, `specs/`, `.github/` SEMPRE da raiz SFW
+- ✅ Em brownfield: consulta TRD §1.6 Padrões Observados (na raiz SFW) antes de implementar
+
+### O que o agente NÃO FAZ
+
+- ❌ NÃO troca cwd pra `projetos/<repo>/` (nem implícita nem explicitamente)
+- ❌ NÃO lê `copilot-instructions.md` que exista DENTRO do repo legado em `projetos/<repo>/` (esse é do time do repo, não nosso)
+- ❌ NÃO lê `.github/copilot-instructions.md` DENTRO do repo legado (idem)
+- ❌ NÃO segue convenções/regras documentadas em `projetos/<repo>/.cursor/`, `projetos/<repo>/.github/`, `projetos/<repo>/AGENTS.md` ou similares
+- ❌ NÃO carrega `.env`, `.cursorrules` ou config files do repo legado como "regras vivas"
+
+### Por quê
+
+- Repo legado pode ter próprio `copilot-instructions.md` / `.github/copilot-instructions.md` que **conflita** com SFW
+- "Padrões observados" (TRD §1.6, descritivos) ≠ "regras invioláveis" (este arquivo, prescritivas) — se misturar, vira bagunça
+- A "verdade operacional" do agente é sempre a raiz SFW; código nos `projetos/` é objeto de leitura/escrita
+
+### Fronteira clara
+
+| Camada | Localização | Quem manda |
+|--------|-------------|------------|
+| Operacional (como o agente trabalha) | Raiz SFW: `.github/`, `rules.md`, `docs/`, `specs/` | **SFW** |
+| Descritiva (como o código existe) | `projetos/<repo>/` + TRD §1.6 (na raiz SFW) | Refletida no TRD pelo `/sfw-onboard` |
+| Histórica do repo legado | `projetos/<repo>/README.md`, `CHANGELOG.md`, ADRs internos | Contexto opcional, não regra |
+
+## Convenções de Código
+
+### Padrão geral
+- Todo código segue a stack e convenções de `docs/architecture.md` + `docs/conventions.md`
+- Nomes em inglês (código) — documentação em português
+- Sem código morto (comentado) — se não usa, apaga
+- Sem secrets hardcoded — sempre variáveis de ambiente
+
+### Backend
+- Testes obrigatórios: mínimo happy path + 1 cenário de erro
+- Validação de input na borda (controller/handler) — não no service
+- Erros de negócio: usar códigos definidos em `docs/conventions.md` (seção Códigos de Erro do Domínio)
+- Tipos explícitos (sem `any`, `object`, `dynamic` genéricos)
+
+### Frontend
+- Componentes tipados com props documentadas
+- Estados explícitos: loading, empty, error, success
+- Sem lógica de negócio no componente — delegar para hooks/services
+
+### Banco de dados
+- Toda migration tem rollback testado
+- Execução sequencial — nunca pular migrations
+- Seeds apenas para ambiente de desenvolvimento
+
+## Convenções de Git
+
+> **Escopo**: Estas regras se aplicam aos **repositórios em `projetos/`** (api, web, worker, etc.).
+> O projeto-base em si é o orquestrador — specs e docs ficam aqui, código fica nos repos.
+
+### Commits
+```
+tipo(TASK-ID): descrição curta
+
+Corpo opcional com detalhes.
+
+Refs: feat_cadastro_cliente
+```
+
+| Tipo | Quando usar |
+|------|-------------|
+| `feat` | Nova funcionalidade |
+| `fix` | Correção de bug |
+| `refactor` | Mudança sem alterar comportamento |
+| `test` | Adição/alteração de testes |
+| `docs` | Documentação |
+| `chore` | Configuração, build, CI |
+
+### Branches
+```
+feature/feat_cadastro_cliente
+feature/feat_mvp_fase1
+bugfix/bug_cpf_duplicado
+task/task_otimizar_listagem
+```
+
+| Regra | Descrição |
+|-------|-----------|
+| Base | Sempre a partir de `main` atualizada (origin) |
+| Merge | Via Pull Request aprovado pelo usuário — NUNCA merge automático |
+| Conflitos | Resolver antes de mergear — nunca force push em branch compartilhada |
+
+### Git Workflow (5 passos obrigatórios)
+
+O /sf-dev DEVE seguir este fluxo para CADA fase de entrega:
+
+#### Passo 1 — Antes de codar
+```bash
+# Verificar working tree limpo
+git status
+# Se há mudanças pendentes → sugerir commit ou stash antes de prosseguir
+# NUNCA começar a codar com working tree sujo
+```
+
+#### Passo 2 — Criar branch
+```bash
+# Atualizar main a partir do remote
+git checkout main
+git pull origin main
+
+# Criar branch para a fase
+git checkout -b feature/{nome}_fase{N}
+# Ex: feature/feat_mvp_fase1
+```
+- Branch criada no **repo do serviço** (projetos/api, projetos/web, etc.)
+- Se a fase afeta múltiplos repos → branch com mesmo nome em cada um
+- NUNCA desenvolver direto na main
+
+#### Passo 3 — Ao terminar a fase
+```bash
+# Atualizar Progresso.md com status da fase
+# Push da branch
+git push origin feature/{nome}_fase{N}
+
+# Abrir PR com template detalhado (ver seção abaixo)
+gh pr create --title "..." --body "..."
+```
+- Deixar ambiente local **rodando** (docker compose up + dotnet run + npm run dev)
+- Informar ao usuário que o ambiente está ON para testes manuais
+
+#### Passo 4 — Aguardar aprovação
+```
+⏸️ PARAR e aguardar.
+- O usuário revisa o PR, testa manualmente o ambiente local
+- Merge é MANUAL — o agente NUNCA faz merge
+- Se o usuário pedir ajustes → corrigir na mesma branch, push, atualizar PR
+```
+
+#### Passo 5 — Após merge (quando usuário confirmar)
+```bash
+# Atualizar main local
+git checkout main
+git pull origin main
+
+# Limpar branches mergeadas
+git branch -d feature/{nome}_fase{N}
+git remote prune origin
+```
+
+### Template de Pull Request
+
+Todo PR aberto pelo /sf-dev DEVE seguir este formato:
+
+```markdown
+## Fase {N} — {Nome da fase}
+
+### O que foi entregue
+- [ ] {Entregável 1 da fase}
+- [ ] {Entregável 2 da fase}
+
+### Tasks concluídas
+| Task | Descrição | Testes |
+|------|-----------|--------|
+| BACK-001 | Criar endpoint X | ✅ unit + integration |
+| DB-001 | Migration tabela Y | ✅ rollback testado |
+| FRONT-001 | Tela de cadastro | ✅ unit |
+
+### Testes
+- ✅ Unit tests passando ({N}/{N})
+- ✅ Integration tests passando ({N}/{N})
+- ✅ Security Review aprovado
+- ⬜ E2E (aguardando teste manual do usuário)
+
+### Como testar manualmente
+1. Ambiente já está rodando em:
+   - API: http://localhost:8080
+   - Web: http://localhost:3000
+   - Banco: localhost:5432
+2. Fluxo para testar:
+   - {Passo 1 do teste manual}
+   - {Passo 2 do teste manual}
+   - {Resultado esperado}
+
+### Observações
+- {Decisões tomadas, trade-offs, pontos de atenção}
+```
+
+## Quality Gate (por task)
+
+> Checklist obrigatório. O Reviewer valida TODOS os itens antes de aprovar.
+
+- [ ] Código compila sem erros
+- [ ] Testes passam (se aplicável à task)
+- [ ] Lint limpo (sem warnings não justificados)
+- [ ] Critérios de aceite da task atendidos (ref `specs/{nome}/scenarios.md`)
+- [ ] Sem TODOs no código sem justificativa
+- [ ] Sem secrets hardcoded
+- [ ] Commit segue convenção: `tipo(TASK-ID): descrição`
+- [ ] Arquivos listados na task foram os únicos modificados (sem side effects)
+
+## Regras por Stack
+
+> Seção opcional. Adicionar regras específicas da tecnologia escolhida.
+> Exemplos abaixo — remover/ajustar conforme o projeto.
+
+<!--
+### Node.js / TypeScript
+- ESLint + Prettier como formatador
+- Strict mode no tsconfig
+- Path aliases configurados (@/modules, @/shared)
+
+### Python
+- Ruff como linter/formatter
+- Type hints obrigatórios (mypy strict)
+- Virtual environment (venv ou poetry)
+
+### React / Next.js
+- Server Components por padrão, Client Components só quando necessário
+- Zustand ou Context para estado global (não Redux)
+- Tailwind CSS para estilos
+-->
+
+---
+
+> **Atualização**: Editado manualmente pelo time. Aplicado globalmente a todas as features.

package/templates/.github/skills/sf-onboard/SKILL.md

@@ -161,6 +161,17 @@ git pull --ff-only
 
 Capturar `commit_hash` resultante (`git rev-parse HEAD`) — vai pro snapshot.
 
+> ⚠️ **Working directory NÃO muda**. O agente continua operando da raiz SFW.
+> Use `git -C projetos/<repo-name> <comando>` em vez de `cd`. Comandos que
+> precisam executar dentro do repo (linters, tree, etc.) usam path explícito
+> ou flag `-C` equivalente.
+>
+> **NÃO carregar** `copilot-instructions.md`, `.github/copilot-instructions.md`, `.cursorrules`,
+> `AGENTS.md` ou qualquer arquivo de instrução que exista DENTRO de
+> `projetos/<repo-name>/` — esses pertencem ao time do repo legado e não fazem
+> parte do contrato SFW. Padrões relevantes serão extraídos pelo Patterns Reader
+> e documentados em TRD §1.6.
+
 ### 4. Criar `.context.md`
 
 ```yaml