@brunosps00/dev-workflow 1.0.4 → 1.0.6

package/lib/agents.js

@@ -0,0 +1,410 @@
+const fs = require('fs');
+const path = require('path');
+const { ensureDir, readJson, writeFile, log } = require('./utils');
+
+const SCAFFOLD_DIR = path.join(__dirname, '..', 'scaffold');
+const REGISTRY_PATH = path.join(SCAFFOLD_DIR, 'agent-registry.json');
+
+const AGENT_TARGETS = {
+  claude: {
+    dir: '.claude/agents',
+    fileName: (name) => `${name}.md`,
+    render: renderClaudeAgent,
+  },
+  opencode: {
+    dir: '.opencode/agent',
+    fileName: (name) => `${name}.md`,
+    render: renderOpenCodeAgent,
+  },
+  agents: {
+    dir: '.agents/agents',
+    fileName: (name) => `${name}.md`,
+    render: renderFallbackAgent,
+  },
+  copilot: {
+    dir: '.github/agents',
+    fileName: (name) => `${name}.agent.md`,
+    render: renderCopilotAgent,
+  },
+};
+
+const LEGACY_AGENT_TARGETS = {
+  copilot: {
+    dir: '.github/copilot/agents',
+    fileName: (name) => `${name}.agent.md`,
+  },
+};
+
+const REQUIRED_AGENT_FIELDS = [
+  'name',
+  'module',
+  'description',
+  'mode',
+  'context_mode',
+  'tool_policy',
+  'max_turns',
+  'input_budget_words',
+  'output_budget_words',
+  'parallel_safe',
+  'handoff_required',
+  'skill_policy',
+  'recommended_for',
+  'avoid_when',
+];
+
+function readAgentRegistry() {
+  const registry = readJson(REGISTRY_PATH, null);
+  if (!registry || !Array.isArray(registry.agents)) {
+    throw new Error('Invalid scaffold/agent-registry.json');
+  }
+  return registry;
+}
+
+function validateAgentRegistry(registry = readAgentRegistry()) {
+  const issues = [];
+  const warnings = [];
+  if (registry.schema_version !== '2.0') {
+    issues.push('Agent registry must use schema_version 2.0.');
+  }
+
+  const names = new Set();
+  for (const agent of registry.agents || []) {
+    for (const field of REQUIRED_AGENT_FIELDS) {
+      if (agent[field] === undefined || agent[field] === null || agent[field] === '') {
+        issues.push(`Agent ${agent.name || '<unnamed>'} is missing required field: ${field}`);
+      }
+    }
+    if (names.has(agent.name)) issues.push(`Duplicate agent name: ${agent.name}`);
+    names.add(agent.name);
+
+    if (!Array.isArray(agent.recommended_for)) {
+      issues.push(`Agent ${agent.name} recommended_for must be an array.`);
+    }
+    if (!Array.isArray(agent.avoid_when)) {
+      issues.push(`Agent ${agent.name} avoid_when must be an array.`);
+    }
+    if (agent.mode === 'read-only' && agent.tool_policy !== 'read-only') {
+      issues.push(`Read-only agent ${agent.name} must use tool_policy read-only.`);
+    }
+    if (agent.output_budget_words > 1500) {
+      warnings.push(`Agent ${agent.name} output budget is above 1500 words.`);
+    }
+  }
+
+  for (const [commandName, agents] of Object.entries(registry.commands || {})) {
+    if (!Array.isArray(agents)) {
+      issues.push(`Agent registry command ${commandName} must map to an array.`);
+      continue;
+    }
+    for (const agentName of agents) {
+      if (!names.has(agentName)) issues.push(`Agent registry references missing agent: ${agentName}`);
+    }
+  }
+
+  return { issues, warnings };
+}
+
+function selectAgents(modules) {
+  const registry = readAgentRegistry();
+  const validation = validateAgentRegistry(registry);
+  if (validation.issues.length) {
+    throw new Error(`Invalid scaffold/agent-registry.json:\n- ${validation.issues.join('\n- ')}`);
+  }
+  const selectedModules = new Set(modules || []);
+  return registry.agents.filter((agent) => selectedModules.has(agent.module));
+}
+
+function generateAgents(projectRoot, modules, force = false) {
+  const results = { created: 0, skipped: 0, overwritten: 0, files: [] };
+  const agents = selectAgents(modules);
+
+  if (force) removeLegacyAgentTargets(projectRoot, agents);
+
+  for (const agent of agents) {
+    const source = readAgentSource(agent);
+    for (const target of Object.values(AGENT_TARGETS)) {
+      const dest = path.join(projectRoot, target.dir, target.fileName(agent.name));
+      const status = writeFile(dest, target.render(agent, source), force);
+      results[status]++;
+      results.files.push(dest);
+      log(status, dest);
+    }
+  }
+
+  writeAgentIndex(projectRoot, agents, force);
+  const indexPath = path.join(projectRoot, '.agents', 'agents', 'README.md');
+  results.files.push(indexPath);
+
+  return results;
+}
+
+function readAgentSource(agent) {
+  const src = path.join(SCAFFOLD_DIR, 'agents', agent.module, `${agent.name}.md`);
+  if (!fs.existsSync(src)) {
+    throw new Error(`Agent source missing: ${path.relative(process.cwd(), src)}`);
+  }
+  const raw = fs.readFileSync(src, 'utf-8');
+  const parsed = parseMarkdownFrontmatter(raw);
+  return {
+    path: src,
+    metadata: parsed.metadata,
+    body: parsed.body.trim(),
+  };
+}
+
+function parseMarkdownFrontmatter(raw) {
+  if (!raw.startsWith('---\n')) return { metadata: {}, body: raw };
+  const end = raw.indexOf('\n---', 4);
+  if (end === -1) return { metadata: {}, body: raw };
+  const metadata = {};
+  const frontmatter = raw.slice(4, end).trim();
+  for (const line of frontmatter.split('\n')) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!match) continue;
+    metadata[match[1]] = match[2].replace(/^["']|["']$/g, '');
+  }
+  return {
+    metadata,
+    body: raw.slice(end + 4).replace(/^\s+/, ''),
+  };
+}
+
+function renderClaudeAgent(agent, source) {
+  const tools = claudeToolsFor(agent, source);
+  const lines = [
+    '---',
+    `name: ${agent.name}`,
+    `description: "${yamlString(agent.description)}"`,
+    `tools: ${tools.join(', ')}`,
+    `model: ${source.metadata.model || 'sonnet'}`,
+    `permissionMode: ${agent.tool_policy === 'read-only' ? 'plan' : 'default'}`,
+    `maxTurns: ${agent.max_turns}`,
+    '---',
+    '',
+    renderContract(agent, 'Claude Code project subagent'),
+    '',
+    source.body,
+    '',
+  ];
+  return lines.join('\n');
+}
+
+function renderOpenCodeAgent(agent, source) {
+  const canWrite = agent.tool_policy !== 'read-only';
+  const lines = [
+    '---',
+    'mode: subagent',
+    `description: "${yamlString(agent.description)}"`,
+    `steps: ${agent.max_turns}`,
+    'permission:',
+    `  edit: ${canWrite ? 'allow' : 'deny'}`,
+    `  write: ${canWrite ? 'allow' : 'deny'}`,
+    `  bash: ${agent.tool_policy === 'read-only' ? 'deny' : 'allow'}`,
+    '---',
+    '',
+    renderContract(agent, 'OpenCode project subagent'),
+    '',
+    source.body,
+    '',
+  ];
+  return lines.join('\n');
+}
+
+function renderCopilotAgent(agent, source) {
+  const tools = copilotToolsFor(agent);
+  const lines = [
+    '---',
+    `name: ${agent.name}`,
+    `description: "${yamlString(agent.description)}"`,
+    `tools: ${tools.join(', ')}`,
+    '---',
+    '',
+    renderContract(agent, 'GitHub Copilot custom agent'),
+    '',
+    source.body,
+    '',
+  ];
+  return lines.join('\n');
+}
+
+function renderFallbackAgent(agent, source) {
+  const lines = [
+    '---',
+    `name: ${agent.name}`,
+    `description: "${yamlString(agent.description)}"`,
+    `mode: ${agent.mode}`,
+    `context_mode: ${agent.context_mode}`,
+    `tool_policy: ${agent.tool_policy}`,
+    `max_turns: ${agent.max_turns}`,
+    `input_budget_words: ${agent.input_budget_words}`,
+    `output_budget_words: ${agent.output_budget_words}`,
+    `parallel_safe: ${agent.parallel_safe}`,
+    '---',
+    '',
+    renderContract(agent, 'Fallback prompt profile'),
+    '',
+    source.body,
+    '',
+  ];
+  return lines.join('\n');
+}
+
+function renderContract(agent, targetLabel) {
+  return [
+    `# ${agent.name}`,
+    '',
+    `Provider target: ${targetLabel}.`,
+    '',
+    '## Dispatch Contract',
+    '',
+    `- Context mode: \`${agent.context_mode}\`.`,
+    `- Tool policy: \`${agent.tool_policy}\`.`,
+    `- Max turns: ${agent.max_turns}.`,
+    `- Input budget: ${agent.input_budget_words} words.`,
+    `- Output budget: ${agent.output_budget_words} words.`,
+    `- Parallel safe: ${agent.parallel_safe ? 'yes' : 'no'}.`,
+    `- Handoff required: ${agent.handoff_required ? 'yes' : 'no'}.`,
+    `- Skill policy: \`${agent.skill_policy}\`; do not preload large skills.`,
+    '',
+    '## Use When',
+    ...agent.recommended_for.map((item) => `- ${item}.`),
+    '',
+    '## Do Not Use When',
+    ...agent.avoid_when.map((item) => `- ${item}.`),
+    '',
+    '## Input Packet Expected',
+    '',
+    '- Objective and stop condition.',
+    '- Allowed files, folders, commands, and write boundaries.',
+    '- Relevant constraints from `.dw/rules/`, `.dw/intel/`, or the parent session.',
+    '- Expected return packet shape and verification command, when applicable.',
+    '',
+    '## Context Rules',
+    '',
+    '- Do not request or paste the full parent transcript.',
+    '- Read only the files needed for the objective.',
+    '- Summarize logs; include only failing lines, paths, commands, and decisions.',
+    '',
+    '## Tool/Write Boundaries',
+    '',
+    toolBoundary(agent),
+    '',
+    '## Return Packet',
+    '',
+    '- Result: pass, findings, changed files, or blocked.',
+    '- Files read and files changed.',
+    '- Decisions made and risks that remain.',
+    '- Verification run, including command and outcome.',
+    '- Recommended next step for the parent session.',
+    '',
+    '## Stop Conditions',
+    '',
+    '- Stop when the requested packet is complete.',
+    '- Stop if required context exceeds the input budget.',
+    '- Stop if the task needs broader architecture, product, or permission decisions.',
+  ].join('\n');
+}
+
+function toolBoundary(agent) {
+  if (agent.tool_policy === 'read-only') {
+    return '- Read-only. Do not edit, write, delete, or format files.';
+  }
+  if (agent.tool_policy === 'qa-write') {
+    return '- Write only QA artifacts, test scripts, traces, screenshots, and reports unless the parent explicitly assigns a fix.';
+  }
+  if (agent.tool_policy === 'shell-limited') {
+    return '- Shell commands are allowed only for inspection and targeted verification. Do not edit files unless explicitly assigned.';
+  }
+  return '- Edits are allowed only inside the files or module boundaries named in the input packet.';
+}
+
+function claudeToolsFor(agent, source) {
+  if (source.metadata.tools) {
+    return source.metadata.tools.split(',').map((tool) => tool.trim()).filter(Boolean);
+  }
+  return agent.tool_policy === 'read-only'
+    ? ['Read', 'Grep', 'Glob']
+    : ['Read', 'Write', 'Edit', 'Bash', 'Grep', 'Glob'];
+}
+
+function copilotToolsFor(agent) {
+  return agent.tool_policy === 'read-only'
+    ? ['read', 'grep']
+    : ['read', 'edit', 'terminal'];
+}
+
+function yamlString(value) {
+  return String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+function writeAgentIndex(projectRoot, agents, force) {
+  const lines = [
+    '# dev-workflow Agents',
+    '',
+    'These files are fallback prompt profiles for harnesses that do not expose native project subagents.',
+    'Claude Code uses `.claude/agents/`; OpenCode uses `.opencode/agent/`; Copilot receives `.github/agents/*.agent.md`.',
+    'Codex should treat this directory as delegable profiles when subagents are available, or as a manual prompt pack otherwise.',
+    '',
+    '| Agent | Module | Mode | Context | Output Budget | Purpose |',
+    '|---|---|---|---|---:|---|',
+  ];
+
+  for (const agent of agents) {
+    lines.push(`| \`${agent.name}\` | \`${agent.module}\` | \`${agent.mode}\` | \`${agent.context_mode}\` | ${agent.output_budget_words} words | ${agent.description} |`);
+  }
+
+  const content = lines.join('\n') + '\n';
+  writeFile(path.join(projectRoot, '.agents', 'agents', 'README.md'), content, force);
+}
+
+function listExpectedAgentFiles(projectRoot, modules) {
+  const files = [];
+  for (const agent of selectAgents(modules)) {
+    for (const target of Object.values(AGENT_TARGETS)) {
+      files.push(path.join(projectRoot, target.dir, target.fileName(agent.name)));
+    }
+  }
+  files.push(path.join(projectRoot, '.agents', 'agents', 'README.md'));
+  return files;
+}
+
+function listLegacyAgentFiles(projectRoot, modules) {
+  const files = [];
+  for (const agent of selectAgents(modules)) {
+    for (const target of Object.values(LEGACY_AGENT_TARGETS)) {
+      files.push(path.join(projectRoot, target.dir, target.fileName(agent.name)));
+    }
+  }
+  return files;
+}
+
+function ensureAgentDirs(projectRoot) {
+  for (const target of Object.values(AGENT_TARGETS)) {
+    ensureDir(path.join(projectRoot, target.dir));
+  }
+}
+
+function removeLegacyAgentTargets(projectRoot, agents) {
+  for (const target of Object.values(LEGACY_AGENT_TARGETS)) {
+    for (const agent of agents) {
+      const file = path.join(projectRoot, target.dir, target.fileName(agent.name));
+      if (fs.existsSync(file)) fs.rmSync(file);
+    }
+    const dir = path.join(projectRoot, target.dir);
+    if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  }
+}
+
+module.exports = {
+  AGENT_TARGETS,
+  LEGACY_AGENT_TARGETS,
+  readAgentRegistry,
+  validateAgentRegistry,
+  selectAgents,
+  generateAgents,
+  listExpectedAgentFiles,
+  listLegacyAgentFiles,
+  ensureAgentDirs,
+};

package/lib/constants.js

@@ -2,7 +2,7 @@ const COMMANDS = {
   en: [
     { name: 'dw-adr', description: 'Records an architectural decision and the trade-offs accepted, before they get lost.' },
     { name: 'dw-analyze-project', description: 'Scans the repo to learn its stack and conventions, then writes the rules other commands rely on.' },
-    { name: 'dw-autopilot', description: 'Trigger when user asks to implement, build, create, or add a feature non-trivially. Runs full PRD-to-PR pipeline with three gates. Use --from-prd <slug> to resume from an existing PRD (e.g., after a /dw-bugfix safety-valve escalation), skipping Steps 1-4 and starting at GATE 1.' },
+    { name: 'dw-autopilot', description: 'Trigger when user asks to implement, build, create, or add a feature non-trivially. First invocation plans and stops; second invocation resumes via dw-goal, then commit and PR.' },
     { name: 'dw-brainstorm', description: 'Refine an idea against the product\'s existing features. Modes: default ideation, --research (multi-source cited research), --refactor (Fowler code-smell catalog), --onepager, --council.' },
     { name: 'dw-bugfix', description: 'Trigger when user reports a bug, pastes an error, or describes broken behavior. Triages with three questions, then fixes or routes to PRD.' },
     { name: 'dw-commit', description: 'Trigger when implementation is complete and pending changes need to be committed. Atomic commits with Conventional Commits messages.' },
@@ -10,7 +10,10 @@ const COMMANDS = {
     { name: 'dw-find-skills', description: 'Searches the npx skills ecosystem for a skill matching what you need, vets it, and installs it where you choose.' },
     { 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-goal', description: 'Trigger when long-running implementation work needs a durable objective. Portable Codex-style goal contract; used by autopilot after planning.' },
     { 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,12 +26,16 @@ 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': [
     { name: 'dw-adr', description: 'Registra uma decisao arquitetural e os trade-offs aceitos, antes que se percam.' },
     { name: 'dw-analyze-project', description: 'Escaneia o repo para aprender stack e convencoes, e escreve as regras que os outros commands usam.' },
-    { name: 'dw-autopilot', description: 'Trigger quando usuario pede pra implementar, criar ou adicionar uma feature nao-trivial. Roda pipeline completo PRD-ao-PR com tres gates. Use --from-prd <slug> para retomar de um PRD existente (ex: apos escalacao do safety valve do /dw-bugfix), pulando Etapas 1-4 e comecando no GATE 1.' },
+    { name: 'dw-autopilot', description: 'Trigger quando usuario pede pra implementar, criar ou adicionar uma feature nao-trivial. Primeira invocacao planeja e para; segunda retoma via dw-goal, depois commit e PR.' },
     { name: 'dw-brainstorm', description: 'Refina uma ideia contra features existentes do produto. Modos: ideacao default, --research (research multi-fonte citada), --refactor (catalogo de code smells Fowler), --onepager, --council.' },
     { name: 'dw-bugfix', description: 'Trigger quando usuario reporta bug, cola erro ou descreve comportamento quebrado. Tria com tres perguntas, depois corrige ou roteia pra PRD.' },
     { name: 'dw-commit', description: 'Trigger quando implementacao esta completa e ha mudancas pendentes pra commit. Commits atomicos com mensagens Conventional Commits.' },
@@ -36,7 +43,10 @@ const COMMANDS = {
     { name: 'dw-find-skills', description: 'Busca no ecossistema npx skills uma skill que resolva o que voce precisa, valida e instala onde voce escolher.' },
     { 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-goal', description: 'Trigger quando trabalho longo precisa de objetivo duravel. Contrato portavel estilo Codex goal; usado pelo autopilot apos o planejamento.' },
     { 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 +59,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 };