worclaude 1.2.8 → 1.3.0

package/README.md

@@ -10,7 +10,7 @@
 
 [Full Documentation](https://sefaertunc.github.io/Worclaude/) · [Interactive Demo](https://sefaertunc.github.io/Worclaude/demo/) · [npm](https://www.npmjs.com/package/worclaude)
 
-Worclaude scaffolds a complete Claude Code workflow into any project in seconds. It implements all [53 tips by Boris Cherny](https://www.howborisusesclaudecode.com/) — the creator of Claude Code at Anthropic — as a reusable, upgradable scaffold. One `init` command gives you 23 agents, 10 slash commands, 12 skills, hooks, permissions, and a CLAUDE.md template tuned for your tech stack. Whether you're starting fresh or adding structure to an existing project, Worclaude handles the setup so you can focus on building.
+Worclaude scaffolds a complete Claude Code workflow into any project in seconds. It implements all [53 tips by Boris Cherny](https://www.howborisusesclaudecode.com/) — the creator of Claude Code at Anthropic — as a reusable, upgradable scaffold. One `init` command gives you 23 agents, 10 slash commands, 13 skills, hooks, permissions, and a CLAUDE.md template tuned for your tech stack. Whether you're starting fresh or adding structure to an existing project, Worclaude handles the setup so you can focus on building.
 
 ---
 
@@ -26,10 +26,11 @@ Worclaude scaffolds a complete Claude Code workflow into any project in seconds.
 **Slash Commands (10)**
 `/start` `/end` `/commit-push-pr` `/review-plan` `/techdebt` `/verify` `/compact-safe` `/status` `/update-claude-md` `/setup`
 
-**Skills (12)**
+**Skills (13)**
 
 - 9 universal knowledge files (testing, git conventions, context management, and more)
 - 3 project-specific templates filled in by `/setup`
+- 1 generated agent routing guide (dynamically built from your agent selection)
 
 **Hooks**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worclaude",
-  "version": "1.2.8",
+  "version": "1.3.0",
   "description": "CLI tool that scaffolds a comprehensive Claude Code workflow into any project",
   "type": "module",
   "bin": {

package/src/commands/init.js

@@ -27,6 +27,7 @@ import {
   CONFIRMATION_STEPS,
   SPEC_MD_TEMPLATE_MAP,
 } from '../data/agents.js';
+import { buildAgentRoutingSkill } from '../generators/agent-routing.js';
 
 // --- Helper functions ---
 
@@ -436,6 +437,13 @@ async function scaffoldFresh(projectRoot, selections, variables, settingsStr, ve
     }
     spinner.text = `Created ${TEMPLATE_SKILLS.length} template skills`;
 
+    const agentRoutingContent = buildAgentRoutingSkill(selectedAgents, projectTypes);
+    await writeFile(
+      path.join(projectRoot, '.claude', 'skills', 'agent-routing.md'),
+      agentRoutingContent
+    );
+    spinner.text = 'Created agent routing guide';
+
     await scaffoldFile('mcp-json.json', '.mcp.json', {}, projectRoot);
     spinner.text = 'Created .mcp.json';
 
@@ -481,7 +489,7 @@ async function scaffoldFresh(projectRoot, selections, variables, settingsStr, ve
 
 function displayFreshSuccess(selections, skipped) {
   const totalAgents = UNIVERSAL_AGENTS.length + selections.selectedAgents.length;
-  const totalSkills = UNIVERSAL_SKILLS.length + TEMPLATE_SKILLS.length;
+  const totalSkills = UNIVERSAL_SKILLS.length + TEMPLATE_SKILLS.length + 1; // +1 for agent-routing.md
 
   display.newline();
   display.success('CLAUDE.md');

package/src/core/merger.js

@@ -18,6 +18,7 @@ import {
   NOTIFICATION_COMMANDS,
   SPEC_MD_TEMPLATE_MAP,
 } from '../data/agents.js';
+import { buildAgentRoutingSkill } from '../generators/agent-routing.js';
 import * as display from '../utils/display.js';
 
 // --- Settings builder (shared with Scenario A) ---
@@ -95,7 +96,7 @@ function parseUserJson(raw, filename) {
 
 // --- Sub-merge operations ---
 
-async function mergeSkills(projectRoot, existingScan, variables, report) {
+async function mergeSkills(projectRoot, existingScan, variables, report, selections) {
   const allSkills = [
     ...UNIVERSAL_SKILLS.map((s) => ({
       name: s,
@@ -128,6 +129,25 @@ async function mergeSkills(projectRoot, existingScan, variables, report) {
       report.added.skills.push(filename);
     }
   }
+
+  // Generated skill: agent-routing.md
+  const routingFilename = 'agent-routing.md';
+  const skillsDir = path.join('.claude', 'skills');
+  const routingContent = buildAgentRoutingSkill(
+    selections.selectedAgents,
+    selections.projectTypes
+  );
+
+  if (existingScan.existingSkills.includes(routingFilename)) {
+    await writeFile(
+      path.join(projectRoot, skillsDir, 'agent-routing.workflow-ref.md'),
+      routingContent
+    );
+    report.conflicts.skills.push(routingFilename);
+  } else {
+    await writeFile(path.join(projectRoot, skillsDir, routingFilename), routingContent);
+    report.added.skills.push(routingFilename);
+  }
 }
 
 async function mergeAgents(projectRoot, existingScan, selectedAgents, report) {
@@ -395,7 +415,7 @@ export async function performMerge(
     hookConflicts: [],
   };
 
-  await mergeSkills(projectRoot, existingScan, variables, report);
+  await mergeSkills(projectRoot, existingScan, variables, report, selections);
   await mergeAgents(projectRoot, existingScan, selections.selectedAgents, report);
   await mergeCommands(projectRoot, existingScan, report);
 

package/src/data/agent-registry.js

@@ -0,0 +1,324 @@
+/**
+ * Agent routing metadata for all 23 agents.
+ * Used by the agent-routing generator to produce the routing skill file.
+ * Separate from agents.js because this data is only consumed by the generator,
+ * not by CLI prompts or display logic.
+ */
+export const AGENT_REGISTRY = {
+  // --- Universal agents (5) ---
+
+  'plan-reviewer': {
+    category: 'universal',
+    model: 'Opus',
+    isolation: 'none',
+    pipelineStage: 'Stage 2: Review',
+    triggerType: 'manual',
+    triggerCommand: '/review-plan',
+    whenToUse: 'Before executing any implementation prompt. Always.',
+    whatItDoes:
+      'Reviews implementation plans as a senior staff engineer. Challenges assumptions, finds ambiguity, checks verification strategy, identifies missing edge cases.',
+    expectBack: 'Refined plan with concerns addressed, or list of blocking questions.',
+    situationLabel: 'Got an implementation prompt',
+  },
+  'test-writer': {
+    category: 'universal',
+    model: 'Sonnet',
+    isolation: 'worktree',
+    pipelineStage: 'Stage 5: Verify',
+    triggerType: 'automatic',
+    triggerCommand: null,
+    whenToUse: 'After completing implementation of any feature or module.',
+    whatItDoes:
+      'Writes unit tests, integration tests, edge case tests. Covers happy path, error cases, boundary conditions.',
+    expectBack: 'Test files committed to worktree branch. Merge when reviewed.',
+    situationLabel: 'Finished implementing a feature',
+  },
+  'code-simplifier': {
+    category: 'universal',
+    model: 'Sonnet',
+    isolation: 'worktree',
+    pipelineStage: 'Stage 4: Quality',
+    triggerType: 'automatic',
+    triggerCommand: '/simplify',
+    whenToUse:
+      'After a feature is implemented and tests pass. Also when you notice growing complexity or duplication.',
+    whatItDoes:
+      'Reviews code for duplication, unnecessary abstraction, missed reuse opportunities. Simplifies without changing behavior.',
+    expectBack: 'Cleanup commits on worktree branch. Diff review before merge.',
+    situationLabel: 'Notice code getting complex',
+  },
+  'build-validator': {
+    category: 'universal',
+    model: 'Haiku',
+    isolation: 'none',
+    pipelineStage: 'Stage 5: Verify',
+    triggerType: 'automatic',
+    triggerCommand: null,
+    whenToUse: 'Before every commit. After merging worktree branches.',
+    whatItDoes:
+      'Quick validation — tests pass, build succeeds, lint clean. Fast and cheap (Haiku model).',
+    expectBack: 'Pass/fail with specific errors if failed.',
+    situationLabel: 'Are about to commit',
+  },
+  'verify-app': {
+    category: 'universal',
+    model: 'Sonnet',
+    isolation: 'worktree',
+    pipelineStage: 'Stage 5: Verify',
+    triggerType: 'manual',
+    triggerCommand: '/verify',
+    whenToUse: 'Before creating a PR. After major changes.',
+    whatItDoes:
+      'Full end-to-end verification. Runs the app, tests all major flows, checks for regressions. More thorough than build-validator.',
+    expectBack: 'Detailed verification report. Blocking issues listed.',
+    situationLabel: 'Finished a task, ready for PR',
+  },
+
+  // --- Frontend agents (2) ---
+
+  'ui-reviewer': {
+    category: 'frontend',
+    model: 'Sonnet',
+    isolation: 'none',
+    triggerType: 'manual',
+    triggerCommand: null,
+    whenToUse:
+      'After implementing or modifying UI components. When adding new pages or layouts. During design system changes.',
+    whatItDoes:
+      'Reviews UI components for consistency, accessibility, responsiveness. Checks component hierarchy and prop patterns.',
+    expectBack: 'UI review report with specific issues and accessibility findings.',
+    situationLabel: 'Implemented or changed UI components',
+  },
+  'style-enforcer': {
+    category: 'frontend',
+    model: 'Haiku',
+    isolation: 'none',
+    triggerType: 'manual',
+    triggerCommand: null,
+    whenToUse: 'After CSS/styling changes. When new components are added. During theme updates.',
+    whatItDoes:
+      'Ensures design system compliance, catches CSS/styling drift, validates consistent spacing/colors/typography.',
+    expectBack: 'List of design system violations with fix suggestions.',
+    situationLabel: 'Made styling or CSS changes',
+  },
+
+  // --- Backend agents (3) ---
+
+  'api-designer': {
+    category: 'backend',
+    model: 'Opus',
+    isolation: 'none',
+    triggerType: 'manual',
+    triggerCommand: null,
+    whenToUse:
+      'Designing new API endpoints. Changing existing API contracts. Adding new routes or modifying request/response shapes.',
+    whatItDoes:
+      'Reviews API design for RESTful conventions, naming consistency, backward compatibility, request/response shape validation.',
+    expectBack: 'Design review with specific recommendations.',
+    situationLabel: 'Designed a new API endpoint',
+  },
+  'database-analyst': {
+    category: 'backend',
+    model: 'Sonnet',
+    isolation: 'none',
+    triggerType: 'manual',
+    triggerCommand: null,
+    whenToUse: 'Writing migrations. Changing schemas. Complex queries. Data integrity concerns.',
+    whatItDoes:
+      'Reviews schema design, migration safety, query performance, index usage, data integrity constraints.',
+    expectBack: 'Analysis with specific concerns and recommendations.',
+    situationLabel: 'Wrote a database migration or schema change',
+  },
+  'auth-auditor': {
+    category: 'backend',
+    model: 'Opus',
+    isolation: 'none',
+    triggerType: 'manual',
+    triggerCommand: null,
+    whenToUse:
+      'Any change to authentication or authorization flow. New roles, permissions, token handling.',
+    whatItDoes:
+      'Reviews auth flows for correctness, token lifecycle, permission checks, session management, OWASP compliance.',
+    expectBack: 'Audit report with pass/fail per check.',
+    situationLabel: 'Changed auth or authorization logic',
+  },
+
+  // --- DevOps agents (4) ---
+
+  'dependency-manager': {
+    category: 'devops',
+    model: 'Haiku',
+    isolation: 'none',
+    triggerType: 'manual',
+    triggerCommand: null,
+    whenToUse:
+      'After adding new packages. During regular maintenance. When security advisories are published.',
+    whatItDoes:
+      'Audits, updates, and resolves dependency issues. Checks for security vulnerabilities in packages.',
+    expectBack: 'Dependency audit report with update recommendations.',
+    situationLabel: 'Added new dependencies or running maintenance',
+  },
+  'ci-fixer': {
+    category: 'devops',
+    model: 'Sonnet',
+    isolation: 'worktree',
+    triggerType: 'manual',
+    triggerCommand: null,
+    whenToUse: 'CI pipeline fails. Build errors in GitHub Actions/CI. Flaky tests blocking merges.',
+    whatItDoes: 'Reads CI logs, identifies root cause, implements fix in worktree isolation.',
+    expectBack: 'Fix committed to worktree branch with CI passing.',
+    situationLabel: 'CI pipeline is failing',
+  },
+  'docker-helper': {
+    category: 'devops',
+    model: 'Sonnet',
+    isolation: 'none',
+    triggerType: 'manual',
+    triggerCommand: null,
+    whenToUse:
+      'Creating or modifying Dockerfiles. Compose file changes. Multi-stage build optimization. Container debugging.',
+    whatItDoes:
+      'Manages containerization, Dockerfile optimization, compose file configuration, multi-stage builds.',
+    expectBack: 'Optimized Docker configuration with size/performance improvements.',
+    situationLabel: 'Working with Docker or containers',
+  },
+  'deploy-validator': {
+    category: 'devops',
+    model: 'Sonnet',
+    isolation: 'none',
+    triggerType: 'manual',
+    triggerCommand: null,
+    whenToUse:
+      'Before deploying to staging or production. After infrastructure changes. New environment setup.',
+    whatItDoes:
+      'Validates deployment readiness — environment configs, secrets management, health checks, rollback strategy.',
+    expectBack: 'Deployment readiness checklist with pass/fail.',
+    situationLabel: 'Preparing for deployment',
+  },
+
+  // --- Quality agents (4) ---
+
+  'bug-fixer': {
+    category: 'quality',
+    model: 'Sonnet',
+    isolation: 'worktree',
+    triggerType: 'manual',
+    triggerCommand: null,
+    whenToUse:
+      "Bug reported. Test failing. Error in logs. Something broke but you don't want to derail current work.",
+    whatItDoes:
+      'Investigates the bug in isolation. Reads logs, reproduces, finds root cause, implements fix, writes regression test.',
+    expectBack: 'Fix committed to worktree branch with regression test.',
+    situationLabel: 'Got a bug report mid-task',
+  },
+  'security-reviewer': {
+    category: 'quality',
+    model: 'Opus',
+    isolation: 'none',
+    triggerType: 'manual',
+    triggerCommand: null,
+    whenToUse:
+      'Auth changes. User input handling. New API endpoints exposed to external users. Dependency updates.',
+    whatItDoes:
+      'Scans for injection vulnerabilities, auth bypasses, data exposure, insecure defaults, dependency vulnerabilities.',
+    expectBack: 'Security report with severity ratings.',
+    situationLabel: 'Made security-sensitive changes',
+  },
+  'performance-auditor': {
+    category: 'quality',
+    model: 'Sonnet',
+    isolation: 'none',
+    triggerType: 'manual',
+    triggerCommand: null,
+    whenToUse:
+      'Performance concern raised. Slow endpoint discovered. Before releasing to production. After major changes.',
+    whatItDoes:
+      'Profiles code, identifies bottlenecks, checks database query efficiency, measures response times, suggests optimizations.',
+    expectBack: 'Performance report with benchmarks and recommendations.',
+    situationLabel: 'Suspect performance issues',
+  },
+  refactorer: {
+    category: 'quality',
+    model: 'Sonnet',
+    isolation: 'worktree',
+    triggerType: 'manual',
+    triggerCommand: null,
+    whenToUse:
+      'Large-scale renames. Architectural pattern changes. Library migrations. Moving code between modules.',
+    whatItDoes:
+      'Handles large-scale refactoring in worktree isolation. Renames, architectural changes, pattern migrations with full test verification.',
+    expectBack: 'Refactored code on worktree branch with all tests passing.',
+    situationLabel: 'Need large-scale refactoring',
+  },
+
+  // --- Documentation agents (2) ---
+
+  'doc-writer': {
+    category: 'documentation',
+    model: 'Sonnet',
+    isolation: 'worktree',
+    triggerType: 'manual',
+    triggerCommand: null,
+    whenToUse:
+      'After implementing new features. After API changes. When README is outdated. Before release.',
+    whatItDoes:
+      'Updates documentation, README, API docs from code changes. Keeps docs in sync with implementation.',
+    expectBack: 'Updated docs committed to worktree branch.',
+    situationLabel: 'Need docs updated after implementation',
+  },
+  'changelog-generator': {
+    category: 'documentation',
+    model: 'Haiku',
+    isolation: 'none',
+    triggerType: 'manual',
+    triggerCommand: null,
+    whenToUse:
+      'Before releasing a new version. After merging a batch of PRs. When preparing release notes.',
+    whatItDoes:
+      'Generates changelogs from git history, PR descriptions, and commit messages. Formats for release notes.',
+    expectBack: 'Formatted changelog entry for the release.',
+    situationLabel: 'Preparing a release',
+  },
+
+  // --- Data / AI agents (3) ---
+
+  'data-pipeline-reviewer': {
+    category: 'data',
+    model: 'Sonnet',
+    isolation: 'none',
+    triggerType: 'manual',
+    triggerCommand: null,
+    whenToUse:
+      'New data pipeline created. ETL logic changed. Data transformation modified. Schema compatibility concerns.',
+    whatItDoes:
+      'Reviews data flows, validates transformations, checks for data loss, validates schema compatibility.',
+    expectBack: 'Pipeline review with data integrity concerns.',
+    situationLabel: 'Created or changed a data pipeline',
+  },
+  'ml-experiment-tracker': {
+    category: 'data',
+    model: 'Sonnet',
+    isolation: 'none',
+    triggerType: 'manual',
+    triggerCommand: null,
+    whenToUse:
+      'Running ML experiments. Comparing model performance. Hyperparameter tuning. Model selection.',
+    whatItDoes:
+      'Tracks ML experiments, compares metrics across runs, documents hyperparameters and results.',
+    expectBack: 'Experiment comparison report with recommendations.',
+    situationLabel: 'Running or comparing ML experiments',
+  },
+  'prompt-engineer': {
+    category: 'data',
+    model: 'Opus',
+    isolation: 'none',
+    triggerType: 'manual',
+    triggerCommand: null,
+    whenToUse:
+      'Writing LLM prompts. Optimizing prompt performance. Building prompt chains. Testing prompt variations.',
+    whatItDoes:
+      'Reviews and optimizes LLM prompts and chains. Tests prompt variations, measures output quality.',
+    expectBack: 'Optimized prompts with test results and quality comparison.',
+    situationLabel: 'Writing or optimizing LLM prompts',
+  },
+};

package/src/generators/agent-routing.js

@@ -0,0 +1,149 @@
+import { UNIVERSAL_AGENTS } from '../data/agents.js';
+import { AGENT_REGISTRY } from '../data/agent-registry.js';
+
+/**
+ * Generates the agent-routing.md skill file content based on selected agents.
+ * @param {string[]} selectedAgentNames - names of optional agents the user selected
+ * @param {string[]} projectTypes - e.g. ['Backend / API', 'Frontend / UI']
+ * @returns {string} - complete markdown content for agent-routing.md
+ */
+export function buildAgentRoutingSkill(selectedAgentNames, _projectTypes) {
+  const allAgents = [...UNIVERSAL_AGENTS, ...selectedAgentNames];
+
+  const automaticAgents = [];
+  const manualAgents = [];
+
+  for (const name of allAgents) {
+    const entry = AGENT_REGISTRY[name];
+    if (!entry) continue;
+    if (entry.triggerType === 'automatic') {
+      automaticAgents.push({ name, ...entry });
+    } else {
+      manualAgents.push({ name, ...entry });
+    }
+  }
+
+  const sections = [
+    buildHeader(),
+    buildHowAgentsWork(),
+    buildAutomaticTriggers(automaticAgents),
+    buildManualTriggers(manualAgents),
+    buildDecisionMatrix(allAgents),
+    buildRules(),
+  ];
+
+  return sections.join('\n');
+}
+
+function buildHeader() {
+  return `# Agent Routing Guide
+
+Read this file at the start of every session. It tells you which agents are available and when to use them.
+`;
+}
+
+function buildHowAgentsWork() {
+  return `## How Agents Work
+- Agents are specialist subprocesses. Spawn them to keep your main context clean.
+- Worktree agents run in isolation — safe to run in parallel with your work.
+- Non-worktree agents share your context — don't edit the same files they're reading.
+- Never spawn more than 3 agents simultaneously.
+- If a task is small enough to do yourself in 2 minutes, don't spawn an agent for it.
+
+---
+`;
+}
+
+function buildAgentEntry(agent) {
+  const isolation = agent.isolation === 'worktree' ? 'Worktree' : 'None';
+  let trigger;
+  if (agent.triggerType === 'automatic' && agent.triggerCommand) {
+    trigger = `Automatic — spawn when trigger condition is met (also: ${agent.triggerCommand})`;
+  } else if (agent.triggerType === 'automatic') {
+    trigger = 'Automatic — spawn when trigger condition is met';
+  } else if (agent.triggerCommand) {
+    trigger = `Manual — ${agent.triggerCommand}`;
+  } else {
+    trigger = 'Manual — spawn when needed';
+  }
+
+  return `### ${agent.name}
+- **Model:** ${agent.model} | **Isolation:** ${isolation}
+- **When:** ${agent.whenToUse}
+- **Trigger:** ${trigger}
+- **What it does:** ${agent.whatItDoes}
+- **Expect back:** ${agent.expectBack}
+`;
+}
+
+function buildAutomaticTriggers(agents) {
+  if (agents.length === 0) {
+    return `## Automatic Triggers
+
+No automatic-trigger agents installed.
+
+---
+`;
+  }
+
+  const entries = agents.map(buildAgentEntry).join('\n');
+  return `## Automatic Triggers
+
+These agents should be spawned without being asked when their trigger condition is met.
+
+${entries}
+---
+`;
+}
+
+function buildManualTriggers(agents) {
+  if (agents.length === 0) {
+    return `## Manual Triggers
+
+No manual-trigger agents installed.
+
+---
+`;
+  }
+
+  const entries = agents.map(buildAgentEntry).join('\n');
+  return `## Manual Triggers
+
+These agents are spawned when you or the user explicitly requests them.
+
+${entries}
+---
+`;
+}
+
+function buildDecisionMatrix(allAgents) {
+  const header = `## Decision Matrix
+
+| You just... | Spawn this | Auto? |
+|---|---|---|`;
+
+  const rows = [];
+  for (const name of allAgents) {
+    const entry = AGENT_REGISTRY[name];
+    if (!entry) continue;
+    const auto = entry.triggerType === 'automatic' ? 'Yes' : 'Manual';
+    rows.push(`| ${entry.situationLabel} | ${name} | ${auto} |`);
+  }
+
+  return `${header}
+${rows.join('\n')}
+
+---
+`;
+}
+
+function buildRules() {
+  return `## Rules
+1. Universal agents are your defaults. Use them every session.
+2. Project agents are specialists. Use them when their domain is relevant.
+3. Worktree agents are safe to run in parallel — they can't break your work.
+4. Non-worktree agents share your context — don't edit the same files they're reading.
+5. When in doubt, spawn the agent. A wasted agent run costs less than a missed bug.
+6. If you spawn an agent and it's not useful, tell the user — they may remove it.
+`;
+}

package/templates/claude-md.md

@@ -20,11 +20,12 @@ See `.claude/skills/` — load only what's relevant:
 - review-and-handoff.md — Session endings
 - verification.md — How to verify work
 - testing.md — Test philosophy and patterns
+- agent-routing.md — When and how to use each installed agent (READ EVERY SESSION)
 {project_specific_skills}
 
 ## Session Protocol
-**Start:** Read PROGRESS.md. Read active implementation prompt if any.
-**During:** One task at a time. Commit after each. Use subagents for side work.
+**Start:** Read PROGRESS.md → Read `.claude/skills/agent-routing.md` → Read active implementation prompt if any.
+**During:** One task at a time. Commit after each. Use subagents per routing guide.
 **End:** Update PROGRESS.md. Write handoff if ending mid-task.
 
 ## Critical Rules