@spec-wave/cli 0.7.1 → 0.8.1

package/README.md

@@ -72,7 +72,7 @@ Ferramenta Node.js que configura e opera o fluxo via linha de comando.
 | `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 |
+| `implement` | Aciona o spec-kit localmente para implementar uma Feature (Stories pendentes em ordem de dependência), Story ou Task |
 | `uninstall` | Remove labels, workflows e `.spec-wave.json` |
 
 ### GitHub Actions (instalados pelo `init`)

package/bin/spec-wave.mjs

@@ -184,8 +184,8 @@ program
 
 program
   .command('implement')
-  .description('Aciona o spec-kit implement para uma Story (todas as tasks) ou uma Task')
-  .argument('<issue>', 'Número da issue (Story ou Task), ex.: 12 ou #12')
+  .description('Aciona o spec-kit implement para uma Feature (Stories pendentes em ordem de dependência), uma Story (todas as tasks) ou uma Task')
+  .argument('<issue>', 'Número da issue (Feature, Story ou Task), ex.: 12 ou #12')
   .option('--feature-dir <path>', 'Caminho do docs/features/<slug> (sobrescreve a resolução automática)')
   .option('--dry-run', 'Monta o contexto e imprime o comando sem executar o spec-kit')
   .action(async (issue, options) => {

package/package.json

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

package/src/commands/decompose.mjs

@@ -1,8 +1,8 @@
 import { existsSync, readFileSync } from 'node:fs';
-import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, createIssue, removeLabel, addLabel, commentOnIssue, addBlockedBy } from '../api/github-rest.mjs';
-import { addSubIssue, addProjectItem, setItemSingleSelect, getSingleSelectField, listSubIssues } from '../api/github-graphql.mjs';
+import { addSubIssue, listSubIssues } from '../api/github-graphql.mjs';
+import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
 import { generateDocument } from '../lib/claude.mjs';
 import { runCritique } from '../lib/critique.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
@@ -10,34 +10,13 @@ import { formatDependencyLine } from '../lib/dependencies.mjs';
 import { lintLanguage } from '../lib/output-lint.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
-import { CONFIG_FILE, DECOMPOSE_TARGETS, LABEL_DECOMPOSED, LABEL_CRITIQUE_FAILED, TARGET_LANGUAGE } from '../config.mjs';
+import { DECOMPOSE_TARGETS, LABEL_DECOMPOSED, LABEL_CRITIQUE_FAILED, TARGET_LANGUAGE, STAGE_READY, PROGRESS_TODO } from '../config.mjs';
 
-const READY_STAGE = 'Todo';
-
-// Carrega o projeto do .spec-wave.json. Retorna null se ausente ou sem project.id.
-function loadProject() {
-  const configPath = path.join(process.cwd(), CONFIG_FILE);
-  if (!existsSync(configPath)) return null;
-  try {
-    return JSON.parse(readFileSync(configPath, 'utf-8')).project || null;
-  } catch {
-    return null;
-  }
-}
-
-// Resolve o campo Status do Project: usa .spec-wave.json ou consulta API.
-async function resolveStatusField(token, project) {
-  if (project.fields?.Status) return project.fields.Status;
-  return await getSingleSelectField(token, project.id, 'Status');
-}
-
-// Adiciona issue ao board e move para a etapa informada. Best-effort.
-async function moveToStage(token, project, statusField, nodeId, stageName) {
-  if (!project?.id || !statusField) return;
-  const optionId = statusField.options?.[stageName];
-  if (!statusField.id || !optionId) return;
-  const itemId = await addProjectItem(token, project.id, nodeId);
-  await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
+// Adiciona a issue ao board na Etapa ✅ Ready / Status Todo. Best-effort; a
+// Etapa nunca retrocede (advanceToStage não toca itens já adiante).
+async function moveToReady(token, project, etapaField, statusField, nodeId) {
+  if (!project?.id) return;
+  await advanceToStage(token, project, etapaField, statusField, nodeId, STAGE_READY, PROGRESS_TODO);
 }
 
 // Extrai JSON da resposta do modelo (tolera texto em volta).
@@ -149,7 +128,7 @@ Regras:
 
 // Decompõe uma Feature em Stories (+ Tasks), cada uma vinculada como sub-issue.
 async function decomposeFeature(ctx) {
-  const { token, projectToken, owner, repo, issue, issueNumber, project, statusField, usage } = ctx;
+  const { token, projectToken, owner, repo, issue, issueNumber, project, etapaField, statusField, usage } = ctx;
   const slug = slugify(issue.title);
   const featureDir = `docs/features/${slug}`;
 
@@ -243,9 +222,9 @@ async function decomposeFeature(ctx) {
       console.warn(`  Story #${createdStory.number} criada, mas falhou ao vincular à Feature: ${err.message}`);
     }
     try {
-      await moveToStage(projectToken, project, statusField, createdStory.nodeId, READY_STAGE);
+      await moveToReady(projectToken, project, etapaField, statusField, createdStory.nodeId);
     } catch (err) {
-      console.warn(`  Falha ao mover story #${createdStory.number} para "${READY_STAGE}": ${err.message}`);
+      console.warn(`  Falha ao mover story #${createdStory.number} para "${STAGE_READY}": ${err.message}`);
     }
 
     for (const task of story.tasks || []) {
@@ -260,18 +239,18 @@ async function decomposeFeature(ctx) {
         console.warn(`    Task #${createdTask.number} criada, mas falhou ao vincular à Story: ${err.message}`);
       }
       try {
-        await moveToStage(projectToken, project, statusField, createdTask.nodeId, READY_STAGE);
+        await moveToReady(projectToken, project, etapaField, statusField, createdTask.nodeId);
       } catch (err) {
-        console.warn(`    Falha ao mover task #${createdTask.number} para "${READY_STAGE}": ${err.message}`);
+        console.warn(`    Falha ao mover task #${createdTask.number} para "${STAGE_READY}": ${err.message}`);
       }
     }
   }
 
   try {
-    await moveToStage(projectToken, project, statusField, featureNodeId, READY_STAGE);
-    if (project?.id && statusField) console.log(`Feature movida para "${READY_STAGE}" no board.`);
+    await moveToReady(projectToken, project, etapaField, statusField, featureNodeId);
+    if (project?.id && etapaField) console.log(`Feature movida para "${STAGE_READY}" no board.`);
   } catch (err) {
-    console.warn(`Falha ao mover Feature para "${READY_STAGE}": ${err.message}`);
+    console.warn(`Falha ao mover Feature para "${STAGE_READY}": ${err.message}`);
   }
 
   // Marca a Feature como decomposta (guard de idempotência em runs futuros).
@@ -295,7 +274,7 @@ async function decomposeFeature(ctx) {
 // Decompõe um RFC diretamente em Tasks (sem Stories), cada uma vinculada como
 // sub-issue do RFC.
 async function decomposeRFC(ctx) {
-  const { token, projectToken, owner, repo, issue, issueNumber, project, statusField, usage } = ctx;
+  const { token, projectToken, owner, repo, issue, issueNumber, project, etapaField, statusField, usage } = ctx;
   console.log(`Decompondo RFC: ${issue.title}`);
 
   const userContent = [
@@ -324,9 +303,9 @@ async function decomposeRFC(ctx) {
       console.warn(`  Task #${createdTask.number} criada, mas falhou ao vincular ao RFC: ${err.message}`);
     }
     try {
-      await moveToStage(projectToken, project, statusField, createdTask.nodeId, READY_STAGE);
+      await moveToReady(projectToken, project, etapaField, statusField, createdTask.nodeId);
     } catch (err) {
-      console.warn(`  Falha ao mover task #${createdTask.number} para "${READY_STAGE}": ${err.message}`);
+      console.warn(`  Falha ao mover task #${createdTask.number} para "${STAGE_READY}": ${err.message}`);
     }
   }
 
@@ -399,12 +378,19 @@ export async function decompose({ issueNumber }) {
     return;
   }
 
-  // Projeto + campo Status (reutilizado em todos os itens).
-  const project = loadProject();
+  // Projeto + campos Etapa/Status do board (reutilizados em todos os itens).
+  const { project, error: projectError } = loadProjectConfig();
+  if (projectError) console.warn(`${projectError} — itens criados não serão posicionados no board.`);
+  let etapaField = null;
   let statusField = null;
   if (project?.id) {
     try {
-      statusField = await resolveStatusField(projectToken, project);
+      etapaField = await resolveField(projectToken, project, 'Etapa');
+    } catch (err) {
+      console.warn(`Não foi possível resolver campo Etapa do board: ${err.message}`);
+    }
+    try {
+      statusField = await resolveField(projectToken, project, 'Status');
     } catch (err) {
       console.warn(`Não foi possível resolver campo Status do board: ${err.message}`);
     }
@@ -413,7 +399,7 @@ export async function decompose({ issueNumber }) {
   // Coletor de uso de IA — o finally registra o custo já incorrido mesmo nos
   // fluxos que retornam cedo (ex.: abort da crítica grave) ou que falham.
   const usageEntries = [];
-  const ctx = { token, projectToken, owner, repo, issue, issueNumber, project, statusField, usage: usageEntries };
+  const ctx = { token, projectToken, owner, repo, issue, issueNumber, project, etapaField, statusField, usage: usageEntries };
   try {
     if (type === 'Feature') await decomposeFeature(ctx);
     else if (type === 'RFC') await decomposeRFC(ctx);

package/src/commands/doctor.mjs

@@ -333,6 +333,37 @@ async function checkAi(ctx) {
   return { name, status, detail: notes.join('\n') };
 }
 
+// Exportado para teste: só lê ctx.cfg e process.env — sem rede/filesystem.
+export function checkSpecKit(ctx) {
+  const name = 'Spec-kit (specKit.command para o implement)';
+  const fromEnv = process.env.SPEC_WAVE_IMPLEMENT_CMD;
+  const fromConfig = ctx.cfg?.specKit?.command;
+  if (fromEnv) {
+    return {
+      name,
+      status: 'ok',
+      detail: `Definido via env SPEC_WAVE_IMPLEMENT_CMD${fromConfig ? ' (sobrepõe o specKit.command do config)' : ''}: ${fromEnv}`,
+    };
+  }
+  if (fromConfig) {
+    return { name, status: 'ok', detail: `Definido no ${CONFIG_FILE}: ${fromConfig}` };
+  }
+  return {
+    name,
+    status: 'warn',
+    detail:
+      'Nenhum comando configurado — `implement` só monta o contexto, sem acionar um agente.\n' +
+      `Defina "specKit": { "command": "..." } no ${CONFIG_FILE} (ou a env SPEC_WAVE_IMPLEMENT_CMD).\n` +
+      'Placeholders: {tasksFile} {specFile} {planFile} {issue} {type} {title}. Exemplos por agente:\n' +
+      '  Claude Code: claude -p "Implemente as tasks descritas em {tasksFile}"\n' +
+      '  opencode:    opencode run "Implemente as tasks descritas em {tasksFile}"\n' +
+      '  Codex:       codex exec "Implemente as tasks descritas em {tasksFile}"\n' +
+      '  Copilot CLI: copilot -p "Implemente as tasks descritas em {tasksFile}" --allow-all-tools\n' +
+      '  Kiro CLI:    kiro-cli chat --no-interactive --trust-all-tools "Implemente as tasks descritas em {tasksFile}"\n' +
+      '  Qwen Code:   qwen -p "Implemente as tasks descritas em {tasksFile}"',
+  };
+}
+
 async function checkWorkflows(ctx) {
   const name = 'Workflows do Actions';
   const dir = path.join(ctx.cwd, '.github', 'workflows');
@@ -380,6 +411,7 @@ export async function doctor() {
     checkConfig,
     checkRepoAccess,
     checkAi,
+    checkSpecKit,
     checkWorkflows,
   ];
   const results = [];

package/src/commands/generate-plan.mjs

@@ -27,6 +27,7 @@ O plano deve conter EXATAMENTE estas seções em português, nesta ordem:
 # Estratégia Técnica
   - Abordagem Arquitetural, Decisões-Chave e uma Matriz de Rastreabilidade (tabela) ligando cada Critério de Aceite do spec a um componente técnico.
 # Detalhamento da Implementação
+  - Abra a seção com um diagrama de sequência Mermaid (bloco \`\`\`mermaid iniciado com sequenceDiagram) do fluxo principal ponta a ponta, com os componentes técnicos reais como participants (frontend, endpoints/controllers, services, banco de dados, filas). Use APENAS componentes do tech_context ou definidos neste plano; rotule as mensagens com os caminhos de endpoint e nomes de método reais, em português.
   - Subseções: ## Backend, ## Banco de Dados, ## Frontend, ## Infraestrutura.
 # Segurança e Conformidade
 # Estratégia de Testes

package/src/commands/generate-spec.mjs

@@ -27,6 +27,8 @@ O spec deve conter EXATAMENTE estas seções em português, nesta ordem:
 # Regras de Negócio
 # Fluxos
   - Subseções: ## Fluxo Principal (Happy Path), ## Fluxos Alternativos, ## Cenários de Erro.
+  - O Fluxo Principal DEVE conter, além da descrição passo a passo, um diagrama de sequência Mermaid (bloco \`\`\`mermaid iniciado com sequenceDiagram) mostrando a interação entre as personas (actor) e o sistema (participant). Rotule mensagens e notas em português.
+  - Cubra os Fluxos Alternativos e Cenários de Erro relevantes no mesmo diagrama usando blocos alt/opt/break — ou, se ficarem complexos, em um segundo diagrama na subseção correspondente.
 # Critérios de Aceite
   - OBRIGATORIAMENTE no formato Gherkin, dentro de um bloco \`\`\`gherkin com Given/When/Then. Um cenário por critério.
 # Dependências

package/src/commands/implement.mjs

@@ -5,19 +5,24 @@ import { execSync } from 'node:child_process';
 import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import {
-  CONFIG_FILE, STAGE_DEVELOPMENT, STAGE_CODE_REVIEW, STAGE_DONE,
+  CONFIG_FILE, STAGE_DEVELOPMENT, STAGE_CODE_REVIEW, STAGE_DONE, STAGE_ORDER,
   PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE,
 } from '../config.mjs';
 import { getIssue, listIssueComments, listBlockedBy } from '../api/github-rest.mjs';
-import { listSubIssues, getIssueParent } from '../api/github-graphql.mjs';
+import { listSubIssues, getIssueParent, addProjectItem, getItemSingleSelectValue } from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { slugify } from '../lib/slugify.mjs';
-import { parseDependencies } from '../lib/dependencies.mjs';
+import { parseDependencies, orderStories, formatDependencyLine } from '../lib/dependencies.mjs';
+import { loadProjectConfig, resolveField } from '../lib/board.mjs';
 import { extractPathsFromPlan, buildCodeDigest } from '../lib/code-digest.mjs';
 
 // Diretório onde montamos o arquivo de contexto entregue ao spec-kit.
 const WORK_DIR = '.spec-wave';
 
+// Caps dos comentários anexados ao contexto (por issue).
+const MAX_COMMENTS_PER_ISSUE = 15;
+const MAX_COMMENT_CHARS = 2000;
+
 // Sobe a cadeia de pais (Task → Story → Feature) até achar uma issue do tipo
 // "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
@@ -47,6 +52,89 @@ function readSpecPlan(featureDir) {
   };
 }
 
+// ── Blocos compartilhados entre buildContext (Story/Task) e buildFeatureContext ──
+
+// Explica os dois campos do board (Etapa × Status) — abre as instruções de execução.
+function boardFieldsExplainer() {
+  return (
+    'Há **dois campos** no board com papéis diferentes — não os confunda:\n' +
+    `- **Etapa** (Backlog → … → ${STAGE_DEVELOPMENT} → ${STAGE_CODE_REVIEW} → … → ${STAGE_DONE}): 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} — exceto ao chegar na Etapa ${STAGE_DONE}, onde o Status fica **${PROGRESS_DONE}**.`
+  );
+}
+
+// Blockquote-resumo da regra do board — fecha as instruções de execução.
+function boardRuleBlockquote() {
+  return (
+    `> **Regra do board:** a **Etapa** só avança (nunca retrocede); o **Status** (${PROGRESS_TODO}/${PROGRESS_IN_PROGRESS}/${PROGRESS_DONE}) ` +
+    `mede o progresso dentro da etapa atual e reinicia a cada avanço (na Etapa ${STAGE_DONE}, o Status fica ${PROGRESS_DONE}).`
+  );
+}
+
+// Dependências ainda abertas — logo após o cabeçalho, para máxima visibilidade.
+function pushBlockedByWarnings(lines, blockedByWarnings) {
+  if (!blockedByWarnings || blockedByWarnings.length === 0) return;
+  lines.push('');
+  lines.push('## ⚠️ Dependências pendentes');
+  lines.push('');
+  for (const w of blockedByWarnings) lines.push(`- ${w}`);
+  lines.push('');
+  lines.push(
+    '**Implemente somente se tiver certeza de que a dependência não é bloqueante; ' +
+    'caso contrário, pare e reporte.**'
+  );
+}
+
+// Comentários das issues — é onde vivem as revisões/correções feitas depois
+// que spec/plan/stories foram escritos; em conflito, o comentário vence.
+function pushCommentsSection(lines, comments) {
+  if (!comments || comments.length === 0) return;
+  lines.push('');
+  lines.push('## Comentários das issues (revisões e correções)');
+  lines.push('');
+  lines.push(
+    '> Comentários frequentemente **corrigem ou substituem** instruções dos documentos ' +
+    'acima — em caso de conflito, o comentário mais recente prevalece.'
+  );
+  for (const group of comments) {
+    lines.push('');
+    lines.push(`### Comentários da ${group.kind} #${group.issueNumber}`);
+    if (group.total > group.items.length) {
+      lines.push('');
+      lines.push(`_(mostrando os ${group.items.length} mais recentes de ${group.total})_`);
+    }
+    for (const c of group.items) {
+      lines.push('');
+      lines.push(`**${c.author || 'desconhecido'}** (${c.createdAt}):`);
+      lines.push('');
+      lines.push(c.body.trim());
+    }
+  }
+}
+
+// Estado atual do código + spec.md + plan.md — fecho comum dos dois contextos.
+function pushDigestSpecPlan(lines, { codeDigest, spec, plan, specPath, planPath }) {
+  if (codeDigest) {
+    lines.push('');
+    lines.push('## Estado atual do código');
+    lines.push('');
+    lines.push('> **NÃO reimplemente o que já existe; estenda os módulos listados abaixo.**');
+    lines.push('');
+    lines.push(codeDigest.trim());
+  }
+
+  if (spec) {
+    lines.push('');
+    lines.push(`## spec.md (${specPath})`);
+    lines.push(spec.trim());
+  }
+  if (plan) {
+    lines.push('');
+    lines.push(`## plan.md (${planPath})`);
+    lines.push(plan.trim());
+  }
+}
+
 // Monta o markdown de contexto que será entregue ao spec-kit implement.
 function buildContext({
   type, issue, tasks, feature, siblingStories = [], spec, plan, specPath, planPath,
@@ -61,18 +149,7 @@ function buildContext({
     lines.push(issue.body.trim());
   }
 
-  // Dependências ainda abertas — logo após o cabeçalho, para máxima visibilidade.
-  if (blockedByWarnings.length > 0) {
-    lines.push('');
-    lines.push('## ⚠️ Dependências pendentes');
-    lines.push('');
-    for (const w of blockedByWarnings) lines.push(`- ${w}`);
-    lines.push('');
-    lines.push(
-      '**Implemente somente se tiver certeza de que a dependência não é bloqueante; ' +
-      'caso contrário, pare e reporte.**'
-    );
-  }
+  pushBlockedByWarnings(lines, blockedByWarnings);
 
   // Modelo do board: "Etapa" (coluna do kanban) = DIREÇÃO, só avança; "Status"
   // (Todo/In Progress/Done) = PROGRESSO dentro da etapa. O desenvolvimento de
@@ -81,11 +158,7 @@ function buildContext({
   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} → … → ${STAGE_DONE}): 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} — exceto ao chegar na Etapa ${STAGE_DONE}, onde o Status fica **${PROGRESS_DONE}**.`
-  );
+  lines.push(boardFieldsExplainer());
   lines.push('');
   if (type === 'Story') {
     lines.push(
@@ -125,10 +198,7 @@ function buildContext({
     lines.push(`3. **Ao concluir:** **avance a Task #${issue.number} para a Etapa ${STAGE_DONE}** com Status **${PROGRESS_DONE}**.`);
   }
   lines.push('');
-  lines.push(
-    `> **Regra do board:** a **Etapa** só avança (nunca retrocede); o **Status** (${PROGRESS_TODO}/${PROGRESS_IN_PROGRESS}/${PROGRESS_DONE}) ` +
-    `mede o progresso dentro da etapa atual e reinicia a cada avanço (na Etapa ${STAGE_DONE}, o Status fica ${PROGRESS_DONE}).`
-  );
+  lines.push(boardRuleBlockquote());
 
   lines.push('');
   lines.push(`## Tasks a implementar — NESTA ORDEM (${tasks.length})`);
@@ -138,52 +208,136 @@ function buildContext({
     if (t.body && t.body.trim()) lines.push(t.body.trim());
   });
 
-  // Comentários das issues — é onde vivem as revisões/correções feitas depois
-  // que spec/plan/stories foram escritos; em conflito, o comentário vence.
-  if (comments.length > 0) {
-    lines.push('');
-    lines.push('## Comentários das issues (revisões e correções)');
+  pushCommentsSection(lines, comments);
+  pushDigestSpecPlan(lines, { codeDigest, spec, plan, specPath, planPath });
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Planeja a implementação de uma Feature: separa as Stories já implementadas
+ * (Etapa >= reviewStage na ordem canônica) das pendentes e ordena as pendentes
+ * topologicamente pelas dependências. Pura — sem I/O. NUNCA lança.
+ *
+ * Stories com stage null/desconhecido contam como pendentes (mais seguro
+ * incluir do que pular em silêncio). O grafo é montado só com as pendentes:
+ * dependências para Stories puladas (ou externas) contam como satisfeitas, e o
+ * `cycle` retornado só acusa ciclos entre pendentes.
+ *
+ * @param {Array<{number:number, stage:string|null, dependsOn?:number[]}>} stories
+ * @param {{reviewStage?:string, stageOrder?:string[]}} [opts]
+ * @returns {{ pending: object[], skipped: object[], cycle: number[] }}
+ *          pending: objetos originais na ordem de execução; skipped: em ordem
+ *          crescente de number; cycle: numbers pendentes em/bloqueados por ciclo.
+ */
+export function planFeatureImplementation(stories, {
+  reviewStage = STAGE_CODE_REVIEW,
+  stageOrder = STAGE_ORDER,
+} = {}) {
+  const list = Array.isArray(stories) ? stories : [];
+  const reviewIdx = stageOrder.indexOf(reviewStage);
+  const skipped = [];
+  const pendingSet = [];
+  for (const s of list) {
+    const idx = s.stage ? stageOrder.indexOf(s.stage) : -1;
+    if (reviewIdx !== -1 && idx !== -1 && idx >= reviewIdx) skipped.push(s);
+    else pendingSet.push(s);
+  }
+  skipped.sort((a, b) => a.number - b.number);
+
+  const { order, cycle } = orderStories(
+    pendingSet.map(s => ({ number: s.number, dependsOn: s.dependsOn || [] }))
+  );
+  const byNumber = new Map(pendingSet.map(s => [s.number, s]));
+  const pending = order.map(n => byNumber.get(n)).filter(Boolean);
+  return { pending, skipped, cycle };
+}
+
+/**
+ * Monta o markdown de contexto do modo Feature (puro — testável): todas as
+ * Stories pendentes em ordem de execução, cada uma com suas Tasks, mais as já
+ * implementadas (não tocar), comentários, digest e spec/plan.
+ */
+export function buildFeatureContext({
+  feature, stories, skipped = [],
+  spec, plan, specPath, planPath,
+  comments = [], codeDigest = null, blockedByWarnings = [],
+}) {
+  const lines = [];
+  lines.push(`# Contexto de implementação — Feature #${feature.number}`);
+  lines.push('');
+  lines.push(`**Feature:** ${feature.title}`);
+  if (feature.body && feature.body.trim()) {
     lines.push('');
-    lines.push(
-      '> Comentários frequentemente **corrigem ou substituem** instruções dos documentos ' +
-      'acima — em caso de conflito, o comentário mais recente prevalece.'
-    );
-    for (const group of comments) {
-      lines.push('');
-      lines.push(`### Comentários da ${group.kind} #${group.issueNumber}`);
-      if (group.total > group.items.length) {
-        lines.push('');
-        lines.push(`_(mostrando os ${group.items.length} mais recentes de ${group.total})_`);
-      }
-      for (const c of group.items) {
-        lines.push('');
-        lines.push(`**${c.author || 'desconhecido'}** (${c.createdAt}):`);
-        lines.push('');
-        lines.push(c.body.trim());
-      }
-    }
+    lines.push(feature.body.trim());
   }
 
-  // Estado atual do código — evita reimplementar módulos que já existem.
-  if (codeDigest) {
+  pushBlockedByWarnings(lines, blockedByWarnings);
+
+  lines.push('');
+  lines.push('## Instruções de execução (uma Story por vez, na ordem)');
+  lines.push('');
+  lines.push(boardFieldsExplainer());
+  lines.push('');
+  lines.push(
+    `Implemente as ${stories.length} story(ies) pendentes abaixo **uma de cada vez, na ordem listada** — ` +
+    'a ordem já respeita as dependências entre elas (linhas `Depende de:`). Para **cada Story**, na ordem:'
+  );
+  lines.push('');
+  lines.push(`1. **Ao começar a Story:** garanta que ela está na Etapa **${STAGE_DEVELOPMENT}** com Status **${PROGRESS_IN_PROGRESS}** (as Tasks dela nessa Etapa com Status **${PROGRESS_TODO}**).`);
+  lines.push(`2. Implemente as Tasks da Story **uma de cada vez, na ordem listada**. É PROIBIDO ter mais de uma Task com Status **${PROGRESS_IN_PROGRESS}** ao mesmo tempo. Para **cada Task**:`);
+  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:** **avance a Task para a Etapa ${STAGE_DONE}** com Status **${PROGRESS_DONE}**.`);
+  lines.push(`3. **Ao concluir TODAS as Tasks da Story:** faça o **commit**, abra o **Pull Request** da Story e **avance a Etapa da Story para ${STAGE_CODE_REVIEW}** (Status ${PROGRESS_TODO}).`);
+  lines.push('4. Só então inicie a próxima Story.');
+  lines.push('');
+  lines.push(
+    `**Feature #${feature.number}:** avance-a para a Etapa **${STAGE_CODE_REVIEW}** (Status ${PROGRESS_TODO}) ` +
+    `**somente após concluir a ÚLTIMA Story da lista**${skipped.length > 0 ? ' (as Stories já implementadas listadas abaixo não precisam ser refeitas)' : ''}. ` +
+    `Enquanto houver Story pendente, a Feature permanece em ${STAGE_DEVELOPMENT}.`
+  );
+  lines.push('');
+  lines.push(boardRuleBlockquote());
+
+  if (skipped.length > 0) {
     lines.push('');
-    lines.push('## Estado atual do código');
+    lines.push(`## Stories já implementadas — NÃO tocar (${skipped.length})`);
     lines.push('');
-    lines.push('> **NÃO reimplemente o que já existe; estenda os módulos listados abaixo.**');
+    lines.push(`> Já estão em ${STAGE_CODE_REVIEW} ou além; **não** as reimplemente nem as mova.`);
     lines.push('');
-    lines.push(codeDigest.trim());
+    for (const s of skipped) {
+      lines.push(`- #${s.number} ${s.title} — Etapa atual: ${s.stage || '—'}`);
+    }
   }
 
-  if (spec) {
+  lines.push('');
+  lines.push(`## Stories a implementar — NESTA ORDEM (${stories.length})`);
+  stories.forEach((s, i) => {
     lines.push('');
-    lines.push(`## spec.md (${specPath})`);
-    lines.push(spec.trim());
-  }
-  if (plan) {
+    lines.push(`### ${i + 1}. Story #${s.number} — ${s.title}`);
+    const depLine = formatDependencyLine(s.dependsOn || []);
+    if (depLine) {
+      lines.push('');
+      lines.push(depLine);
+    }
+    if (s.body && s.body.trim()) {
+      lines.push('');
+      lines.push(s.body.trim());
+    }
+    const tasks = s.tasks || [];
     lines.push('');
-    lines.push(`## plan.md (${planPath})`);
-    lines.push(plan.trim());
-  }
+    lines.push(`#### Tasks da Story #${s.number} — NESTA ORDEM (${tasks.length})`);
+    tasks.forEach((t, j) => {
+      lines.push('');
+      lines.push(`##### ${j + 1}. #${t.number} ${t.title}`);
+      if (t.body && t.body.trim()) lines.push(t.body.trim());
+    });
+  });
+
+  pushCommentsSection(lines, comments);
+  pushDigestSpecPlan(lines, { codeDigest, spec, plan, specPath, planPath });
 
   lines.push('');
   return lines.join('\n');
@@ -194,6 +348,182 @@ function renderCommand(template, vars) {
   return template.replace(/\{(\w+)\}/g, (m, key) => (key in vars ? vars[key] : m));
 }
 
+// Modo Feature: avalia as Stories da Feature (dependências + Etapa no board),
+// pula as já implementadas (Code Review+) e monta UM contexto único com todas
+// as pendentes em ordem topológica — spec-kit acionado uma vez.
+async function implementFeature({ token, owner, repo, config, feature, featureDirOpt, dryRun }) {
+  // F1. Stories (sub-issues) da Feature.
+  const subs = await listSubIssues(token, feature.node_id).catch(() => []);
+  const stories = subs.filter(s => detectIssueType({ title: s.title, labels: s.labels }) === 'Story');
+  if (stories.length === 0) {
+    p.log.error(
+      `Feature #${feature.number} não tem Stories (sub-issues). ` +
+      'Decomponha primeiro: adicione a label spec-wave:decompose.'
+    );
+    process.exitCode = 1;
+    return;
+  }
+  p.log.info(`Feature com ${stories.length} story(ies): ${stories.map(s => `#${s.number}`).join(', ')}`);
+
+  // F2. Dependências de cada Story: linha "Depende de:" do body ∪ blocked_by nativo.
+  const enriched = await Promise.all(stories.map(async (s) => {
+    let body = s.body;
+    if (!body) body = (await getIssue(token, owner, repo, s.number).catch(() => null))?.body || '';
+    const deps = new Set(parseDependencies(body));
+    const blocked = await listBlockedBy(token, owner, repo, s.number).catch(() => []);
+    for (const b of blocked) deps.add(b.number);
+    return { number: s.number, title: s.title, nodeId: s.nodeId, body: body || '', dependsOn: [...deps] };
+  }));
+
+  // F3. Etapa de cada Story no board (best-effort — sem board, nada é pulado).
+  const { project, error: projectError } = loadProjectConfig();
+  const stageOf = new Map();
+  if (projectError) {
+    p.log.warn(`${projectError} — Etapas do board não consultadas; nenhuma Story será considerada implementada.`);
+  } else {
+    const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
+    if (etapaField?.id) {
+      await Promise.all(enriched.map(async (s) => {
+        try {
+          const itemId = await addProjectItem(token, project.id, s.nodeId);
+          stageOf.set(s.number, await getItemSingleSelectValue(token, itemId, etapaField.id));
+        } catch {
+          stageOf.set(s.number, null);
+        }
+      }));
+    }
+  }
+
+  // F4. Planejamento: pendentes em ordem topológica, puladas, ciclos.
+  const { pending, skipped, cycle } = planFeatureImplementation(
+    enriched.map(s => ({ ...s, stage: stageOf.get(s.number) ?? null }))
+  );
+  if (cycle.length > 0) {
+    p.log.error(
+      `Ciclo de dependências entre Stories pendentes: ${cycle.map(n => `#${n}`).join(', ')}. ` +
+      'Corrija as linhas "Depende de:" (ou as relações blocked by) dessas Stories — ' +
+      `use \`spec-wave order ${feature.number}\` para visualizar.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (skipped.length > 0) {
+    p.log.info(
+      `Puladas (já em ${STAGE_CODE_REVIEW}+): ` +
+      skipped.map(s => `#${s.number} (${s.stage})`).join(', ')
+    );
+  }
+  if (pending.length === 0) {
+    p.outro(`Todas as ${stories.length} story(ies) da Feature #${feature.number} já estão implementadas — nada a fazer.`);
+    return;
+  }
+  p.log.info(`Ordem de implementação: ${pending.map(s => `#${s.number}`).join(' → ')}`);
+
+  // F5. Tasks de cada Story pendente.
+  const noTasks = [];
+  for (const s of pending) {
+    const storySubs = await listSubIssues(token, s.nodeId).catch(() => []);
+    s.tasks = storySubs
+      .filter(t => detectIssueType({ title: t.title, labels: t.labels }) === 'Task')
+      .map(t => ({ number: t.number, title: t.title, body: t.body || '' }));
+    if (s.tasks.length === 0) noTasks.push(s.number);
+  }
+  if (noTasks.length > 0) {
+    p.log.error(
+      `Story(ies) pendente(s) sem Tasks (sub-issues): ${noTasks.map(n => `#${n}`).join(', ')}. ` +
+      'Decomponha-as antes de implementar (re-rode o decompose da Feature se necessário).'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  // F6. spec.md/plan.md — a issue-alvo JÁ é a Feature (sem resolveFeature).
+  const featureDir = featureDirOpt || path.join('docs', 'features', slugify(feature.title));
+  let specPlan = { spec: null, plan: null, specPath: null, planPath: null };
+  if (existsSync(featureDir)) {
+    specPlan = readSpecPlan(featureDir);
+  } else {
+    p.log.warn(`Diretório da feature não encontrado (${featureDir}); seguindo só com as Stories.`);
+  }
+
+  // F7. Dependências EXTERNAS ainda abertas (da Feature e das Stories pendentes)
+  // — as internas ao conjunto de Stories já estão cobertas pela ordem topológica.
+  const blockedByWarnings = [];
+  try {
+    const internal = new Set(stories.map(s => s.number));
+    const featureDeps = new Set(parseDependencies(feature.body));
+    const featureBlocked = await listBlockedBy(token, owner, repo, feature.number).catch(() => []);
+    for (const b of featureBlocked) featureDeps.add(b.number);
+    const check = [
+      { kind: 'Feature', number: feature.number, deps: featureDeps },
+      ...pending.map(s => ({ kind: 'Story', number: s.number, deps: new Set(s.dependsOn) })),
+    ];
+    for (const c of check) {
+      for (const depNumber of [...c.deps].sort((a, b) => a - b)) {
+        if (internal.has(depNumber)) continue;
+        const dep = await getIssue(token, owner, repo, depNumber).catch(() => null);
+        if (!dep || dep.state === 'closed') continue;
+        const warning =
+          `${c.kind} #${c.number} depende de #${depNumber} («${dep.title}»), ` +
+          `que ainda não está concluída (state: ${dep.state}).`;
+        blockedByWarnings.push(warning);
+        p.log.warn(warning);
+      }
+    }
+  } catch { /* aviso é best-effort — segue sem ele */ }
+
+  // F8. Comentários: Feature primeiro, depois cada Story pendente na ordem.
+  const comments = [];
+  const commentSources = [
+    { number: feature.number, kind: 'Feature' },
+    ...pending.map(s => ({ number: s.number, kind: 'Story' })),
+  ];
+  for (const src of commentSources) {
+    const all = await listIssueComments(token, owner, repo, src.number).catch(() => []);
+    if (all.length === 0) continue;
+    const items = all.slice(-MAX_COMMENTS_PER_ISSUE).map(c => ({
+      ...c,
+      body: c.body.length > MAX_COMMENT_CHARS
+        ? `${c.body.slice(0, MAX_COMMENT_CHARS)}…[truncado]`
+        : c.body,
+    }));
+    comments.push({ issueNumber: src.number, kind: src.kind, total: all.length, items });
+  }
+
+  // F9. Digest do estado do código desde a criação da Feature.
+  let codeDigest = null;
+  try {
+    const paths = specPlan.plan ? extractPathsFromPlan(specPlan.plan) : [];
+    codeDigest = await buildCodeDigest({ sinceIso: feature.created_at || null, paths });
+  } catch {
+    codeDigest = null;
+  }
+
+  // F10. Contexto único + spec-kit (uma execução).
+  const context = buildFeatureContext({
+    feature: { number: feature.number, title: feature.title, body: feature.body || '' },
+    stories: pending,
+    skipped,
+    ...specPlan,
+    comments,
+    codeDigest,
+    blockedByWarnings,
+  });
+  writeContextAndRunSpecKit({
+    config,
+    issueNumber: feature.number,
+    type: 'Feature',
+    title: feature.title,
+    specPlan,
+    context,
+    dryRun,
+    outroSuccess:
+      `${chalk.green('✓')} Implementação acionada para a Feature #${feature.number} ` +
+      `(${pending.length} story(ies) pendente(s)).\n` +
+      `  Próximo: acompanhe os PRs de cada Story; a Feature avança para ${STAGE_CODE_REVIEW} após a última.`,
+  });
+}
+
 export async function implement({ issue: issueArg, featureDir: featureDirOpt, dryRun }) {
   const issueNumber = parseInt(String(issueArg).replace('#', ''), 10);
   if (!Number.isInteger(issueNumber)) {
@@ -260,9 +590,13 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
   } else if (type === 'Task') {
     tasks = [{ number: issue.number, title: issue.title, body: issue.body || '' }];
     p.log.info(`Task única #${issueNumber}.`);
+  } else if (type === 'Feature') {
+    // Modo Feature: Stories pendentes em ordem de dependência, contexto único.
+    await implementFeature({ token, owner, repo, config, feature: issue, featureDirOpt, dryRun });
+    return;
   } else {
     p.log.error(
-      `implement só aceita Story ou Task. Issue #${issueNumber} é do tipo ${type || 'desconhecido'}.`
+      `implement só aceita Feature, Story ou Task. Issue #${issueNumber} é do tipo ${type || 'desconhecido'}.`
     );
     process.exitCode = 1;
     return;
@@ -298,8 +632,6 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
   // 4c. Comentários das issues (best-effort) — revisões e correções vivem nos
   // comentários, não no body; sem eles o agente implementa instruções já
   // corrigidas. Feature primeiro (correções de escopo), depois a issue-alvo.
-  const MAX_COMMENTS_PER_ISSUE = 15;
-  const MAX_COMMENT_CHARS = 2000;
   const comments = [];
   const commentSources = [];
   if (feature && feature.number !== issue.number) {
@@ -353,17 +685,27 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
     }
   } catch { /* aviso é best-effort — segue sem ele */ }
 
-  // 5. Monta e grava o arquivo de contexto.
+  // 5-6. Monta o contexto e aciona o spec-kit (comando configurável).
   const context = buildContext({
     type, issue, tasks, feature, siblingStories, ...specPlan,
     comments, codeDigest, blockedByWarnings,
   });
+  writeContextAndRunSpecKit({
+    config, issueNumber, type, title: issue.title, specPlan, context, dryRun,
+    outroSuccess:
+      `${chalk.green('✓')} Implementação acionada para ${type} #${issueNumber}.\n` +
+      '  Próximo: revise as mudanças, abra o PR e mova o card para 👀 Code Review.',
+  });
+}
+
+// Grava o arquivo de contexto e aciona o spec-kit (comando configurável) —
+// fecho comum dos modos Feature e Story/Task.
+function writeContextAndRunSpecKit({ config, issueNumber, type, title, specPlan, context, dryRun, outroSuccess }) {
   mkdirSync(WORK_DIR, { recursive: true });
   const tasksFile = path.join(WORK_DIR, `implement-${issueNumber}.md`);
   writeFileSync(tasksFile, context);
   p.log.success(`Contexto montado em ${chalk.cyan(tasksFile)}.`);
 
-  // 6. Aciona o spec-kit (comando configurável).
   const template = process.env.SPEC_WAVE_IMPLEMENT_CMD || config.specKit?.command;
   const vars = {
     tasksFile,
@@ -371,7 +713,7 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
     planFile: specPlan.planPath || '',
     issue: String(issueNumber),
     type,
-    title: issue.title,
+    title,
   };
 
   if (!template) {
@@ -404,8 +746,5 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
     return;
   }
 
-  p.outro(
-    `${chalk.green('✓')} Implementação acionada para ${type} #${issueNumber}.\n` +
-    '  Próximo: revise as mudanças, abra o PR e mova o card para 👀 Code Review.'
-  );
+  p.outro(outroSuccess);
 }

package/src/commands/info.mjs

@@ -3,20 +3,57 @@ import chalk from 'chalk';
 import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
 import { CONFIG_FILE, PORTAL_URL } from '../config.mjs';
+import { skillStatus } from './install-skill.mjs';
+
+// Resume o estado da skill para a saída JSON. `null` = não foi possível checar.
+function skillJson(status) {
+  if (!status) return null;
+  return {
+    agentsDetected: status.agentsDetected,
+    installNeeded: status.agentsDetected.length === 0 || status.pending.length > 0,
+    pending: status.pending,
+  };
+}
+
+// Reporta (saída humana) se o usuário precisa rodar o install-skill: nenhum
+// agente detectado → não dá para validar, sugere instalar; cópia ausente ou
+// de versão antiga → aponta o agente e o motivo.
+function reportSkill(status) {
+  if (!status) return;
+  if (status.agentsDetected.length === 0) {
+    p.log.warn(
+      'Nenhum agente de código detectado neste diretório — a skill spec-wave ' +
+      'não parece instalada. Rode `npx @spec-wave/cli install-skill`.'
+    );
+    return;
+  }
+  if (status.pending.length === 0) {
+    p.log.success(`Skill instalada e atualizada (${status.agentsDetected.join(', ')}).`);
+    return;
+  }
+  p.log.warn(
+    'Skill pendente de instalação/atualização:\n' +
+    status.pending.map(s => `  ${chalk.yellow('↻')} ${s.agent} (${s.reason}) — ${chalk.dim(s.path)}`).join('\n') +
+    '\nRode `npx @spec-wave/cli install-skill` (ou `npx @spec-wave/cli update`).'
+  );
+}
 
 // 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
-// as informações ou oferecer rodar o `init`.
+// as informações ou oferecer rodar o `init`. Também valida se a skill instalada
+// nos agentes detectados está em dia com a versão empacotada na CLI.
 export async function info(options = {}) {
   const configPath = path.join(process.cwd(), CONFIG_FILE);
+  const skill = skillStatus();
 
   if (!existsSync(configPath)) {
     if (options.json) {
-      console.log(JSON.stringify({ initialized: false }));
+      console.log(JSON.stringify({ initialized: false, skill: skillJson(skill) }));
       return;
     }
     p.intro(chalk.bold('spec-wave info'));
     p.log.warn(`Este repositório ${chalk.bold('não foi inicializado')} (sem ${CONFIG_FILE}).`);
+    reportSkill(skill);
     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;
@@ -27,7 +64,7 @@ export async function info(options = {}) {
     config = JSON.parse(readFileSync(configPath, 'utf-8'));
   } catch (err) {
     if (options.json) {
-      console.log(JSON.stringify({ initialized: false, error: err.message }));
+      console.log(JSON.stringify({ initialized: false, error: err.message, skill: skillJson(skill) }));
       return;
     }
     p.log.error(`${CONFIG_FILE} existe mas está corrompido: ${err.message}`);
@@ -36,7 +73,7 @@ export async function info(options = {}) {
   }
 
   if (options.json) {
-    console.log(JSON.stringify({ initialized: true, ...config }));
+    console.log(JSON.stringify({ initialized: true, ...config, skill: skillJson(skill) }));
     return;
   }
 
@@ -51,6 +88,7 @@ export async function info(options = {}) {
     `${chalk.dim('Criado em:')}   ${config.initializedAt ?? '?'}`,
     'Configuração'
   );
+  reportSkill(skill);
   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/install-skill.mjs

@@ -178,6 +178,46 @@ export function isDetected(target, baseDir) {
   return target.detect.some((sig) => existsSync(path.join(baseDir, sig)));
 }
 
+// Motivo pelo qual a cópia da skill em `dest` precisa ser (re)instalada:
+// 'ausente' | 'bloco ausente' | 'desatualizada' — ou null se está em dia com a
+// versão empacotada na CLI. Compartilhado entre `update` e `info`.
+export function skillCopyReason(dest, parsed) {
+  const desired = renderContent(dest.format, parsed, CLI_VERSION);
+  const existing = existsSync(dest.path) ? readFileSync(dest.path, 'utf-8') : null;
+  if (existing === null) return 'ausente';
+  if (dest.format === 'agents') {
+    const block = extractAgentsBlock(existing);
+    if (block === null) return 'bloco ausente';
+    return block.trim() !== desired.trim() ? 'desatualizada' : null;
+  }
+  return existing !== desired ? 'desatualizada' : null;
+}
+
+// Estado da skill para os agentes detectados em cwd (escopo projeto), com
+// fallback: uma cópia GLOBAL atualizada atende o agente mesmo sem cópia local.
+// Retorna null quando a fonte da skill não está no pacote (instalação parcial).
+export function skillStatus(cwd = process.cwd()) {
+  if (!existsSync(SKILL_SOURCE)) return null;
+  const parsed = parseSkill(readFileSync(SKILL_SOURCE, 'utf-8'));
+  const agentsDetected = [];
+  const pending = [];
+  for (const target of TARGETS) {
+    if (!isDetected(target, cwd)) continue;
+    agentsDetected.push(target.name);
+    const dest = resolveDest(target, cwd, false);
+    if (!dest) continue;
+    let reason = skillCopyReason(dest, parsed);
+    if (reason === 'ausente') {
+      const globalDest = resolveDest(target, homedir(), true);
+      if (globalDest && skillCopyReason(globalDest, parsed) === null) reason = null;
+    }
+    if (reason) {
+      pending.push({ agent: target.name, key: target.key, path: dest.path, reason });
+    }
+  }
+  return { agentsDetected, pending };
+}
+
 export async function installSkill(options = {}) {
   p.intro(chalk.bold('spec-wave install-skill'));
 

package/src/commands/update.mjs

@@ -12,7 +12,7 @@ import {
 } from '../api/github-rest.mjs';
 import {
   TARGETS, SKILL_SOURCE, CLI_VERSION, parseSkill, renderContent,
-  mergeAgentsFile, resolveDest, isDetected, extractAgentsBlock,
+  mergeAgentsFile, resolveDest, isDetected, skillCopyReason,
 } from './install-skill.mjs';
 
 const __dir = path.dirname(fileURLToPath(import.meta.url));
@@ -35,19 +35,10 @@ function detectSkill(parsed, baseDir, isGlobal) {
     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';
+    const reason = skillCopyReason(dest, parsed);
+    if (reason) {
+      jobs.push({ target, dest, desired: renderContent(dest.format, parsed, CLI_VERSION), reason });
     }
-    if (reason) jobs.push({ target, dest, desired, reason });
   }
   return jobs;
 }

package/src/config.mjs

@@ -68,6 +68,7 @@ export const STATUS_OPTIONS = [
 //    atual. Ao avançar de etapa, o Status reinicia em "Todo".
 
 // Etapas (campo Etapa) referenciadas pelo fluxo de implementação.
+export const STAGE_READY = STATUS_OPTIONS.find(s => s.name.includes('Ready')).name;
 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;
 export const STAGE_DONE = STATUS_OPTIONS.find(s => s.name.includes('Done')).name;

package/src/templates/skill/SKILL.md

@@ -86,7 +86,7 @@ Labels de **estado** (gravadas pelas automações — **não** são gatilhos, n
 - `spec-wave:critique-failed` → a crítica adversarial apontou contradições **graves** nos documentos; **bloqueia** o `spec-wave:ready` até ser removida (veja *Crítica adversarial* abaixo)
 - `spec-wave:decomposed` → a Feature/RFC já foi decomposta; o `decompose` pula silenciosamente enquanto ela existir (veja *Guard de idempotência* abaixo)
 
-A etapa **🚧 Desenvolvimento** é coberta pelo comando **local** `npx @spec-wave/cli implement <número>` (não é uma label/Action): lê uma Story ou Task e aciona o spec-kit para implementar. Veja `/spec-wave implement`.
+A etapa **🚧 Desenvolvimento** é coberta pelo comando **local** `npx @spec-wave/cli implement <número>` (não é uma label/Action): lê uma **Feature** (todas as Stories pendentes, em ordem de dependência), uma Story ou uma Task e aciona o spec-kit para implementar. Veja `/spec-wave implement`.
 
 ---
 
@@ -137,7 +137,9 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 ### `@spec-wave/cli info` — status de configuração do repo atual
 | Flag | Tipo | Descrição |
 |------|------|-----------|
-| `--json` | flag | Saída JSON (`{"initialized":bool, ...}`) para parsing programático. |
+| `--json` | flag | Saída JSON (`{"initialized":bool, ..., "skill":{...}}`) para parsing programático. |
+
+> Além do `.spec-wave.json`, valida a **skill instalada**: para cada agente detectado no diretório, compara a cópia instalada com a versão empacotada na CLI (uma cópia **global** atualizada também conta). No JSON, o campo `skill` traz `{agentsDetected, installNeeded, pending:[{agent, reason, path}]}` — `installNeeded: true` significa que o usuário precisa rodar `install-skill` (ou `update`).
 
 ### `@spec-wave/cli refresh` — atualiza o `.spec-wave.json` local
 | Flag | Tipo | Descrição |
@@ -167,17 +169,17 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 > - `generate-spec` / `generate-plan` → **apenas Features**. Para **Spike, RFC e Bug** a geração é **pulada** (o Action remove a label e comenta) — esses tipos não usam spec/plan.
 > - `decompose` → **Feature** (gera Stories + Tasks) e **RFC** (gera **Tasks** diretamente, sem Stories). Para outros tipos, o Action recusa.
 
-### `@spec-wave/cli implement` — aciona o spec-kit para uma Story ou Task (comando LOCAL)
+### `@spec-wave/cli implement` — aciona o spec-kit para uma Feature, Story ou Task (comando LOCAL)
 | Flag/Arg | Tipo | Descrição |
 |----------|------|-----------|
-| `<issue>` | string (obrigatório) | Número da issue (Story ou Task), ex.: `12` ou `#12`. Argumento posicional. |
+| `<issue>` | string (obrigatório) | Número da issue (Feature, Story ou Task), ex.: `12` ou `#12`. Argumento posicional. |
 | `--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 os **comentários da issue**, um **digest do código recente** e um **aviso de dependências pendentes** quando a issue depende (linha `Depende de: #N` ou relação nativa *blocked by*) de outra que ainda não foi concluída — nesse caso, confirme com o usuário antes de seguir. Inclui também instruções para o agente implementar as Tasks **sequencialmente, uma por vez** (nunca duas com Status "In Progress" ao mesmo tempo): cada Task usa o **Status** (In Progress) *dentro* da Etapa 🚧 Desenvolvimento e, **ao concluir, avança para a Etapa 🎉 Done com Status Done**. **Ao concluir toda a Story**: fazer o commit, abrir o PR e **avançar a Etapa da Story para 👀 Code Review** (Status → Todo) — as Tasks já estão em 🎉 Done. 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.
+> Diferente dos quatro acima, `implement` roda **localmente** (lê `.spec-wave.json`, como `issue`), não por Action. Detecta o tipo da issue: **Feature** → lista as Stories (sub-issues), **ordena topologicamente pelas dependências** (`Depende de:` + *blocked by*), **pula** as já em 👀 Code Review+ (listadas no contexto como "não tocar") e monta **um único** contexto com todas as pendentes (cada uma com suas Tasks), acionando o spec-kit **uma vez** com `{issue}/{type}/{title}` da Feature — **ciclo de dependências entre Stories pendentes aborta o comando (exit 1)**; **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 os **comentários da issue**, um **digest do código recente** e um **aviso de dependências pendentes** quando a issue depende (linha `Depende de: #N` ou relação nativa *blocked by*) de outra que ainda não foi concluída — nesse caso, confirme com o usuário antes de seguir. Inclui também instruções para o agente implementar as Tasks **sequencialmente, uma por vez** (nunca duas com Status "In Progress" ao mesmo tempo): cada Task usa o **Status** (In Progress) *dentro* da Etapa 🚧 Desenvolvimento e, **ao concluir, avança para a Etapa 🎉 Done com Status Done**. **Ao concluir toda a Story**: fazer o commit, abrir o PR e **avançar a Etapa da Story para 👀 Code Review** (Status → Todo) — as Tasks já estão em 🎉 Done. 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.
 
 ### `@spec-wave/cli doctor` — preflight de auth e configuração (comando LOCAL)
-Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub (e a fonte dele), escopos (`repo`, `project`, `workflow` — com degradação para checks funcionais em fine-grained PATs), conta ativa do `gh` vs. owner, `.spec-wave.json` (campos e sincronia com o Project real), acesso ao repositório, configuração de IA (provider/modelo/`ai.models` + secrets do Actions) e presença dos workflows.
+Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub (e a fonte dele), escopos (`repo`, `project`, `workflow` — com degradação para checks funcionais em fine-grained PATs), conta ativa do `gh` vs. owner, `.spec-wave.json` (campos e sincronia com o Project real), acesso ao repositório, configuração de IA (provider/modelo/`ai.models` + secrets do Actions), **spec-kit** (`specKit.command` / env `SPEC_WAVE_IMPLEMENT_CMD` — se ausente, avisa e sugere exemplos por agente: Claude Code, opencode, Codex, Copilot CLI, Kiro CLI, Qwen Code) e presença dos workflows.
 
 > Saída: `✓` ok, `✗` problema confirmado, `!` não verificável (best-effort — falha de rede nunca derruba o doctor). **Exit 1** se houver algum `✗`. **Quando rodar:** no início de uma sessão de trabalho, ou sempre que aparecer um erro estranho (ex.: **404 ao criar issues** — causa típica: token sem acesso ao repo/org, que o doctor aponta). É o primeiro passo de troubleshooting — prefira-o a depurar `gh api` na mão.
 
@@ -226,7 +228,8 @@ O evento `labeled` pode redisparar (re-add da label, retry de runner). Para não
 
 O `decompose` grava nas Stories geradas uma linha **`Depende de: #N, #M`** no corpo e cria a relação nativa *blocked by* do GitHub. Essas dependências alimentam:
 - `spec-wave order <feature>` → ordem topológica de execução;
-- `spec-wave implement <n>` → **aviso** no contexto quando uma dependência ainda não está concluída (confirme com o usuário antes de implementar fora de ordem).
+- `spec-wave implement <feature>` → Stories pendentes implementadas **nessa ordem**; **ciclo de dependências → erro** (corrija as linhas `Depende de:`); dependências **externas** abertas viram aviso no contexto;
+- `spec-wave implement <n>` (Story/Task) → **aviso** no contexto quando uma dependência ainda não está concluída (confirme com o usuário antes de implementar fora de ordem).
 
 Não apague a linha `Depende de:` ao editar o corpo de uma Story; para mudar dependências, edite a linha (e/ou a relação *blocked by*).
 
@@ -263,6 +266,7 @@ Mostra se o repositório atual já foi configurado com o spec-wave.
 3. **Se NÃO estiver inicializado**, pergunte ao usuário: "Este repositório ainda não foi configurado com o spec-wave. Quer rodar o `init` agora?"
    - Se sim → siga o fluxo de `/spec-wave setup`.
    - Se não → encerre sem alterar nada.
+4. **Se a saída indicar skill pendente** (aviso "Skill pendente de instalação/atualização" ou, no `--json`, `skill.installNeeded: true`), pergunte ao usuário se quer instalar/atualizar agora: skill `ausente` → `npx @spec-wave/cli install-skill`; skill `desatualizada` → `npx @spec-wave/cli update` (atualiza tudo que ficou para trás). Lembre-o de recarregar o agente depois.
 
 ---
 
@@ -470,20 +474,22 @@ Para qualquer outro tipo (Spike, Bug, Story, Task, …) o Action **recusa** e co
    gh issue edit <número> --add-label "spec-wave:decompose"
    ```
 3. Informe: "Decomposição iniciada — Feature gera Stories+Tasks; RFC gera Tasks."
-4. Após a conclusão, as issues filhas aparecerão como comentário na issue pai, junto com o comentário 🔎 da crítica adversarial. As Stories geradas trazem a linha `Depende de: #N` (+ relação *blocked by*) — use `npx @spec-wave/cli order <número>` para ver a ordem de execução.
+4. Após a conclusão, as issues filhas aparecerão como comentário na issue pai, junto com o comentário 🔎 da crítica adversarial. A issue pai e as Stories/Tasks criadas entram no board na Etapa **✅ Ready** (Status Todo; a Etapa nunca retrocede — itens já adiante não são tocados). As Stories geradas trazem a linha `Depende de: #N` (+ relação *blocked by*) — use `npx @spec-wave/cli order <número>` para ver a ordem de execução.
 5. A issue recebe a label `spec-wave:decomposed` (guard de idempotência): rodar de novo **não** duplica as issues. Para forçar um re-decompose, siga a seção *Guard de idempotência*.
 
 ---
 
 ### `/spec-wave implement <número-da-issue>`
 
-Aciona o spec-kit para implementar uma **Story** (todas as suas Tasks) ou uma **Task** isolada. Comando **local** (etapa 🚧 Desenvolvimento) — não usa label/Action.
+Aciona o spec-kit para implementar uma **Feature** (todas as Stories pendentes, em ordem de dependência), uma **Story** (todas as suas Tasks) ou uma **Task** isolada. Comando **local** (etapa 🚧 Desenvolvimento) — não usa label/Action.
+
+**Pré-requisitos:** o repositório atual precisa estar inicializado (`.spec-wave.json` presente) e a issue deve ser do tipo Feature, Story ou Task. Para executar de fato (fora do `--dry-run`), o spec-kit precisa estar configurado via `specKit.command` no `.spec-wave.json` ou a env `SPEC_WAVE_IMPLEMENT_CMD`.
 
-**Pré-requisitos:** o repositório atual precisa estar inicializado (`.spec-wave.json` presente) e a issue deve ser do tipo Story ou Task. Para executar de fato (fora do `--dry-run`), o spec-kit precisa estar configurado via `specKit.command` no `.spec-wave.json` ou a env `SPEC_WAVE_IMPLEMENT_CMD`.
+**Modo Feature:** o comando avalia as Stories da Feature — ordena topologicamente pelas dependências (`Depende de:` + *blocked by*), consulta a Etapa de cada uma no board e **pula as já implementadas** (👀 Code Review ou além). O contexto único (`.spec-wave/implement-<feature>.md`) traz as pendentes em ordem, cada uma com suas Tasks. **Ciclo de dependências entre Stories pendentes → o comando aborta** (corrija as linhas `Depende de:`; use `npx @spec-wave/cli order <feature>` para visualizar). Story pendente sem Tasks → aborta pedindo decomposição. Todas implementadas → encerra sem acionar o spec-kit.
 
 **Passos:**
 1. Confirme que há `.spec-wave.json` no repo (senão, oriente `/spec-wave setup`).
-2. **Sempre comece com `--dry-run`** para inspecionar o que será feito — detecção do tipo, lista de Tasks coletadas (no caso de Story) e o comando do spec-kit que seria executado:
+2. **Sempre comece com `--dry-run`** para inspecionar o que será feito — detecção do tipo, lista de Tasks coletadas (Story) ou a ordem/puladas/ciclos das Stories (Feature) e o comando do spec-kit que seria executado:
    ```bash
    npx @spec-wave/cli implement <número> --dry-run
    ```
@@ -495,8 +501,8 @@ 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 (Tasks em **🎉 Done**, Story 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.
+6. **No modo Feature**, siga o contexto Story a Story, na ordem listada: para cada Story pendente, implemente as Tasks com `task start`/`task done`, depois commit + PR + `npx @spec-wave/cli story review <n>`; só então passe à próxima Story. Se a issue **não** for Feature, Story nem Task (ex.: Bug, Spike, Epic), o comando recusa. Feature **sem Stories** → rode `/spec-wave decompose` primeiro. **Ciclo de dependências** → corrija as linhas `Depende de:` (veja `spec-wave order`).
+7. Ao final (Tasks em **🎉 Done**, Story em **👀 Code Review**; a Feature só vai para Code Review quando a última Story concluir — no modo Feature, isso acontece dentro da mesma execução): confirme o resultado com o usuário e oriente a revisão dos PRs.
 
 ---