@spec-wave/cli 0.1.0

package/src/commands/refresh.mjs

@@ -0,0 +1,116 @@
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { resolveToken } from '../api/auth.mjs';
+import { CONFIG_FILE } from '../config.mjs';
+import { getProjectSnapshot } from '../api/github-graphql.mjs';
+
+const __dir = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(path.join(__dir, '..', '..', 'package.json'), 'utf-8'));
+
+// Re-consulta o GitHub Project e reescreve o .spec-wave.json local com os dados
+// atuais (id/number/url/title do Project, IDs do campo Etapa e das opções, e a
+// versão da CLI). Útil para repositórios inicializados antes do enriquecimento,
+// ou quando o Project foi renomeado/teve campos alterados.
+export async function refresh(options = {}) {
+  if (!options.config) {
+    p.log.error('Nada a fazer. Use `spec-wave refresh --config` para atualizar o .spec-wave.json.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const configPath = path.join(process.cwd(), CONFIG_FILE);
+  if (!existsSync(configPath)) {
+    p.log.error(`Repositório não inicializado (sem ${CONFIG_FILE}). Rode \`spec-wave init\` primeiro.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  let config;
+  try {
+    config = JSON.parse(readFileSync(configPath, 'utf-8'));
+  } catch (err) {
+    p.log.error(`${CONFIG_FILE} corrompido: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const projectId = config.project?.id;
+  if (!projectId) {
+    p.log.error(
+      `${CONFIG_FILE} não tem o id do Project (project.id). ` +
+      'Re-rode `spec-wave init` (sem --skip-project) para registrá-lo.'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let token;
+  try {
+    token = await resolveToken();
+  } catch (err) {
+    p.log.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  p.intro(chalk.bold('spec-wave refresh --config'));
+
+  const spinner = p.spinner();
+  spinner.start('Consultando o GitHub Project...');
+  let snapshot;
+  try {
+    snapshot = await getProjectSnapshot(token, projectId);
+  } catch (err) {
+    spinner.stop('');
+    p.log.error(`Erro ao consultar o Project: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!snapshot) {
+    spinner.stop('');
+    p.log.error(`Project ${projectId} não encontrado. Ele pode ter sido excluído.`);
+    process.exitCode = 1;
+    return;
+  }
+  spinner.stop('Project consultado.');
+
+  // Remove campos legados (versões anteriores gravavam etapaFieldId/stageOptions soltos).
+  const { etapaFieldId: _e, stageOptions: _s, ...projectRest } = config.project;
+  const updated = {
+    ...config,
+    version: pkg.version,
+    project: {
+      ...projectRest,
+      title: snapshot.title,
+      url: snapshot.url,
+      id: snapshot.id,
+      number: snapshot.number,
+      fields: snapshot.fields,
+    },
+    refreshedAt: new Date().toISOString(),
+  };
+
+  try {
+    writeFileSync(configPath, JSON.stringify(updated, null, 2) + '\n');
+  } catch (err) {
+    p.log.error(`Falha ao gravar ${CONFIG_FILE}: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const fieldNames = Object.keys(snapshot.fields || {});
+  if (!fieldNames.includes('Etapa')) {
+    p.log.warn('Campo "Etapa" não encontrado no Project.');
+  }
+
+  p.note(
+    `${chalk.dim('Project:')}    ${snapshot.title} (#${snapshot.number})\n` +
+    `${chalk.dim('Campos:')}     ${fieldNames.length ? fieldNames.join(', ') : '—'}\n` +
+    `${chalk.dim('Versão CLI:')} ${pkg.version}`,
+    'Configuração atualizada'
+  );
+  p.outro(`${CONFIG_FILE} atualizado. Faça commit do arquivo para versioná-lo.`);
+}

package/src/commands/uninstall.mjs

@@ -0,0 +1,132 @@
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { readFileSync, existsSync, unlinkSync } from 'node:fs';
+import path from 'node:path';
+import { resolveToken } from '../api/auth.mjs';
+import { CONFIG_FILE, ALL_LABELS, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES } from '../config.mjs';
+import { deleteLabel, deleteFile } from '../api/github-rest.mjs';
+
+const REPO_FILES = [
+  ...WORKFLOW_FILES.map(f => `.github/workflows/${f}`),
+  ...ISSUE_TEMPLATE_FILES.map(f => `.github/ISSUE_TEMPLATE/${f}`),
+];
+
+// Reverte o que o `init` criou — EXCETO o GitHub Project, que nunca é apagado
+// (perderia todo o histórico do board). Remove labels, arquivos .github e o
+// marcador .spec-wave.json local.
+export async function uninstall(options = {}) {
+  const configPath = path.join(process.cwd(), CONFIG_FILE);
+  const hasConfig = existsSync(configPath);
+
+  let owner, repo;
+  if (options.repo) {
+    if (!options.repo.includes('/')) {
+      p.log.error('Formato inválido para --repo. Use: owner/repo');
+      process.exitCode = 1;
+      return;
+    }
+    [owner, repo] = options.repo.split('/');
+  } else if (hasConfig) {
+    try {
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      owner = config.owner;
+      repo = config.repo;
+    } catch (err) {
+      p.log.error(`${CONFIG_FILE} corrompido: ${err.message}. Use --repo owner/repo.`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  if (!owner || !repo) {
+    p.log.error(`Não encontrei o repositório. Rode dentro de um repo com ${CONFIG_FILE} ou use --repo owner/repo.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const doLabels = !options.skipLabels;
+  const doFiles = !options.skipFiles;
+  const doConfig = hasConfig && !options.keepConfig;
+
+  p.intro(chalk.bold('spec-wave uninstall'));
+  p.note(
+    `${chalk.dim('Repositório:')} ${owner}/${repo}\n\n` +
+    `${doLabels ? '✓' : '○'} Labels do repo (${ALL_LABELS.length})\n` +
+    `${doFiles ? '✓' : '○'} Arquivos .github (${REPO_FILES.length})\n` +
+    `${doConfig ? '✓' : '○'} ${CONFIG_FILE} (local)\n\n` +
+    `${chalk.yellow('O GitHub Project NÃO será apagado')} — remova-o manualmente se desejar.`,
+    options.dryRun ? 'Dry-run — nada será alterado' : 'Será removido'
+  );
+
+  if (options.dryRun) {
+    p.outro('Dry-run concluído.');
+    return;
+  }
+
+  if (!options.yes) {
+    const ok = await p.confirm({ message: `Remover a configuração do spec-wave de ${owner}/${repo}?`, initialValue: false });
+    if (p.isCancel(ok) || !ok) {
+      p.cancel('Cancelado. Nada foi alterado.');
+      return;
+    }
+  }
+
+  let token;
+  try {
+    token = await resolveToken();
+  } catch (err) {
+    p.log.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  // --- Labels ---
+  if (doLabels) {
+    const spinner = p.spinner();
+    spinner.start('Removendo labels...');
+    let removed = 0;
+    try {
+      for (let i = 0; i < ALL_LABELS.length; i++) {
+        spinner.message(`Removendo label ${i + 1}/${ALL_LABELS.length}: ${ALL_LABELS[i].name}`);
+        if (await deleteLabel(token, owner, repo, ALL_LABELS[i].name)) removed++;
+      }
+      spinner.stop(`Labels removidas (${removed}/${ALL_LABELS.length}).`);
+    } catch (err) {
+      spinner.stop('');
+      p.log.warn(`Erro ao remover labels: ${err.message}`);
+    }
+  }
+
+  // --- Arquivos .github (cada remoção é um commit) ---
+  if (doFiles) {
+    const spinner = p.spinner();
+    spinner.start('Removendo arquivos...');
+    let removed = 0;
+    try {
+      for (let i = 0; i < REPO_FILES.length; i++) {
+        const filePath = REPO_FILES[i];
+        spinner.message(`Removendo ${i + 1}/${REPO_FILES.length}: ${filePath}`);
+        if (await deleteFile(token, owner, repo, filePath, `chore: remove ${filePath} [spec-wave]`)) removed++;
+      }
+      spinner.stop(`Arquivos removidos (${removed}/${REPO_FILES.length}).`);
+    } catch (err) {
+      spinner.stop('');
+      p.log.warn(`Erro ao remover arquivos: ${err.message}`);
+    }
+  }
+
+  // --- Marcador local ---
+  if (doConfig) {
+    try {
+      unlinkSync(configPath);
+      p.log.success(`${CONFIG_FILE} removido.`);
+    } catch (err) {
+      p.log.warn(`Não foi possível remover ${CONFIG_FILE}: ${err.message}`);
+    }
+  }
+
+  p.outro(
+    `${chalk.green('✓')} spec-wave removido de ${owner}/${repo}.\n` +
+    '  Lembre-se de excluir o GitHub Project manualmente, se quiser.'
+  );
+}

package/src/commands/validate.mjs

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolveToken } from '../api/auth.mjs';
+import { getIssue, removeLabel, addLabel, commentOnIssue } from '../api/github-rest.mjs';
+import { slugify } from '../lib/slugify.mjs';
+import { REQUIRED_PLAN_SECTIONS, REQUIRED_SPEC_SECTIONS } from '../config.mjs';
+
+export async function validate({ issueNumber }) {
+  const token = await resolveToken();
+  const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
+
+  if (!owner || !repo) {
+    throw new Error(
+      'GITHUB_REPOSITORY env var não definida.\n' +
+      'Este comando roda no GitHub Actions. Para testar localmente:\n' +
+      '  GITHUB_REPOSITORY=owner/repo spec-wave validate --issue-number 1'
+    );
+  }
+
+  const issue = await getIssue(token, owner, repo, parseInt(issueNumber, 10));
+  const slug = slugify(issue.title);
+  const featureDir = `docs/features/${slug}`;
+
+  const errors = [];
+
+  // Check plan.md
+  const planPath = `${featureDir}/plan.md`;
+  if (!existsSync(planPath)) {
+    errors.push('❌ `plan.md` não encontrado em `' + planPath + '`');
+  } else {
+    const planContent = readFileSync(planPath, 'utf-8');
+    for (const section of REQUIRED_PLAN_SECTIONS) {
+      if (!planContent.includes(`# ${section}`)) {
+        errors.push(`❌ Seção obrigatória ausente no plan.md: **${section}**`);
+      }
+    }
+  }
+
+  // Check spec.md
+  const specPath = `${featureDir}/spec.md`;
+  if (!existsSync(specPath)) {
+    errors.push('❌ `spec.md` não encontrado em `' + specPath + '`');
+  } else {
+    const specContent = readFileSync(specPath, 'utf-8');
+    for (const section of REQUIRED_SPEC_SECTIONS) {
+      if (!specContent.includes(`# ${section}`)) {
+        errors.push(`❌ Seção obrigatória ausente no spec.md: **${section}**`);
+      }
+    }
+  }
+
+  // Remove trigger label
+  await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:ready');
+
+  if (errors.length > 0) {
+    await commentOnIssue(
+      token, owner, repo, parseInt(issueNumber, 10),
+      `⚠️ **Validação falhou — Feature não está pronta.**\n\n` +
+      errors.join('\n') +
+      `\n\nCorreija os problemas e adicione novamente a label \`spec-wave:ready\`.`
+    );
+    // Send back to spec stage
+    await addLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:spec');
+    console.error('Validação falhou:', errors.join(', '));
+    process.exit(1);
+  }
+
+  await commentOnIssue(
+    token, owner, repo, parseInt(issueNumber, 10),
+    `✅ **Validação concluída com sucesso!**\n\n` +
+    `- [\`${planPath}\`](${planPath}) ✓\n` +
+    `- [\`${specPath}\`](${specPath}) ✓\n\n` +
+    `A Feature está pronta para decomposição. Mova o card para **📋 Backlog Técnico** ou use:\n` +
+    `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:decompose"\n\`\`\``
+  );
+
+  console.log('Validação OK. Feature pronta para decomposição.');
+}

package/src/config.mjs

@@ -0,0 +1,131 @@
+// Single source of truth for all RFC-001 data
+
+// Marcador de configuração gravado pelo `init` na raiz do repo-alvo e lido
+// pelo comando `info` (e pela skill) para detectar se o spec-wave já foi configurado.
+export const CONFIG_FILE = '.spec-wave.json';
+
+export const STATUS_OPTIONS = [
+  { name: '📥 Backlog',          color: 'GRAY'   },
+  { name: '🎯 Priorizado',       color: 'BLUE'   },
+  { name: '📋 Plan',             color: 'YELLOW' },
+  { name: '📋 Spec',             color: 'YELLOW' },
+  { name: '✅ Ready',            color: 'GREEN'  },
+  { name: '📋 Backlog Técnico',  color: 'BLUE'   },
+  { name: '🚧 Desenvolvimento',  color: 'ORANGE' },
+  { name: '👀 Code Review',      color: 'PURPLE' },
+  { name: '🧪 QA',              color: 'PINK'   },
+  { name: '📋 Homologação',      color: 'YELLOW' },
+  { name: '🚀 Deploy',           color: 'ORANGE' },
+  { name: '🎉 Done',            color: 'GREEN'  },
+];
+
+export const CUSTOM_FIELDS = [
+  {
+    name: 'Work Item Type',
+    dataType: 'SINGLE_SELECT',
+    options: [
+      { name: 'Epic',    color: 'PURPLE', description: 'Objetivo estratégico' },
+      { name: 'Feature', color: 'BLUE',   description: 'Capacidade funcional' },
+      { name: 'Story',   color: 'GREEN',  description: 'Necessidade do usuário' },
+      { name: 'Task',    color: 'YELLOW', description: 'Atividade técnica' },
+      { name: 'Bug',     color: 'RED',    description: 'Defeito a corrigir' },
+      { name: 'Spike',   color: 'ORANGE', description: 'Investigação técnica' },
+      { name: 'RFC',     color: 'GRAY',   description: 'Proposta de processo' },
+    ],
+  },
+  {
+    name: 'Priority',
+    dataType: 'SINGLE_SELECT',
+    options: [
+      { name: 'P0', color: 'RED',    description: 'Crítico' },
+      { name: 'P1', color: 'ORANGE', description: 'Alta' },
+      { name: 'P2', color: 'YELLOW', description: 'Média' },
+      { name: 'P3', color: 'GRAY',   description: 'Baixa' },
+    ],
+  },
+  {
+    name: 'Story Points',
+    dataType: 'SINGLE_SELECT',
+    options: [
+      { name: '1',  color: 'GREEN',  description: '' },
+      { name: '2',  color: 'GREEN',  description: '' },
+      { name: '3',  color: 'BLUE',   description: '' },
+      { name: '5',  color: 'BLUE',   description: '' },
+      { name: '8',  color: 'YELLOW', description: '' },
+      { name: '13', color: 'ORANGE', description: '' },
+      { name: '21', color: 'RED',    description: '' },
+    ],
+  },
+  {
+    name: 'Area',
+    dataType: 'SINGLE_SELECT',
+    options: [
+      { name: 'Frontend', color: 'BLUE',   description: '' },
+      { name: 'Backend',  color: 'GREEN',  description: '' },
+      { name: 'Mobile',   color: 'PURPLE', description: '' },
+      { name: 'Infra',    color: 'ORANGE', description: '' },
+      { name: 'DevOps',   color: 'YELLOW', description: '' },
+      { name: 'Data',     color: 'PINK',   description: '' },
+    ],
+  },
+  {
+    name: 'Release',
+    dataType: 'TEXT',
+  },
+];
+
+// Tipos de work item (Epic, Feature, Story, Task, Bug, Spike, RFC) — derivados do
+// campo "Work Item Type". Usados pelo comando `issue` para validar --type.
+export const WORK_ITEM_TYPES = CUSTOM_FIELDS
+  .find(f => f.name === 'Work Item Type')
+  .options.map(o => o.name);
+
+export const TYPE_LABELS = [
+  { name: '[EPIC]',    color: '7B61FF', description: 'Objetivo estratégico'  },
+  { name: '[FEATURE]', color: '0075CA', description: 'Capacidade funcional'  },
+  { name: '[STORY]',   color: '0E8A16', description: 'Necessidade do usuário' },
+  { name: '[TASK]',    color: 'E4E669', description: 'Atividade técnica'     },
+  { name: '[BUG]',     color: 'D93F0B', description: 'Defeito a corrigir'    },
+  { name: '[SPIKE]',   color: 'E99695', description: 'Investigação técnica'  },
+  { name: '[RFC]',     color: 'EDEDED', description: 'Proposta de processo'  },
+];
+
+export const PRIORITY_LABELS = [
+  { name: 'P0', color: 'B60205', description: 'Crítico'  },
+  { name: 'P1', color: 'D93F0B', description: 'Alta'     },
+  { name: 'P2', color: 'E4E669', description: 'Média'    },
+  { name: 'P3', color: 'EDEDED', description: 'Baixa'    },
+];
+
+export const TRIGGER_LABELS = [
+  { name: 'spec-wave:plan',      color: 'BFD4F2', description: 'Gerar plan.md via GitHub Action'     },
+  { name: 'spec-wave:spec',      color: 'BFD4F2', description: 'Gerar spec.md via GitHub Action'     },
+  { name: 'spec-wave:ready',     color: '0E8A16', description: 'Validar spec+plan e mover para Ready' },
+  { name: 'spec-wave:decompose', color: 'BFD4F2', description: 'Decompor em Stories e Tasks'         },
+];
+
+export const ALL_LABELS = [...TYPE_LABELS, ...PRIORITY_LABELS, ...TRIGGER_LABELS];
+
+export const WORKFLOW_FILES = [
+  'generate-plan.yml',
+  'generate-spec.yml',
+  'validate.yml',
+  'decompose.yml',
+];
+
+export const ISSUE_TEMPLATE_FILES = [
+  'plan-template.md',
+  'spec-template.md',
+];
+
+export const REQUIRED_PLAN_SECTIONS = [
+  'Frontend',
+  'Backend',
+  'Banco de dados',
+  'Testes',
+];
+
+export const REQUIRED_SPEC_SECTIONS = [
+  'Objetivo',
+  'Critérios de Aceite',
+];

package/src/lib/claude.mjs

@@ -0,0 +1,25 @@
+import Anthropic from '@anthropic-ai/sdk';
+
+const DEFAULT_MODEL = 'claude-sonnet-4-6';
+
+export async function generateDocument(systemPrompt, userContent) {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      'ANTHROPIC_API_KEY not set.\n' +
+      'Add it as a GitHub Actions secret or set it in your environment.'
+    );
+  }
+
+  const client = new Anthropic({ apiKey });
+  const model = process.env.ANTHROPIC_MODEL || DEFAULT_MODEL;
+
+  const message = await client.messages.create({
+    model,
+    max_tokens: 4096,
+    messages: [{ role: 'user', content: userContent }],
+    system: systemPrompt,
+  });
+
+  return message.content[0].text;
+}

package/src/lib/slugify.mjs

@@ -0,0 +1,13 @@
+// Converts an issue title like "[FEATURE] Cadastro de Pedidos com PIX"
+// into a filesystem slug like "cadastro-de-pedidos-com-pix"
+export function slugify(title) {
+  return title
+    .replace(/^\[.*?\]\s*/, '')   // strip [PREFIX] at start
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '') // remove diacritics
+    .replace(/[^a-z0-9\s-]/g, '')   // remove non-alphanumeric
+    .trim()
+    .replace(/\s+/g, '-')           // spaces to hyphens
+    .replace(/-+/g, '-');           // collapse multiple hyphens
+}

package/src/setup/files.mjs

@@ -0,0 +1,63 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { upsertFile, isRepoInitialized } from '../api/github-rest.mjs';
+
+const __dir = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(__dir, '..', 'templates');
+
+function readTemplate(...parts) {
+  return readFileSync(path.join(TEMPLATES_DIR, ...parts), 'utf-8');
+}
+
+export async function setupFiles(token, owner, repo, spinner) {
+  spinner.message('Verificando repositório...');
+  const initialized = await isRepoInitialized(token, owner, repo);
+  if (!initialized) {
+    throw new Error(
+      `O repositório ${owner}/${repo} está vazio (sem commits).\n` +
+      `Inicialize-o com um commit antes de continuar:\n` +
+      `  gh repo clone ${owner}/${repo} && cd ${repo}\n` +
+      `  git commit --allow-empty -m "chore: initial commit" && git push`
+    );
+  }
+
+  const filesToCreate = [
+    {
+      path: '.github/ISSUE_TEMPLATE/plan-template.md',
+      content: readTemplate('issue', 'plan-template.md'),
+      message: 'chore: add plan.md issue template [spec-wave]',
+    },
+    {
+      path: '.github/ISSUE_TEMPLATE/spec-template.md',
+      content: readTemplate('issue', 'spec-template.md'),
+      message: 'chore: add spec.md issue template [spec-wave]',
+    },
+    {
+      path: '.github/workflows/generate-plan.yml',
+      content: readTemplate('workflows', 'generate-plan.yml'),
+      message: 'chore: add generate-plan workflow [spec-wave]',
+    },
+    {
+      path: '.github/workflows/generate-spec.yml',
+      content: readTemplate('workflows', 'generate-spec.yml'),
+      message: 'chore: add generate-spec workflow [spec-wave]',
+    },
+    {
+      path: '.github/workflows/validate.yml',
+      content: readTemplate('workflows', 'validate.yml'),
+      message: 'chore: add validate workflow [spec-wave]',
+    },
+    {
+      path: '.github/workflows/decompose.yml',
+      content: readTemplate('workflows', 'decompose.yml'),
+      message: 'chore: add decompose workflow [spec-wave]',
+    },
+  ];
+
+  for (let i = 0; i < filesToCreate.length; i++) {
+    const file = filesToCreate[i];
+    spinner.message(`Criando arquivo ${i + 1}/${filesToCreate.length}: ${file.path}`);
+    await upsertFile(token, owner, repo, file.path, file.content, file.message);
+  }
+}

package/src/setup/labels.mjs

@@ -0,0 +1,17 @@
+import { createLabel } from '../api/github-rest.mjs';
+import { ALL_LABELS } from '../config.mjs';
+
+const DELAY_MS = 120;
+
+function sleep(ms) {
+  return new Promise(r => setTimeout(r, ms));
+}
+
+export async function setupLabels(token, owner, repo, spinner) {
+  for (let i = 0; i < ALL_LABELS.length; i++) {
+    const label = ALL_LABELS[i];
+    spinner.message(`Criando label ${i + 1}/${ALL_LABELS.length}: ${label.name}`);
+    await createLabel(token, owner, repo, label);
+    if (i < ALL_LABELS.length - 1) await sleep(DELAY_MS);
+  }
+}

package/src/setup/project.mjs

@@ -0,0 +1,62 @@
+import {
+  createProject,
+  createSingleSelectField,
+  createTextField,
+  linkProjectToRepo,
+} from '../api/github-graphql.mjs';
+import { getOwnerNodeId, getRepoNodeId } from '../api/github-rest.mjs';
+import { STATUS_OPTIONS, CUSTOM_FIELDS } from '../config.mjs';
+
+// The GitHub Projects v2 API does not allow replacing the built-in Status field
+// options atomically ("Position has already been taken" error). We create a custom
+// "Etapa" field with the RFC-001 kanban columns instead, and configure the board
+// view to group by it.
+const ETAPA_FIELD = {
+  name: 'Etapa',
+  dataType: 'SINGLE_SELECT',
+  options: STATUS_OPTIONS,
+};
+
+export async function setupProject(token, owner, repo, projectTitle, spinner) {
+  spinner.message('Buscando IDs do owner e repositório...');
+  const [ownerId, repositoryId] = await Promise.all([
+    getOwnerNodeId(token, owner),
+    getRepoNodeId(token, owner, repo),
+  ]);
+
+  spinner.message('Criando GitHub Project...');
+  const { projectId, projectNumber, projectUrl } = await createProject(token, ownerId, projectTitle);
+
+  spinner.message('Criando campos customizados...');
+  const selectFields = CUSTOM_FIELDS.filter(f => f.dataType === 'SINGLE_SELECT');
+  const textFields = CUSTOM_FIELDS.filter(f => f.dataType === 'TEXT');
+  const allFields = [ETAPA_FIELD, ...selectFields];
+
+  // Sequential creation: the GitHub Projects v2 API raises "Position has already
+  // been taken" when multiple SINGLE_SELECT fields are created concurrently.
+  // Capturamos id + opções de cada campo num mapa `fields` (nome → {id, options})
+  // para o .spec-wave.json — o comando `issue` usa isso para setar Etapa e Work Item Type.
+  const fields = {};
+  for (const f of allFields) {
+    spinner.message(`Criando campo "${f.name}"...`);
+    fields[f.name] = await createSingleSelectField(token, projectId, f.name, f.options);
+  }
+  for (const f of textFields) {
+    spinner.message(`Criando campo "${f.name}"...`);
+    await createTextField(token, projectId, f.name);
+  }
+
+  const result = { projectId, projectNumber, projectUrl, fields };
+
+  spinner.message('Vinculando projeto ao repositório...');
+  try {
+    await linkProjectToRepo(token, projectId, repositoryId);
+  } catch (err) {
+    // Linking is cosmetic (shows project in repo's Projects tab).
+    // It requires `repo` scope in addition to `project`. Skip gracefully.
+    spinner.message('');
+    return { ...result, linkWarning: err.message };
+  }
+
+  return result;
+}

package/src/templates/issue/plan-template.md

@@ -0,0 +1,35 @@
+---
+name: "Plano Técnico (plan.md)"
+about: "Plano técnico de uma Feature. Gerado automaticamente ao mover para a coluna 📋 Plan."
+title: "[FEATURE] "
+labels: "[FEATURE]"
+assignees: ""
+---
+
+# Frontend
+
+<!-- Componentes, rotas, estados, integrações de UI -->
+
+# Backend
+
+<!-- Endpoints, serviços, regras de negócio -->
+
+# Banco de dados
+
+<!-- Migrations, tabelas, índices, queries relevantes -->
+
+# Infraestrutura
+
+<!-- Configurações de ambiente, variáveis, serviços externos -->
+
+# Segurança
+
+<!-- Autenticação, autorização, validações críticas -->
+
+# Testes
+
+<!-- Estratégia de testes: unitários, integração, E2E -->
+
+# Estimativa (Story Points)
+
+<!-- 1 / 2 / 3 / 5 / 8 / 13 / 21 -->