@brunosps00/dev-workflow 1.0.4 → 1.0.5

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

package/lib/subtasks.js

@@ -0,0 +1,264 @@
+const fs = require('fs');
+const path = require('path');
+const { ensureDir, writeFile } = require('./utils');
+const { readAgentRegistry } = require('./agents');
+
+const SUBTASKS_RELATIVE_DIR = path.join('.dw', 'subtasks');
+
+function run(argv = []) {
+  const action = argv[0];
+  const flags = parseFlags(argv.slice(1));
+  const projectRoot = process.cwd();
+
+  switch (action) {
+    case 'create':
+      createSubtask(projectRoot, flags);
+      break;
+    case 'complete':
+      completeSubtask(projectRoot, flags);
+      break;
+    case 'consume':
+      consumeSubtasks(projectRoot);
+      break;
+    case 'list':
+      listSubtasks(projectRoot);
+      break;
+    case undefined:
+    case 'help':
+    case '--help':
+    case '-h':
+      printHelp();
+      break;
+    default:
+      throw new Error(`Unknown subtask action: ${action}`);
+  }
+}
+
+function createSubtask(projectRoot, flags) {
+  const agent = required(flags, 'agent');
+  const goal = required(flags, 'goal');
+  validateAgent(agent);
+  ensureSubtaskLayout(projectRoot);
+
+  const now = new Date();
+  const stamp = now.toISOString().replace(/[-:]/g, '').replace(/\..+$/, 'Z');
+  const slug = `${stamp}-${slugify(goal)}`;
+  const dir = path.join(projectRoot, SUBTASKS_RELATIVE_DIR, 'pending', slug);
+  ensureDir(dir);
+
+  const task = [
+    `# Subtask: ${goal}`,
+    '',
+    `- Slug: \`${slug}\``,
+    `- Agent: \`${agent}\``,
+    `- Created: ${now.toISOString()}`,
+    '',
+    '## Objective',
+    goal,
+    '',
+    '## Allowed Files And Sources',
+    flags.files || 'Parent must fill this before dispatch if the boundary is not obvious.',
+    '',
+    '## Constraints',
+    flags.constraints || 'Use project rules. Do not request or paste the full parent transcript.',
+    '',
+    '## Expected Output',
+    flags.output || 'Structured handoff with result, files read, files changed, decisions, risks, verification, next steps, and blockers.',
+    '',
+    '## Context Budget',
+    flags.budget || 'Use the agent registry default. Return only summarized logs and relevant paths.',
+    '',
+    '## Stop Condition',
+    flags.stop || 'Stop when the expected output packet is complete or the scope exceeds the packet.',
+    '',
+    '## Handoff Command',
+    '',
+    `When complete, write a handoff markdown file and run:`,
+    '',
+    '```bash',
+    `npx @brunosps00/dev-workflow subtask complete --slug=${slug} --file=<handoff.md>`,
+    '```',
+    '',
+  ].join('\n');
+
+  writeFile(path.join(dir, 'TASK.md'), task, true);
+  console.log(path.relative(projectRoot, path.join(dir, 'TASK.md')));
+}
+
+function completeSubtask(projectRoot, flags) {
+  const slug = required(flags, 'slug');
+  const handoffFile = required(flags, 'file');
+  const taskDir = resolvePendingSubtask(projectRoot, slug);
+  const sourcePath = path.resolve(projectRoot, handoffFile);
+  if (!fs.existsSync(sourcePath)) throw new Error(`Handoff file not found: ${handoffFile}`);
+
+  const content = fs.readFileSync(sourcePath, 'utf-8');
+  validateHandoff(content);
+  fs.writeFileSync(path.join(taskDir, 'HANDOFF.md'), content.endsWith('\n') ? content : `${content}\n`, 'utf-8');
+  console.log(path.relative(projectRoot, path.join(taskDir, 'HANDOFF.md')));
+}
+
+function consumeSubtasks(projectRoot) {
+  ensureSubtaskLayout(projectRoot);
+  const pendingDir = path.join(projectRoot, SUBTASKS_RELATIVE_DIR, 'pending');
+  const entries = fs.readdirSync(pendingDir, { withFileTypes: true }).filter((entry) => entry.isDirectory());
+  const ready = entries
+    .map((entry) => path.join(pendingDir, entry.name))
+    .filter((dir) => fs.existsSync(path.join(dir, 'HANDOFF.md')));
+
+  if (!ready.length) {
+    console.log('No completed subtasks to consume.');
+    return;
+  }
+
+  const date = new Date().toISOString().slice(0, 10);
+  const archiveDateDir = path.join(projectRoot, SUBTASKS_RELATIVE_DIR, 'archive', date);
+  ensureDir(archiveDateDir);
+
+  console.log('Subtask handoffs consumed:\n');
+  for (const dir of ready) {
+    const handoff = fs.readFileSync(path.join(dir, 'HANDOFF.md'), 'utf-8');
+    const summary = summarizeHandoff(handoff);
+    console.log(`- ${path.basename(dir)}: ${summary}`);
+    fs.renameSync(dir, path.join(archiveDateDir, path.basename(dir)));
+  }
+  console.log('\nArchive updated. Promote durable lessons manually into .dw/STATE.md, .dw/rules/, or .dw/intel/ when they should survive beyond this workstream.');
+}
+
+function listSubtasks(projectRoot) {
+  ensureSubtaskLayout(projectRoot);
+  const pendingDir = path.join(projectRoot, SUBTASKS_RELATIVE_DIR, 'pending');
+  const entries = fs.readdirSync(pendingDir, { withFileTypes: true }).filter((entry) => entry.isDirectory());
+  if (!entries.length) {
+    console.log('No pending subtasks.');
+    return;
+  }
+  for (const entry of entries) {
+    const dir = path.join(pendingDir, entry.name);
+    const state = fs.existsSync(path.join(dir, 'HANDOFF.md')) ? 'complete' : 'pending';
+    console.log(`${entry.name}\t${state}`);
+  }
+}
+
+function ensureSubtaskLayout(projectRoot) {
+  const root = path.join(projectRoot, SUBTASKS_RELATIVE_DIR);
+  ensureDir(path.join(root, 'pending'));
+  ensureDir(path.join(root, 'archive'));
+  const gitignore = ['pending/', 'archive/', '', '!/.gitignore', ''].join('\n');
+  writeFile(path.join(root, '.gitignore'), gitignore, false);
+}
+
+function validateAgent(agentName) {
+  const registry = readAgentRegistry();
+  if (!registry.agents.some((agent) => agent.name === agentName)) {
+    throw new Error(`Unknown agent: ${agentName}`);
+  }
+}
+
+function validateHandoff(content) {
+  const requiredHeadings = [
+    'Objective',
+    'Result',
+    'Files Read',
+    'Files Changed',
+    'Decisions',
+    'Risks',
+    'Verification',
+    'Next Steps',
+    'Blocked Or Not Done',
+  ];
+  const missing = requiredHeadings.filter((heading) => !new RegExp(`^##\\s+${escapeRegExp(heading)}\\b`, 'mi').test(content));
+  if (missing.length) {
+    throw new Error(`Handoff is missing required headings: ${missing.join(', ')}`);
+  }
+}
+
+function summarizeHandoff(content) {
+  const result = extractSection(content, 'Result') || firstNonEmptyLine(content) || 'handoff recorded';
+  const verification = extractSection(content, 'Verification');
+  const next = extractSection(content, 'Next Steps');
+  const parts = [compact(result)];
+  if (verification) parts.push(`verification: ${compact(verification)}`);
+  if (next) parts.push(`next: ${compact(next)}`);
+  return parts.join(' | ');
+}
+
+function extractSection(content, heading) {
+  const match = content.match(new RegExp(`^##\\s+${escapeRegExp(heading)}\\b\\s*\\n([\\s\\S]*?)(?=^##\\s+|\\s*$)`, 'mi'));
+  return match ? match[1].trim() : '';
+}
+
+function firstNonEmptyLine(content) {
+  return content.split('\n').map((line) => line.trim()).find(Boolean) || '';
+}
+
+function compact(value) {
+  return value.replace(/\s+/g, ' ').slice(0, 220);
+}
+
+function resolvePendingSubtask(projectRoot, slug) {
+  const pendingDir = path.join(projectRoot, SUBTASKS_RELATIVE_DIR, 'pending');
+  if (!fs.existsSync(pendingDir)) throw new Error('No pending subtasks directory. Run subtask create first.');
+  const direct = path.join(pendingDir, slug);
+  if (fs.existsSync(direct)) return direct;
+  const matches = fs.readdirSync(pendingDir).filter((entry) => entry === slug || entry.endsWith(`-${slug}`));
+  if (matches.length === 1) return path.join(pendingDir, matches[0]);
+  if (matches.length > 1) throw new Error(`Ambiguous slug: ${slug}`);
+  throw new Error(`Pending subtask not found: ${slug}`);
+}
+
+function parseFlags(args) {
+  const flags = {};
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (!arg.startsWith('--')) continue;
+    const raw = arg.slice(2);
+    if (raw.includes('=')) {
+      const [key, ...rest] = raw.split('=');
+      flags[key] = rest.join('=');
+    } else {
+      const next = args[index + 1];
+      flags[raw] = next && !next.startsWith('--') ? next : true;
+      if (flags[raw] === next) index++;
+    }
+  }
+  return flags;
+}
+
+function required(flags, name) {
+  if (!flags[name] || flags[name] === true) throw new Error(`Missing required flag: --${name}`);
+  return String(flags[name]);
+}
+
+function slugify(value) {
+  return String(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'subtask';
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function printHelp() {
+  console.log(`
+  dev-workflow subtask
+
+  Usage:
+    npx @brunosps00/dev-workflow subtask create --agent=<name> --goal="<goal>"
+    npx @brunosps00/dev-workflow subtask complete --slug=<slug> --file=<handoff.md>
+    npx @brunosps00/dev-workflow subtask consume
+    npx @brunosps00/dev-workflow subtask list
+`);
+}
+
+module.exports = {
+  run,
+  ensureSubtaskLayout,
+  createSubtask,
+  completeSubtask,
+  consumeSubtasks,
+  listSubtasks,
+};

package/lib/uninstall.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const { COMMANDS, PLATFORMS, MCP_SERVERS } = require('./constants');
+const { AGENT_TARGETS, LEGACY_AGENT_TARGETS, readAgentRegistry } = require('./agents');
 
 function run() {
   const projectRoot = process.cwd();
@@ -37,6 +38,7 @@ function run() {
   removeDir(path.join(projectRoot, '.dw', 'templates'), '.dw/templates/');
   removeDir(path.join(projectRoot, '.dw', 'references'), '.dw/references/');
   removeDir(path.join(projectRoot, '.dw', 'scripts'), '.dw/scripts/');
+  removeFile(path.join(projectRoot, '.dw', 'agent-registry.json'));
   console.log();
 
   // 2. Remove platform wrappers (only dw-* skills, not user skills)
@@ -56,23 +58,29 @@ function run() {
 
   // 3. Remove bundled skills from .agents/skills/
   console.log('  Bundled skills:');
-  // Currently-active bundled skills. If a skill is removed in a future release,
-  // add it to lib/removed-bundled-skills.js (append-only manifest used by
-  // migrate-skills.js during `dev-workflow update`); this list is just for
-  // wholesale uninstall.
-  const bundledSkills = [
-    'dw-ui-discipline',
-    'dw-testing-discipline',
-    'humanizer',
-    'remotion-best-practices',
-    'security-review',
-    'vercel-react-best-practices',
-  ];
+  const skillsDir = path.join(__dirname, '..', 'scaffold', 'skills');
+  const bundledSkills = fs.existsSync(skillsDir)
+    ? fs.readdirSync(skillsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name)
+    : [];
   for (const skill of bundledSkills) {
     removeDir(path.join(projectRoot, '.agents', 'skills', skill));
   }
   console.log();
 
+  // 3.5. Remove generated dev-workflow agents from platform folders.
+  console.log('  Agents:');
+  const registry = readAgentRegistry();
+  for (const agent of registry.agents) {
+    for (const target of Object.values(AGENT_TARGETS)) {
+      removeFile(path.join(projectRoot, target.dir, target.fileName(agent.name)));
+    }
+    for (const target of Object.values(LEGACY_AGENT_TARGETS)) {
+      removeFile(path.join(projectRoot, target.dir, target.fileName(agent.name)));
+    }
+  }
+  removeFile(path.join(projectRoot, '.agents', 'agents', 'README.md'));
+  console.log();
+
   // 4. Remove MCP servers from .claude/settings.json
   console.log('  MCP Servers:');
   const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
@@ -97,6 +105,7 @@ function run() {
 
   // 5. Remove .opencode/package.json
   removeFile(path.join(projectRoot, '.opencode', 'package.json'));
+  removeFile(path.join(projectRoot, '.dw', 'install-state.json'));
 
   // 6. Remove legacy .codex/skills/
   removeDir(path.join(projectRoot, '.codex', 'skills'));

package/lib/utils.js

@@ -60,6 +60,36 @@ function copyDir(srcDir, destDir, force = false, overridesDir = null) {
   return results;
 }
 
+function listFilesRecursive(dirPath) {
+  const files = [];
+  if (!fs.existsSync(dirPath)) return files;
+
+  for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+    const fullPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listFilesRecursive(fullPath));
+    } else if (entry.isFile()) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+function readJson(filePath, fallback = null) {
+  if (!fs.existsSync(filePath)) return fallback;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(filePath, value) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2) + '\n', 'utf-8');
+}
+
 /**
  * Upsert a delimited block inside an existing file.
  *
@@ -113,4 +143,15 @@ function log(status, filePath) {
   console.log(`  ${icon} ${relative} [${status}]`);
 }
 
-module.exports = { ensureDir, fileExists, copyFile, writeFile, copyDir, upsertDelimitedBlock, log };
+module.exports = {
+  ensureDir,
+  fileExists,
+  copyFile,
+  writeFile,
+  copyDir,
+  listFilesRecursive,
+  readJson,
+  writeJson,
+  upsertDelimitedBlock,
+  log,
+};

package/lib/wrappers.js

@@ -3,7 +3,7 @@ const { PLATFORMS } = require('./constants');
 const { writeFile, log } = require('./utils');
 
 function generateWrappers(projectRoot, commands, force = false) {
-  const results = { created: 0, skipped: 0, overwritten: 0 };
+  const results = { created: 0, skipped: 0, overwritten: 0, files: [] };
 
   for (const [platformName, platform] of Object.entries(PLATFORMS)) {
     for (const cmd of commands) {
@@ -18,6 +18,7 @@ function generateWrappers(projectRoot, commands, force = false) {
       const content = platform.wrapperTemplate(cmd.name, cmd.description);
       const status = writeFile(skillFile, content, force);
       results[status]++;
+      results.files.push(skillFile);
       log(status, skillFile);
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "AI-driven development workflow commands for any project. Scaffolds a complete PRD-to-PR pipeline with multi-platform AI assistant support.",
   "bin": {
     "dev-workflow": "./bin/dev-workflow.js"