adi_dev_workflow 1.3.0 → 1.4.0

package/frameworks/skills/sdd-tech-direction-expert/SKILL.md

@@ -20,6 +20,20 @@ Estilo: Objetivo. Contextualizado. Perguntas curtas com opções baseadas no cod
 
 ---
 
+# Paths dos Artefatos
+
+> **OBRIGATÓRIO**: Antes de salvar qualquer artefato, leia `.claude/config/ai-framework-config.yaml` seção `sdd` e use os paths ali definidos.
+
+Paths definidos no config (para referência):
+
+| Artefato | Path |
+|----------|------|
+| tech_direction | `docs/specs/{feature}/{version}/tech_direction.md` |
+
+Substitua `{feature}` pelo nome da feature em kebab-case e `{version}` pela versão (ex: `v1`) identificados a partir do path do PRD recebido como argumento.
+
+---
+
 # Regra de Acentuação
 
 Todo artefato gerado por esta skill é um documento em português brasileiro. Todo conteúdo textual (títulos, descrições, instruções, regras, mensagens) deve usar acentuação correta do pt-BR:
@@ -188,7 +202,7 @@ Estas regras sao **absolutas** e nao podem ser violadas em nenhuma circunstancia
 
 O Tech Direction e salvo **na mesma pasta** do PRD aprovado. O versionamento ja foi definido pelo PRD:
 
-- Se o PRD esta em `docs/feature-x/v1/prd.md`, o tech_direction vai em `docs/feature-x/v1/tech_direction.md`
+- Se o PRD esta em `docs/specs/feature-x/v1/prd.md`, o tech_direction vai em `docs/specs/feature-x/v1/tech_direction.md`
 - **NAO crie nova versao** — use a mesma pasta do PRD fornecido como argumento
 
 ---
@@ -197,10 +211,11 @@ O Tech Direction e salvo **na mesma pasta** do PRD aprovado. O versionamento ja
 
 **ANTES de apresentar o Tech Direction ao usuario**, voce DEVE:
 
-1. **Identificar o diretorio** do PRD fornecido (ex: `docs/feature-x/v1/`)
-2. **Remover todos os comentarios `<!-- LLM-ONLY: ... -->`** do conteudo antes de salvar
-3. **Salvar o arquivo fisico** em: `docs/[nome-feature]/vN/tech_direction.md` (mesmo diretorio do PRD)
-4. **Confirmar** que o arquivo foi criado com sucesso
+1. **Ler o config** `.claude/config/ai-framework-config.yaml` secao `sdd.tech_direction` para obter o path
+2. **Identificar o diretorio** do PRD fornecido (ex: `docs/specs/feature-x/v1/`)
+3. **Remover todos os comentarios `<!-- LLM-ONLY: ... -->`** do conteudo antes de salvar
+4. **Salvar o arquivo fisico** em: `docs/specs/[nome-feature]/[versao]/tech_direction.md` (mesmo diretorio do PRD)
+5. **Confirmar** que o arquivo foi criado com sucesso
 
 ---
 
@@ -209,7 +224,7 @@ O Tech Direction e salvo **na mesma pasta** do PRD aprovado. O versionamento ja
 Apos salvar o arquivo fisico, apresente **apenas um resumo compacto**. NAO exiba o tech_direction completo no terminal.
 
 ```
-Arquivo salvo em: docs/[nome-feature]/vN/tech_direction.md
+Arquivo salvo em: docs/specs/[nome-feature]/[versao]/tech_direction.md
 
 ## Resumo do Tech Direction
 - **Decisoes:** [lista curta]

package/frameworks/skills/sdd-tech-spec-expert/SKILL.md

@@ -8,6 +8,22 @@ Responsabilidade: Transformar PRDs aprovados em especificações técnicas compl
 
 ---
 
+# Paths dos Artefatos
+
+> **OBRIGATÓRIO**: Antes de salvar qualquer artefato, leia `.claude/config/ai-framework-config.yaml` seção `sdd` e use os paths ali definidos.
+
+Paths definidos no config (para referência):
+
+| Artefato | Path |
+|----------|------|
+| prd (leitura) | `docs/specs/{feature}/{version}/prd.md` |
+| tech_direction (leitura, opcional) | `docs/specs/{feature}/{version}/tech_direction.md` |
+| spec_tech (escrita) | `docs/specs/{feature}/{version}/spec_tech.md` |
+
+Substitua `{feature}` pelo nome da feature em kebab-case e `{version}` pela versão (ex: `v1`) identificados a partir do path do PRD recebido como argumento.
+
+---
+
 # Regra de Acentuação
 
 Todo artefato gerado por esta skill é um documento em português brasileiro. Todo conteúdo textual (títulos, descrições, instruções, regras, mensagens) deve usar acentuação correta do pt-BR:
@@ -57,7 +73,7 @@ O SPEC_TECH responde: **COMO a solução será implementada tecnicamente?**
 **ANTES de definir o SPEC_TECH**, você DEVE obrigatoriamente:
 
 ### 1. Verificar Tech Direction (opcional)
-- Buscar em: `docs/[nome-feature]/vN/tech_direction.md` (onde vN é a versão mais recente)
+- Buscar em: `docs/specs/[nome-feature]/[versão]/tech_direction.md` (onde vN é a versão mais recente)
 - Se existir, **use como ponto de partida** para decisões técnicas
 - O tech_direction contém decisões já tomadas, tecnologias sugeridas, padrões preferidos e restrições
 - Você pode **complementar, ajustar ou questionar** qualquer item — não é uma ordem, é um direcionamento
@@ -107,7 +123,7 @@ O usuário pode criar um arquivo **`tech_direction.md`** na pasta da feature **a
 
 ### O que é
 
-É um arquivo estruturado localizado em `docs/[nome-feature]/vN/tech_direction.md` com as seguintes seções:
+É um arquivo estruturado localizado em `docs/specs/[nome-feature]/[versão]/tech_direction.md` com as seguintes seções:
 
 | Seção | O que contém |
 |-------|-------------|
@@ -124,7 +140,7 @@ O template completo está em: [tech_direction-template.md](templates/tech_direct
 **ANTES de iniciar as perguntas**, você DEVE buscar o arquivo:
 
 ```
-docs/[nome-feature]/vN/tech_direction.md
+docs/specs/[nome-feature]/[versão]/tech_direction.md
 ```
 
 - **Se existir**: use como ponto de partida para decisões técnicas
@@ -223,7 +239,7 @@ A seção 14 é preenchida pelo **comando orquestrador** (`/sdd:generate-spec-te
 Após coletar todas as decisões:
 1. Gere o SPEC_TECH completo (todas as 16 seções) usando as respostas coletadas
 2. Preencha a seção 15 (Arquivos Envolvidos) baseado na pesquisa do codebase
-3. **Salve o arquivo** em `docs/[nome-feature]/vN/spec_tech.md`
+3. **Salve o arquivo** em `docs/specs/[nome-feature]/[versão]/spec_tech.md`
 4. Apresente ao usuário para validação final
 
 ### Regras do Processo
@@ -288,9 +304,9 @@ O template completo está em: [spec_tech_template.md](templates/spec_tech_templa
 **ANTES de apresentar o SPEC_TECH ao usuário**, você DEVE:
 
 1. **Identificar o nome da feature** a partir do PRD (kebab-case, letras minúsculas, sem espaços)
-2. **Criar diretório** se não existir: `docs/[nome-feature]/vN/`
+2. **Criar diretório** se não existir: `docs/specs/[nome-feature]/[versão]/`
 3. **Remover todos os comentários `<!-- LLM-ONLY: ... -->`** do conteúdo antes de salvar — são instruções internas do template e NÃO devem aparecer no arquivo gerado
-4. **Salvar o arquivo físico** em: `docs/[nome-feature]/vN/spec_tech.md`
+4. **Salvar o arquivo físico** em: `docs/specs/[nome-feature]/[versão]/spec_tech.md`
 5. **Confirmar** que o arquivo foi criado com sucesso
 
 ---
@@ -300,7 +316,7 @@ O template completo está em: [spec_tech_template.md](templates/spec_tech_templa
 Após salvar o arquivo físico:
 
 ```
-Arquivo salvo em: docs/[nome-feature]/vN/spec_tech.md
+Arquivo salvo em: docs/specs/[nome-feature]/[versão]/spec_tech.md
 
 Essa especificação técnica está aprovada? (sim/não)
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adi_dev_workflow",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Install SDD, miniStack and TaskCard development frameworks for Claude Code and Cursor",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -92,10 +92,35 @@ export async function run(argv) {
 
   console.log(`\nInstalling to ${ideLabel} ...\n`);
 
-  const summary = await install({ cwd, target, frameworks });
+  const summary = await install({
+    cwd,
+    target,
+    frameworks,
+    confirmOverwrite: async (labels) => {
+      console.log(`  Os seguintes ${labels.length} itens ja existem em ${ideLabel} e serao SOBRESCRITOS:\n`);
+      for (const l of labels) console.log(`    - ${l}`);
+      console.log('');
+      const res = await prompts({
+        type: 'confirm',
+        name: 'ok',
+        message: 'Deseja continuar e sobrescrever?',
+        initial: true,
+      });
+      return res.ok === true;
+    },
+  });
+
+  if (summary.cancelled) {
+    console.log('\n  Install cancelled.\n');
+    return;
+  }
 
   console.log(`  Done!\n`);
-  console.log(`  ${summary.skills} skills + ${summary.commands} commands + ${summary.templates} templates + ${summary.agents} agents + ${summary.config} config installed.\n`);
+  console.log(`  ${summary.skills} skills + ${summary.commands} commands + ${summary.templates} templates + ${summary.agents} agents + ${summary.config} config installed.`);
+  if (summary.overwritten > 0) {
+    console.log(`  ${summary.overwritten} item(s) sobrescritos.`);
+  }
+  console.log('');
 
   // Usage hints
   const hints = [];

package/src/installer.js

@@ -6,64 +6,176 @@ import { transformContent } from './transformer.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const FRAMEWORKS_DIR = join(__dirname, '..', 'frameworks');
 
-const FRAMEWORK_MAP = {
-  sdd: {
-    commands: 'sdd',
-    skills: ['sdd-prd-expert', 'sdd-spec-tech-expert', 'sdd-task-plan-expert', 'sdd-qa-expert'],
-  },
-  ministack: {
-    commands: 'ministack',
-    skills: ['ministack-intent-expert', 'ministack-scope-expert', 'ministack-expert', 'ministack-qa-expert'],
-  },
-  taskcard: {
-    commands: 'taskcard',
-    skills: ['taskcard-expert', 'taskcard-qa-expert'],
-  },
-  shared: {
-    commands: null, // root-level commands
-    skills: [],
-  },
-};
-
 const IDE_DIRS = {
   claude: '.claude',
   cursor: '.cursor',
 };
 
-/**
- * Copy a directory recursively, applying transformation.
- */
+// Prefixos usados para rotear skills e commands ao framework correto.
+// Qualquer skill sem prefixo conhecido vai para 'shared'.
+const FRAMEWORK_PREFIXES = {
+  sdd: 'sdd',
+  ministack: 'ministack',
+  taskcard: 'taskcard',
+};
+
+async function exists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function listDirs(dir) {
+  if (!(await exists(dir))) return [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+}
+
+async function listFiles(dir) {
+  if (!(await exists(dir))) return [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  return entries.filter((e) => e.isFile()).map((e) => e.name);
+}
+
+function skillFramework(skillName) {
+  for (const [fw, prefix] of Object.entries(FRAMEWORK_PREFIXES)) {
+    if (skillName === prefix || skillName.startsWith(prefix + '-')) return fw;
+  }
+  return 'shared';
+}
+
+async function copyFile(src, dest, target) {
+  await mkdir(dirname(dest), { recursive: true });
+  if (src.endsWith('.md')) {
+    const content = await readFile(src, 'utf-8');
+    const transformed = transformContent(content, target);
+    await writeFile(dest, transformed, 'utf-8');
+  } else {
+    const content = await readFile(src);
+    await writeFile(dest, content);
+  }
+}
+
 async function copyDir(src, dest, target) {
   await mkdir(dest, { recursive: true });
   const entries = await readdir(src, { withFileTypes: true });
-
   for (const entry of entries) {
     const srcPath = join(src, entry.name);
     const destPath = join(dest, entry.name);
-
     if (entry.isDirectory()) {
       await copyDir(srcPath, destPath, target);
-    } else if (entry.name.endsWith('.md')) {
-      const content = await readFile(srcPath, 'utf-8');
-      const transformed = transformContent(content, target);
-      await writeFile(destPath, transformed, 'utf-8');
     } else {
-      const content = await readFile(srcPath);
-      await writeFile(destPath, content);
+      await copyFile(srcPath, destPath, target);
     }
   }
 }
 
+async function countMarkdownRecursive(dir) {
+  let count = 0;
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) count += await countMarkdownRecursive(full);
+    else if (entry.name.endsWith('.md')) count++;
+  }
+  return count;
+}
+
 /**
- * Check if a path exists.
+ * Constroi o plano de instalacao varrendo frameworks/ e mapeando cada item
+ * (skill, command, agent, template, config) para seu destino no IDE.
+ * Cada item e marcado com `overwrite: true` se o destino ja existir.
  */
-async function exists(path) {
-  try {
-    await stat(path);
-    return true;
-  } catch {
-    return false;
+async function buildPlan({ cwd, target, frameworks }) {
+  const ideDir = join(cwd, IDE_DIRS[target]);
+  const selected = new Set(frameworks);
+  const items = [];
+
+  // Skills: detectadas automaticamente por prefixo
+  const skillNames = await listDirs(join(FRAMEWORKS_DIR, 'skills'));
+  for (const name of skillNames) {
+    const fw = skillFramework(name);
+    if (!selected.has(fw)) continue;
+    items.push({
+      category: 'skills',
+      kind: 'dir',
+      src: join(FRAMEWORKS_DIR, 'skills', name),
+      dest: join(ideDir, 'skills', name),
+      label: `skills/${name}`,
+    });
+  }
+
+  // Commands: subdir por framework + arquivos root-level para 'shared'
+  const commandDirs = await listDirs(join(FRAMEWORKS_DIR, 'commands'));
+  for (const name of commandDirs) {
+    if (!FRAMEWORK_PREFIXES[name] || !selected.has(name)) continue;
+    items.push({
+      category: 'commands',
+      kind: 'dir',
+      src: join(FRAMEWORKS_DIR, 'commands', name),
+      dest: join(ideDir, 'commands', name),
+      label: `commands/${name}/`,
+    });
+  }
+  if (selected.has('shared')) {
+    const rootCmds = await listFiles(join(FRAMEWORKS_DIR, 'commands'));
+    for (const name of rootCmds) {
+      if (!name.endsWith('.md')) continue;
+      items.push({
+        category: 'commands',
+        kind: 'file',
+        src: join(FRAMEWORKS_DIR, 'commands', name),
+        dest: join(ideDir, 'commands', name),
+        label: `commands/${name}`,
+      });
+    }
+  }
+
+  // Agents, templates, config: pertencem a 'shared'
+  if (selected.has('shared')) {
+    for (const name of await listFiles(join(FRAMEWORKS_DIR, 'agents'))) {
+      if (!name.endsWith('.md')) continue;
+      items.push({
+        category: 'agents',
+        kind: 'file',
+        src: join(FRAMEWORKS_DIR, 'agents', name),
+        dest: join(ideDir, 'agents', name),
+        label: `agents/${name}`,
+      });
+    }
+    for (const name of await listFiles(join(FRAMEWORKS_DIR, 'templates'))) {
+      if (!name.endsWith('.md')) continue;
+      items.push({
+        category: 'templates',
+        kind: 'file',
+        src: join(FRAMEWORKS_DIR, 'templates', name),
+        dest: join(ideDir, 'templates', name),
+        label: `templates/${name}`,
+      });
+    }
+    for (const name of await listFiles(join(FRAMEWORKS_DIR, 'config'))) {
+      items.push({
+        category: 'config',
+        kind: 'file',
+        src: join(FRAMEWORKS_DIR, 'config', name),
+        dest: join(ideDir, 'config', name),
+        label: `config/${name}`,
+      });
+    }
+  }
+
+  for (const item of items) {
+    item.overwrite = await exists(item.dest);
   }
+
+  return { ideDir, items };
+}
+
+export async function planInstall(options) {
+  return buildPlan(options);
 }
 
 /**
@@ -73,81 +185,48 @@ async function exists(path) {
  * @param {string} options.cwd - Current working directory
  * @param {'claude'|'cursor'} options.target - Target IDE
  * @param {string[]} options.frameworks - Frameworks to install ('sdd', 'ministack', 'taskcard', 'shared')
- * @returns {Object} Summary of installed items
+ * @param {(labels: string[]) => Promise<boolean>} [options.confirmOverwrite] - Called when items will be overwritten
+ * @returns {Object} Summary of installed items (or { cancelled: true })
  */
-export async function install({ cwd, target, frameworks }) {
-  const ideDir = join(cwd, IDE_DIRS[target]);
-  const commandsDir = join(ideDir, 'commands');
-  const skillsDir = join(ideDir, 'skills');
-  const templatesDir = join(ideDir, 'templates');
-  const agentsDir = join(ideDir, 'agents');
-
-  const summary = { commands: 0, skills: 0, templates: 0, agents: 0, config: 0 };
-
-  for (const fw of frameworks) {
-    const config = FRAMEWORK_MAP[fw];
-    if (!config) continue;
-
-    // Copy commands
-    if (fw === 'shared') {
-      // Root-level commands (generate-prompt.md, sync-tasks-to-linear.md)
-      await mkdir(commandsDir, { recursive: true });
-      const srcCmds = join(FRAMEWORKS_DIR, 'commands');
-      const entries = await readdir(srcCmds, { withFileTypes: true });
-
-      for (const entry of entries) {
-        if (entry.isFile() && entry.name.endsWith('.md')) {
-          const content = await readFile(join(srcCmds, entry.name), 'utf-8');
-          const transformed = transformContent(content, target);
-          await writeFile(join(commandsDir, entry.name), transformed, 'utf-8');
-          summary.commands++;
-        }
-      }
+export async function install({ cwd, target, frameworks, confirmOverwrite }) {
+  const plan = await buildPlan({ cwd, target, frameworks });
+  const overwrites = plan.items.filter((i) => i.overwrite);
 
-      // Shared templates
-      const srcTemplates = join(FRAMEWORKS_DIR, 'templates');
-      if (await exists(srcTemplates)) {
-        await copyDir(srcTemplates, templatesDir, target);
-        const tplEntries = await readdir(srcTemplates);
-        summary.templates += tplEntries.filter((f) => f.endsWith('.md')).length;
-      }
-
-      // Shared agents
-      const srcAgents = join(FRAMEWORKS_DIR, 'agents');
-      if (await exists(srcAgents)) {
-        await copyDir(srcAgents, agentsDir, target);
-        const agentEntries = await readdir(srcAgents);
-        summary.agents += agentEntries.filter((f) => f.endsWith('.md')).length;
-      }
+  if (overwrites.length > 0 && typeof confirmOverwrite === 'function') {
+    const ok = await confirmOverwrite(overwrites.map((i) => i.label));
+    if (!ok) return { cancelled: true };
+  }
 
-      // Config file
-      const srcConfig = join(FRAMEWORKS_DIR, 'config', 'ai-framework-config.yaml');
-      if (await exists(srcConfig)) {
-        const configDestDir = join(ideDir, 'config');
-        await mkdir(configDestDir, { recursive: true });
-        const content = await readFile(srcConfig);
-        await writeFile(join(configDestDir, 'ai-framework-config.yaml'), content);
-        summary.config = 1;
-      }
+  const summary = {
+    skills: 0,
+    commands: 0,
+    templates: 0,
+    agents: 0,
+    config: 0,
+    overwritten: overwrites.length,
+  };
+
+  for (const item of plan.items) {
+    if (item.kind === 'dir') {
+      await copyDir(item.src, item.dest, target);
     } else {
-      // Framework-specific commands
-      if (config.commands) {
-        const srcCmdDir = join(FRAMEWORKS_DIR, 'commands', config.commands);
-        const destCmdDir = join(commandsDir, config.commands);
-        await copyDir(srcCmdDir, destCmdDir, target);
-        const entries = await readdir(srcCmdDir);
-        summary.commands += entries.filter((f) => f.endsWith('.md')).length;
-      }
+      await copyFile(item.src, item.dest, target);
+    }
 
-      // Framework-specific skills
-      for (const skillName of config.skills) {
-        const srcSkillDir = join(FRAMEWORKS_DIR, 'skills', skillName);
-        const destSkillDir = join(skillsDir, skillName);
-        if (await exists(srcSkillDir)) {
-          await copyDir(srcSkillDir, destSkillDir, target);
-          summary.skills++;
-        }
+    if (item.category === 'skills') {
+      summary.skills++;
+    } else if (item.category === 'commands') {
+      if (item.kind === 'dir') {
+        summary.commands += await countMarkdownRecursive(item.src);
+      } else {
+        summary.commands++;
       }
+    } else if (item.category === 'agents') {
+      summary.agents++;
+    } else if (item.category === 'templates') {
+      summary.templates++;
+    } else if (item.category === 'config') {
+      summary.config++;
     }
   }