spec-first-claude 0.8.0-beta.1 → 0.8.0-beta.3

package/package.json

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

package/templates/.claude/CHANGELOG.md

@@ -8,6 +8,51 @@
 
 ---
 
+## 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 `CLAUDE.md` (Claude kit) e
+  `copilot-instructions.md` (Copilot kit) — antes de qualquer outra seção
+- **Aviso reforçado no Passo 3 do `/sfw-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
+
+`/sfw-onboard` agora verifica autenticação git **antes** de tentar clonar,
+detectando SSH vs HTTPS e testando ssh-agent / credential helper / GH CLI.
+Falha cedo com mensagem específica em vez de erro genérico do `git clone`.
+
+### Adicionado
+
+- Passo 0 do `/sfw-onboard`: verificação proativa de auth
+  - SSH: `ssh-add -l` (agent vazio?) + `ssh -T git@<host>` (chave autorizada?)
+  - HTTPS: `git config credential.helper` + `gh auth status` + `git ls-remote`
+- 6 mensagens de erro específicas (ssh-agent off, agent vazio, chave não
+  autorizada, sem helper nem GH CLI, GH CLI deslogado, falha desconhecida)
+- Nota Windows/PowerShell sobre ssh-agent + alternativas (GH CLI, PAT)
+
+---
+
 ## 0.8.0-beta.1 (2026-05-11) — Brownfield onboarding
 
 Skill nova `/sfw-onboard` pra assumir aplicações **já existentes**. Lê o

package/templates/.claude/commands/sfw-onboard.md

@@ -41,11 +41,77 @@ execução adiciona uma entry em `projetos.yaml` e merge aditivo no TRD.
 | # | Validação | Se falhar |
 |---|-----------|-----------|
 | 1 | `<git-url>` informado | Parar → "Informe a URL do repositório. Ex: /sfw-onboard https://github.com/org/app.git" |
-| 2 | `git` instalado no PATH | Parar → "Git não encontrado no PATH" |
-| 3 | URL acessível (auth do user) | Parar → "Falha ao clonar. Configure SSH/PAT antes de rodar /sfw-onboard" |
+| 2 | `git` instalado no PATH (`git --version`) | Parar → "Git não encontrado no PATH" |
+| 3 | **Auth git pré-verificada** (ver passo 0) | Parar com instrução específica conforme tipo de URL |
 | 4 | `--branch` e `--tag` não usados juntos | Parar → "Use --branch OU --tag, não ambos" |
 | 5 | Scope `onboard_<repo>` não está em `analyzing` | Se sim → "Onboarding anterior incompleto. Rode novamente pra retomar" |
 
+### Passo 0 — Verificar autenticação ANTES de clonar
+
+Detectar tipo de URL e testar auth proativamente. Falhar cedo com mensagem
+clara é melhor que esperar o `git clone` quebrar sem contexto.
+
+**Detectar tipo de URL**:
+
+| Padrão | Tipo |
+|--------|------|
+| `git@<host>:<org>/<repo>.git` | SSH |
+| `ssh://git@<host>/...` | SSH |
+| `https://<host>/...` | HTTPS |
+
+**Se SSH** — testar agente + conectividade:
+
+```bash
+# 1. ssh-agent rodando com chave carregada?
+ssh-add -l
+#    Saída esperada: linha(s) com fingerprint. Se "The agent has no identities",
+#    user precisa rodar `ssh-add ~/.ssh/id_ed25519` (ou similar).
+#    Se "Could not open a connection to your authentication agent",
+#    user precisa iniciar o ssh-agent.
+
+# 2. Host autenticável? (extrair host da URL, ex: github.com)
+ssh -T -o StrictHostKeyChecking=accept-new -o BatchMode=yes git@<host>
+#    GitHub retorna exit 1 com "Hi <user>! You've successfully authenticated"
+#    GitLab/Bitbucket têm mensagens análogas.
+#    Exit 255 ou "Permission denied (publickey)" → chave não autorizada.
+```
+
+**Se HTTPS** — testar credential helper ou GH CLI:
+
+```bash
+# 1. Git credential helper configurado?
+git config --get credential.helper
+#    Vazio → user usa GH CLI ou vai ser perguntado credencial no clone.
+
+# 2. (Se host = github.com) GH CLI autenticado?
+gh auth status --hostname github.com
+#    Exit 0 + "Logged in to github.com" → ok
+#    Exit 1 → não logado
+
+# 3. Alternativa: tentar ls-remote sem clonar (mais leve que clone)
+GIT_TERMINAL_PROMPT=0 git ls-remote --heads <git-url> HEAD
+#    Exit 0 → auth ok
+#    Exit ≠ 0 + "Authentication failed" → credencial ausente/inválida
+#    Exit ≠ 0 + "could not read Username" → terminal prompt bloqueado, sem credential helper
+```
+
+**Mensagens de erro específicas**:
+
+| Cenário | Mensagem |
+|---------|----------|
+| SSH sem ssh-agent | "ssh-agent não está rodando. Inicie com `eval $(ssh-agent)` (Linux/Mac) ou `Start-Service ssh-agent` (Windows)" |
+| SSH agent vazio | "Nenhuma chave SSH carregada. Rode `ssh-add ~/.ssh/id_ed25519` (ajuste o nome se diferente)" |
+| SSH host nega | "Chave SSH não autorizada em `<host>`. Verifique se a chave pública está cadastrada em `<host>/settings/keys` (GitHub) ou equivalente" |
+| HTTPS sem helper nem GH CLI | "Credencial HTTPS não configurada. Opções: (1) `gh auth login` se host=github.com; (2) configurar credential helper (`git config --global credential.helper manager`); (3) usar URL SSH (`git@<host>:...`)" |
+| HTTPS GH CLI deslogado | "GH CLI não autenticado. Rode `gh auth login` e tente novamente" |
+| `ls-remote` falha por motivo desconhecido | "Falha ao acessar o repo: `<stderr do ls-remote>`. Verifique a URL e suas credenciais" |
+
+**Sucesso**: log breve "Auth OK ({tipo})" e prosseguir para o Passo 1.
+
+> **Nota Windows/PowerShell**: comandos `ssh-add`, `ssh -T`, `gh`, `git`
+> assumem disponíveis no PATH. Em ambientes sem ssh-agent nativo (Windows
+> antigo), instruir uso do GH CLI ou HTTPS+PAT.
+
 ## Passos
 
 ### 1. Resolver nome do scope e path
@@ -84,6 +150,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** `CLAUDE.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
@@ -332,7 +409,8 @@ Se `--name` diferentes → scopes separados (raro, mas suportado).
 
 | Erro | Ação |
 |------|------|
-| URL não acessível | Parar, sugerir checar SSH/PAT |
+| Auth falha (capturado no Passo 0) | Parar com mensagem específica conforme cenário (ver tabela do Passo 0) |
+| Clone falha mesmo com auth OK | Reportar `stderr` do git; verificar se a URL e branch existem |
 | Repo vazio | Parar — "Nada a onboardar" |
 | Nenhum reader produziu fragmento (stack desconhecida) | Parar — "Stack não reconhecida. Detalhe TRD manualmente ou peça suporte" |
 | `projetos/<repo-name>/` já existe e NÃO é clone do mesmo URL | Parar — "Path já em uso por outro repo. Use --name pra dar outro nome" |

package/templates/.claude/rules.md

@@ -32,6 +32,43 @@ As regras abaixo são o padrão do framework. O time pode:
 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 `.claude/`, `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/`, `.claude/` 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ê `CLAUDE.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 `CLAUDE.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: `.claude/`, `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
 

package/templates/CLAUDE.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 `.claude/`, `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ê `CLAUDE.md` que exista DENTRO de `projetos/<repo>/` |
+| Lê regras de `rules.md` da raiz SFW | Lê `.github/copilot-instructions.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 (`/sfw-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 `/sfw-onboard`.
+
+Detalhamento completo em `.claude/rules.md` (Regra Inviolável #7 + seção
+"Working Directory").
+
+---
+
 ## Identidade do Projeto
 
 Este é um projeto que utiliza desenvolvimento **spec-first** assistido por IA.