worclaude 1.0.0

package/src/data/agents.js

@@ -0,0 +1,164 @@
+export const UNIVERSAL_AGENTS = [
+  'plan-reviewer',
+  'code-simplifier',
+  'test-writer',
+  'build-validator',
+  'verify-app',
+];
+
+export const AGENT_CATALOG = {
+  'ui-reviewer': { model: 'sonnet', isolation: 'none', category: 'frontend', description: 'Reviews UI for consistency and accessibility' },
+  'style-enforcer': { model: 'haiku', isolation: 'none', category: 'frontend', description: 'Ensures design system compliance' },
+  'api-designer': { model: 'opus', isolation: 'none', category: 'backend', description: 'Reviews API design for RESTful conventions' },
+  'database-analyst': { model: 'sonnet', isolation: 'none', category: 'backend', description: 'Reviews database schemas and queries' },
+  'auth-auditor': { model: 'opus', isolation: 'none', category: 'backend', description: 'Audits authentication and authorization' },
+  'security-reviewer': { model: 'opus', isolation: 'none', category: 'quality', description: 'Reviews code for security vulnerabilities' },
+  'performance-auditor': { model: 'sonnet', isolation: 'none', category: 'quality', description: 'Analyzes code for performance issues' },
+  'bug-fixer': { model: 'sonnet', isolation: 'worktree', category: 'quality', description: 'Diagnoses and fixes bugs' },
+  'refactorer': { model: 'sonnet', isolation: 'worktree', category: 'quality', description: 'Refactors code to improve maintainability' },
+  'dependency-manager': { model: 'haiku', isolation: 'none', category: 'devops', description: 'Reviews dependency health and updates' },
+  'ci-fixer': { model: 'sonnet', isolation: 'worktree', category: 'devops', description: 'Diagnoses and fixes CI/CD failures' },
+  'docker-helper': { model: 'sonnet', isolation: 'none', category: 'devops', description: 'Reviews Docker configs for best practices' },
+  'deploy-validator': { model: 'sonnet', isolation: 'none', category: 'devops', description: 'Validates deployment readiness' },
+  'doc-writer': { model: 'sonnet', isolation: 'worktree', category: 'docs', description: 'Writes and updates documentation' },
+  'changelog-generator': { model: 'haiku', isolation: 'none', category: 'docs', description: 'Generates changelog from commits' },
+  'data-pipeline-reviewer': { model: 'sonnet', isolation: 'none', category: 'data', description: 'Reviews data pipeline correctness' },
+  'ml-experiment-tracker': { model: 'sonnet', isolation: 'none', category: 'data', description: 'Reviews ML experiment reproducibility' },
+  'prompt-engineer': { model: 'opus', isolation: 'none', category: 'data', description: 'Reviews and improves LLM prompts' },
+};
+
+export const CATEGORY_RECOMMENDATIONS = {
+  'Full-stack web application': ['ui-reviewer', 'api-designer', 'database-analyst', 'security-reviewer', 'bug-fixer', 'doc-writer'],
+  'Backend / API': ['api-designer', 'database-analyst', 'security-reviewer', 'auth-auditor', 'bug-fixer', 'performance-auditor'],
+  'Frontend / UI': ['ui-reviewer', 'style-enforcer', 'performance-auditor', 'bug-fixer'],
+  'CLI tool': ['bug-fixer', 'doc-writer', 'dependency-manager'],
+  'Data / ML / AI': ['data-pipeline-reviewer', 'ml-experiment-tracker', 'prompt-engineer', 'database-analyst'],
+  'Library / Package': ['doc-writer', 'dependency-manager', 'performance-auditor', 'refactorer', 'changelog-generator'],
+  'DevOps / Infrastructure': ['ci-fixer', 'docker-helper', 'deploy-validator', 'dependency-manager'],
+};
+
+export const COMMAND_FILES = [
+  'start',
+  'end',
+  'commit-push-pr',
+  'review-plan',
+  'techdebt',
+  'verify',
+  'compact-safe',
+  'status',
+  'update-claude-md',
+  'setup',
+];
+
+export const UNIVERSAL_SKILLS = [
+  'context-management',
+  'git-conventions',
+  'planning-with-files',
+  'review-and-handoff',
+  'prompt-engineering',
+  'verification',
+  'testing',
+  'claude-md-maintenance',
+  'subagent-usage',
+];
+
+export const TEMPLATE_SKILLS = [
+  'backend-conventions',
+  'frontend-design-system',
+  'project-patterns',
+];
+
+export const PROJECT_TYPES = [
+  'Full-stack web application',
+  'Backend / API',
+  'Frontend / UI',
+  'CLI tool',
+  'Data / ML / AI',
+  'Library / Package',
+  'DevOps / Infrastructure',
+];
+
+export const TECH_STACKS = [
+  { name: 'Python', value: 'python' },
+  { name: 'Node.js / TypeScript', value: 'node' },
+  { name: 'Rust', value: 'rust' },
+  { name: 'Go', value: 'go' },
+  { name: 'Other / None', value: 'other' },
+];
+
+export const FORMATTER_COMMANDS = {
+  python: 'ruff format . || true',
+  node: 'npx prettier --write . || true',
+  rust: 'cargo fmt || true',
+  go: 'gofmt -w . || true',
+};
+
+export const PROJECT_TYPE_DESCRIPTIONS = {
+  'Full-stack web application': 'Frontend + backend in one repo',
+  'Backend / API': 'Server, REST/GraphQL, no frontend',
+  'Frontend / UI': 'Client-side app, no backend',
+  'CLI tool': 'Command-line application',
+  'Data / ML / AI': 'Data pipelines, ML models, LLM apps',
+  'Library / Package': 'Reusable module published to npm/PyPI',
+  'DevOps / Infrastructure': 'Infrastructure, CI/CD, deployment',
+};
+
+export const AGENT_CATEGORIES = {
+  Backend: {
+    agents: ['api-designer', 'database-analyst', 'auth-auditor'],
+    description: 'api-designer, database-analyst, auth-auditor',
+  },
+  Frontend: {
+    agents: ['ui-reviewer', 'style-enforcer'],
+    description: 'ui-reviewer, style-enforcer',
+  },
+  DevOps: {
+    agents: ['ci-fixer', 'docker-helper', 'deploy-validator', 'dependency-manager'],
+    description: 'ci-fixer, docker-helper, deploy-validator, dependency-manager',
+  },
+  Quality: {
+    agents: ['bug-fixer', 'security-reviewer', 'performance-auditor', 'refactorer'],
+    description: 'bug-fixer, security-reviewer, performance-auditor, refactorer',
+  },
+  Documentation: {
+    agents: ['doc-writer', 'changelog-generator'],
+    description: 'doc-writer, changelog-generator',
+  },
+  'Data / AI': {
+    agents: ['data-pipeline-reviewer', 'ml-experiment-tracker', 'prompt-engineer'],
+    description: 'data-pipeline-reviewer, ml-experiment-tracker, prompt-engineer',
+  },
+};
+
+export const PROJECT_TYPE_TO_CATEGORIES = {
+  'Full-stack web application': ['Backend', 'Frontend', 'Quality', 'Documentation'],
+  'Backend / API': ['Backend', 'Quality'],
+  'Frontend / UI': ['Frontend', 'Quality'],
+  'CLI tool': ['Quality', 'Documentation'],
+  'Data / ML / AI': ['Data / AI', 'Backend'],
+  'Library / Package': ['Quality', 'Documentation'],
+  'DevOps / Infrastructure': ['DevOps'],
+};
+
+export const SPEC_MD_TEMPLATE_MAP = {
+  'Full-stack web application': 'spec-md-fullstack.md',
+  'Backend / API': 'spec-md-backend.md',
+  'Frontend / UI': 'spec-md-frontend.md',
+  'CLI tool': 'spec-md-cli.md',
+  'Data / ML / AI': 'spec-md-data.md',
+  'Library / Package': 'spec-md-library.md',
+  'DevOps / Infrastructure': 'spec-md-devops.md',
+};
+
+export const CONFIRMATION_STEPS = [
+  { name: 'Project name and description', value: 'projectInfo' },
+  { name: 'Project type', value: 'projectType' },
+  { name: 'Tech stack', value: 'techStack' },
+  { name: 'Agent selection', value: 'agents' },
+];
+
+export const NOTIFICATION_COMMANDS = {
+  linux: "notify-send 'Claude Code' 'Session needs attention' 2>/dev/null || true",
+  darwin: `osascript -e 'display notification "Session needs attention" with title "Claude Code"' 2>/dev/null || true`,
+  win32: `powershell -command "New-BurntToastNotification -Text 'Claude Code','Session needs attention'" 2>/dev/null || true`,
+};

package/src/index.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { initCommand } from './commands/init.js';
+import { upgradeCommand } from './commands/upgrade.js';
+import { statusCommand } from './commands/status.js';
+import { backupCommand } from './commands/backup.js';
+import { restoreCommand } from './commands/restore.js';
+import { diffCommand } from './commands/diff.js';
+
+const program = new Command();
+
+program
+  .name('worclaude')
+  .version('1.0.0')
+  .description('Scaffold a comprehensive Claude Code workflow into any project');
+
+program.showSuggestionAfterError(true);
+program.showHelpAfterError(true);
+
+program
+  .command('init')
+  .description('Initialize Claude workflow in the current project')
+  .action(initCommand);
+
+program
+  .command('upgrade')
+  .description('Update workflow components to the latest version')
+  .action(upgradeCommand);
+
+program
+  .command('status')
+  .description('Show current workflow installation status')
+  .action(statusCommand);
+
+program
+  .command('backup')
+  .description('Create a backup of current Claude setup')
+  .action(backupCommand);
+
+program
+  .command('restore')
+  .description('Restore Claude setup from a backup')
+  .action(restoreCommand);
+
+program
+  .command('diff')
+  .description('Compare current setup against installed workflow version')
+  .action(diffCommand);
+
+program.parse();

package/src/prompts/agent-selection.js

@@ -0,0 +1,99 @@
+import inquirer from 'inquirer';
+import {
+  UNIVERSAL_AGENTS,
+  AGENT_CATALOG,
+  AGENT_CATEGORIES,
+  PROJECT_TYPE_TO_CATEGORIES,
+} from '../data/agents.js';
+import * as display from '../utils/display.js';
+
+export async function promptAgentSelection(projectTypes) {
+  // Show universal agents (informational)
+  display.newline();
+  display.info('Universal agents (always installed):');
+  for (const agent of UNIVERSAL_AGENTS) {
+    display.success(agent);
+  }
+  display.newline();
+
+  // Derive pre-selected categories from project types
+  const preSelectedCategories = new Set();
+  for (const type of projectTypes) {
+    const cats = PROJECT_TYPE_TO_CATEGORIES[type] || [];
+    for (const cat of cats) {
+      preSelectedCategories.add(cat);
+    }
+  }
+
+  // Step 1: Category selection
+  const categoryNames = Object.keys(AGENT_CATEGORIES);
+  const { selectedCategories } = await inquirer.prompt([
+    {
+      type: 'checkbox',
+      name: 'selectedCategories',
+      message: 'Which agent categories do you need? (space to toggle)',
+      choices: categoryNames.map((cat) => ({
+        name: `${cat} — ${AGENT_CATEGORIES[cat].description}`,
+        value: cat,
+        checked: preSelectedCategories.has(cat),
+      })),
+    },
+  ]);
+
+  // Step 2: Fine-tune each selected category
+  const selected = [];
+
+  for (const cat of selectedCategories) {
+    const agentNames = AGENT_CATEGORIES[cat].agents;
+    const { selectedAgents } = await inquirer.prompt([
+      {
+        type: 'checkbox',
+        name: 'selectedAgents',
+        message: `Fine-tune ${cat} agents? (space to toggle, enter to accept defaults)`,
+        choices: agentNames.map((name) => ({
+          name: `${name} — ${AGENT_CATALOG[name].description}`,
+          value: name,
+          checked: true,
+        })),
+      },
+    ]);
+    selected.push(...selectedAgents);
+  }
+
+  // Step 3: Offer unselected categories
+  const unselectedCategories = categoryNames.filter((cat) => !selectedCategories.includes(cat));
+
+  if (unselectedCategories.length > 0) {
+    const { additionalCategories } = await inquirer.prompt([
+      {
+        type: 'checkbox',
+        name: 'additionalCategories',
+        message: 'Any other agent categories you\'d like to add? (space to toggle, enter to skip)',
+        choices: unselectedCategories.map((cat) => ({
+          name: `${cat} — ${AGENT_CATEGORIES[cat].description}`,
+          value: cat,
+        })),
+      },
+    ]);
+
+    for (const cat of additionalCategories) {
+      const agentNames = AGENT_CATEGORIES[cat].agents;
+      const { selectedAgents } = await inquirer.prompt([
+        {
+          type: 'checkbox',
+          name: 'selectedAgents',
+          message: `Fine-tune ${cat} agents? (space to toggle, enter to accept defaults)`,
+          choices: agentNames.map((name) => ({
+            name: `${name} — ${AGENT_CATALOG[name].description}`,
+            value: name,
+            checked: true,
+          })),
+        },
+      ]);
+      selected.push(...selectedAgents);
+    }
+  }
+
+  // Deduplicate
+  return [...new Set(selected)];
+}

package/src/prompts/claude-md-merge.js

@@ -0,0 +1,153 @@
+import inquirer from 'inquirer';
+import * as display from '../utils/display.js';
+
+const SECTION_DETECTORS = [
+  {
+    name: 'Key Files',
+    heading: '## Key Files',
+    test: (c) => /PROGRESS\.md/i.test(c) || /Key Files/i.test(c),
+  },
+  {
+    name: 'Session Protocol',
+    heading: '## Session Protocol',
+    test: (c) =>
+      /Session Protocol/i.test(c) || (/\*\*Start:\*\*/i.test(c) && /\*\*End:\*\*/i.test(c)),
+  },
+  {
+    name: 'Critical Rules',
+    heading: '## Critical Rules',
+    test: (c) => /Critical Rules/i.test(c) || /## Rules/i.test(c),
+  },
+  {
+    name: 'Skills pointer',
+    heading: '## Skills',
+    test: (c) => /\.claude\/skills\//i.test(c) || /Skills.*read on demand/i.test(c),
+  },
+  {
+    name: 'Gotchas section',
+    heading: '## Gotchas',
+    test: (c) => /Gotchas/i.test(c),
+  },
+];
+
+export function detectMissingSections(existingContent) {
+  return SECTION_DETECTORS.filter((s) => !s.test(existingContent)).map((s) => s.name);
+}
+
+function extractSection(content, heading) {
+  const lines = content.split(/\r?\n/);
+  const startIdx = lines.findIndex((l) => l.startsWith(heading));
+  if (startIdx === -1) return null;
+
+  // Find the next ## heading after this one
+  let endIdx = lines.length;
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    if (/^## /.test(lines[i])) {
+      endIdx = i;
+      break;
+    }
+  }
+
+  return lines.slice(startIdx, endIdx).join('\n').trimEnd();
+}
+
+export function generateWorkflowSuggestions(existingContent, renderedTemplate) {
+  const missing = detectMissingSections(existingContent);
+
+  const lines = [
+    '# Worclaude — Suggested CLAUDE.md Additions',
+    '',
+    'The following sections are recommended based on the Claude Code',
+    'workflow system. Review and merge what\'s useful into your CLAUDE.md.',
+    '',
+  ];
+
+  for (const sectionName of missing) {
+    const detector = SECTION_DETECTORS.find((s) => s.name === sectionName);
+    if (!detector) continue;
+
+    const sectionContent = extractSection(renderedTemplate, detector.heading);
+    if (!sectionContent) continue;
+
+    lines.push(`## Suggested: ${sectionName}`);
+    lines.push('```');
+    lines.push(sectionContent);
+    lines.push('```');
+    lines.push('');
+  }
+
+  if (missing.length === 0) {
+    lines.push('Your CLAUDE.md already has all recommended sections. No suggestions needed.');
+  }
+
+  return lines.join('\n');
+}
+
+export async function promptClaudeMdMerge(existingContent, missingSections) {
+  const lineCount = existingContent.split(/\r?\n/).length;
+
+  display.newline();
+  display.info(`Your CLAUDE.md (${lineCount} lines) was detected.`);
+
+  if (missingSections.length === 0) {
+    display.success('Your CLAUDE.md already has all recommended sections!');
+    return 'keep';
+  }
+
+  display.newline();
+  display.info('The workflow recommends these additions:');
+  for (const section of missingSections) {
+    display.success(`[+] ${section}`);
+  }
+
+  const { choice } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'choice',
+      message: 'How would you like to handle CLAUDE.md?',
+      choices: [
+        { name: 'Keep mine, save suggestions to CLAUDE.md.workflow-suggestions', value: 'keep' },
+        { name: 'Merge interactively section by section', value: 'merge-sections' },
+      ],
+    },
+  ]);
+
+  return choice;
+}
+
+export async function interactiveSectionMerge(existingContent, renderedTemplate, missingSections) {
+  let updatedContent = existingContent;
+
+  for (const sectionName of missingSections) {
+    const detector = SECTION_DETECTORS.find((s) => s.name === sectionName);
+    if (!detector) continue;
+
+    const sectionContent = extractSection(renderedTemplate, detector.heading);
+    if (!sectionContent) continue;
+
+    display.newline();
+    display.info(`Section: ${sectionName}`);
+    display.dim(sectionContent.split(/\r?\n/).slice(0, 5).join('\n'));
+    if (sectionContent.split(/\r?\n/).length > 5) {
+      display.dim('  ...');
+    }
+
+    const { addSection } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'addSection',
+        message: `Add "${sectionName}" to your CLAUDE.md?`,
+        choices: [
+          { name: 'Yes', value: true },
+          { name: 'No', value: false },
+        ],
+      },
+    ]);
+
+    if (addSection) {
+      updatedContent = updatedContent.trimEnd() + '\n\n' + sectionContent + '\n';
+    }
+  }
+
+  return updatedContent;
+}

package/src/prompts/conflict-resolution.js

@@ -0,0 +1,24 @@
+import inquirer from 'inquirer';
+import * as display from '../utils/display.js';
+
+export async function promptHookConflict(hookCategory, existingHook, workflowHook) {
+  display.newline();
+  display.warn(`Hook conflict: ${hookCategory} matcher "${existingHook.matcher}"`);
+  display.dim(`  Existing: ${existingHook.hooks[0].command}`);
+  display.dim(`  Workflow: ${workflowHook.hooks[0].command}`);
+
+  const { resolution } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'resolution',
+      message: 'How would you like to resolve this?',
+      choices: [
+        { name: 'Keep existing hook', value: 'keep' },
+        { name: 'Replace with workflow hook', value: 'replace' },
+        { name: 'Chain both (existing && workflow)', value: 'chain' },
+      ],
+    },
+  ]);
+
+  return resolution;
+}

package/src/prompts/project-type.js

@@ -0,0 +1,75 @@
+import inquirer from 'inquirer';
+import { PROJECT_TYPES, PROJECT_TYPE_DESCRIPTIONS, CATEGORY_RECOMMENDATIONS } from '../data/agents.js';
+import * as display from '../utils/display.js';
+
+export async function promptProjectType() {
+  const { projectTypes } = await inquirer.prompt([
+    {
+      type: 'checkbox',
+      name: 'projectTypes',
+      message:
+        'What type of project is this? (space to toggle, enter to confirm)\n  ℹ Not sure? Pick what\'s closest. You can add/remove agents later.',
+      choices: PROJECT_TYPES.map((t) => ({
+        name: `${t} — ${PROJECT_TYPE_DESCRIPTIONS[t]}`,
+        value: t,
+      })),
+      validate(answer) {
+        if (answer.length === 0) {
+          return 'Please select at least one project type.';
+        }
+        return true;
+      },
+    },
+  ]);
+
+  // Smart redundancy detection — confirm prompt if overlap detected
+  if (projectTypes.includes('Full-stack web application')) {
+    const overlaps = [];
+    if (projectTypes.includes('Backend / API')) overlaps.push('Backend / API');
+    if (projectTypes.includes('Frontend / UI')) overlaps.push('Frontend / UI');
+    if (overlaps.length > 0) {
+      display.newline();
+      display.warn('"Full-stack web" already includes backend and frontend.');
+      display.dim('You may not need both.');
+      const { continueAnyway } = await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'continueAnyway',
+          message: 'Continue anyway?',
+          choices: [
+            { name: 'Yes', value: true },
+            { name: 'No', value: false },
+          ],
+        },
+      ]);
+      if (!continueAnyway) {
+        return promptProjectType();
+      }
+    }
+  }
+
+  // Check for overlapping agent recommendations
+  if (projectTypes.length > 1) {
+    const agentSets = projectTypes.map((t) => new Set(CATEGORY_RECOMMENDATIONS[t] || []));
+    const allAgents = new Set();
+    const overlapping = new Set();
+
+    for (const agentSet of agentSets) {
+      for (const agent of agentSet) {
+        if (allAgents.has(agent)) {
+          overlapping.add(agent);
+        }
+        allAgents.add(agent);
+      }
+    }
+
+    if (overlapping.size > 0) {
+      display.info(
+        `Some agents are recommended by multiple project types: ${[...overlapping].join(', ')}`
+      );
+      display.dim('They will only be installed once.');
+    }
+  }
+
+  return projectTypes;
+}

package/src/prompts/tech-stack.js

@@ -0,0 +1,35 @@
+import inquirer from 'inquirer';
+import { TECH_STACKS } from '../data/agents.js';
+
+export async function promptTechStack(_projectTypes) {
+  const { languages } = await inquirer.prompt([
+    {
+      type: 'checkbox',
+      name: 'languages',
+      message:
+        'Primary language(s) / runtime: (space to toggle, enter to confirm)\n  ℹ This sets tool permissions and formatters. Update anytime via settings.json.',
+      choices: TECH_STACKS,
+      validate(answer) {
+        if (answer.length === 0) {
+          return 'Please select at least one language or "Other / None".';
+        }
+        return true;
+      },
+    },
+  ]);
+
+  const { useDocker } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'useDocker',
+      message: 'Do you use Docker currently?',
+      choices: [
+        { name: 'Yes', value: true },
+        { name: 'No', value: false },
+      ],
+      suffix: '\n  ℹ If you add Docker later, run `worclaude upgrade`.',
+    },
+  ]);
+
+  return { languages, useDocker };
+}

package/src/utils/display.js

@@ -0,0 +1,41 @@
+import chalk from 'chalk';
+
+export function header(text) {
+  console.log();
+  console.log(chalk.bold(text));
+  console.log(chalk.dim('─'.repeat(text.length)));
+}
+
+export function success(text) {
+  console.log(chalk.green('  ✓ ') + text);
+}
+
+export function error(text) {
+  console.log(chalk.red('  ✗ ') + text);
+}
+
+export function info(text) {
+  console.log(chalk.blue('  ℹ ') + text);
+}
+
+export function warn(text) {
+  console.log(chalk.yellow('  ⚠ ') + text);
+}
+
+export function dim(text) {
+  console.log(chalk.dim('    ' + text));
+}
+
+export function newline() {
+  console.log();
+}
+
+export function reviewBox(lines) {
+  console.log();
+  console.log(chalk.dim('  ─── Review Your Selections ───'));
+  console.log();
+  for (const line of lines) {
+    console.log('  ' + line);
+  }
+  console.log();
+}