@spec-wave/cli 0.5.8 → 0.5.9

package/package.json

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

package/src/commands/implement.mjs

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

package/src/commands/info.mjs

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

package/src/commands/init.mjs

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

package/src/commands/install-skill.mjs

@@ -9,6 +9,9 @@ import path from 'node:path';
 const __dir = path.dirname(fileURLToPath(import.meta.url));
 // Fonte única da skill, publicada via "files": ["src"] no package.json.
 const SKILL_SOURCE = path.join(__dir, '..', 'templates', 'skill', 'SKILL.md');
+// Versão da CLI que gerou a skill instalada — carimbada no arquivo para detecção
+// de desatualização (a skill é uma cópia estática; não acompanha o `npx` sozinha).
+const pkg = JSON.parse(readFileSync(path.join(__dir, '..', '..', 'package.json'), 'utf-8'));
 
 // Marcadores usados para gravar/atualizar a skill de forma idempotente em
 // arquivos compartilhados (AGENTS.md) — permite reinstalar sem duplicar.
@@ -83,39 +86,50 @@ 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) {
   const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
-  if (!match) return { meta: {}, body: raw.trim() };
+  if (!match) return { meta: {}, frontmatter: '', body: raw.trim() };
   let meta = {};
   try {
     meta = yaml.load(match[1]) || {};
   } catch {
     meta = {};
   }
-  return { meta, body: match[2].trim() };
+  return { meta, frontmatter: match[1], body: match[2].trim() };
 }
 
-// Converte o SKILL.md para o formato exigido por cada agente.
-function renderContent(format, raw, parsed) {
-  const { meta, body } = parsed;
+// Banner de versão inserido no topo do corpo da skill instalada. O agente lê
+// esta linha e, se `npx @spec-wave/cli --version` for maior, orienta reinstalar.
+function versionBanner(version) {
+  return (
+    `> ⚙️ **spec-wave skill v${version}** — esta skill é uma cópia estática. ` +
+    'Se `npx @spec-wave/cli --version` indicar uma versão maior, ela está ' +
+    'desatualizada: rode `npx @spec-wave/cli install-skill --force` para atualizá-la.'
+  );
+}
+
+// Converte o SKILL.md para o formato exigido por cada agente, carimbando a versão.
+function renderContent(format, parsed, version) {
+  const { meta, frontmatter, body } = parsed;
   const description = meta.description ?? 'Skill spec-wave.';
+  const banner = versionBanner(version);
   switch (format) {
     case 'skill':
-      // Claude Code / opencode consomem o SKILL.md nativo. Campos extras do
-      // frontmatter são ignorados pelo opencode — sem problema.
-      return raw.trimEnd() + '\n';
+      // Claude Code / opencode consomem o SKILL.md nativo. Preserva o frontmatter
+      // original (allowed-tools etc.) e insere o banner no topo do corpo.
+      return `---\n${frontmatter}\n---\n\n${banner}\n\n${body}\n`;
     case 'mdc':
       return (
         `---\n` +
         `description: ${JSON.stringify(description)}\n` +
         `alwaysApply: false\n` +
         `---\n\n` +
-        `${body}\n`
+        `${banner}\n\n${body}\n`
       );
     case 'rules':
-      return `# spec-wave\n\n${description}\n\n${body}\n`;
+      return `# spec-wave\n\n${banner}\n\n${description}\n\n${body}\n`;
     case 'agents':
-      return `${BLOCK_START}\n\n# spec-wave\n\n${description}\n\n${body}\n\n${BLOCK_END}\n`;
+      return `${BLOCK_START}\n\n# spec-wave\n\n${banner}\n\n${description}\n\n${body}\n\n${BLOCK_END}\n`;
     default:
-      return raw;
+      return body;
   }
 }
 
@@ -258,8 +272,8 @@ export async function installSkill(options = {}) {
   for (const { target, dest } of jobs) {
     const content =
       dest.format === 'agents'
-        ? mergeAgentsFile(dest.path, renderContent('agents', raw, parsed))
-        : renderContent(dest.format, raw, parsed);
+        ? mergeAgentsFile(dest.path, renderContent('agents', parsed, pkg.version))
+        : renderContent(dest.format, parsed, pkg.version);
 
     // Confirmar sobrescrita de arquivos "próprios" (skill/rules/mdc). Para
     // 'agents' o merge por marcadores já é seguro (não apaga conteúdo alheio).
@@ -286,7 +300,10 @@ export async function installSkill(options = {}) {
 
   p.note(
     written.map((w) => `${chalk.green('✓')} ${chalk.bold(w.target.name)}\n  ${chalk.dim(w.dest.path)}`).join('\n'),
-    `Skill instalada (escopo: ${scopeLabel})`,
+    `Skill v${pkg.version} instalada (escopo: ${scopeLabel})`,
+  );
+  p.outro(
+    'Reinicie/recarregue o agente para que ele detecte a skill. ' +
+    'Ao atualizar a CLI, rode `install-skill --force` para atualizar a skill também.',
   );
-  p.outro('Reinicie/recarregue o agente para que ele detecte a skill.');
 }

package/src/config.mjs

@@ -4,6 +4,9 @@
 // pelo comando `info` (e pela skill) para detectar se o spec-wave já foi configurado.
 export const CONFIG_FILE = '.spec-wave.json';
 
+// Portal Web da ferramenta — exibido ao final do `init` e no `info`.
+export const PORTAL_URL = 'https://spec-wave.astratech.net.br';
+
 // Providers de IA suportados pelos workflows (generate-plan/spec/decompose).
 // O provider e o modelo escolhidos no `init` são persistidos em .spec-wave.json
 // (bloco `ai`) e lidos em runtime por src/lib/claude.mjs. Cada provider declara
@@ -48,6 +51,14 @@ 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;
+export const STAGE_CODE_REVIEW = STATUS_OPTIONS.find(s => s.name.includes('Code Review')).name;
+
 export const CUSTOM_FIELDS = [
   {
     name: 'Work Item Type',

package/src/templates/skill/SKILL.md

@@ -4,7 +4,7 @@ description: "Use when the user wants to set up a spec-driven GitHub workflow, c
 argument-hint: "[info|setup|issue|feature|spec|plan|ready|decompose|implement|uninstall|rfc|fix-pr] [target]"
 user-invocable: true
 allowed-tools:
-  - Bash(npx spec-wave *)
+  - Bash(npx @spec-wave/cli *)
   - Bash(gh issue *)
   - Bash(gh project *)
   - Bash(gh repo view *)
@@ -27,16 +27,18 @@ 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.
+
 ---
 
 ## Detecção de configuração (faça isto primeiro, sempre)
 
-Antes de qualquer sub-comando, leia o arquivo `.spec-wave.json` na raiz do repositório atual (use o tool Read). Esse arquivo é gravado pelo `npx spec-wave init` e é a fonte de estado persistente entre sessões.
+Antes de qualquer sub-comando, leia o arquivo `.spec-wave.json` na raiz do repositório atual (use o tool Read). Esse arquivo é gravado pelo `npx @spec-wave/cli init` e é a fonte de estado persistente entre sessões.
 
 - **Se existir**, o spec-wave já foi configurado. Use seus campos para contextualizar as respostas, sem perguntar de novo:
   - `owner`/`repo` → repositório alvo dos comandos `gh`
   - `project.url` / `project.title` → o GitHub Project a referenciar
-  - `version` → versão da CLI usada no `init` (compare com `npx spec-wave --version`; se divergir, sugira `npx spec-wave refresh --config` para atualizar o arquivo, ou re-rodar o `init` para atualizar workflows/labels)
+  - `version` → versão da CLI usada no `init` (compare com `npx @spec-wave/cli --version`; se divergir, sugira `npx @spec-wave/cli refresh --config` para atualizar o arquivo, ou re-rodar o `init` para atualizar workflows/labels)
   - `initializedAt` → quando foi configurado
   Não rode `/spec-wave setup` de novo a menos que o usuário peça explicitamente.
 - **Se não existir**, o repositório provavelmente ainda não foi configurado. Sugira começar por `/spec-wave setup`.
@@ -80,15 +82,15 @@ Labels de gatilho:
 - `spec-wave:ready` → dispara `validate.yml` → valida ambos os arquivos
 - `spec-wave:decompose` → dispara `decompose.yml` → gera Stories e Tasks
 
-A etapa **🚧 Desenvolvimento** é coberta pelo comando **local** `spec-wave 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 Story ou Task e aciona o spec-kit para implementar. Veja `/spec-wave implement`.
 
 ---
 
 ## Referência da CLI (conheça os parâmetros ANTES de executar)
 
-Esta skill é um **wrapper** da CLI `spec-wave`. Regra de ouro: **nunca rode um comando sem os parâmetros que ele aceita** esperando que ele pergunte — colete os valores com o usuário e passe via flags. Em especial, **`init` sem `--repo` abre um wizard interativo (@clack/prompts) que a skill NÃO consegue dirigir** — sempre passe `--repo`.
+Esta skill é um **wrapper** da CLI `@spec-wave/cli`, sempre invocada como `npx @spec-wave/cli <comando>`. Regra de ouro: **nunca rode um comando sem os parâmetros que ele aceita** esperando que ele pergunte — colete os valores com o usuário e passe via flags. Em especial, **`init` sem `--repo` abre um wizard interativo (@clack/prompts) que a skill NÃO consegue dirigir** — sempre passe `--repo`.
 
-### `spec-wave init` — configura o repositório
+### `@spec-wave/cli init` — configura o repositório
 | Flag | Tipo | Descrição |
 |------|------|-----------|
 | `--repo <owner/repo>` | string | Repositório alvo. **Passe SEMPRE** para evitar o wizard interativo. |
@@ -98,25 +100,25 @@ Esta skill é um **wrapper** da CLI `spec-wave`. Regra de ouro: **nunca rode um
 | `--skip-files` | flag | Pula a criação dos workflows + issue templates. |
 | `--dry-run` | flag | Simula a configuração sem alterar nada. |
 
-### `spec-wave issue` — cria um work item tipado, opcionalmente como sub-issue, e adiciona ao board
+### `@spec-wave/cli issue` — cria um work item tipado, opcionalmente como sub-issue, e adiciona ao board
 | Flag | Tipo | Descrição |
 |------|------|-----------|
 | `--title <title>` | string (obrigatório) | Título, **sem** o prefixo de tipo (a CLI adiciona, ex.: `[STORY]`). |
 | `--type <type>` | string | `initiative`, `epic`, `feature`, `story`, `task`, `bug`, `spike` ou `rfc`. Default: `feature`. |
 | `--parent <n>` | string | Número da issue pai — cria como **sub-issue** dela (relação nativa do GitHub). |
 | `--body <text>` | string | Descrição. |
-| `--priority <p>` | string | `P0`, `P1`, `P2` ou `P3`. |
+| `--priority <p>` | string | **Opcional.** `P0`, `P1`, `P2` ou `P3`. Omita se o usuário não pediu — a prioridade fica `null` (sem prioridade). Nunca atribua por conta própria. |
 | `--area <area>` | string | `Frontend`, `Backend`, `Mobile`, `Infra`, `DevOps` ou `Data`. |
 
-> Faz tudo: cria a issue (label de tipo + prioridade), vincula ao parent como sub-issue, adiciona ao Project e define os campos **Etapa = 📥 Backlog**, **Work Item Type**, **Priority** e **Area**. Grava `Parent: #N` no corpo. Lê o Project do `.spec-wave.json`. **Não use `gh issue create` direto** — ele não adiciona ao board nem vincula o parent.
+> Faz tudo: cria a issue (label de tipo — e de prioridade **apenas se `--priority` for informado**), vincula ao parent como sub-issue, adiciona ao Project e define os campos **Etapa = 📥 Backlog**, **Work Item Type**, **Area** e, **só se informada, Priority**. Grava `Parent: #N` no corpo. Lê o Project do `.spec-wave.json`. **Não use `gh issue create` direto** — ele não adiciona ao board nem vincula o parent.
 
-### `spec-wave initiative` — atalho de `issue --type initiative`
+### `@spec-wave/cli initiative` — atalho de `issue --type initiative`
 Cria o nó raiz da hierarquia (agrupa Epics). Mesmas flags do `issue` exceto `--type` (fixo em `initiative`) e `--parent` (Initiative é raiz, não tem pai).
 
-### `spec-wave feature` — atalho de `issue --type feature`
+### `@spec-wave/cli feature` — atalho de `issue --type feature`
 Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o fluxo do RFC-001.
 
-### `spec-wave uninstall` — remove a configuração (mantém o Project)
+### `@spec-wave/cli uninstall` — remove a configuração (mantém o Project)
 | Flag | Tipo | Descrição |
 |------|------|-----------|
 | `--repo <owner/repo>` | string | Repositório (default: lê do `.spec-wave.json`). |
@@ -128,33 +130,33 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 
 > Remove labels + arquivos `.github` + `.spec-wave.json`. **NUNCA apaga o GitHub Project** (preserva o histórico do board) — o usuário deve excluí-lo manualmente se quiser.
 
-### `spec-wave info` — status de configuração do repo atual
+### `@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. |
 
-### `spec-wave refresh` — atualiza o `.spec-wave.json` local
+### `@spec-wave/cli refresh` — atualiza o `.spec-wave.json` local
 | Flag | Tipo | Descrição |
 |------|------|-----------|
 | `--config` | flag | Re-consulta o GitHub Project e reescreve o `.spec-wave.json` (IDs do campo Etapa, opções, number, versão da CLI). |
 
 > 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 generate-plan` · `generate-spec` · `validate` · `decompose`
+### `@spec-wave/cli generate-plan` · `generate-spec` · `validate` · `decompose`
 | Flag | Tipo | Descrição |
 |------|------|-----------|
 | `--issue-number <n>` | string (obrigatório) | Número da issue no GitHub. |
 
 > ⚠️ Esses quatro comandos são executados pelos **GitHub Actions** (disparados por labels), **não** pela skill diretamente. Veja a *Regra fundamental*: para gerar plan/spec/decompor, adicione a **label** correspondente — não rode o comando à mão (a não ser para debug local).
 
-### `spec-wave implement` — aciona o spec-kit para uma Story ou Task (comando LOCAL)
+### `@spec-wave/cli implement` — aciona o spec-kit para uma 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. |
 | `--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 já inclui uma instrução para o agente mover a Story e as Tasks para **🚧 Desenvolvimento** (in progress) ao iniciar.
+> 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).
 
 ---
 
@@ -165,7 +167,7 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 Mostra se o repositório atual já foi configurado com o spec-wave.
 
 **Passos:**
-1. Execute: `npx spec-wave info`
+1. Execute: `npx @spec-wave/cli info`
 2. **Se o repositório estiver inicializado**, o comando mostra os dados do `.spec-wave.json` (owner/repo, project, versão da CLI, data). Apresente essas informações ao usuário.
 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`.
@@ -175,17 +177,17 @@ Mostra se o repositório atual já foi configurado com o spec-wave.
 
 ### `/spec-wave setup`
 
-Configura o spec-wave no repositório. Você dirige o `init` com flags — **nunca rode `npx spec-wave init` sem `--repo`** (abre o wizard interativo que você não controla).
+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).
 
 **Passos:**
-1. **Já configurado?** Leia `.spec-wave.json` (ou rode `npx spec-wave info`). Se existir, avise (mostre `project.url` e `version`) e confirme com o usuário antes de reconfigurar.
+1. **Já configurado?** Leia `.spec-wave.json` (ou rode `npx @spec-wave/cli info`). Se existir, avise (mostre `project.url` e `version`) e confirme com o usuário antes de reconfigurar.
 2. **Descubra o repositório alvo** (parâmetro `--repo`): rode `gh repo view --json nameWithOwner -q .nameWithOwner` para obter `owner/repo` do repo atual. Confirme com o usuário; se não houver remote, pergunte o `owner/repo`.
 3. **Pergunte o título do Project** (parâmetro `--project-title`). Ofereça o default `<repo> — Spec Wave` e aceite-o se o usuário não tiver preferência.
 4. **Cheque o auth:** `gh auth status`. Se faltarem os escopos `project,repo,workflow`, oriente o usuário a rodar ele mesmo `gh auth refresh --scopes project,repo,workflow` (comando interativo — o usuário executa, não você).
-5. **(Opcional) Pré-visualize** antes de aplicar: `npx spec-wave init --repo <owner/repo> --dry-run`.
+5. **(Opcional) Pré-visualize** antes de aplicar: `npx @spec-wave/cli init --repo <owner/repo> --dry-run`.
 6. **Execute com os parâmetros coletados:**
    ```bash
-   npx spec-wave init --repo <owner/repo> --project-title "<título>"
+   npx @spec-wave/cli init --repo <owner/repo> --project-title "<título>"
    ```
    Use `--skip-project` / `--skip-labels` / `--skip-files` **apenas** para re-rodar uma fase específica que falhou antes.
 7. O `init` cria o Project, as labels, os workflows, um **scaffold de `.github/config/tech_context.yml`** (só se ainda não existir) e grava `.spec-wave.json`. Oriente o usuário a fazer `git pull` para trazer os arquivos ao checkout local.
@@ -201,19 +203,19 @@ Crie um work item tipado (Initiative/Epic/Feature/Story/Task/...) já adicionado
 **Hierarquia típica:** Initiative → Epic → Feature → Story → Task. A **Initiative** é o nó raiz e agrupa Epics. Use `--parent <n>` para criar como sub-issue do nível acima (ex.: um Epic filho de uma Initiative, ou uma Story filha de uma Feature). O GitHub mostra o parent na issue filha e vice-versa; a CLI ainda grava `Parent: #N` no corpo.
 
 **Passos:**
-1. Pergunte ao usuário: tipo (initiative/epic/feature/story/task/...), título (sem prefixo), descrição, área, prioridade, e se há uma issue **pai** (número).
-2. Execute o comando com os parâmetros coletados:
+1. Pergunte ao usuário: tipo (initiative/epic/feature/story/task/...), título (sem prefixo), descrição e se há uma issue **pai** (número). **Prioridade e área são opcionais**: só as inclua se o usuário pedir explicitamente. **Nunca atribua uma prioridade por conta própria** — se o usuário não informou, **omita `--priority`** e a prioridade fica `null` (sem prioridade) no board.
+2. Execute o comando com os parâmetros coletados (inclua **apenas** as flags que o usuário forneceu):
    ```bash
-   npx spec-wave issue \
+   npx @spec-wave/cli issue \
      --type "<tipo>" \
      --title "<título>" \
      --body "<descrição>" \
-     --area "<área>" \
-     --priority "<prioridade>" \
+     --area "<área>" \            # opcional — omita se o usuário não informou
+     --priority "<prioridade>" \  # opcional — só se o usuário pediu; caso contrário OMITA (prioridade fica null)
      --parent "<número-do-pai>"   # opcional
    ```
-   Para Features, pode usar o atalho `npx spec-wave feature --title ...` (equivale a `--type feature`).
-   A CLI cria a issue (label de tipo + prioridade), vincula como sub-issue do parent, adiciona ao Project e define Etapa = 📥 Backlog + Work Item Type + Priority + Area. **Não use `gh issue create`** (não adiciona ao board nem vincula o parent).
+   Para Features, pode usar o atalho `npx @spec-wave/cli feature --title ...` (equivale a `--type feature`).
+   A CLI cria a issue (label de tipo — e de prioridade **apenas se `--priority` for informado**), vincula como sub-issue do parent, adiciona ao Project e define Etapa = 📥 Backlog + Work Item Type + Area (+ Priority só se informada). **Não use `gh issue create`** (não adiciona ao board nem vincula o parent).
 3. Informe o número criado e o vínculo com o pai (se houver).
 4. Para Features: "Quando quiser iniciar, mova para **📋 Spec** e use `/spec-wave spec <número>` para gerar a especificação funcional (o plano técnico vem depois)".
 
@@ -225,8 +227,8 @@ Remove a configuração do spec-wave do repositório (labels, arquivos `.github`
 
 **Passos:**
 1. Confirme com o usuário que ele quer remover (a ação remove labels e faz commits removendo os workflows).
-2. Mostre antes o que será removido com `npx spec-wave uninstall --dry-run`.
-3. Execute `npx spec-wave uninstall` (a CLI pede confirmação; use `--yes` só se o usuário já confirmou).
+2. Mostre antes o que será removido com `npx @spec-wave/cli uninstall --dry-run`.
+3. Execute `npx @spec-wave/cli uninstall` (a CLI pede confirmação; use `--yes` só se o usuário já confirmou).
 4. Lembre o usuário de excluir o **GitHub Project** manualmente, se desejar — a CLI não o apaga de propósito.
 
 ---
@@ -267,7 +269,7 @@ O plano técnico segue o schema do RFC-002 §3.2: **Estratégia Técnica** (com
 
 ### Tech Context (`.github/config/tech_context.yml`)
 
-Fonte de verdade estática da stack do sistema (RFC-002 §4). O `generate-plan` lê este arquivo para embasar o plano técnico e usar **APENAS** as tecnologias/serviços nele declarados — sem ele, o plano fica genérico e pode inventar APIs inexistentes. O `npx spec-wave init` gera um **scaffold de exemplo** que **deve ser adaptado** à stack real. Use este fluxo quando o arquivo estiver ausente ou desatualizado.
+Fonte de verdade estática da stack do sistema (RFC-002 §4). O `generate-plan` lê este arquivo para embasar o plano técnico e usar **APENAS** as tecnologias/serviços nele declarados — sem ele, o plano fica genérico e pode inventar APIs inexistentes. O `npx @spec-wave/cli init` gera um **scaffold de exemplo** que **deve ser adaptado** à stack real. Use este fluxo quando o arquivo estiver ausente ou desatualizado.
 
 **Como ajudar a criar (quando não existir):**
 
@@ -361,17 +363,18 @@ Aciona o spec-kit para implementar uma **Story** (todas as suas Tasks) ou uma **
 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:
    ```bash
-   npx spec-wave implement <número> --dry-run
+   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.
-4. Se o usuário aprovar e o spec-kit estiver configurado, rode sem `--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).
+5. Se o usuário aprovar e o spec-kit estiver configurado, rode sem `--dry-run`:
    ```bash
-   npx spec-wave implement <número>
+   npx @spec-wave/cli implement <número>
    ```
    - 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.
-5. 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.
-6. Após implementar: oriente revisar as mudanças, abrir o PR e mover o card para **👀 Code Review**.
+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.
 
 ---