@spec-wave/cli 0.5.8 → 0.5.10

package/bin/spec-wave.mjs

@@ -86,6 +86,20 @@ program
     await feature(options).catch(err => { console.error(err.message); process.exit(1); });
   });
 
+program
+  .command('update')
+  .description('Detecta o que está desatualizado (skill, .spec-wave.json, workflows/labels do repo) e atualiza só o que mudou')
+  .option('--global', 'Verifica a skill no escopo do usuário (padrão: projeto)')
+  .option('--skip-skill', 'Não verifica/atualiza a skill instalada')
+  .option('--skip-config', 'Não verifica/atualiza o .spec-wave.json local')
+  .option('--skip-repo', 'Não verifica/atualiza workflows e labels do repo')
+  .option('--dry-run', 'Mostra o que seria atualizado sem alterar nada')
+  .option('--yes', 'Aplica sem pedir confirmação')
+  .action(async (options) => {
+    const { update } = await import('../src/commands/update.mjs');
+    await update(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')

package/package.json

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

package/src/api/github-graphql.mjs

@@ -233,6 +233,31 @@ export async function getIssueParent(token, issueNodeId) {
   return { number: parent.number, title: parent.title, nodeId: parent.id };
 }
 
+// Lê o valor atual (nome da opção) de um campo SINGLE_SELECT para um item do
+// Project. Usado para garantir que a Etapa só avança (nunca retrocede).
+export async function getItemSingleSelectValue(token, itemId, fieldId) {
+  const client = makeClient(token);
+  const result = await client(`
+    query ItemValue($itemId: ID!) {
+      node(id: $itemId) {
+        ... on ProjectV2Item {
+          fieldValues(first: 50) {
+            nodes {
+              ... on ProjectV2ItemFieldSingleSelectValue {
+                name
+                field { ... on ProjectV2SingleSelectField { id } }
+              }
+            }
+          }
+        }
+      }
+    }
+  `, { itemId });
+  const nodes = result.node?.fieldValues?.nodes || [];
+  const value = nodes.find(n => n && n.field?.id === fieldId);
+  return value?.name ?? null;
+}
+
 // Define o valor de um campo SINGLE_SELECT para um item do Project.
 export async function setItemSingleSelect(token, projectId, itemId, fieldId, optionId) {
   const client = makeClient(token);

package/src/api/github-rest.mjs

@@ -43,6 +43,31 @@ export async function createLabel(token, owner, repo, label) {
   }
 }
 
+// Lista todas as labels do repo: [{ name, color, description }]. color é hex
+// sem "#" (minúsculo, como a API retorna). Usado pelo `update` para detectar
+// labels ausentes ou com cor/descrição divergente.
+export async function listLabels(token, owner, repo) {
+  const octokit = makeOctokit(token);
+  const labels = await octokit.paginate(octokit.rest.issues.listLabelsForRepo, {
+    owner,
+    repo,
+    per_page: 100,
+  });
+  return labels.map(l => ({ name: l.name, color: l.color, description: l.description || '' }));
+}
+
+// Atualiza cor/descrição de uma label existente (mantém o nome).
+export async function updateLabel(token, owner, repo, label) {
+  const octokit = makeOctokit(token);
+  await octokit.rest.issues.updateLabel({
+    owner,
+    repo,
+    name: label.name,
+    color: label.color,
+    description: label.description,
+  });
+}
+
 export async function upsertFile(token, owner, repo, path, content, message) {
   const octokit = makeOctokit(token);
   let sha;

package/src/commands/code-review.mjs

@@ -2,13 +2,13 @@ import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, getPR, commentOnIssue } from '../api/github-rest.mjs';
-import { addProjectItem, setItemSingleSelect, getSingleSelectField, getIssueParent } from '../api/github-graphql.mjs';
+import { addProjectItem, setItemSingleSelect, getSingleSelectField, getIssueParent, listSubIssues, getItemSingleSelectValue } from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
-import { CONFIG_FILE, STATUS_OPTIONS } from '../config.mjs';
+import { CONFIG_FILE, STATUS_OPTIONS, STAGE_ORDER, PROGRESS_TODO } from '../config.mjs';
 
 // Campo "Etapa" (custom) → "👀 Code Review". Campo "Status" (nativo) → "Todo".
 const CODE_REVIEW_STAGE = STATUS_OPTIONS.find(s => s.name.includes('Code Review'))?.name;
-const TODO_STATUS = 'Todo';
+const TODO_STATUS = PROGRESS_TODO;
 
 // Extrai números de issues referenciadas no corpo do PR (Closes #N, Fixes #N, #N solto).
 function extractIssueNumbers(body) {
@@ -54,17 +54,69 @@ async function resolveFeatureIssue(token, owner, repo, issueNumber) {
   return null;
 }
 
-// Move um item do board para Etapa "👀 Code Review" e Status "Todo".
+// Coleta a "unidade de review" de uma issue referenciada no PR: a Feature
+// ancestral + a Story + as Tasks dessa Story — tudo anda junto com a Feature.
+// Retorna Map number -> { nodeId, title }.
+async function collectReviewUnit(token, owner, repo, issueNumber) {
+  const unit = new Map();
+  const add = (n, nodeId, title) => { if (n && nodeId && !unit.has(n)) unit.set(n, { nodeId, title }); };
+
+  let issue;
+  try { issue = await getIssue(token, owner, repo, issueNumber); } catch { return unit; }
+  const type = detectIssueType(issue);
+  if (type !== 'Feature' && type !== 'Story' && type !== 'Task') return unit;
+
+  // Feature ancestral (ou a própria).
+  const feature = await resolveFeatureIssue(token, owner, repo, issueNumber);
+  if (feature) add(feature.number, feature.node_id, feature.title);
+
+  if (type === 'Feature') {
+    // Toda a subárvore da Feature: Stories + Tasks.
+    const stories = await listSubIssues(token, issue.node_id).catch(() => []);
+    for (const st of stories) {
+      add(st.number, st.nodeId, st.title);
+      const tasks = await listSubIssues(token, st.nodeId).catch(() => []);
+      for (const t of tasks) add(t.number, t.nodeId, t.title);
+    }
+  } else if (type === 'Story') {
+    add(issue.number, issue.node_id, issue.title);
+    const tasks = await listSubIssues(token, issue.node_id).catch(() => []);
+    for (const t of tasks) add(t.number, t.nodeId, t.title);
+  } else { // Task → inclui a Story pai e as Tasks irmãs.
+    add(issue.number, issue.node_id, issue.title);
+    const parent = await getIssueParent(token, issue.node_id).catch(() => null);
+    if (parent && detectIssueType({ title: parent.title }) === 'Story') {
+      add(parent.number, parent.nodeId, parent.title);
+      const tasks = await listSubIssues(token, parent.nodeId).catch(() => []);
+      for (const t of tasks) add(t.number, t.nodeId, t.title);
+    }
+  }
+  return unit;
+}
+
+// Avança um item do board para a Etapa "👀 Code Review" e reinicia o Status
+// (nativo) para "Todo". Uma issue só AVANÇA: se já estiver em Code Review ou em
+// uma etapa posterior, não é tocada (retorna false). Retorna true se avançou.
 async function setCodeReview(token, project, etapaField, statusField, nodeId) {
   const itemId = await addProjectItem(token, project.id, nodeId);
+
   if (etapaField?.id && CODE_REVIEW_STAGE) {
+    // Nunca retroceder: compara a etapa atual com a de destino na ordem canônica.
+    const current = await getItemSingleSelectValue(token, itemId, etapaField.id).catch(() => null);
+    const curIdx = current ? STAGE_ORDER.indexOf(current) : -1;
+    const tgtIdx = STAGE_ORDER.indexOf(CODE_REVIEW_STAGE);
+    if (curIdx !== -1 && tgtIdx !== -1 && curIdx >= tgtIdx) {
+      return false; // já está em Code Review ou adiante — não retrocede
+    }
     const optionId = etapaField.options?.[CODE_REVIEW_STAGE];
     if (optionId) await setItemSingleSelect(token, project.id, itemId, etapaField.id, optionId);
   }
+  // Ao avançar de etapa, o Status reinicia em "Todo".
   if (statusField?.id) {
     const optionId = statusField.options?.[TODO_STATUS];
     if (optionId) await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
   }
+  return true;
 }
 
 export async function codeReview({ prNumber }) {
@@ -117,16 +169,24 @@ export async function codeReview({ prNumber }) {
   const seen = new Set();
   const updated = [];
 
+  // Para cada issue referenciada, move a unidade inteira (Feature + Story +
+  // Tasks) para Code Review — tudo anda junto com a Feature.
   for (const num of issueNums) {
-    const feature = await resolveFeatureIssue(token, owner, repo, num);
-    if (!feature || seen.has(feature.number)) continue;
-    seen.add(feature.number);
-    try {
-      await setCodeReview(projectToken, project, etapaField, statusField, feature.node_id);
-      updated.push(`#${feature.number} ${feature.title}`);
-      console.log(`Feature #${feature.number} → "${CODE_REVIEW_STAGE}" / Status "${TODO_STATUS}".`);
-    } catch (err) {
-      console.warn(`Falha ao atualizar Feature #${feature.number}: ${err.message}`);
+    const unit = await collectReviewUnit(token, owner, repo, num);
+    for (const [n, info] of unit) {
+      if (seen.has(n)) continue;
+      seen.add(n);
+      try {
+        const moved = await setCodeReview(projectToken, project, etapaField, statusField, info.nodeId);
+        if (moved) {
+          updated.push(`#${n} ${info.title}`);
+          console.log(`#${n} → "${CODE_REVIEW_STAGE}" / Status "${TODO_STATUS}".`);
+        } else {
+          console.log(`#${n} já está em "${CODE_REVIEW_STAGE}" ou etapa posterior — mantido (não retrocede).`);
+        }
+      } catch (err) {
+        console.warn(`Falha ao atualizar #${n}: ${err.message}`);
+      }
     }
   }
 
@@ -134,10 +194,10 @@ export async function codeReview({ prNumber }) {
     await commentOnIssue(
       token, owner, repo, parseInt(prNumber, 10),
       `🔍 **Code Review iniciado**\n\n` +
-      `Feature(s) movida(s) para **${CODE_REVIEW_STAGE}**:\n\n` +
+      `Movidos para **${CODE_REVIEW_STAGE}** (Feature + Story + Tasks):\n\n` +
       updated.map(f => `- ${f}`).join('\n')
     ).catch(() => {});
   }
 
-  console.log(`code-review: ${updated.length} feature(s) atualizada(s).`);
+  console.log(`code-review: ${updated.length} item(ns) movido(s) para "${CODE_REVIEW_STAGE}".`);
 }

package/src/commands/implement.mjs

@@ -4,7 +4,10 @@ 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_DEVELOPMENT, STAGE_CODE_REVIEW,
+  PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE,
+} 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 +17,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 +46,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 +56,66 @@ 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);
+  // Modelo do board: "Etapa" (coluna do kanban) = DIREÇÃO, só avança; "Status"
+  // (Todo/In Progress/Done) = PROGRESSO dentro da etapa, reinicia a cada avanço.
+  // O desenvolvimento acontece na Etapa 🚧 Desenvolvimento; o progresso por task
+  // é registrado no STATUS. Ao final, a Etapa avança para Code Review.
   lines.push('');
-  lines.push('## Instruções para o agente');
+  lines.push('## Instruções de execução (uma task por vez, sequencial)');
   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}.`)
+    'Há **dois campos** no board com papéis diferentes — não os confunda:\n' +
+    `- **Etapa** (Backlog → … → ${STAGE_DEVELOPMENT} → ${STAGE_CODE_REVIEW} → …): a DIREÇÃO no kanban. Uma issue só **avança**, **nunca** volta para uma etapa anterior.\n` +
+    `- **Status** (${PROGRESS_TODO} → ${PROGRESS_IN_PROGRESS} → ${PROGRESS_DONE}): o **progresso dentro da etapa atual**. Ao avançar de etapa, o Status **reinicia em ${PROGRESS_TODO}**.`
   );
+  lines.push('');
+  if (type === 'Story') {
+    lines.push(
+      `Nesta fase, a Story #${issue.number} e suas Tasks estão na Etapa **${STAGE_DEVELOPMENT}**. ` +
+      'Durante a implementação, mexa **apenas no Status** das Tasks — **não** mude a Etapa delas.'
+    );
+    lines.push('');
+    lines.push(`1. Garanta que a Story #${issue.number} está na Etapa **${STAGE_DEVELOPMENT}** com Status **${PROGRESS_IN_PROGRESS}**, e que as Tasks estão nessa Etapa com Status **${PROGRESS_TODO}**.`);
+    lines.push(`2. Implemente as ${tasks.length} task(s) **uma de cada vez, na ordem abaixo**. É PROIBIDO ter mais de uma Task com Status **${PROGRESS_IN_PROGRESS}** ao mesmo tempo. Para **cada Task**, na ordem:`);
+    lines.push(`   1. **Ao começar:** Status da Task → **${PROGRESS_IN_PROGRESS}** (a Etapa continua ${STAGE_DEVELOPMENT}).`);
+    lines.push('   2. **Implemente** a Task por completo.');
+    lines.push(`   3. **Ao concluir:** Status da Task → **${PROGRESS_DONE}** (ainda na Etapa ${STAGE_DEVELOPMENT}).`);
+    lines.push('   4. Só então avance para a próxima Task.');
+    lines.push('');
+    lines.push(`3. **Ao concluir TODA a Story** (todas as Tasks com Status ${PROGRESS_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. **Avance a Etapa — em conjunto — ${feature ? `da Feature #${feature.number}` : 'da Feature (issue pai da Story)'}, ` +
+      `a Story #${issue.number} e todas as ${tasks.length} Task(s) (${tasks.map(t => `#${t.number}`).join(', ')}) ` +
+      `para ${STAGE_CODE_REVIEW}**, e **reinicie o Status de cada um para ${PROGRESS_TODO}**. ` +
+      'Tudo anda junto com a Feature e sempre para frente.'
+    );
+  } else {
+    lines.push(
+      `Esta Task #${issue.number} está na Etapa **${STAGE_DEVELOPMENT}**. Acompanhe o progresso pelo ` +
+      '**Status** — **não** mude a Etapa aqui:'
+    );
+    lines.push('');
+    lines.push(`1. **Ao começar:** Status da Task #${issue.number} → **${PROGRESS_IN_PROGRESS}**.`);
+    lines.push('2. **Implemente** a Task por completo.');
+    lines.push(`3. **Ao concluir:** Status da Task #${issue.number} → **${PROGRESS_DONE}**.`);
+    lines.push('');
+    lines.push(`> A Etapa avança para **${STAGE_CODE_REVIEW}** (Status reinicia em ${PROGRESS_TODO}) junto com a Story/Feature quando o PR é aberto — nunca volta para uma etapa anterior.`);
+  }
+  lines.push('');
   lines.push(
-    '(Atualize o campo "Etapa"/Status do item no board; mantenha o status coerente ' +
-    'conforme o progresso da implementação.)'
+    `> **Regra do board:** a **Etapa** só avança (nunca retrocede); o **Status** (${PROGRESS_TODO}/${PROGRESS_IN_PROGRESS}/${PROGRESS_DONE}) ` +
+    'só mede o progresso dentro da etapa atual e reinicia a cada avanço de etapa.'
   );
 
   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 +211,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 +228,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 instalar a skill no seu agente: npx @spec-wave/cli install-skill')}`
+    (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)}`
   );
 }

package/src/commands/install-skill.mjs

@@ -9,16 +9,22 @@ import path from 'node:path';
 const __dir = path.dirname(fileURLToPath(import.meta.url));
 // Fonte única da skill, publicada via "files": ["src"] no package.json.
 const SKILL_SOURCE = path.join(__dir, '..', 'templates', 'skill', 'SKILL.md');
+// Versão da CLI que gerou a skill instalada — carimbada no arquivo para detecção
+// de desatualização (a skill é uma cópia estática; não acompanha o `npx` sozinha).
+const pkg = JSON.parse(readFileSync(path.join(__dir, '..', '..', 'package.json'), 'utf-8'));
+// Reexportados para o comando `update` (detecção de skill desatualizada).
+export { SKILL_SOURCE };
+export const CLI_VERSION = pkg.version;
 
 // Marcadores usados para gravar/atualizar a skill de forma idempotente em
 // arquivos compartilhados (AGENTS.md) — permite reinstalar sem duplicar.
-const BLOCK_START = '<!-- spec-wave:start -->';
-const BLOCK_END = '<!-- spec-wave:end -->';
+export const BLOCK_START = '<!-- spec-wave:start -->';
+export const BLOCK_END = '<!-- spec-wave:end -->';
 
 // Registro de agentes suportados. Cada alvo descreve como detectá-lo no
 // diretório-base, onde gravar (projeto vs. global) e em que formato converter
 // o SKILL.md. Caminhos conferidos na doc oficial de cada ferramenta.
-const TARGETS = [
+export const TARGETS = [
   {
     key: 'claude',
     name: 'Claude Code',
@@ -81,47 +87,59 @@ const TARGETS = [
 const TARGET_BY_KEY = new Map(TARGETS.map((t) => [t.key, t]));
 
 // Separa o frontmatter YAML do corpo do SKILL.md. Retorna { meta, body }.
-function parseSkill(raw) {
+export function parseSkill(raw) {
   const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
-  if (!match) return { meta: {}, body: raw.trim() };
+  if (!match) return { meta: {}, frontmatter: '', body: raw.trim() };
   let meta = {};
   try {
     meta = yaml.load(match[1]) || {};
   } catch {
     meta = {};
   }
-  return { meta, body: match[2].trim() };
+  return { meta, frontmatter: match[1], body: match[2].trim() };
 }
 
-// Converte o SKILL.md para o formato exigido por cada agente.
-function renderContent(format, raw, parsed) {
-  const { meta, body } = parsed;
+// Banner de versão inserido no topo do corpo da skill instalada. O agente lê
+// esta linha e, se `npx @spec-wave/cli --version` for maior, orienta reinstalar.
+function versionBanner(version) {
+  return (
+    `> ⚙️ **spec-wave skill v${version}** — esta skill é uma cópia estática. ` +
+    'Se `npx @spec-wave/cli --version` indicar uma versão maior, ela está ' +
+    'desatualizada: rode `npx @spec-wave/cli update` (atualiza só o que mudou) ' +
+    'ou `npx @spec-wave/cli install-skill --force` (só a skill).'
+  );
+}
+
+// Converte o SKILL.md para o formato exigido por cada agente, carimbando a versão.
+export function renderContent(format, parsed, version) {
+  const { meta, frontmatter, body } = parsed;
   const description = meta.description ?? 'Skill spec-wave.';
+  const banner = versionBanner(version);
   switch (format) {
     case 'skill':
-      // Claude Code / opencode consomem o SKILL.md nativo. Campos extras do
-      // frontmatter são ignorados pelo opencode — sem problema.
-      return raw.trimEnd() + '\n';
+      // Claude Code / opencode consomem o SKILL.md nativo. Preserva o frontmatter
+      // original (allowed-tools etc.) e insere o banner no topo do corpo.
+      return `---\n${frontmatter}\n---\n\n${banner}\n\n${body}\n`;
     case 'mdc':
       return (
         `---\n` +
         `description: ${JSON.stringify(description)}\n` +
         `alwaysApply: false\n` +
         `---\n\n` +
-        `${body}\n`
+        `${banner}\n\n${body}\n`
       );
     case 'rules':
-      return `# spec-wave\n\n${description}\n\n${body}\n`;
+      return `# spec-wave\n\n${banner}\n\n${description}\n\n${body}\n`;
     case 'agents':
-      return `${BLOCK_START}\n\n# spec-wave\n\n${description}\n\n${body}\n\n${BLOCK_END}\n`;
+      return `${BLOCK_START}\n\n# spec-wave\n\n${banner}\n\n${description}\n\n${body}\n\n${BLOCK_END}\n`;
     default:
-      return raw;
+      return body;
   }
 }
 
 // Insere/atualiza o bloco spec-wave num arquivo compartilhado (AGENTS.md),
 // preservando o restante do conteúdo. Idempotente via marcadores.
-function mergeAgentsFile(destPath, block) {
+export function mergeAgentsFile(destPath, block) {
   const existing = existsSync(destPath) ? readFileSync(destPath, 'utf-8') : '';
   const blockRe = new RegExp(
     `${escapeRe(BLOCK_START)}[\\s\\S]*?${escapeRe(BLOCK_END)}\\n?`,
@@ -137,9 +155,18 @@ function escapeRe(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+// Extrai o bloco spec-wave (entre marcadores) de um arquivo compartilhado
+// (AGENTS.md). Retorna o texto do bloco incluindo os marcadores, ou null.
+export function extractAgentsBlock(fileContent) {
+  const m = fileContent.match(
+    new RegExp(`${escapeRe(BLOCK_START)}[\\s\\S]*?${escapeRe(BLOCK_END)}`),
+  );
+  return m ? m[0] : null;
+}
+
 // Resolve o alvo do agente para um destino concreto no escopo escolhido.
 // Retorna null quando o agente não suporta o escopo global.
-function resolveDest(target, baseDir, isGlobal) {
+export function resolveDest(target, baseDir, isGlobal) {
   const rel = isGlobal ? target.global : target.project;
   if (!rel) return null;
   const format = isGlobal && target.globalFormat ? target.globalFormat : target.format;
@@ -147,7 +174,7 @@ function resolveDest(target, baseDir, isGlobal) {
 }
 
 // Retorna true se algum dos sinais de detecção existir em baseDir.
-function isDetected(target, baseDir) {
+export function isDetected(target, baseDir) {
   return target.detect.some((sig) => existsSync(path.join(baseDir, sig)));
 }
 
@@ -258,8 +285,8 @@ export async function installSkill(options = {}) {
   for (const { target, dest } of jobs) {
     const content =
       dest.format === 'agents'
-        ? mergeAgentsFile(dest.path, renderContent('agents', raw, parsed))
-        : renderContent(dest.format, raw, parsed);
+        ? mergeAgentsFile(dest.path, renderContent('agents', parsed, pkg.version))
+        : renderContent(dest.format, parsed, pkg.version);
 
     // Confirmar sobrescrita de arquivos "próprios" (skill/rules/mdc). Para
     // 'agents' o merge por marcadores já é seguro (não apaga conteúdo alheio).
@@ -286,7 +313,10 @@ export async function installSkill(options = {}) {
 
   p.note(
     written.map((w) => `${chalk.green('✓')} ${chalk.bold(w.target.name)}\n  ${chalk.dim(w.dest.path)}`).join('\n'),
-    `Skill instalada (escopo: ${scopeLabel})`,
+    `Skill v${pkg.version} instalada (escopo: ${scopeLabel})`,
+  );
+  p.outro(
+    'Reinicie/recarregue o agente para que ele detecte a skill. ' +
+    'Ao atualizar a CLI, rode `install-skill --force` para atualizar a skill também.',
   );
-  p.outro('Reinicie/recarregue o agente para que ele detecte a skill.');
 }