@brunosps00/dev-workflow 1.0.4 → 1.0.5

package/lib/constants.js

@@ -11,6 +11,8 @@ const COMMANDS = {
     { name: 'dw-functional-doc', description: 'Maps screens and user flows into a functional doc, validated end-to-end with Playwright.' },
     { name: 'dw-generate-pr', description: 'Trigger when commits are ready and the branch needs a PR. Pushes branch and opens PR with summary + test plan + hard verify gate.' },
     { name: 'dw-help', description: 'Lists primary commands and the flows that connect them. Pass --advanced to see internal/hidden commands.' },
+    { name: 'dw-context-budget', description: 'Audits context overhead from commands, skills, agents, instructions, and MCPs; recommends token savings.' },
+    { name: 'dw-harness-audit', description: 'Runs a deterministic health scorecard for dev-workflow installation, agents, MCPs, gates, and context discipline.' },
     { name: 'dw-install-aws-skills', description: 'Trigger when user asks to install AWS expertise, setup AWS MCP server, or add AWS agent skills. Opt-in: clones curated skills from aws/agent-toolkit-for-aws into .agents/skills/aws/ and registers the unified AWS MCP Server (stdio via mcp-proxy-for-aws). Requires uv, aws cli, and AWS credentials.' },
     { name: 'dw-install-azure-skills', description: 'Trigger when user asks to install Azure expertise, setup Microsoft docs MCP, or add Azure agent skills. Opt-in: clones curated skills from MicrosoftDocs/Agent-Skills into .agents/skills/azure/ and registers the Microsoft Learn MCP server.' },
     { name: 'dw-intel', description: 'Codebase intelligence: query mode (default) answers questions citing .dw/intel/ + .dw/rules/; --build mode (re)builds the index.' },
@@ -23,6 +25,10 @@ const COMMANDS = {
     { name: 'dw-review', description: 'Trigger when user asks to review code, check quality, or verify PR readiness. Default runs L2 (PRD coverage) + L3 (code quality). Flags --coverage-only / --code-only / --bugfix <slug>.' },
     { name: 'dw-run', description: 'Trigger when user wants to execute tasks. Default runs all pending in dependency order; \'run <task-id>\' runs one; \'run --resume\' continues an interrupted plan.' },
     { name: 'dw-secure-audit', description: 'Unified security audit: OWASP + Trivy SCA/secret/IaC + lockfile + supply-chain compromise check. Hidden; auto-invoked by /dw-review and /dw-generate-pr.' },
+    { name: 'dw-skill-health', description: 'Audits installed skills and agents for bloat, duplication, missing references, and stale or unused modules.' },
+    { name: 'dw-subtask-start', description: 'Creates a minimal input packet for a subagent without injecting the parent transcript.' },
+    { name: 'dw-subtask-complete', description: 'Records a structured subagent handoff with result, files, decisions, risks, verification, and blockers.' },
+    { name: 'dw-subtask-resume', description: 'Consumes pending subagent handoffs, summarizes them for the parent, and archives the local packets.' },
     { name: 'dw-update', description: 'Updates dev-workflow to the latest npm release in-place, with a snapshot you can roll back to.' },
   ],
   'pt-br': [
@@ -37,6 +43,8 @@ const COMMANDS = {
     { name: 'dw-functional-doc', description: 'Mapeia telas e fluxos em um dossie funcional, validado E2E com Playwright.' },
     { name: 'dw-generate-pr', description: 'Trigger quando commits estao prontos e branch precisa de PR. Push da branch e abre PR com summary + test plan + hard verify gate.' },
     { name: 'dw-help', description: 'Lista comandos primarios e fluxos que os conectam. Passe --advanced para ver comandos internos/escondidos.' },
+    { name: 'dw-context-budget', description: 'Audita overhead de contexto em comandos, skills, agentes, instrucoes e MCPs; recomenda economia de tokens.' },
+    { name: 'dw-harness-audit', description: 'Roda um scorecard deterministico da instalacao dev-workflow, agentes, MCPs, gates e disciplina de contexto.' },
     { name: 'dw-install-aws-skills', description: 'Trigger quando usuario pede pra instalar expertise AWS, configurar MCP da AWS, ou adicionar agent skills AWS. Opt-in: clona skills curadas de aws/agent-toolkit-for-aws para .agents/skills/aws/ e registra o AWS MCP Server unificado (stdio via mcp-proxy-for-aws). Requer uv, aws cli e credenciais AWS.' },
     { name: 'dw-install-azure-skills', description: 'Trigger quando usuario pede pra instalar expertise Azure, configurar MCP do Microsoft docs, ou adicionar agent skills Azure. Opt-in: clona skills curadas de MicrosoftDocs/Agent-Skills para .agents/skills/azure/ e registra o Microsoft Learn MCP server.' },
     { name: 'dw-intel', description: 'Inteligencia do codebase: modo query (default) responde citando .dw/intel/ + .dw/rules/; modo --build (re)constroi indice.' },
@@ -49,6 +57,10 @@ const COMMANDS = {
     { name: 'dw-review', description: 'Trigger quando usuario pede pra revisar codigo, checar qualidade ou validar prontidao pra PR. Default roda L2 (cobertura PRD) + L3 (qualidade). Flags --coverage-only / --code-only / --bugfix <slug>.' },
     { name: 'dw-run', description: 'Trigger quando usuario quer executar tasks. Default roda todas pendentes em ordem de dependencia; \'run <task-id>\' roda uma; \'run --resume\' continua plan interrompido.' },
     { name: 'dw-secure-audit', description: 'Audit unificado de seguranca: OWASP + Trivy SCA/secret/IaC + lockfile + supply-chain compromise. Hidden; auto-invocado por /dw-review e /dw-generate-pr.' },
+    { name: 'dw-skill-health', description: 'Audita skills e agentes instalados por bloat, duplicacao, referencias quebradas e modulos sem uso.' },
+    { name: 'dw-subtask-start', description: 'Cria um input packet minimo para subagente sem injetar transcript bruto do parent.' },
+    { name: 'dw-subtask-complete', description: 'Registra handoff estruturado do subagente com resultado, arquivos, decisoes, riscos, verificacao e bloqueios.' },
+    { name: 'dw-subtask-resume', description: 'Consome handoffs pendentes de subagentes, resume para o parent e arquiva os pacotes locais.' },
     { name: 'dw-update', description: 'Atualiza o dev-workflow para o release mais recente no npm, com snapshot para rollback.' },
   ],
 };

package/lib/doctor.js

@@ -0,0 +1,213 @@
+const fs = require('fs');
+const path = require('path');
+const { COMMANDS, PLATFORMS, MCP_SERVERS } = require('./constants');
+const {
+  listExpectedAgentFiles,
+  listLegacyAgentFiles,
+  readAgentRegistry,
+  validateAgentRegistry,
+  AGENT_TARGETS,
+} = require('./agents');
+const { readInstallState, STATE_RELATIVE_PATH } = require('./install-state');
+const { validateSkillRegistry, readSkillRegistry } = require('./skill-registry');
+const removedCommands = require('./removed-commands');
+
+function run() {
+  const projectRoot = process.cwd();
+  const state = readInstallState(projectRoot);
+  const issues = [];
+  const warnings = [];
+
+  if (!state) {
+    issues.push(`Missing ${STATE_RELATIVE_PATH}. Run \`dev-workflow repair\`.`);
+  }
+
+  const lang = (state && state.lang) || 'en';
+  const modules = (state && state.modules) || ['core', 'security', 'frontend'];
+  const commands = COMMANDS[lang] || COMMANDS.en;
+
+  checkCommands(projectRoot, commands, issues);
+  checkWrappers(projectRoot, commands, issues);
+  checkAgents(projectRoot, modules, issues);
+  checkAgentRegistry(issues, warnings);
+  checkSubtaskLayout(projectRoot, issues);
+  checkSkillRegistry(projectRoot, issues, warnings);
+  checkMcp(projectRoot, issues);
+  checkLegacyCommands(projectRoot, warnings);
+
+  console.log('dev-workflow doctor\n');
+  if (issues.length === 0 && warnings.length === 0) {
+    console.log('PASS: managed commands, wrappers, agents, skills, and MCP config look healthy.');
+    return;
+  }
+
+  if (issues.length) {
+    console.log('Issues:');
+    for (const issue of issues) console.log(`- ${issue}`);
+    console.log();
+  }
+
+  if (warnings.length) {
+    console.log('Warnings:');
+    for (const warning of warnings) console.log(`- ${warning}`);
+    console.log();
+  }
+
+  console.log('Run `npx @brunosps00/dev-workflow repair` to reconcile managed files.');
+  if (issues.length) process.exitCode = 1;
+}
+
+function checkCommands(projectRoot, commands, issues) {
+  for (const cmd of commands) {
+    const file = path.join(projectRoot, '.dw', 'commands', `${cmd.name}.md`);
+    if (!fs.existsSync(file)) issues.push(`Missing command source: ${path.relative(projectRoot, file)}`);
+  }
+}
+
+function checkWrappers(projectRoot, commands, issues) {
+  for (const [, platform] of Object.entries(PLATFORMS)) {
+    for (const cmd of commands) {
+      const file = platform.flat
+        ? path.join(projectRoot, platform.dir, `${cmd.name}.md`)
+        : path.join(projectRoot, platform.dir, cmd.name, 'SKILL.md');
+      if (!fs.existsSync(file)) issues.push(`Missing wrapper: ${path.relative(projectRoot, file)}`);
+    }
+  }
+}
+
+function checkAgents(projectRoot, modules, issues) {
+  for (const file of listExpectedAgentFiles(projectRoot, modules)) {
+    if (!fs.existsSync(file)) issues.push(`Missing agent: ${path.relative(projectRoot, file)}`);
+  }
+  for (const file of listLegacyAgentFiles(projectRoot, modules)) {
+    if (fs.existsSync(file)) issues.push(`Legacy Copilot agent path still exists: ${path.relative(projectRoot, file)}`);
+  }
+  for (const file of listExpectedAgentFiles(projectRoot, modules)) {
+    if (fs.existsSync(file) && file.endsWith('.md') && fs.statSync(file).size > 8 * 1024) {
+      issues.push(`Agent prompt exceeds 8KB: ${path.relative(projectRoot, file)}`);
+    }
+  }
+  checkProviderAgentCompatibility(projectRoot, modules, issues);
+}
+
+function checkAgentRegistry(issues, warnings) {
+  const registry = readAgentRegistry();
+  const validation = validateAgentRegistry(registry);
+  issues.push(...validation.issues);
+  warnings.push(...validation.warnings);
+  const installedRegistryPath = path.join(process.cwd(), '.dw', 'agent-registry.json');
+  if (!fs.existsSync(installedRegistryPath)) {
+    issues.push(`Missing agent registry: ${path.relative(process.cwd(), installedRegistryPath)}`);
+  } else {
+    try {
+      const installedRegistry = JSON.parse(fs.readFileSync(installedRegistryPath, 'utf-8'));
+      if (installedRegistry.schema_version !== '2.0') {
+        issues.push('Installed agent registry must use schema_version 2.0.');
+      }
+    } catch {
+      issues.push(`Malformed agent registry: ${path.relative(process.cwd(), installedRegistryPath)}`);
+    }
+  }
+  const agentNames = new Set(registry.agents.map((agent) => agent.name));
+  for (const [commandName, agents] of Object.entries(registry.commands || {})) {
+    if (!COMMANDS.en.some((cmd) => cmd.name === commandName)) {
+      issues.push(`Agent registry references unknown command: ${commandName}`);
+    }
+    for (const agentName of agents) {
+      if (!agentNames.has(agentName)) {
+        issues.push(`Agent registry references missing agent: ${agentName}`);
+      }
+    }
+  }
+}
+
+function checkProviderAgentCompatibility(projectRoot, modules, issues) {
+  const expected = listExpectedAgentFiles(projectRoot, modules);
+  for (const file of expected) {
+    if (!fs.existsSync(file)) continue;
+    const rel = path.relative(projectRoot, file);
+    const content = fs.readFileSync(file, 'utf-8');
+    if (rel.startsWith(`${AGENT_TARGETS.copilot.dir}/`)) {
+      for (const unsupported of ['permissionMode:', 'maxTurns:', 'model:', 'mode: subagent']) {
+        if (content.includes(unsupported)) issues.push(`Copilot agent contains unsupported field ${unsupported} ${rel}`);
+      }
+    }
+    if (rel.startsWith(`${AGENT_TARGETS.claude.dir}/`) && !content.includes('permissionMode:')) {
+      issues.push(`Claude agent missing permissionMode: ${rel}`);
+    }
+    if (rel.startsWith(`${AGENT_TARGETS.opencode.dir}/`) && content.includes('\ntools:')) {
+      issues.push(`OpenCode agent should use permission instead of tools: ${rel}`);
+    }
+  }
+}
+
+function checkSubtaskLayout(projectRoot, issues) {
+  const gitignore = path.join(projectRoot, '.dw', 'subtasks', '.gitignore');
+  if (!fs.existsSync(gitignore)) issues.push(`Missing subtask gitignore: ${path.relative(projectRoot, gitignore)}`);
+}
+
+function checkSkillRegistry(projectRoot, issues, warnings) {
+  const validation = validateSkillRegistry();
+  issues.push(...validation.issues);
+  warnings.push(...validation.warnings);
+
+  const installedRegistryPath = path.join(projectRoot, '.dw', 'skill-registry.json');
+  if (!fs.existsSync(installedRegistryPath)) {
+    issues.push(`Missing skill registry: ${path.relative(projectRoot, installedRegistryPath)}`);
+  } else {
+    try {
+      const installedRegistry = JSON.parse(fs.readFileSync(installedRegistryPath, 'utf-8'));
+      const currentRegistry = readSkillRegistry();
+      if (installedRegistry.schema_version !== currentRegistry.schema_version) {
+        warnings.push('Installed skill registry schema differs from package registry; run repair.');
+      }
+      const installedNames = new Set((installedRegistry.skills || []).map((entry) => entry.name));
+      for (const entry of currentRegistry.skills) {
+        if (entry.bundled && !installedNames.has(entry.name)) {
+          warnings.push(`Installed skill registry missing bundled entry: ${entry.name}`);
+        }
+      }
+    } catch {
+      issues.push(`Malformed skill registry: ${path.relative(projectRoot, installedRegistryPath)}`);
+    }
+  }
+
+  const registry = readSkillRegistry();
+  for (const entry of registry.skills) {
+    if (!entry.bundled) continue;
+    const skillPath = path.join(projectRoot, '.agents', 'skills', entry.name, 'SKILL.md');
+    if (!fs.existsSync(skillPath)) {
+      issues.push(`Missing bundled skill: ${path.relative(projectRoot, skillPath)}`);
+    }
+  }
+}
+
+function checkMcp(projectRoot, issues) {
+  const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+  if (!fs.existsSync(settingsPath)) {
+    issues.push('Missing .claude/settings.json with MCP configuration');
+    return;
+  }
+
+  try {
+    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    for (const name of Object.keys(MCP_SERVERS)) {
+      if (!settings.mcpServers || !settings.mcpServers[name]) {
+        issues.push(`Missing MCP server: ${name}`);
+      }
+    }
+  } catch {
+    issues.push('Malformed .claude/settings.json');
+  }
+}
+
+function checkLegacyCommands(projectRoot, warnings) {
+  for (const entry of removedCommands) {
+    const file = path.join(projectRoot, '.dw', 'commands', `${entry.name}.md`);
+    if (fs.existsSync(file)) {
+      warnings.push(`Legacy command source still exists: ${path.relative(projectRoot, file)} -> ${entry.replacedBy}`);
+    }
+  }
+}
+
+module.exports = { run };

package/lib/init.js

@@ -1,38 +1,55 @@
 const path = require('path');
 const { COMMANDS } = require('./constants');
-const { ensureDir, copyDir, writeFile, upsertDelimitedBlock, log } = require('./utils');
+const { ensureDir, copyDir, writeFile, upsertDelimitedBlock, log, listFilesRecursive } = require('./utils');
 const { selectLanguage } = require('./prompts');
 const { generateWrappers } = require('./wrappers');
 const { installMCPs } = require('./mcp');
+const { generateAgents } = require('./agents');
 const { migrate: migrateGsd } = require('./migrate-gsd');
 const { migrate: migrateSkills } = require('./migrate-skills');
+const { hasExistingInstall, readInstallState, writeInstallState, listManagedFiles } = require('./install-state');
+const { resolveInstallSelection } = require('./profiles');
+const { ensureSubtaskLayout } = require('./subtasks');
 
 const SCAFFOLD_DIR = path.join(__dirname, '..', 'scaffold');
 
-async function run({ force = false, lang = null, mode = 'init' }) {
+async function run({ force = false, lang = null, mode = 'init', profile = null, modules = null }) {
   const projectRoot = process.cwd();
   const isUpdate = mode === 'update';
+  const isRepair = mode === 'repair';
+  const existingInstall = hasExistingInstall(projectRoot);
+  const priorState = readInstallState(projectRoot);
 
-  // In update mode, always overwrite managed files (commands, templates, references, scripts, skills)
-  // but never touch user files (rules, spec, MCPs)
-  const managedForce = isUpdate ? true : force;
+  // Update/repair and init over an existing dev-workflow install reconcile managed
+  // files to the current scaffold. Fresh init keeps normal non-destructive behavior.
+  const shouldReconcile = isUpdate || isRepair || (mode === 'init' && existingInstall);
+  const managedForce = shouldReconcile ? true : force;
 
-  console.log(`\n  dev-workflow ${isUpdate ? 'update' : 'init'}`);
+  console.log(`\n  dev-workflow ${isRepair ? 'repair' : (isUpdate ? 'update' : 'init')}`);
   console.log(`  ${'='.repeat(40)}\n`);
+  if (mode === 'init' && existingInstall) {
+    console.log('  Existing dev-workflow install detected; reconciling managed files.\n');
+  }
 
   // 0. GSD migration (idempotent; only runs if legacy GSD artifacts are detected)
   // 0.1. Skill migration: removed bundled skills + orphan dw-* wrappers (idempotent)
-  if (isUpdate) {
+  if (shouldReconcile) {
     migrateGsd(projectRoot);
     migrateSkills(projectRoot);
   }
 
   // 1. Select language
-  const selectedLang = await selectLanguage(lang);
+  const selectedLang = await selectLanguage(lang || (priorState && priorState.lang));
+  const selection = resolveInstallSelection({
+    profile: profile || (priorState && priorState.profile),
+    modules: modules || (priorState && Array.isArray(priorState.modules) ? priorState.modules.join(',') : null),
+  });
   console.log(`\n  Language: ${selectedLang}\n`);
+  console.log(`  Profile: ${selection.profile} (${selection.modules.join(', ')})\n`);
 
   const commands = COMMANDS[selectedLang];
   const langDir = path.join(SCAFFOLD_DIR, selectedLang);
+  const touchedFiles = [];
 
   // Track totals
   let totalCreated = 0;
@@ -49,6 +66,7 @@ async function run({ force = false, lang = null, mode = 'init' }) {
   totalCreated += cmdResults.created;
   totalSkipped += cmdResults.skipped;
   totalOverwritten += cmdResults.overwritten;
+  touchedFiles.push(...listFilesRecursive(path.join(projectRoot, '.dw', 'commands')));
   console.log(`    ${cmdResults.created} created, ${cmdResults.skipped} skipped, ${cmdResults.overwritten} overwritten\n`);
 
   // 3. Copy templates (override-aware: .dw/templates/overrides/<name> wins over scaffold core)
@@ -64,6 +82,7 @@ async function run({ force = false, lang = null, mode = 'init' }) {
   totalCreated += tplResults.created;
   totalSkipped += tplResults.skipped;
   totalOverwritten += tplResults.overwritten;
+  touchedFiles.push(...listFilesRecursive(templatesDir));
   console.log(`    ${tplResults.created} created, ${tplResults.skipped} skipped, ${tplResults.overwritten} overwritten\n`);
 
   // 3.1. Seed .dw/templates/overrides/ with README on first init (never overwritten)
@@ -78,6 +97,7 @@ async function run({ force = false, lang = null, mode = 'init' }) {
     );
     if (ovrStatus === 'created') totalCreated++;
     else totalSkipped++;
+    touchedFiles.push(overridesReadmeDest);
   }
 
   // 3.5. Copy references (language-specific)
@@ -92,6 +112,7 @@ async function run({ force = false, lang = null, mode = 'init' }) {
     totalCreated += refsResults.created;
     totalSkipped += refsResults.skipped;
     totalOverwritten += refsResults.overwritten;
+    touchedFiles.push(...listFilesRecursive(path.join(projectRoot, '.dw', 'references')));
     console.log(`    ${refsResults.created} created, ${refsResults.skipped} skipped, ${refsResults.overwritten} overwritten\n`);
   }
 
@@ -107,9 +128,46 @@ async function run({ force = false, lang = null, mode = 'init' }) {
     totalCreated += scriptsResults.created;
     totalSkipped += scriptsResults.skipped;
     totalOverwritten += scriptsResults.overwritten;
+    touchedFiles.push(...listFilesRecursive(path.join(projectRoot, '.dw', 'scripts')));
     console.log(`    ${scriptsResults.created} created, ${scriptsResults.skipped} skipped, ${scriptsResults.overwritten} overwritten\n`);
   }
 
+  // 3.7. Copy skill registry for agent-facing skill health audits.
+  const skillRegistrySrc = path.join(SCAFFOLD_DIR, 'skill-registry.json');
+  if (require('fs').existsSync(skillRegistrySrc)) {
+    console.log('  Skill registry:');
+    const skillRegistryDest = path.join(projectRoot, '.dw', 'skill-registry.json');
+    const registryStatus = writeFile(
+      skillRegistryDest,
+      require('fs').readFileSync(skillRegistrySrc, 'utf-8'),
+      managedForce
+    );
+    log(registryStatus, skillRegistryDest);
+    if (registryStatus === 'created') totalCreated++;
+    else if (registryStatus === 'overwritten') totalOverwritten++;
+    else totalSkipped++;
+    touchedFiles.push(skillRegistryDest);
+    console.log();
+  }
+
+  // 3.8. Copy agent registry for dispatch, budgets, and provider health audits.
+  const agentRegistrySrc = path.join(SCAFFOLD_DIR, 'agent-registry.json');
+  if (require('fs').existsSync(agentRegistrySrc)) {
+    console.log('  Agent registry:');
+    const agentRegistryDest = path.join(projectRoot, '.dw', 'agent-registry.json');
+    const registryStatus = writeFile(
+      agentRegistryDest,
+      require('fs').readFileSync(agentRegistrySrc, 'utf-8'),
+      managedForce
+    );
+    log(registryStatus, agentRegistryDest);
+    if (registryStatus === 'created') totalCreated++;
+    else if (registryStatus === 'overwritten') totalOverwritten++;
+    else totalSkipped++;
+    touchedFiles.push(agentRegistryDest);
+    console.log();
+  }
+
   // 4. Create .dw/rules/ with README
   if (!isUpdate) {
     console.log('  Rules:');
@@ -124,6 +182,7 @@ async function run({ force = false, lang = null, mode = 'init' }) {
     log(status, rulesReadmeDest);
     if (status === 'created') totalCreated++;
     else totalSkipped++;
+    touchedFiles.push(rulesReadmeDest);
     console.log();
   }
 
@@ -146,6 +205,7 @@ async function run({ force = false, lang = null, mode = 'init' }) {
       log(stateStatus, stateDestPath);
       if (stateStatus === 'created') totalCreated++;
       else totalSkipped++;
+      touchedFiles.push(stateDestPath);
     }
     console.log();
   }
@@ -158,8 +218,13 @@ async function run({ force = false, lang = null, mode = 'init' }) {
     const gitkeepStatus = writeFile(gitkeepPath, '', false);
     if (gitkeepStatus === 'created') totalCreated++;
     else totalSkipped++;
+    touchedFiles.push(gitkeepPath);
   }
 
+  // 5.3. Create local ephemeral subtask handoff directories.
+  ensureSubtaskLayout(projectRoot);
+  touchedFiles.push(path.join(projectRoot, '.dw', 'subtasks', '.gitignore'));
+
   // 5.5. Copy bundled skills to .agents/skills/
   const skillsSrcDir = path.join(SCAFFOLD_DIR, 'skills');
   if (require('fs').existsSync(skillsSrcDir)) {
@@ -172,9 +237,19 @@ async function run({ force = false, lang = null, mode = 'init' }) {
     totalCreated += skillsResults.created;
     totalSkipped += skillsResults.skipped;
     totalOverwritten += skillsResults.overwritten;
+    touchedFiles.push(...listFilesRecursive(path.join(projectRoot, '.agents', 'skills')));
     console.log(`    ${skillsResults.created} created, ${skillsResults.skipped} skipped, ${skillsResults.overwritten} overwritten\n`);
   }
 
+  // 5.6. Generate platform-native/fallback agents from the selected modules.
+  console.log('  Agents:');
+  const agentResults = generateAgents(projectRoot, selection.modules, managedForce);
+  totalCreated += agentResults.created;
+  totalSkipped += agentResults.skipped;
+  totalOverwritten += agentResults.overwritten;
+  touchedFiles.push(...agentResults.files);
+  console.log(`    ${agentResults.created} created, ${agentResults.skipped} skipped, ${agentResults.overwritten} overwritten\n`);
+
   // 5.7. Install CLAUDE.md + AGENTS.md with auto-trigger decision tree
   // Both files receive the same content (Claude Code reads CLAUDE.md; Codex/Copilot/OpenCode
   // converge on AGENTS.md). Merge-aware: user edits outside the dev-workflow markers are preserved.
@@ -191,6 +266,7 @@ async function run({ force = false, lang = null, mode = 'init' }) {
       if (status === 'created') totalCreated++;
       else if (status === 'updated') totalOverwritten++;
       else totalSkipped++;
+      touchedFiles.push(target);
     }
     console.log();
   }
@@ -201,6 +277,7 @@ async function run({ force = false, lang = null, mode = 'init' }) {
   const opcStatus = writeFile(opencodePackageJson, opencodeContent, false);
   if (opcStatus === 'created') totalCreated++;
   else totalSkipped++;
+  touchedFiles.push(opencodePackageJson);
 
   // 6.5. Clean up legacy .codex/skills/ (now served by .agents/skills/)
   const legacyCodexDir = path.join(projectRoot, '.codex', 'skills');
@@ -216,6 +293,7 @@ async function run({ force = false, lang = null, mode = 'init' }) {
   totalCreated += wrapperResults.created;
   totalSkipped += wrapperResults.skipped;
   totalOverwritten += wrapperResults.overwritten;
+  touchedFiles.push(...wrapperResults.files);
   console.log();
 
   // 9. Install MCPs (always, including updates)
@@ -223,6 +301,16 @@ async function run({ force = false, lang = null, mode = 'init' }) {
   const mcpResults = installMCPs(projectRoot);
   console.log(`    ${mcpResults.added} configured, ${mcpResults.skipped} already present\n`);
 
+  // 9.5. Persist install state for diagnostics and repair.
+  const installState = writeInstallState(projectRoot, {
+    lang: selectedLang,
+    profile: selection.profile,
+    modules: selection.modules,
+    platforms: ['claude', 'agents', 'opencode', 'copilot'],
+    managedFiles: listManagedFiles(projectRoot, touchedFiles),
+  });
+  console.log(`  Install state: ${path.relative(projectRoot, path.join(projectRoot, '.dw', 'install-state.json'))} (${installState.managed_files.length} files tracked)\n`);
+
   // 10. Summary
   console.log(`  ${'='.repeat(40)}`);
   console.log(`  Done! ${totalCreated} created, ${totalSkipped} skipped, ${totalOverwritten} overwritten`);

package/lib/install-state.js

@@ -0,0 +1,57 @@
+const fs = require('fs');
+const path = require('path');
+const pkg = require('../package.json');
+const { readJson, writeJson } = require('./utils');
+
+const STATE_RELATIVE_PATH = path.join('.dw', 'install-state.json');
+
+function statePath(projectRoot) {
+  return path.join(projectRoot, STATE_RELATIVE_PATH);
+}
+
+function readInstallState(projectRoot) {
+  return readJson(statePath(projectRoot), null);
+}
+
+function hasExistingInstall(projectRoot) {
+  return Boolean(
+    fs.existsSync(path.join(projectRoot, '.dw', 'commands')) ||
+    fs.existsSync(path.join(projectRoot, 'CLAUDE.md')) ||
+    fs.existsSync(path.join(projectRoot, 'AGENTS.md')) ||
+    readInstallState(projectRoot)
+  );
+}
+
+function writeInstallState(projectRoot, state) {
+  const existing = readInstallState(projectRoot);
+  const now = new Date().toISOString();
+  const next = {
+    schema_version: '1.0',
+    package: pkg.name,
+    version: pkg.version,
+    lang: state.lang,
+    profile: state.profile,
+    modules: state.modules || [],
+    platforms: state.platforms || [],
+    managed_files: state.managedFiles || [],
+    installed_at: existing && existing.installed_at ? existing.installed_at : now,
+    updated_at: now,
+  };
+  writeJson(statePath(projectRoot), next);
+  return next;
+}
+
+function listManagedFiles(projectRoot, relativeFiles) {
+  return relativeFiles
+    .filter(Boolean)
+    .map((filePath) => path.relative(projectRoot, filePath))
+    .sort();
+}
+
+module.exports = {
+  STATE_RELATIVE_PATH,
+  hasExistingInstall,
+  readInstallState,
+  writeInstallState,
+  listManagedFiles,
+};

package/lib/list-installed.js

@@ -0,0 +1,27 @@
+const path = require('path');
+const { readInstallState, STATE_RELATIVE_PATH } = require('./install-state');
+
+function run() {
+  const projectRoot = process.cwd();
+  const state = readInstallState(projectRoot);
+
+  if (!state) {
+    console.log(`No dev-workflow install state found at ${STATE_RELATIVE_PATH}.`);
+    console.log('Run `npx @brunosps00/dev-workflow init` or `update` to create it.');
+    return;
+  }
+
+  console.log('dev-workflow install\n');
+  console.log(`Root: ${projectRoot}`);
+  console.log(`Package: ${state.package || '@brunosps00/dev-workflow'}@${state.version || '(unknown)'}`);
+  console.log(`Language: ${state.lang || '(unknown)'}`);
+  console.log(`Profile: ${state.profile || '(unknown)'}`);
+  console.log(`Modules: ${(state.modules || []).join(', ') || '(none)'}`);
+  console.log(`Platforms: ${(state.platforms || []).join(', ') || '(none)'}`);
+  console.log(`Managed files tracked: ${(state.managed_files || []).length}`);
+  console.log(`Installed at: ${state.installed_at || '(unknown)'}`);
+  console.log(`Updated at: ${state.updated_at || '(unknown)'}`);
+  console.log(`State: ${path.join(projectRoot, STATE_RELATIVE_PATH)}`);
+}
+
+module.exports = { run };

package/lib/migrate-skills.js

@@ -28,8 +28,9 @@ const removedCommands = require('./removed-commands');
 function migrate(projectRoot) {
   const removed = scanRemovedBundledSkills(projectRoot);
   const orphans = scanOrphanCommandWrappers(projectRoot);
+  const commandSources = scanRemovedCommandSources(projectRoot);
 
-  if (removed.length === 0 && orphans.length === 0) {
+  if (removed.length === 0 && orphans.length === 0 && commandSources.length === 0) {
     return null; // silent — nothing to clean
   }
 
@@ -56,8 +57,16 @@ function migrate(projectRoot) {
     rmRecursive(entry.path);
   }
 
+  for (const entry of commandSources) {
+    const rel = path.relative(projectRoot, entry.path);
+    console.log(
+      `    \x1b[33m-\x1b[0m [legacy] Removing command source ${rel} (replaced in v${entry.removedIn} by \`${entry.replacedBy}\`)`
+    );
+    rmRecursive(entry.path);
+  }
+
   console.log();
-  return { removed: removed.length, orphans: orphans.length };
+  return { removed: removed.length, orphans: orphans.length, commandSources: commandSources.length };
 }
 
 function scanRemovedBundledSkills(projectRoot) {
@@ -128,6 +137,21 @@ function scanOrphanCommandWrappers(projectRoot) {
   return orphans;
 }
 
+function scanRemovedCommandSources(projectRoot) {
+  const matches = [];
+  const commandsDir = path.join(projectRoot, '.dw', 'commands');
+  if (!fs.existsSync(commandsDir)) return matches;
+
+  for (const entry of removedCommands) {
+    const target = path.join(commandsDir, `${entry.name}.md`);
+    if (fs.existsSync(target)) {
+      matches.push({ ...entry, path: target });
+    }
+  }
+
+  return matches;
+}
+
 function rmRecursive(target) {
   if (!fs.existsSync(target)) return;
   fs.rmSync(target, { recursive: true, force: true });

package/lib/profiles.js

@@ -0,0 +1,44 @@
+const PROFILES = {
+  core: {
+    description: 'Core workflow agents only.',
+    modules: ['core'],
+  },
+  standard: {
+    description: 'Core workflow plus security and frontend QA agents.',
+    modules: ['core', 'security', 'frontend'],
+  },
+  full: {
+    description: 'All bundled dev-workflow agents.',
+    modules: ['core', 'security', 'frontend', 'typescript', 'python', 'csharp', 'rust'],
+  },
+};
+
+const DEFAULT_PROFILE = 'standard';
+
+function parseCsv(value) {
+  if (!value || value === true) return [];
+  return String(value)
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function resolveInstallSelection({ profile, modules }) {
+  const selectedProfile = profile || DEFAULT_PROFILE;
+  if (!PROFILES[selectedProfile]) {
+    throw new Error(`Unknown profile: ${selectedProfile}. Valid profiles: ${Object.keys(PROFILES).join(', ')}`);
+  }
+
+  const explicitModules = parseCsv(modules);
+  const selectedModules = new Set(PROFILES[selectedProfile].modules);
+  for (const moduleName of explicitModules) {
+    selectedModules.add(moduleName);
+  }
+
+  return {
+    profile: selectedProfile,
+    modules: Array.from(selectedModules).sort(),
+  };
+}
+
+module.exports = { DEFAULT_PROFILE, PROFILES, resolveInstallSelection };