@spec-wave/cli 0.5.7 → 0.5.9

package/README.md

@@ -0,0 +1,390 @@
+# @spec-wave/cli
+
+CLI e skill para implementar um fluxo **spec-driven** completo no GitHub — do backlog ao deploy — com GitHub Projects v2, labels de gatilho e GitHub Actions com IA.
+
+---
+
+## Conceito
+
+Spec Wave é um sistema de processo de desenvolvimento baseado em especificações. Cada Feature passa por um ciclo documentado antes de ser implementada:
+
+1. **Spec funcional** gerada por IA a partir do título e descrição da issue
+2. **Plano técnico** gerado por IA a partir da spec e do contexto tecnológico do repositório
+3. **Validação automática** das seções obrigatórias
+4. **Decomposição em Stories e Tasks** gerada por IA
+5. **Automação do board** durante o ciclo de desenvolvimento (Code Review → QA → Done)
+
+O resultado é um board Kanban no GitHub Projects v2 que avança automaticamente conforme o trabalho progride, com toda a documentação versionada no próprio repositório.
+
+---
+
+## Fluxo Kanban
+
+```
+📥 Backlog
+  → 🎯 Priorizado
+  → 📋 Spec          ← label spec-wave:spec → Action gera spec.md
+  → 📋 Plan          ← label spec-wave:plan → Action gera plan.md
+  → ✅ Ready         ← label spec-wave:ready → Action valida ambos
+  → 📋 Backlog Técnico
+  → 🚧 Desenvolvimento ← comando local: spec-wave implement <n>
+  → 👀 Code Review   ← PR aberto → Action move automaticamente
+  → 🧪 QA            ← PR aprovado → Action move automaticamente
+  → 📋 Homologação
+  → 🚀 Deploy
+  → 🎉 Done
+```
+
+---
+
+## Hierarquia de Work Items
+
+```
+Initiative
+  └── Epic
+        └── Feature
+              ├── Story
+              │     └── Task
+              └── Task
+```
+
+Cada nível é uma GitHub Issue com prefixo no título (`[FEATURE]`, `[STORY]`, etc.) e vínculo de sub-issue nativo do GitHub.
+
+---
+
+## Componentes
+
+### CLI (`@spec-wave/cli`)
+
+Ferramenta Node.js que configura e opera o fluxo via linha de comando.
+
+| Comando | O que faz |
+|---------|-----------|
+| `init` | Cria o GitHub Project, labels, workflows e `.spec-wave.json` |
+| `info` | Mostra o estado de configuração do repositório atual |
+| `refresh` | Re-sincroniza o `.spec-wave.json` com o GitHub Project |
+| `issue` | Cria qualquer work item (initiative/epic/feature/story/task/bug/spike/rfc) |
+| `initiative` | Atalho para `issue --type initiative` |
+| `feature` | Atalho para `issue --type feature` |
+| `generate-spec` | Gera `spec.md` (usado pelo GitHub Action) |
+| `generate-plan` | Gera `plan.md` (usado pelo GitHub Action) |
+| `validate` | Valida spec.md e plan.md (usado pelo GitHub Action) |
+| `decompose` | Decompõe Feature em Stories e Tasks (usado pelo GitHub Action) |
+| `code-review` | Move Feature para Code Review ao abrir PR (usado pelo GitHub Action) |
+| `qa` | Move Feature para QA ao aprovar PR (usado pelo GitHub Action) |
+| `implement` | Aciona o spec-kit localmente para implementar uma Story ou Task |
+| `uninstall` | Remove labels, workflows e `.spec-wave.json` |
+
+### GitHub Actions (instalados pelo `init`)
+
+| Workflow | Gatilho | Ação |
+|----------|---------|------|
+| `generate-spec.yml` | label `spec-wave:spec` | Gera `docs/features/<slug>/spec.md` via IA |
+| `generate-plan.yml` | label `spec-wave:plan` | Gera `docs/features/<slug>/plan.md` via IA |
+| `validate.yml` | label `spec-wave:ready` | Valida seções obrigatórias; adiciona `spec-wave:plan-approved` |
+| `decompose.yml` | label `spec-wave:decompose` | Cria Stories e Tasks como sub-issues |
+| `code-review.yml` | PR aberto/reaberto | Move Feature para `👀 Code Review` |
+| `qa.yml` | PR aprovado | Move Feature para `🧪 QA` |
+
+### Skill (`src/templates/skill/SKILL.md`)
+
+Skill que guia o usuário pelo fluxo via comandos como `/spec-wave spec 42`, `/spec-wave plan 42`, `/spec-wave decompose 42`. A skill lê o `.spec-wave.json` local, detecta o estado atual e executa os comandos corretos sem abrir wizards interativos. Instale-a no seu agente com `install-skill` (ver abaixo).
+
+### `.spec-wave.json`
+
+Arquivo de configuração gerado pelo `init` na raiz do repositório. Armazena `owner/repo`, dados do GitHub Project (ID, URL, campos) e o provider de IA configurado. Todos os comandos leem este arquivo para operar sem precisar de flags adicionais.
+
+### `tech_context.yml`
+
+Arquivo em `.github/config/tech_context.yml` que descreve a stack tecnológica do sistema (backend, frontend, banco, infra, roles RBAC, schemas, serviços). O `generate-plan` usa este arquivo para embasar o plano técnico — sem ele, o plano fica genérico.
+
+---
+
+## Pré-requisitos
+
+- Node.js >= 20
+- GitHub CLI (`gh`) autenticado com escopos `project`, `repo` e `workflow`:
+  ```bash
+  gh auth refresh --scopes project,repo,workflow
+  ```
+- Secret no repositório: `ANTHROPIC_API_KEY` ou `OPENROUTER_API_KEY` (Settings → Secrets → Actions)
+- Para repositórios em organizações: criar PAT com escopo `project` e adicionar como secret `GH_PROJECT_TOKEN`
+
+---
+
+## Instalação da CLI
+
+Não é necessário instalar globalmente — use `npx`:
+
+```bash
+npx @spec-wave/cli --help
+```
+
+Para instalar globalmente:
+
+```bash
+npm install -g @spec-wave/cli
+spec-wave --help
+```
+
+---
+
+## Instalação da Skill
+
+A skill permite usar o fluxo diretamente no seu agente via `/spec-wave`.
+
+**1. Instale a skill com o comando `install-skill`:**
+
+```bash
+# Autodetecta o agente em uso e instala no local/formato correto
+npx @spec-wave/cli install-skill
+```
+
+O comando suporta Claude Code, Cursor, opencode, Cline, Kilo Code, Antigravity e o
+padrão genérico `AGENTS.md`. Por padrão instala no escopo do projeto (versionável
+com o time); use `--global` para o escopo do usuário. Escolha alvos com
+`--agent <nomes>` (ex.: `--agent claude,cursor`) ou `--all` para todos os
+detectados. Use `--dry-run` para pré-visualizar sem gravar.
+
+**2. Adicione ao `CLAUDE.md` (ou equivalente) do projeto:**
+
+```markdown
+# spec-wave skill
+Trigger `/spec-wave` to invoke the spec-wave skill.
+```
+
+**3. Use no seu agente:**
+
+```
+/spec-wave setup
+/spec-wave spec 42
+/spec-wave plan 42
+/spec-wave ready 42
+/spec-wave decompose 42
+/spec-wave implement 45
+```
+
+---
+
+## Exemplo de uso — do início ao fim
+
+### Contexto
+
+Equipe quer implementar uma feature de "Checkout com PIX" em um repositório `acme/loja`.
+
+---
+
+### 1. Configurar o repositório
+
+```bash
+# Verificar autenticação
+gh auth status
+
+# Se faltarem escopos:
+gh auth refresh --scopes project,repo,workflow
+
+# Configurar spec-wave (cria Project, labels e workflows)
+npx @spec-wave/cli init --repo acme/loja --project-title "Loja — Spec Wave"
+```
+
+O `init` cria:
+- GitHub Project v2 com 12 colunas Kanban e campos personalizados (Work Item Type, Priority, Story Points, Area)
+- 20+ labels de tipo, prioridade e gatilho
+- 6 GitHub Actions workflows em `.github/workflows/`
+- `.spec-wave.json` com os IDs do Project
+
+Adicionar o secret de IA no GitHub: **Settings → Secrets → Actions → `ANTHROPIC_API_KEY`**.
+
+---
+
+### 2. Criar a hierarquia de issues
+
+```bash
+# Criar Epic
+npx @spec-wave/cli issue \
+  --type epic \
+  --title "Checkout e Pagamentos" \
+  --priority P1 \
+  --area Backend
+# → Issue #5 criada: [EPIC] Checkout e Pagamentos
+
+# Criar Feature como sub-issue do Epic
+npx @spec-wave/cli feature \
+  --title "Checkout com PIX" \
+  --parent 5 \
+  --priority P1 \
+  --area Backend
+# → Issue #12 criada: [FEATURE] Checkout com PIX (sub-issue de #5)
+# → Adicionada ao board em 📥 Backlog
+```
+
+---
+
+### 3. Gerar a especificação funcional
+
+```bash
+gh issue edit 12 --add-label "spec-wave:spec"
+```
+
+O GitHub Action `generate-spec.yml` dispara, chama a IA e faz commit de:
+```
+docs/features/checkout-com-pix/spec.md
+```
+
+A issue #12 recebe um comentário com o link para o arquivo.
+
+---
+
+### 4. Gerar o plano técnico
+
+Antes de gerar o plano, garanta que `.github/config/tech_context.yml` existe e reflete a stack real. O `init` cria um scaffold — edite-o:
+
+```yaml
+system_info:
+  name: "Loja ACME"
+  stack:
+    backend: "Node.js (NestJS v11)"
+    frontend: "Next.js 16"
+    database: "PostgreSQL (Prisma 5)"
+    infra: "Docker / AWS ECS"
+security:
+  auth_protocol: "JWT"
+  rbac_roles: ["ADMIN", "CUSTOMER"]
+database_schemas:
+  - table: "orders"
+    columns: "id, customer_id, status, total, created_at"
+```
+
+```bash
+git add .github/config/tech_context.yml
+git commit -m "chore: tech_context.yml"
+git push
+
+# Acionar geração do plano
+gh issue edit 12 --add-label "spec-wave:plan"
+```
+
+O Action gera `docs/features/checkout-com-pix/plan.md` com:
+- Estratégia Técnica e Matriz de Rastreabilidade
+- Detalhamento da Implementação
+- Segurança e Conformidade
+- Estratégia de Testes
+- Rollback e Monitoramento
+
+---
+
+### 5. Validar spec e plan
+
+```bash
+gh issue edit 12 --add-label "spec-wave:ready"
+```
+
+O Action `validate.yml` verifica se todas as seções obrigatórias estão presentes em spec.md e plan.md. Se passar:
+- Remove a label `spec-wave:ready`
+- Adiciona a label `spec-wave:plan-approved`
+- Comenta "Validação aprovada ✅" na issue
+
+---
+
+### 6. Decompor em Stories e Tasks
+
+```bash
+gh issue edit 12 --add-label "spec-wave:decompose"
+```
+
+O Action `decompose.yml` usa IA para criar sub-issues da Feature #12:
+
+```
+#13 [STORY] Como cliente, quero selecionar PIX como forma de pagamento
+  #14 [TASK] Criar endpoint POST /orders/:id/payment/pix
+  #15 [TASK] Integrar API do banco via webhook
+  #16 [TASK] Exibir QR Code na tela de checkout
+#17 [STORY] Como cliente, quero receber confirmação do pagamento
+  #18 [TASK] Webhook de confirmação do banco
+  #19 [TASK] Notificação por e-mail ao confirmar
+```
+
+Todas as Stories e Tasks são adicionadas ao board em **📋 Backlog Técnico** com Status `Todo`.
+
+---
+
+### 7. Implementar
+
+```bash
+# Via skill no Claude Code:
+/spec-wave implement 13
+
+# Ou direto:
+npx @spec-wave/cli implement 13 --dry-run   # ver contexto antes
+npx @spec-wave/cli implement 13             # executar
+```
+
+O comando monta um arquivo de contexto com spec.md, plan.md e todas as Tasks da Story, e aciona o spec-kit configurado.
+
+---
+
+### 8. Code Review automático
+
+Ao abrir um PR que referencia `Closes #14` (ou qualquer issue da hierarquia):
+
+```markdown
+## Descrição
+Implementa endpoint PIX
+
+Closes #14
+```
+
+O Action `code-review.yml` detecta a referência, sobe a hierarquia Task → Story → Feature, e move a Feature #12 para **👀 Code Review** no board.
+
+---
+
+### 9. QA automático
+
+Quando um reviewer aprova o PR, o Action `qa.yml` move a Feature #12 para **🧪 QA**.
+
+---
+
+### 10. Estado final no board
+
+```
+Feature #12: [FEATURE] Checkout com PIX
+  Etapa: 🧪 QA
+  Status: Todo
+  Work Item Type: Feature
+  Priority: P1
+  Area: Backend
+```
+
+Após QA passar, mover manualmente para **📋 Homologação → 🚀 Deploy → 🎉 Done**.
+
+---
+
+## Atualizar repositórios existentes
+
+Quando uma nova versão da CLI for publicada, rode em cada repositório configurado:
+
+```bash
+npx @spec-wave/cli@latest init --skip-project --skip-labels
+```
+
+Isso atualiza apenas os arquivos de workflow sem recriar o Project ou as labels.
+
+---
+
+## Providers de IA
+
+| Provider | Secret | Modelo padrão |
+|----------|--------|---------------|
+| Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-6` |
+| OpenRouter | `OPENROUTER_API_KEY` | `anthropic/claude-3.7-sonnet` |
+
+Configurar no `init`:
+```bash
+npx @spec-wave/cli init --repo owner/repo --provider openrouter --model anthropic/claude-3.7-sonnet
+```
+
+---
+
+## Licença
+
+MIT

package/bin/spec-wave.mjs

@@ -86,6 +86,20 @@ program
     await feature(options).catch(err => { console.error(err.message); process.exit(1); });
   });
 
+program
+  .command('install-skill')
+  .description('Instala a skill spec-wave no(s) agente(s) detectado(s): Claude Code, Cursor, opencode, Cline, Kilo, Antigravity, AGENTS.md')
+  .option('--agent <names>', 'Agente(s) alvo, separados por vírgula (pula a detecção)')
+  .option('--all', 'Instala em todos os agentes detectados')
+  .option('--global', 'Instala no escopo do usuário (padrão: projeto)')
+  .option('--dry-run', 'Mostra o que seria instalado sem gravar')
+  .option('--force', 'Sobrescreve arquivos existentes sem confirmar')
+  .option('--yes', 'Modo não-interativo')
+  .action(async (options) => {
+    const { installSkill } = await import('../src/commands/install-skill.mjs');
+    await installSkill(options).catch(err => { console.error(err.message); process.exit(1); });
+  });
+
 program
   .command('uninstall')
   .description('Remove labels, arquivos .github e o .spec-wave.json (mantém o GitHub Project)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {

package/src/commands/implement.mjs

@@ -4,7 +4,7 @@ import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
-import { CONFIG_FILE } from '../config.mjs';
+import { CONFIG_FILE, STAGE_IN_PROGRESS, STAGE_DONE, STAGE_CODE_REVIEW } from '../config.mjs';
 import { getIssue } from '../api/github-rest.mjs';
 import { listSubIssues, getIssueParent } from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
@@ -14,14 +14,17 @@ import { slugify } from '../lib/slugify.mjs';
 const WORK_DIR = '.spec-wave';
 
 // Sobe a cadeia de pais (Task → Story → Feature) até achar uma issue do tipo
-// "Feature" e devolve seu título (para resolver docs/features/<slug>). Limita a
-// profundidade para evitar loops em dados inconsistentes.
-async function resolveFeatureTitle(token, startNodeId) {
+// "Feature" e devolve { number, title } — usado para resolver docs/features/<slug>
+// e para as instruções de fim de Story (mover a Feature para Code Review). Limita
+// a profundidade para evitar loops em dados inconsistentes.
+async function resolveFeature(token, startNodeId) {
   let current = startNodeId;
   for (let depth = 0; depth < 5 && current; depth++) {
     const parent = await getIssueParent(token, current);
     if (!parent) return null;
-    if (detectIssueType({ title: parent.title }) === 'Feature') return parent.title;
+    if (detectIssueType({ title: parent.title }) === 'Feature') {
+      return { number: parent.number, title: parent.title };
+    }
     current = parent.nodeId;
   }
   return null;
@@ -40,7 +43,7 @@ function readSpecPlan(featureDir) {
 }
 
 // Monta o markdown de contexto que será entregue ao spec-kit implement.
-function buildContext({ type, issue, tasks, spec, plan, specPath, planPath }) {
+function buildContext({ type, issue, tasks, feature, spec, plan, specPath, planPath }) {
   const lines = [];
   lines.push(`# Contexto de implementação — ${type} #${issue.number}`);
   lines.push('');
@@ -50,32 +53,55 @@ function buildContext({ type, issue, tasks, spec, plan, specPath, planPath }) {
     lines.push(issue.body.trim());
   }
 
-  // Issues cujo status deve ir para "in progress" ao iniciar: a issue alvo
-  // (Story ou Task) e, no caso de Story, todas as suas Tasks.
-  const inProgress = [issue.number, ...tasks.map(t => t.number)]
-    .filter((n, i, arr) => arr.indexOf(n) === i);
+  // Fluxo SEQUENCIAL, uma task por vez: cada task só vai para "In Progress"
+  // quando seu desenvolvimento começa e vai para "Done" ao concluir — nunca
+  // todas as tasks em "In Progress" ao mesmo tempo.
   lines.push('');
-  lines.push('## Instruções para o agente');
+  lines.push('## Instruções de execução (uma task por vez, sequencial)');
+  lines.push('');
+  if (type === 'Story') {
+    lines.push(
+      `Implemente as ${tasks.length} task(s) desta Story **uma de cada vez, na ordem listada ` +
+      'abaixo**. É PROIBIDO mover mais de uma task para "In Progress" ao mesmo tempo: uma task ' +
+      'só entra em desenvolvimento depois que a anterior estiver concluída.'
+    );
+    lines.push('');
+    lines.push(`1. Ao **iniciar a primeira** task, mova a Story #${issue.number} para **${STAGE_IN_PROGRESS}**.`);
+    lines.push('2. Para **cada task**, na ordem, execute este ciclo completo antes de passar para a próxima:');
+    lines.push(`   1. **Ao começar a task:** mova o status (campo "Etapa") *apenas dessa task* para **${STAGE_IN_PROGRESS}** (In Progress). Nenhuma outra task.`);
+    lines.push('   2. **Implemente** essa task por completo.');
+    lines.push(`   3. **Ao concluir a task:** mova o status *dessa task* para **${STAGE_DONE}** (Done).`);
+    lines.push('   4. Só então avance para a próxima task e repita o ciclo.');
+    lines.push('');
+    lines.push(`3. **Ao concluir a implementação de TODA a Story** (todas as tasks em **${STAGE_DONE}**):`);
+    lines.push('   1. Faça o **commit** de todas as mudanças da implementação.');
+    lines.push(`   2. Abra o **Pull Request** da Story #${issue.number}.`);
+    lines.push(
+      `   3. Mova ${feature ? `a Feature #${feature.number}` : 'a Feature (issue pai da Story)'} e a ` +
+      `Story #${issue.number} para **${STAGE_CODE_REVIEW}**. ` +
+      `As **Tasks permanecem em ${STAGE_DONE}** (não as mova para trás).`
+    );
+  } else {
+    lines.push(`Implemente a Task #${issue.number} bracketando o status no GitHub Project:`);
+    lines.push('');
+    lines.push(`1. **Ao começar:** mova o status (campo "Etapa") da Task #${issue.number} para **${STAGE_IN_PROGRESS}** (In Progress).`);
+    lines.push('2. **Implemente** a task por completo.');
+    lines.push(`3. **Ao concluir:** mova o status da Task #${issue.number} para **${STAGE_DONE}** (Done).`);
+  }
   lines.push('');
   lines.push(
-    'Antes de começar a implementação, atualize o status no GitHub Project para ' +
-    '**🚧 Desenvolvimento** (in progress) ' +
-    (type === 'Story'
-      ? `da Story #${issue.number} e de cada Task: ${inProgress.filter(n => n !== issue.number).map(n => `#${n}`).join(', ')}.`
-      : `da Task #${issue.number}.`)
-  );
-  lines.push(
-    '(Atualize o campo "Etapa"/Status do item no board; mantenha o status coerente ' +
-    'conforme o progresso da implementação.)'
+    `> Mantenha o status coerente com o progresso real: nenhuma task pode ficar em "${STAGE_IN_PROGRESS}" ` +
+    `antes de você começá-la, nem em "${STAGE_DONE}" antes de concluí-la. Atualize o campo "Etapa"/Status ` +
+    'do item no GitHub Project.'
   );
 
   lines.push('');
-  lines.push(`## Tasks a implementar (${tasks.length})`);
-  for (const t of tasks) {
+  lines.push(`## Tasks a implementar — NESTA ORDEM (${tasks.length})`);
+  tasks.forEach((t, i) => {
     lines.push('');
-    lines.push(`### #${t.number} ${t.title}`);
+    lines.push(`### ${i + 1}. #${t.number} ${t.title}`);
     if (t.body && t.body.trim()) lines.push(t.body.trim());
-  }
+  });
 
   if (spec) {
     lines.push('');
@@ -171,11 +197,12 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
     return;
   }
 
-  // 4. Resolve spec.md/plan.md da Feature (enriquecimento opcional).
+  // 4. Resolve a Feature (pai na cadeia) — para spec.md/plan.md e para as
+  // instruções de fim de Story (mover Feature + Story para Code Review).
+  const feature = await resolveFeature(token, issue.node_id);
   let featureDir = featureDirOpt;
-  if (!featureDir) {
-    const featureTitle = await resolveFeatureTitle(token, issue.node_id);
-    if (featureTitle) featureDir = path.join('docs', 'features', slugify(featureTitle));
+  if (!featureDir && feature?.title) {
+    featureDir = path.join('docs', 'features', slugify(feature.title));
   }
   let specPlan = { spec: null, plan: null, specPath: null, planPath: null };
   if (featureDir && existsSync(featureDir)) {
@@ -187,7 +214,7 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
   }
 
   // 5. Monta e grava o arquivo de contexto.
-  const context = buildContext({ type, issue, tasks, ...specPlan });
+  const context = buildContext({ type, issue, tasks, feature, ...specPlan });
   mkdirSync(WORK_DIR, { recursive: true });
   const tasksFile = path.join(WORK_DIR, `implement-${issueNumber}.md`);
   writeFileSync(tasksFile, context);

package/src/commands/info.mjs

@@ -2,7 +2,7 @@ import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
-import { CONFIG_FILE } from '../config.mjs';
+import { CONFIG_FILE, PORTAL_URL } from '../config.mjs';
 
 // Lê o marcador .spec-wave.json do repositório atual (cwd) e reporta se o
 // spec-wave já foi inicializado. Usado pela skill para decidir entre mostrar
@@ -17,6 +17,7 @@ export async function info(options = {}) {
     }
     p.intro(chalk.bold('spec-wave info'));
     p.log.warn(`Este repositório ${chalk.bold('não foi inicializado')} (sem ${CONFIG_FILE}).`);
+    p.log.info(`🌐 Acesse o Portal Web da ferramenta em ${chalk.cyan(PORTAL_URL)}`);
     p.outro('Execute `npx @spec-wave/cli init` para configurar.');
     return;
   }
@@ -50,5 +51,6 @@ export async function info(options = {}) {
     `${chalk.dim('Criado em:')}   ${config.initializedAt ?? '?'}`,
     'Configuração'
   );
+  p.log.info(`🌐 Acesse o Portal Web da ferramenta em ${chalk.cyan(PORTAL_URL)}`);
   p.outro('Use `/spec-wave feature <descrição>` para criar uma Feature.');
 }

package/src/commands/init.mjs

@@ -1,6 +1,6 @@
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { resolveToken, verifyTokenScopes } from '../api/auth.mjs';
@@ -8,8 +8,8 @@ import { runWizard } from '../ui/wizard.mjs';
 import { setupProject } from '../setup/project.mjs';
 import { setupLabels } from '../setup/labels.mjs';
 import { setupFiles } from '../setup/files.mjs';
-import { upsertFile, getFileContent } from '../api/github-rest.mjs';
-import { CONFIG_FILE, AI_PROVIDERS, getProvider, DEFAULT_PROVIDER } from '../config.mjs';
+import { getFileContent } from '../api/github-rest.mjs';
+import { CONFIG_FILE, AI_PROVIDERS, getProvider, DEFAULT_PROVIDER, PORTAL_URL } from '../config.mjs';
 
 const __dir = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dir, '..', '..', 'package.json'), 'utf-8'));
@@ -91,8 +91,13 @@ export async function init(options) {
   if (options.skipProject) {
     p.log.info('Pulando criação do GitHub Project (--skip-project).');
     // Preserva o bloco project do .spec-wave.json existente (se houver).
+    // Prefere o arquivo local; recorre ao remoto para repos configurados por
+    // versões antigas (que commitavam o config direto no repo).
     try {
-      const raw = await getFileContent(token, owner, repo, CONFIG_FILE);
+      const localConfigPath = path.join(process.cwd(), CONFIG_FILE);
+      const raw = existsSync(localConfigPath)
+        ? readFileSync(localConfigPath, 'utf-8')
+        : await getFileContent(token, owner, repo, CONFIG_FILE);
       if (raw) {
         const existing = JSON.parse(raw);
         if (existing.project) {
@@ -165,10 +170,13 @@ export async function init(options) {
   }
 
   // --- Marcador de configuração (.spec-wave.json) ---
-  // Commitado no repo-alvo para que a skill detecte, em sessões futuras, que o
-  // init já rodou e qual project/versão foi usado. É a fonte de estado persistente.
+  // Gravado LOCALMENTE no diretório atual (não commitado direto no repo): é a
+  // fonte de estado persistente lida por info/refresh/uninstall/skill a partir
+  // do cwd. O usuário revisa e commita quando quiser.
+  const localConfigPath = path.join(process.cwd(), CONFIG_FILE);
+  let configWritten = false;
   const configSpinner = p.spinner();
-  configSpinner.start(`Gravando ${CONFIG_FILE}...`);
+  configSpinner.start(`Gravando ${CONFIG_FILE} local...`);
   try {
     const config = {
       version: pkg.version,
@@ -187,15 +195,9 @@ export async function init(options) {
       },
       initializedAt: new Date().toISOString(),
     };
-    await upsertFile(
-      token,
-      owner,
-      repo,
-      CONFIG_FILE,
-      JSON.stringify(config, null, 2) + '\n',
-      'chore: record spec-wave config [spec-wave]'
-    );
-    configSpinner.stop(`${CONFIG_FILE} gravado (spec-wave v${pkg.version})`);
+    writeFileSync(localConfigPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    configWritten = true;
+    configSpinner.stop(`${CONFIG_FILE} gravado local (spec-wave v${pkg.version})`);
   } catch (err) {
     configSpinner.stop('');
     p.log.warn(`Não foi possível gravar ${CONFIG_FILE}: ${err.message}`);
@@ -214,10 +216,14 @@ export async function init(options) {
     `\n${chalk.green('✓')} spec-wave configurado com sucesso!\n\n` +
     (projectUrl ? `  Projeto: ${chalk.cyan(projectUrl)}\n\n` : '') +
     `  Próximos passos:\n` +
-    `  1. Adicione ${providerMeta.secret} como secret no repositório (provider: ${providerMeta.label})\n` +
-    `  2. Configure o board view para agrupar por "Etapa"\n` +
-    `  3. Crie uma Feature com o prefixo [FEATURE] no título\n` +
-    `  4. Use a skill spec-wave para guiar o fluxo\n\n` +
-    `  ${chalk.dim('Para usar a skill: adicione skill/SKILL.md ao seu projeto Claude Code')}`
+    (configWritten
+      ? `  1. Commite o ${CONFIG_FILE} quando quiser (git add ${CONFIG_FILE} && git commit)\n`
+      : '') +
+    `  ${configWritten ? '2' : '1'}. Adicione ${providerMeta.secret} como secret no repositório (provider: ${providerMeta.label})\n` +
+    `  ${configWritten ? '3' : '2'}. Configure o board view para agrupar por "Etapa"\n` +
+    `  ${configWritten ? '4' : '3'}. Crie uma Feature com o prefixo [FEATURE] no título\n` +
+    `  ${configWritten ? '5' : '4'}. Use a skill spec-wave para guiar o fluxo\n\n` +
+    `  ${chalk.dim('Para instalar a skill no seu agente: npx @spec-wave/cli install-skill')}\n\n` +
+    `  🌐 Acesse o Portal Web da ferramenta em ${chalk.cyan(PORTAL_URL)}`
   );
 }