@spec-wave/cli 0.5.9 → 0.5.11

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.9",
+  "version": "0.5.11",
   "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,89 @@ 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. Separa a
+// Feature dos demais itens, porque a Feature tem regra própria (só avança
+// quando TODAS as suas Stories estiverem em Code Review). Retorna
+// { feature: {number,nodeId,title}|null, items: Map(number -> {nodeId,title}) }
+// onde `items` são as Stories + Tasks que andam juntas neste PR.
+async function collectReviewUnit(token, owner, repo, issueNumber) {
+  const items = new Map();
+  const add = (n, nodeId, title) => { if (n && nodeId && !items.has(n)) items.set(n, { nodeId, title }); };
+
+  let issue;
+  try { issue = await getIssue(token, owner, repo, issueNumber); } catch { return { feature: null, items }; }
+  const type = detectIssueType(issue);
+  if (type !== 'Feature' && type !== 'Story' && type !== 'Task') return { feature: null, items };
+
+  const featureIssue = await resolveFeatureIssue(token, owner, repo, issueNumber);
+  const feature = featureIssue
+    ? { number: featureIssue.number, nodeId: featureIssue.node_id, title: featureIssue.title }
+    : null;
+
+  if (type === 'Feature') {
+    // Referência direta à Feature: toda a subárvore (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 { feature, items };
+}
+
+// A Feature só avança quando TODAS as suas Stories já estiverem em Code Review
+// (ou etapa posterior). readToken lê as issues; projToken opera no Project.
+async function allStoriesReadyForReview(readToken, projToken, project, etapaField, featureNodeId) {
+  if (!etapaField?.id) return true; // sem campo Etapa não há como checar — assume ok
+  const subs = await listSubIssues(readToken, featureNodeId).catch(() => []);
+  const stories = subs.filter(s => detectIssueType({ title: s.title }) === 'Story');
+  if (stories.length === 0) return true;
+  const tgtIdx = STAGE_ORDER.indexOf(CODE_REVIEW_STAGE);
+  for (const st of stories) {
+    const itemId = await addProjectItem(projToken, project.id, st.nodeId);
+    const current = await getItemSingleSelectValue(projToken, itemId, etapaField.id).catch(() => null);
+    const idx = current ? STAGE_ORDER.indexOf(current) : -1;
+    if (idx === -1 || idx < tgtIdx) return false; // há Story pendente
+  }
+  return true;
+}
+
+// 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 }) {
@@ -116,17 +188,49 @@ export async function codeReview({ prNumber }) {
 
   const seen = new Set();
   const updated = [];
+  const featuresChecked = new Set();
 
+  // Para cada issue referenciada: move a Story + Tasks para Code Review. A
+  // Feature só avança quando TODAS as suas Stories já estiverem em Code Review.
   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 { feature, items } = await collectReviewUnit(token, owner, repo, num);
+
+    for (const [n, info] of items) {
+      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}`);
+      }
+    }
+
+    // Feature: só avança se todas as suas Stories já estão em Code Review+.
+    if (feature && !featuresChecked.has(feature.number)) {
+      featuresChecked.add(feature.number);
+      try {
+        const ready = await allStoriesReadyForReview(token, projectToken, project, etapaField, feature.nodeId);
+        if (!ready) {
+          console.log(`Feature #${feature.number} mantida em desenvolvimento — ainda há Stories pendentes (fora de "${CODE_REVIEW_STAGE}").`);
+        } else if (!seen.has(feature.number)) {
+          seen.add(feature.number);
+          const moved = await setCodeReview(projectToken, project, etapaField, statusField, feature.nodeId);
+          if (moved) {
+            updated.push(`#${feature.number} ${feature.title} (Feature)`);
+            console.log(`Feature #${feature.number} → "${CODE_REVIEW_STAGE}" (todas as Stories concluídas).`);
+          } else {
+            console.log(`Feature #${feature.number} já está em "${CODE_REVIEW_STAGE}" ou etapa posterior.`);
+          }
+        }
+      } catch (err) {
+        console.warn(`Falha ao avaliar a Feature #${feature.number}: ${err.message}`);
+      }
     }
   }
 
@@ -134,10 +238,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}** (a Feature só avança quando todas as suas Stories concluírem):\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, STAGE_IN_PROGRESS, STAGE_DONE, STAGE_CODE_REVIEW } 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';
@@ -23,7 +26,7 @@ async function resolveFeature(token, startNodeId) {
     const parent = await getIssueParent(token, current);
     if (!parent) return null;
     if (detectIssueType({ title: parent.title }) === 'Feature') {
-      return { number: parent.number, title: parent.title };
+      return { number: parent.number, title: parent.title, nodeId: parent.nodeId };
     }
     current = parent.nodeId;
   }
@@ -43,7 +46,7 @@ function readSpecPlan(featureDir) {
 }
 
 // Monta o markdown de contexto que será entregue ao spec-kit implement.
-function buildContext({ type, issue, tasks, feature, spec, plan, specPath, planPath }) {
+function buildContext({ type, issue, tasks, feature, siblingStories = [], spec, plan, specPath, planPath }) {
   const lines = [];
   lines.push(`# Contexto de implementação — ${type} #${issue.number}`);
   lines.push('');
@@ -53,46 +56,65 @@ function buildContext({ type, issue, tasks, feature, spec, plan, specPath, planP
     lines.push(issue.body.trim());
   }
 
-  // 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.
+  // 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 de execução (uma task por vez, sequencial)');
   lines.push('');
+  lines.push(
+    '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(
-      `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.'
+      `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. 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(`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 a implementação de TODA a Story** (todas as tasks em **${STAGE_DONE}**):`);
+    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. 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).`
+      `   3. **Avance a Etapa da Story #${issue.number} e de todas as suas ${tasks.length} Task(s) ` +
+      `(${tasks.map(t => `#${t.number}`).join(', ')}) para ${STAGE_CODE_REVIEW}**, reiniciando o Status ` +
+      `de cada uma para ${PROGRESS_TODO}. (Story e Tasks andam juntas.)`
     );
+    // A Feature só avança quando TODAS as suas Stories estiverem implementadas.
+    lines.push(`   4. **A Feature${feature ? ` #${feature.number}` : ' (issue pai da Story)'} só avança para ${STAGE_CODE_REVIEW} quando TODAS as suas Stories estiverem implementadas:**`);
+    if (siblingStories.length === 0) {
+      lines.push(`      - Esta é a **única Story** da Feature → avance também a Feature${feature ? ` #${feature.number}` : ''} para ${STAGE_CODE_REVIEW} (Status → ${PROGRESS_TODO}).`);
+    } else {
+      lines.push(`      - Outras Stories desta Feature: ${siblingStories.map(s => `#${s.number}`).join(', ')}.`);
+      lines.push(`      - Verifique a Etapa de cada uma. Avance a Feature para ${STAGE_CODE_REVIEW} **somente se TODAS** já estiverem em ${STAGE_CODE_REVIEW} (ou etapa posterior).`);
+      lines.push(`      - Se **qualquer** Story ainda estiver pendente (antes de ${STAGE_CODE_REVIEW}), **NÃO mova a Feature** — deixe-a em ${STAGE_DEVELOPMENT} até a última Story ser concluída.`);
+    }
   } else {
-    lines.push(`Implemente a Task #${issue.number} bracketando o status no GitHub Project:`);
+    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(`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(`> 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(
-    `> 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.'
+    `> **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('');
@@ -198,7 +220,7 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
   }
 
   // 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).
+  // instruções de fim de Story (avançar a Etapa para Code Review).
   const feature = await resolveFeature(token, issue.node_id);
   let featureDir = featureDirOpt;
   if (!featureDir && feature?.title) {
@@ -213,8 +235,19 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
     p.log.warn('Não foi possível resolver a Feature; seguindo só com as tasks (use --feature-dir).');
   }
 
+  // 4b. Stories irmãs da Feature — a Feature só avança para Code Review quando
+  // TODAS as suas Stories estiverem implementadas. Lista as outras para o agente
+  // verificar antes de mover a Feature.
+  let siblingStories = [];
+  if (type === 'Story' && feature?.nodeId) {
+    const featureSubs = await listSubIssues(token, feature.nodeId).catch(() => []);
+    siblingStories = featureSubs
+      .filter(s => detectIssueType({ title: s.title }) === 'Story' && s.number !== issue.number)
+      .map(s => ({ number: s.number, title: s.title }));
+  }
+
   // 5. Monta e grava o arquivo de contexto.
-  const context = buildContext({ type, issue, tasks, feature, ...specPlan });
+  const context = buildContext({ type, issue, tasks, feature, siblingStories, ...specPlan });
   mkdirSync(WORK_DIR, { recursive: true });
   const tasksFile = path.join(WORK_DIR, `implement-${issueNumber}.md`);
   writeFileSync(tasksFile, context);

package/src/commands/install-skill.mjs

@@ -12,16 +12,19 @@ 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',
@@ -84,7 +87,7 @@ 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: {}, frontmatter: '', body: raw.trim() };
   let meta = {};
@@ -102,12 +105,13 @@ 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 install-skill --force` para atualizá-la.'
+    '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.
-function renderContent(format, parsed, version) {
+export function renderContent(format, parsed, version) {
   const { meta, frontmatter, body } = parsed;
   const description = meta.description ?? 'Skill spec-wave.';
   const banner = versionBanner(version);
@@ -135,7 +139,7 @@ function renderContent(format, parsed, version) {
 
 // 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?`,
@@ -151,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;
@@ -161,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)));
 }
 

package/src/commands/qa.mjs

@@ -2,12 +2,12 @@ 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, 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';
 
 const QA_STAGE = STATUS_OPTIONS.find(s => s.name.includes('QA'))?.name;
-const TODO_STATUS = 'Todo';
+const TODO_STATUS = PROGRESS_TODO;
 
 function extractIssueNumbers(body) {
   if (!body) return [];
@@ -50,9 +50,17 @@ async function resolveFeatureIssue(token, owner, repo, issueNumber) {
   return null;
 }
 
+// Avança para a Etapa "🧪 QA" e reinicia o Status para "Todo". Uma issue só
+// AVANÇA: se já estiver em QA ou etapa posterior, não é tocada (retorna false).
 async function setQA(token, project, etapaField, statusField, nodeId) {
   const itemId = await addProjectItem(token, project.id, nodeId);
   if (etapaField?.id && QA_STAGE) {
+    const current = await getItemSingleSelectValue(token, itemId, etapaField.id).catch(() => null);
+    const curIdx = current ? STAGE_ORDER.indexOf(current) : -1;
+    const tgtIdx = STAGE_ORDER.indexOf(QA_STAGE);
+    if (curIdx !== -1 && tgtIdx !== -1 && curIdx >= tgtIdx) {
+      return false; // já está em QA ou adiante — não retrocede
+    }
     const optionId = etapaField.options?.[QA_STAGE];
     if (optionId) await setItemSingleSelect(token, project.id, itemId, etapaField.id, optionId);
   }
@@ -60,6 +68,7 @@ async function setQA(token, project, etapaField, statusField, nodeId) {
     const optionId = statusField.options?.[TODO_STATUS];
     if (optionId) await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
   }
+  return true;
 }
 
 export async function qa({ prNumber }) {
@@ -115,9 +124,13 @@ export async function qa({ prNumber }) {
     if (!feature || seen.has(feature.number)) continue;
     seen.add(feature.number);
     try {
-      await setQA(projectToken, project, etapaField, statusField, feature.node_id);
-      updated.push(`#${feature.number} ${feature.title}`);
-      console.log(`Feature #${feature.number} → "${QA_STAGE}" / Status "${TODO_STATUS}".`);
+      const moved = await setQA(projectToken, project, etapaField, statusField, feature.node_id);
+      if (moved) {
+        updated.push(`#${feature.number} ${feature.title}`);
+        console.log(`Feature #${feature.number} → "${QA_STAGE}" / Status "${TODO_STATUS}".`);
+      } else {
+        console.log(`Feature #${feature.number} já está em "${QA_STAGE}" ou etapa posterior — mantida (não retrocede).`);
+      }
     } catch (err) {
       console.warn(`Falha ao atualizar Feature #${feature.number}: ${err.message}`);
     }

package/src/commands/update.mjs

@@ -0,0 +1,300 @@
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { resolveToken } from '../api/auth.mjs';
+import { CONFIG_FILE, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES, ALL_LABELS } from '../config.mjs';
+import { getProjectSnapshot } from '../api/github-graphql.mjs';
+import {
+  getFileContent, upsertFile, listLabels, createLabel, updateLabel,
+} from '../api/github-rest.mjs';
+import {
+  TARGETS, SKILL_SOURCE, CLI_VERSION, parseSkill, renderContent,
+  mergeAgentsFile, resolveDest, isDetected, extractAgentsBlock,
+} from './install-skill.mjs';
+
+const __dir = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(__dir, '..', 'templates');
+function readTemplate(...parts) {
+  return readFileSync(path.join(TEMPLATES_DIR, ...parts), 'utf-8');
+}
+
+// Arquivos do repo gerenciados pela CLI (comparados com o template empacotado).
+const REPO_FILES = [
+  ...WORKFLOW_FILES.map(f => ({ repoPath: `.github/workflows/${f}`, template: ['workflows', f] })),
+  ...ISSUE_TEMPLATE_FILES.map(f => ({ repoPath: `.github/ISSUE_TEMPLATE/${f}`, template: ['issue', f] })),
+];
+
+// Detecta se a skill instalada em cada agente diverge da versão atual da CLI.
+// Retorna os alvos desatualizados (conteúdo diferente ou ausente).
+function detectSkill(parsed, baseDir, isGlobal) {
+  const jobs = [];
+  for (const target of TARGETS) {
+    if (!isDetected(target, baseDir)) continue;
+    const dest = resolveDest(target, baseDir, isGlobal);
+    if (!dest) continue;
+    const desired = renderContent(dest.format, parsed, CLI_VERSION);
+    const existing = existsSync(dest.path) ? readFileSync(dest.path, 'utf-8') : null;
+    let reason = null;
+    if (existing === null) {
+      reason = 'ausente';
+    } else if (dest.format === 'agents') {
+      const block = extractAgentsBlock(existing);
+      if (block === null) reason = 'bloco ausente';
+      else if (block.trim() !== desired.trim()) reason = 'desatualizada';
+    } else if (existing !== desired) {
+      reason = 'desatualizada';
+    }
+    if (reason) jobs.push({ target, dest, desired, reason });
+  }
+  return jobs;
+}
+
+// Aplica a atualização de uma skill (grava o arquivo / faz merge no AGENTS.md).
+function applySkill(job) {
+  const content = job.dest.format === 'agents'
+    ? mergeAgentsFile(job.dest.path, job.desired)
+    : job.desired;
+  mkdirSync(path.dirname(job.dest.path), { recursive: true });
+  writeFileSync(job.dest.path, content, 'utf-8');
+}
+
+// Compara ALL_LABELS com as labels do repo. color no config é hex maiúsculo; a
+// API retorna minúsculo — daí o toLowerCase() na comparação.
+function diffLabels(existing) {
+  const byName = new Map(existing.map(l => [l.name, l]));
+  const missing = [];
+  const changed = [];
+  for (const label of ALL_LABELS) {
+    const cur = byName.get(label.name);
+    if (!cur) {
+      missing.push(label);
+    } else if (
+      cur.color.toLowerCase() !== label.color.toLowerCase() ||
+      (cur.description || '') !== (label.description || '')
+    ) {
+      changed.push(label);
+    }
+  }
+  return { missing, changed };
+}
+
+export async function update(options = {}) {
+  p.intro(chalk.bold(`spec-wave update (CLI v${CLI_VERSION})`));
+
+  const isGlobal = !!options.global;
+  const baseDir = isGlobal ? homedir() : process.cwd();
+
+  // ---------- Detecção ----------
+  // 1) Skill (por agente detectado).
+  const parsed = parseSkill(readFileSync(SKILL_SOURCE, 'utf-8'));
+  const skillJobs = options.skipSkill ? [] : detectSkill(parsed, baseDir, isGlobal);
+
+  // 2) Config + repo dependem do .spec-wave.json local do repo atual.
+  const configPath = path.join(process.cwd(), CONFIG_FILE);
+  let config = null;
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    } catch (err) {
+      p.log.warn(`${CONFIG_FILE} corrompido (${err.message}); pulando config/repo.`);
+    }
+  }
+
+  const doConfig = !options.skipConfig && !!config;
+  const doRepo = !options.skipRepo && !!config?.owner && !!config?.repo;
+
+  // Token resolvido sob demanda (necessário só para repo/config remoto).
+  let token;
+  let tokenError;
+  async function getToken() {
+    if (token || tokenError) return token;
+    try {
+      token = await resolveToken();
+    } catch (err) {
+      tokenError = err;
+    }
+    return token;
+  }
+
+  // 2a) Config desatualizado? (versão divergente ou formato legado).
+  let configStale = null;
+  if (doConfig) {
+    const legacy = !config.project?.fields;
+    if (config.version !== CLI_VERSION || legacy) {
+      configStale = {
+        reason: legacy ? 'formato legado (sem project.fields)' : `versão ${config.version ?? '?'} ≠ ${CLI_VERSION}`,
+        canApply: !!config.project?.id,
+      };
+    }
+  }
+
+  // 2b) Arquivos do repo e labels divergentes (exige token + rede).
+  let repoFiles = [];
+  let labelDiff = { missing: [], changed: [] };
+  let repoChecked = false;
+  if (doRepo) {
+    const s = p.spinner();
+    s.start('Comparando arquivos e labels do repositório...');
+    const tk = await getToken();
+    if (!tk) {
+      s.stop('');
+      p.log.warn(`Sem token do GitHub (${tokenError?.message ?? 'indisponível'}); pulando verificação do repo.`);
+    } else {
+      const { owner, repo } = config;
+      try {
+        for (const f of REPO_FILES) {
+          const remote = await getFileContent(tk, owner, repo, f.repoPath);
+          const local = readTemplate(...f.template);
+          if (remote === null) repoFiles.push({ ...f, reason: 'ausente', local });
+          else if (remote !== local) repoFiles.push({ ...f, reason: 'desatualizado', local });
+        }
+        labelDiff = diffLabels(await listLabels(tk, owner, repo));
+        repoChecked = true;
+        s.stop('Repositório comparado.');
+      } catch (err) {
+        s.stop('');
+        p.log.warn(`Falha ao comparar o repo: ${err.message}`);
+      }
+    }
+  }
+
+  // ---------- Resumo ----------
+  const labelTotal = labelDiff.missing.length + labelDiff.changed.length;
+  const total = skillJobs.length + (configStale ? 1 : 0) + repoFiles.length + labelTotal;
+
+  if (total === 0) {
+    p.log.success('Tudo já está atualizado para a versão atual da CLI.');
+    p.outro('Nada a fazer.');
+    return;
+  }
+
+  const lines = [];
+  if (skillJobs.length) {
+    lines.push(chalk.bold('Skill:'));
+    for (const j of skillJobs) lines.push(`  ${chalk.yellow('↻')} ${j.target.name} (${j.reason})\n     ${chalk.dim(j.dest.path)}`);
+  }
+  if (configStale) {
+    lines.push(chalk.bold('Config local:'));
+    lines.push(`  ${chalk.yellow('↻')} ${CONFIG_FILE} — ${configStale.reason}` +
+      (configStale.canApply ? '' : chalk.dim(' (sem project.id — rode `init` sem --skip-project)')));
+  }
+  if (repoFiles.length) {
+    lines.push(chalk.bold('Arquivos do repo:'));
+    for (const f of repoFiles) lines.push(`  ${chalk.yellow('↻')} ${f.repoPath} (${f.reason})`);
+  }
+  if (labelTotal) {
+    lines.push(chalk.bold('Labels:'));
+    if (labelDiff.missing.length) lines.push(`  ${chalk.yellow('+')} criar: ${labelDiff.missing.map(l => l.name).join(', ')}`);
+    if (labelDiff.changed.length) lines.push(`  ${chalk.yellow('↻')} atualizar: ${labelDiff.changed.map(l => l.name).join(', ')}`);
+  }
+  p.note(lines.join('\n'), `${total} item(ns) desatualizado(s)`);
+
+  if (options.dryRun) {
+    p.outro('Dry-run: nada foi alterado.');
+    return;
+  }
+
+  if (!options.yes) {
+    const ok = await p.confirm({ message: `Aplicar as ${total} atualização(ões)?`, initialValue: true });
+    if (p.isCancel(ok) || !ok) {
+      p.cancel('Update cancelado.');
+      return;
+    }
+  }
+
+  // ---------- Aplicação ----------
+  // Skill
+  for (const job of skillJobs) {
+    try {
+      applySkill(job);
+      p.log.success(`Skill atualizada: ${job.target.name}`);
+    } catch (err) {
+      p.log.error(`Falha ao atualizar skill (${job.target.name}): ${err.message}`);
+    }
+  }
+
+  // Config (.spec-wave.json) — reconsulta o Project e reescreve local.
+  if (configStale) {
+    if (!configStale.canApply) {
+      p.log.warn(`${CONFIG_FILE}: sem project.id — pulei. Rode \`npx @spec-wave/cli init\` (sem --skip-project).`);
+    } else {
+      const tk = await getToken();
+      if (!tk) {
+        p.log.warn(`${CONFIG_FILE}: sem token — pulei. (${tokenError?.message ?? ''})`);
+      } else {
+        const s = p.spinner();
+        s.start('Atualizando .spec-wave.json...');
+        try {
+          const snapshot = await getProjectSnapshot(tk, config.project.id);
+          if (!snapshot) throw new Error('Project não encontrado');
+          const { etapaFieldId: _e, stageOptions: _s, ...projectRest } = config.project;
+          const updated = {
+            ...config,
+            version: CLI_VERSION,
+            project: {
+              ...projectRest,
+              title: snapshot.title,
+              url: snapshot.url,
+              id: snapshot.id,
+              number: snapshot.number,
+              fields: snapshot.fields,
+            },
+            refreshedAt: new Date().toISOString(),
+          };
+          writeFileSync(configPath, JSON.stringify(updated, null, 2) + '\n');
+          s.stop(`${CONFIG_FILE} atualizado (v${CLI_VERSION}).`);
+        } catch (err) {
+          s.stop('');
+          p.log.error(`Falha ao atualizar ${CONFIG_FILE}: ${err.message}`);
+        }
+      }
+    }
+  }
+
+  // Arquivos do repo
+  if (repoFiles.length) {
+    const tk = await getToken();
+    const { owner, repo } = config;
+    for (const f of repoFiles) {
+      try {
+        await upsertFile(tk, owner, repo, f.repoPath, f.local, `chore: update ${path.basename(f.repoPath)} [spec-wave]`);
+        p.log.success(`Arquivo atualizado no repo: ${f.repoPath}`);
+      } catch (err) {
+        p.log.error(`Falha ao atualizar ${f.repoPath}: ${err.message}`);
+      }
+    }
+  }
+
+  // Labels
+  if (labelTotal) {
+    const tk = await getToken();
+    const { owner, repo } = config;
+    for (const label of labelDiff.missing) {
+      try {
+        await createLabel(tk, owner, repo, label);
+        p.log.success(`Label criada: ${label.name}`);
+      } catch (err) {
+        p.log.error(`Falha ao criar label ${label.name}: ${err.message}`);
+      }
+    }
+    for (const label of labelDiff.changed) {
+      try {
+        await updateLabel(tk, owner, repo, label);
+        p.log.success(`Label atualizada: ${label.name}`);
+      } catch (err) {
+        p.log.error(`Falha ao atualizar label ${label.name}: ${err.message}`);
+      }
+    }
+  }
+
+  const committedRepo = repoFiles.length > 0;
+  p.outro(
+    'Update concluído.' +
+    (skillJobs.length ? ' Recarregue o agente para pegar a skill nova.' : '') +
+    (configStale?.canApply ? ` Faça commit do ${CONFIG_FILE}.` : '') +
+    (committedRepo ? ' Arquivos do repo foram commitados no remoto.' : '')
+  );
+}

package/src/config.mjs

@@ -51,13 +51,22 @@ export const STATUS_OPTIONS = [
   { name: '🎉 Done',            color: 'GREEN'  },
 ];
 
-// Etapas usadas pelo fluxo de implementação (comando `implement`): cada task vai
-// para "In Progress" ao INICIAR seu desenvolvimento e para "Done" ao concluir;
-// ao final da Story, Feature + Story vão para "Code Review" (após commit + PR).
-// Resolvidas por nome para não quebrar se a ordem/cor das opções mudar.
-export const STAGE_IN_PROGRESS = STATUS_OPTIONS.find(s => s.name.includes('Desenvolvimento')).name;
-export const STAGE_DONE = STATUS_OPTIONS.find(s => s.name.includes('Done')).name;
+// ⚠️ Dois campos DISTINTOS no board (não confundir):
+//  • "Etapa" (campo custom = as opções de STATUS_OPTIONS acima): as colunas do
+//    kanban. Determina a DIREÇÃO do fluxo — uma issue só AVANÇA, nunca volta.
+//  • "Status" (campo nativo: Todo/In Progress/Done): o PROGRESSO dentro da etapa
+//    atual. Ao avançar de etapa, o Status reinicia em "Todo".
+
+// Etapas (campo Etapa) referenciadas pelo fluxo de implementação.
+export const STAGE_DEVELOPMENT = STATUS_OPTIONS.find(s => s.name.includes('Desenvolvimento')).name;
 export const STAGE_CODE_REVIEW = STATUS_OPTIONS.find(s => s.name.includes('Code Review')).name;
+// Ordem canônica das etapas — usada para garantir que uma issue só AVANÇA.
+export const STAGE_ORDER = STATUS_OPTIONS.map(s => s.name);
+
+// Valores do campo nativo "Status" (progresso dentro da etapa).
+export const PROGRESS_TODO = 'Todo';
+export const PROGRESS_IN_PROGRESS = 'In Progress';
+export const PROGRESS_DONE = 'Done';
 
 export const CUSTOM_FIELDS = [
   {

package/src/templates/skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: spec-wave
 description: "Use when the user wants to set up a spec-driven GitHub workflow, create a Feature issue, generate spec.md or plan.md, decompose a Feature into Stories/Tasks, write RFC documentation, or audit and fix a Pull Request. Implements the RFC-001 workflow with GitHub Projects v2, labels, and AI-powered GitHub Actions."
-argument-hint: "[info|setup|issue|feature|spec|plan|ready|decompose|implement|uninstall|rfc|fix-pr] [target]"
+argument-hint: "[info|setup|update|issue|feature|spec|plan|ready|decompose|implement|uninstall|rfc|fix-pr] [target]"
 user-invocable: true
 allowed-tools:
   - Bash(npx @spec-wave/cli *)
@@ -27,7 +27,7 @@ Este skill guia o usuário pelo fluxo spec-driven definido no RFC-001.
 
 > **Antes de responder a qualquer sub-comando**, leia o arquivo `rfc/rfc-integrate-spec-kit-into-kanban.md` se ele existir no diretório atual, para embasar suas respostas no processo real da equipe.
 
-> **Verifique se esta skill está atualizada:** logo no topo deste arquivo há um banner `spec-wave skill vX.Y.Z` (inserido na instalação). Compare com `npx @spec-wave/cli --version`. Se a CLI for **mais recente**, esta skill está desatualizada — avise o usuário e sugira rodar `npx @spec-wave/cli install-skill --force` para atualizá-la (a skill é uma cópia estática e **não** acompanha o `npx` sozinha). Se o banner estiver ausente, a skill foi instalada por uma versão antiga: sugira a mesma atualização.
+> **Verifique se esta skill está atualizada:** logo no topo deste arquivo há um banner `spec-wave skill vX.Y.Z` (inserido na instalação). Compare com `npx @spec-wave/cli --version`. Se a CLI for **mais recente** (ou o banner estiver ausente = instalada por versão antiga), esta skill está desatualizada — avise o usuário e sugira `npx @spec-wave/cli update` (detecta e atualiza só o que mudou: skill, `.spec-wave.json` e workflows/labels do repo) ou, para atualizar só a skill, `npx @spec-wave/cli install-skill --force`. A skill é uma cópia estática e **não** acompanha o `npx` sozinha.
 
 ---
 
@@ -142,6 +142,16 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 
 > Use quando o `.spec-wave.json` estiver desatualizado: repos inicializados por uma versão antiga (sem `etapaFieldId`/`stageOptions`), Project renomeado, ou versão da CLI divergente. Escreve no arquivo **local** — faça commit depois.
 
+### `@spec-wave/cli update` — atualiza tudo que ficou para trás (só o que mudou)
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--global` | flag | Verifica a skill no escopo do usuário (padrão: projeto). |
+| `--skip-skill` / `--skip-config` / `--skip-repo` | flag | Pula a categoria correspondente. |
+| `--dry-run` | flag | Mostra o que seria atualizado sem alterar nada. |
+| `--yes` | flag | Aplica sem pedir confirmação. |
+
+> Detecta e atualiza **somente o que divergiu** da versão atual da CLI: a **skill** instalada (por agente), o **`.spec-wave.json`** local (se versão/formato divergir) e os **workflows/labels** do repo (compara com os templates empacotados). Interativo por padrão (mostra o plano e confirma). É o atalho recomendado após atualizar a CLI.
+
 ### `@spec-wave/cli generate-plan` · `generate-spec` · `validate` · `decompose`
 | Flag | Tipo | Descrição |
 |------|------|-----------|
@@ -156,7 +166,7 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 | `--feature-dir <path>` | string | Caminho `docs/features/<slug>` para anexar `spec.md`/`plan.md` como contexto (sobrescreve a resolução automática). |
 | `--dry-run` | flag | Monta o contexto e imprime o comando do spec-kit **sem executar**. |
 
-> Diferente dos quatro acima, `implement` roda **localmente** (lê `.spec-wave.json`, como `issue`), não por Action. Detecta o tipo da issue: **Story** → coleta todas as Tasks (sub-issues) e aciona o spec-kit uma única vez; **Task** → só aquela task. Monta o contexto em `.spec-wave/implement-<n>.md` e chama o comando configurado em `specKit.command` (no `.spec-wave.json`) ou na env `SPEC_WAVE_IMPLEMENT_CMD`. Placeholders disponíveis no template: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`. Se nada estiver configurado, ele apenas monta o contexto e mostra como configurar (não executa). O contexto inclui instruções para o agente implementar as Tasks **sequencialmente, uma por vez**: mover a task para **🚧 Desenvolvimento** só ao iniciá-la e para **🎉 Done** ao concluí-la, antes de passar para a próxima (nunca todas em "in progress" ao mesmo tempo). **Ao concluir toda a Story**: fazer o commit, abrir o PR e mover a **Feature** e a **Story** para **👀 Code Review** (as Tasks permanecem em 🎉 Done).
+> Diferente dos quatro acima, `implement` roda **localmente** (lê `.spec-wave.json`, como `issue`), não por Action. Detecta o tipo da issue: **Story** → coleta todas as Tasks (sub-issues) e aciona o spec-kit uma única vez; **Task** → só aquela task. Monta o contexto em `.spec-wave/implement-<n>.md` e chama o comando configurado em `specKit.command` (no `.spec-wave.json`) ou na env `SPEC_WAVE_IMPLEMENT_CMD`. Placeholders disponíveis no template: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`. Se nada estiver configurado, ele apenas monta o contexto e mostra como configurar (não executa). O contexto inclui instruções para o agente implementar as Tasks **sequencialmente, uma por vez**, usando o campo **Status** (Todo → In Progress → Done) para o progresso *dentro* da Etapa 🚧 Desenvolvimento — sem trocar a Etapa das tasks (nunca duas com Status "In Progress" ao mesmo tempo). **Ao concluir toda a Story**: fazer o commit, abrir o PR e **avançar a Etapa** da **Story e de todas as suas Tasks** para **👀 Code Review** (Status → Todo). A **Feature só avança** para Code Review quando **TODAS as suas Stories** já estiverem em Code Review — enquanto houver Story pendente, a Feature fica em 🚧 Desenvolvimento. Etapa só avança (nunca volta); Status mede o progresso dentro da etapa.
 
 ---
 
@@ -175,6 +185,26 @@ Mostra se o repositório atual já foi configurado com o spec-wave.
 
 ---
 
+### `/spec-wave update`
+
+Traz tudo para a versão atual da CLI, atualizando **só o que mudou**: a skill instalada, o `.spec-wave.json` local e os workflows/labels do repo.
+
+**Passos:**
+1. **Sempre comece com `--dry-run`** para inspecionar o que está desatualizado sem alterar nada:
+   ```bash
+   npx @spec-wave/cli update --dry-run
+   ```
+2. Mostre ao usuário o resumo (skill / config / arquivos do repo / labels que divergiram). Se **nada** estiver desatualizado, informe que já está tudo na versão atual e encerre.
+3. Se o usuário aprovar, aplique:
+   ```bash
+   npx @spec-wave/cli update --yes
+   ```
+   - Escopos podem ser limitados com `--skip-skill`, `--skip-config`, `--skip-repo`.
+   - Atualizações de **arquivos do repo** são commitadas no remoto; o **`.spec-wave.json`** é local (lembre o usuário de commitá-lo).
+4. Se a skill foi atualizada, oriente recarregar/reiniciar o agente para pegar a nova versão.
+
+---
+
 ### `/spec-wave setup`
 
 Configura o spec-wave no repositório. Você dirige o `init` com flags — **nunca rode `npx @spec-wave/cli init` sem `--repo`** (abre o wizard interativo que você não controla).
@@ -366,7 +396,7 @@ Aciona o spec-kit para implementar uma **Story** (todas as suas Tasks) ou uma **
    npx @spec-wave/cli implement <número> --dry-run
    ```
 3. Mostre ao usuário o contexto montado em `.spec-wave/implement-<número>.md` e o comando. Esse arquivo contém as **instruções de execução sequencial**: implemente as Tasks **uma por vez** — mova a task para **🚧 Desenvolvimento** só ao iniciá-la e para **🎉 Done** ao concluí-la, antes de passar para a próxima. **Nunca** coloque várias tasks em "in progress" ao mesmo tempo.
-4. **Se você (agente) for implementar diretamente** (sem `specKit.command`): siga o contexto task por task, na ordem listada, respeitando o ciclo In Progress → implementar → Done de cada task antes da seguinte. Atualize o campo "Etapa" do item no board via `gh`. **Ao concluir toda a Story**: faça o commit, abra o PR e mova a **Feature** e a **Story** para **👀 Code Review** (as Tasks ficam em 🎉 Done).
+4. **Se você (agente) for implementar diretamente** (sem `specKit.command`): siga o contexto task por task. Para cada task, use o campo **Status** (In Progress ao começar → Done ao concluir) *dentro* da Etapa 🚧 Desenvolvimento — não troque a Etapa da task. Atualize os campos via `gh`. **Ao concluir toda a Story**: faça o commit, abra o PR e **avance a Etapa** da **Story e de todas as suas Tasks** para **👀 Code Review** (Status → Todo). A **Feature só avança** quando **TODAS as suas Stories** já estiverem em Code Review — se houver Story pendente, deixe a Feature em 🚧 Desenvolvimento. Lembre: Etapa só avança (nunca volta); Status é o progresso dentro da etapa.
 5. Se o usuário aprovar e o spec-kit estiver configurado, rode sem `--dry-run`:
    ```bash
    npx @spec-wave/cli implement <número>
@@ -374,7 +404,7 @@ Aciona o spec-kit para implementar uma **Story** (todas as suas Tasks) ou uma **
    - Se o spec-kit **não** estiver configurado, o comando só monta o contexto e mostra como configurar (`specKit.command` / `SPEC_WAVE_IMPLEMENT_CMD`). Ajude o usuário a definir o template (placeholders: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`).
    - Use `--feature-dir docs/features/<slug>` se a resolução automática da Feature falhar (a skill avisa com warning) e você quiser anexar `spec.md`/`plan.md` como contexto.
 6. Se a issue **não** for Story nem Task (ex.: Feature, Bug), o comando recusa — oriente o usuário: Features se decompõem (`/spec-wave decompose`); implemente as Stories/Tasks resultantes.
-7. Ao final (Story implementada, commit feito, PR aberto e Feature/Story em **👀 Code Review**): confirme o resultado com o usuário e oriente a revisão do PR.
+7. Ao final (Story + Tasks em **👀 Code Review**; a Feature só vai para Code Review quando a última Story concluir): confirme o resultado com o usuário e oriente a revisão do PR.
 
 ---