@brunosps00/dev-workflow 1.0.4 → 1.0.6

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 };

package/lib/skill-registry.js

@@ -0,0 +1,109 @@
+const fs = require('fs');
+const path = require('path');
+const { readJson } = require('./utils');
+
+const SCAFFOLD_DIR = path.join(__dirname, '..', 'scaffold');
+const REGISTRY_PATH = path.join(SCAFFOLD_DIR, 'skill-registry.json');
+const SKILLS_DIR = path.join(SCAFFOLD_DIR, 'skills');
+
+const VALID_KINDS = new Set(['protocol', 'domain-pack', 'recipe-pack', 'asset-pack']);
+const VALID_LOAD_POLICIES = new Set(['always-small', 'lazy-references', 'opt-in-runtime']);
+
+function readSkillRegistry() {
+  const registry = readJson(REGISTRY_PATH, null);
+  if (!registry || !Array.isArray(registry.skills)) {
+    throw new Error('Invalid scaffold/skill-registry.json');
+  }
+  return registry;
+}
+
+function listScaffoldSkillNames() {
+  if (!fs.existsSync(SKILLS_DIR)) return [];
+  return fs
+    .readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function validateSkillRegistry() {
+  const registry = readSkillRegistry();
+  const issues = [];
+  const warnings = [];
+  const entriesByName = new Map();
+  const scaffoldNames = new Set(listScaffoldSkillNames());
+
+  for (const entry of registry.skills) {
+    validateEntry(entry, issues);
+    if (entriesByName.has(entry.name)) {
+      issues.push(`Skill registry duplicates entry: ${entry.name}`);
+    }
+    entriesByName.set(entry.name, entry);
+
+    if (!scaffoldNames.has(entry.name)) {
+      issues.push(`Skill registry references missing scaffold skill: ${entry.name}`);
+      continue;
+    }
+
+    const skillPath = path.join(SKILLS_DIR, entry.name, 'SKILL.md');
+    if (!fs.existsSync(skillPath)) {
+      issues.push(`Scaffold skill missing SKILL.md: ${entry.name}`);
+      continue;
+    }
+
+    const size = fs.statSync(skillPath).size;
+    if (entry.context_limit && size > entry.context_limit) {
+      warnings.push(`Skill ${entry.name} SKILL.md is ${size} bytes; registry limit is ${entry.context_limit}`);
+    }
+
+    if (entry.load_policy === 'always-small' && size > 8000) {
+      warnings.push(`Skill ${entry.name} is marked always-small but SKILL.md is ${size} bytes`);
+    }
+  }
+
+  for (const skillName of scaffoldNames) {
+    if (!entriesByName.has(skillName)) {
+      issues.push(`Scaffold skill missing from registry: ${skillName}`);
+    }
+  }
+
+  return { issues, warnings, registry };
+}
+
+function validateEntry(entry, issues) {
+  for (const field of ['name', 'kind', 'tier', 'owner', 'trigger', 'expected_output', 'load_policy', 'context_limit']) {
+    if (entry[field] === undefined || entry[field] === null || entry[field] === '') {
+      issues.push(`Skill registry entry ${entry.name || '(unknown)'} missing field: ${field}`);
+    }
+  }
+
+  if (entry.kind && !VALID_KINDS.has(entry.kind)) {
+    issues.push(`Skill registry entry ${entry.name} has invalid kind: ${entry.kind}`);
+  }
+
+  if (entry.load_policy && !VALID_LOAD_POLICIES.has(entry.load_policy)) {
+    issues.push(`Skill registry entry ${entry.name} has invalid load_policy: ${entry.load_policy}`);
+  }
+
+  if (typeof entry.context_limit !== 'number' || entry.context_limit <= 0) {
+    issues.push(`Skill registry entry ${entry.name} must set a positive numeric context_limit`);
+  }
+}
+
+function listInstalledSkillNames(projectRoot) {
+  const installedDir = path.join(projectRoot, '.agents', 'skills');
+  if (!fs.existsSync(installedDir)) return [];
+  return fs
+    .readdirSync(installedDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(installedDir, entry.name, 'SKILL.md')))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+module.exports = {
+  REGISTRY_PATH,
+  readSkillRegistry,
+  validateSkillRegistry,
+  listScaffoldSkillNames,
+  listInstalledSkillNames,
+};