worclaude 1.9.0 → 2.1.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 [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 25 agents, 16 slash commands, 14 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 [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 25 agents, 16 slash commands, 15 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,9 +26,9 @@ Worclaude scaffolds a complete Claude Code workflow into any project in seconds.
 **Slash Commands (16)**
 `/start` `/end` `/commit-push-pr` `/review-plan` `/techdebt` `/verify` `/compact-safe` `/status` `/update-claude-md` `/setup` `/sync` `/conflict-resolver` `/review-changes` `/build-fix` `/refactor-clean` `/test-coverage`
 
-**Skills (14)**
+**Skills (15)**
 
-- 10 universal knowledge files (testing, git conventions, context management, security, and more)
+- 11 universal knowledge files (testing, git conventions, context management, security, coordinator mode, and more)
 - 3 project-specific templates filled in by `/setup`
 - 1 generated agent routing guide (dynamically built from your agent selection)
 
@@ -48,6 +48,45 @@ Worclaude scaffolds a complete Claude Code workflow into any project in seconds.
 
 ---
 
+## What's New in v2.0.0
+
+v2.0.0 is a major integration release. Skills and agents now register with Claude Code's runtime systems — they show up in `/skills` and `/agents`, not just as files on disk.
+
+**Claude Code Runtime Integration**
+
+- Skills use directory format (`skill-name/SKILL.md`) and register with `/skills`
+- Agents include `description` frontmatter and register with `/agents`
+- Run `worclaude doctor` to verify everything is wired up correctly
+
+**Conditional Skills**
+
+- 6 skills activate only when relevant files are touched (testing, security, frontend, backend, verification, project-patterns)
+- 8 skills stay always-loaded for cross-cutting guidance
+- Saves context window budget by keeping domain-specific guidance out of unrelated work
+
+**Agent Enhancements**
+
+- Read-only agents blocked from file modifications via `disallowedTools`
+- Background execution for long-running agents (verify-app, build-validator, e2e-runner)
+- Turn limits (`maxTurns`) prevent runaway token consumption
+- Persistent memory for agents that learn across sessions (test-writer, security-reviewer, doc-writer)
+
+**New Content**
+
+- Coordinator-mode skill for multi-agent orchestration patterns
+- Optional MEMORY.md template for Claude Code's memory system
+- Enhanced verify-app agent with structured verdicts and adversarial probe requirements
+- Per-tech-stack permission presets (16 languages)
+
+**Upgrade Migration**
+
+- `worclaude upgrade` auto-migrates v1.x projects: flat skills → directory format, agents get required frontmatter
+- `worclaude doctor` detects old formats and missing fields
+
+See the [Claude Code Integration guide](https://sefaertunc.github.io/Worclaude/guide/claude-code-integration) for technical details.
+
+---
+
 ## Quick Start
 
 ```bash

package/package.json

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

package/src/commands/backup.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import ora from 'ora';
 import { createBackup } from '../core/backup.js';
-import { fileExists, dirExists, listFiles } from '../utils/file.js';
+import { fileExists, dirExists, listFiles, listSkillDirs } from '../utils/file.js';
 import * as display from '../utils/display.js';
 
 export async function backupCommand() {
@@ -33,11 +33,13 @@ export async function backupCommand() {
   if (await dirExists(claudeBackup)) {
     const agents = await listFiles(path.join(claudeBackup, 'agents'));
     const commands = await listFiles(path.join(claudeBackup, 'commands'));
-    const skills = await listFiles(path.join(claudeBackup, 'skills'));
+    const skillFiles = await listFiles(path.join(claudeBackup, 'skills'));
+    const skillDirs = await listSkillDirs(path.join(claudeBackup, 'skills'));
+    const skillCount = skillDirs.length + skillFiles.length;
     const parts = [];
     if (agents.length > 0) parts.push(`${agents.length} agents`);
     if (commands.length > 0) parts.push(`${commands.length} commands`);
-    if (skills.length > 0) parts.push(`${skills.length} skills`);
+    if (skillCount > 0) parts.push(`${skillCount} skills`);
     contents.push(`.claude/ (${parts.join(', ')})`);
   }
 

package/src/commands/delete.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import inquirer from 'inquirer';
 import ora from 'ora';
-import { workflowMetaExists, readWorkflowMeta } from '../core/config.js';
+import { requireWorkflowMeta } from '../core/config.js';
 import { createBackup } from '../core/backup.js';
 import {
   classifyClaudeFiles,
@@ -16,16 +16,13 @@ export async function deleteCommand() {
   const projectRoot = process.cwd();
 
   // Pre-flight: ensure worclaude is installed
-  if (!(await workflowMetaExists(projectRoot))) {
-    display.error('No worclaude workflow found in this project.');
-    display.info('Run `worclaude init` to set up a workflow first.');
+  const { meta, error } = await requireWorkflowMeta(projectRoot);
+  if (error === 'not-installed') {
+    display.info('Workflow is not installed. Run `worclaude init` to set up.');
     return;
   }
-
-  const meta = await readWorkflowMeta(projectRoot);
-  if (!meta) {
-    display.error('workflow-meta.json is corrupted or unreadable.');
-    display.info('You may need to manually remove the .claude/ directory.');
+  if (error === 'corrupted') {
+    display.error('workflow-meta.json is corrupted. Run `worclaude init` to reinstall.');
     return;
   }
 

package/src/commands/diff.js

@@ -1,17 +1,16 @@
-import { readWorkflowMeta, workflowMetaExists, getPackageVersion } from '../core/config.js';
+import { requireWorkflowMeta, getPackageVersion } from '../core/config.js';
 import { categorizeFiles } from '../core/file-categorizer.js';
 import * as display from '../utils/display.js';
 
 export async function diffCommand() {
   const projectRoot = process.cwd();
 
-  if (!(await workflowMetaExists(projectRoot))) {
+  const { meta, error } = await requireWorkflowMeta(projectRoot);
+  if (error === 'not-installed') {
     display.info('Workflow is not installed. Run `worclaude init` to set up.');
     return;
   }
-
-  const meta = await readWorkflowMeta(projectRoot);
-  if (!meta) {
+  if (error === 'corrupted') {
     display.error('workflow-meta.json is corrupted. Run `worclaude init` to reinstall.');
     return;
   }

package/src/commands/doctor.js

@@ -1,3 +1,4 @@
+import fs from 'fs-extra';
 import path from 'node:path';
 import { readWorkflowMeta, workflowMetaExists, getPackageVersion } from '../core/config.js';
 import { hashFile } from '../utils/hash.js';
@@ -72,6 +73,48 @@ async function checkClaudeMd(projectRoot) {
   }
 }
 
+async function checkClaudeMdSize(projectRoot) {
+  const claudeMdPath = path.join(projectRoot, 'CLAUDE.md');
+  if (!(await fileExists(claudeMdPath))) {
+    return []; // Already covered by existing checkClaudeMd
+  }
+  try {
+    const content = await readFile(claudeMdPath);
+    const charCount = content.length;
+    const WARN_THRESHOLD = 30000;
+    const FAIL_THRESHOLD = 38000;
+    const HARD_LIMIT = 40000;
+
+    if (charCount > FAIL_THRESHOLD) {
+      return [
+        result(
+          FAIL,
+          `CLAUDE.md size: ${charCount.toLocaleString()} chars`,
+          `Exceeds recommended limit (${FAIL_THRESHOLD.toLocaleString()}/${HARD_LIMIT.toLocaleString()}). Claude Code caps at ${HARD_LIMIT.toLocaleString()} chars. Move domain-specific content to conditional skills with paths frontmatter.`
+        ),
+      ];
+    }
+    if (charCount > WARN_THRESHOLD) {
+      return [
+        result(
+          WARN,
+          `CLAUDE.md size: ${charCount.toLocaleString()} chars`,
+          `Approaching limit (${WARN_THRESHOLD.toLocaleString()}/${HARD_LIMIT.toLocaleString()}). Consider moving content to skills.`
+        ),
+      ];
+    }
+    return [
+      result(
+        PASS,
+        `CLAUDE.md size: ${charCount.toLocaleString()} chars (limit: ${HARD_LIMIT.toLocaleString()})`,
+        null
+      ),
+    ];
+  } catch {
+    return [];
+  }
+}
+
 async function checkSettingsJson(projectRoot) {
   const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
   if (!(await fileExists(settingsPath))) {
@@ -134,6 +177,60 @@ async function checkAgents(projectRoot, meta) {
   return results;
 }
 
+async function readAgentFrontmatters(projectRoot) {
+  const agentsDir = path.join(projectRoot, '.claude', 'agents');
+  try {
+    const entries = await fs.readdir(agentsDir, { withFileTypes: true });
+    const mdFiles = entries.filter((e) => e.isFile() && e.name.endsWith('.md'));
+    const agents = [];
+    for (const file of mdFiles) {
+      const content = await readFile(path.join(agentsDir, file.name));
+      const match = content.match(/^---\n([\s\S]*?)\n---/);
+      agents.push({ name: file.name, frontmatter: match ? match[1] : null });
+    }
+    return agents;
+  } catch {
+    return [];
+  }
+}
+
+async function checkAgentDescription(projectRoot) {
+  const agents = await readAgentFrontmatters(projectRoot);
+  if (agents.length === 0) return [];
+
+  const results = [];
+  for (const { name, frontmatter } of agents) {
+    if (!frontmatter) {
+      results.push(
+        result(FAIL, `agents/${name}`, 'No YAML frontmatter — agent is invisible to Claude Code')
+      );
+      continue;
+    }
+
+    const hasName = /^name:\s*.+/m.test(frontmatter);
+    const hasDescription = /^description:\s*.+/m.test(frontmatter);
+
+    if (!hasName) {
+      results.push(result(FAIL, `agents/${name}`, 'Missing required "name" field in frontmatter'));
+    } else if (!hasDescription) {
+      results.push(
+        result(
+          FAIL,
+          `agents/${name}`,
+          'Missing required "description" field — agent is invisible to Claude Code\'s /agents and routing'
+        )
+      );
+    }
+  }
+
+  if (results.length === 0) {
+    results.push(
+      result(PASS, `agents/ frontmatter (${agents.length} agents have required fields)`, null)
+    );
+  }
+  return results;
+}
+
 async function checkCommands(projectRoot) {
   const commandsDir = path.join(projectRoot, '.claude', 'commands');
   const missing = [];
@@ -157,7 +254,7 @@ async function checkSkills(projectRoot) {
   const allExpected = [...UNIVERSAL_SKILLS, ...TEMPLATE_SKILLS, 'agent-routing'];
 
   for (const skill of allExpected) {
-    const skillPath = path.join(skillsDir, `${skill}.md`);
+    const skillPath = path.join(skillsDir, skill, 'SKILL.md');
     if (!(await fileExists(skillPath))) {
       missing.push(skill);
     }
@@ -166,7 +263,49 @@ async function checkSkills(projectRoot) {
   if (missing.length === 0) {
     return [result(PASS, `skills/ (${allExpected.length} expected, all present)`, null)];
   }
-  return missing.map((s) => result(WARN, `skills/${s}.md`, 'Missing skill'));
+  return missing.map((s) => result(WARN, `skills/${s}/SKILL.md`, 'Missing skill'));
+}
+
+async function checkSkillFormat(projectRoot) {
+  const skillsDir = path.join(projectRoot, '.claude', 'skills');
+  const results = [];
+
+  try {
+    const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+    const flatMdFiles = entries
+      .filter((e) => e.isFile() && e.name.endsWith('.md'))
+      .map((e) => e.name);
+
+    if (flatMdFiles.length > 0) {
+      results.push(
+        result(
+          FAIL,
+          `skills/ has ${flatMdFiles.length} flat .md file(s)`,
+          `Flat .md files in .claude/skills/ are invisible to Claude Code. Expected format: skill-name/SKILL.md. Run \`worclaude upgrade\` to migrate. Files: ${flatMdFiles.join(', ')}`
+        )
+      );
+    }
+
+    // Also check directory-format skills exist
+    const skillDirs = entries.filter((e) => e.isDirectory());
+    let validDirSkills = 0;
+    for (const dir of skillDirs) {
+      const skillMd = path.join(skillsDir, dir.name, 'SKILL.md');
+      if (await fileExists(skillMd)) {
+        validDirSkills++;
+      }
+    }
+
+    if (validDirSkills > 0 && flatMdFiles.length === 0) {
+      results.push(
+        result(PASS, `skills/ format (${validDirSkills} directory-format skills)`, null)
+      );
+    }
+  } catch {
+    // skills/ doesn't exist — covered by existing component checks
+  }
+
+  return results;
 }
 
 async function checkHashIntegrity(projectRoot, meta) {
@@ -244,6 +383,124 @@ async function checkDocSpecs(projectRoot) {
   return results;
 }
 
+const AGENT_OPTIONAL_FIELDS = [
+  'model',
+  'isolation',
+  'maxTurns',
+  'disallowedTools',
+  'background',
+  'memory',
+  'skills',
+  'initialPrompt',
+  'criticalSystemReminder',
+  'omitClaudeMd',
+];
+
+async function checkAgentCompleteness(projectRoot) {
+  const agents = await readAgentFrontmatters(projectRoot);
+  const withFrontmatter = agents.filter((a) => a.frontmatter);
+  if (withFrontmatter.length === 0) return [];
+
+  let totalFields = 0;
+  const suggestions = [];
+
+  for (const { name, frontmatter } of withFrontmatter) {
+    let fieldCount = 0;
+    for (const field of AGENT_OPTIONAL_FIELDS) {
+      if (new RegExp(`^${field}:`, 'm').test(frontmatter)) fieldCount++;
+    }
+    totalFields += fieldCount;
+
+    const hasDisallowed = /^disallowedTools:/m.test(frontmatter);
+    const hasReminder = /^criticalSystemReminder:/m.test(frontmatter);
+    if (hasDisallowed && !hasReminder) {
+      suggestions.push(`${name}: read-only agent could benefit from criticalSystemReminder`);
+    }
+  }
+
+  const totalPossible = withFrontmatter.length * AGENT_OPTIONAL_FIELDS.length;
+  const pct = Math.round((totalFields / totalPossible) * 100);
+  const results = [];
+
+  if (pct >= 50) {
+    results.push(
+      result(
+        PASS,
+        `Agent enrichment: ${pct}% optional fields used across ${withFrontmatter.length} agents`,
+        null
+      )
+    );
+  } else {
+    results.push(
+      result(
+        WARN,
+        `Agent enrichment: ${pct}% optional fields used across ${withFrontmatter.length} agents`,
+        'Run `worclaude upgrade` to add model, maxTurns, skills, and other metadata'
+      )
+    );
+  }
+
+  for (const s of suggestions) {
+    results.push(result(WARN, s, null));
+  }
+
+  return results;
+}
+
+async function checkClaudeMdSections(projectRoot) {
+  const claudeMdPath = path.join(projectRoot, 'CLAUDE.md');
+  const SECTION_THRESHOLD = 20000; // Only analyze sections if file > 20KB
+  const results = [];
+
+  try {
+    const content = await readFile(claudeMdPath);
+    if (content.length < SECTION_THRESHOLD) return results;
+
+    // Split into ## sections
+    const sections = [];
+    const lines = content.split('\n');
+    let currentHeading = '(top-level)';
+    let currentLines = [];
+
+    for (const line of lines) {
+      const headingMatch = line.match(/^##\s+(.+)/);
+      if (headingMatch) {
+        if (currentLines.length > 0) {
+          sections.push({ heading: currentHeading, size: currentLines.join('\n').length });
+        }
+        currentHeading = headingMatch[1];
+        currentLines = [];
+      } else {
+        currentLines.push(line);
+      }
+    }
+    if (currentLines.length > 0) {
+      sections.push({ heading: currentHeading, size: currentLines.join('\n').length });
+    }
+
+    // Sort by size, suggest extracting the top 3 sections > 2KB
+    const large = sections.filter((s) => s.size > 2000).sort((a, b) => b.size - a.size);
+
+    if (large.length > 0) {
+      const top = large.slice(0, 3);
+      const sectionList = top
+        .map((s) => `"${s.heading}" (${(s.size / 1024).toFixed(1)}KB)`)
+        .join(', ');
+      results.push(
+        result(
+          WARN,
+          `CLAUDE.md has large sections: ${sectionList}`,
+          'Consider extracting to conditional skills with paths frontmatter to save context budget'
+        )
+      );
+    }
+  } catch {
+    // Already covered by checkClaudeMd
+  }
+
+  return results;
+}
+
 async function checkPendingReviewFiles(projectRoot) {
   const pending = [];
   try {
@@ -287,6 +544,8 @@ export async function doctorCommand() {
   const meta = await readWorkflowMeta(projectRoot);
 
   printResult(await checkClaudeMd(projectRoot));
+  for (const r of await checkClaudeMdSize(projectRoot)) printResult(r);
+  for (const r of await checkClaudeMdSections(projectRoot)) printResult(r);
   printResult(await checkSettingsJson(projectRoot));
   printResult(await checkSessions(projectRoot));
   display.newline();
@@ -294,8 +553,11 @@ export async function doctorCommand() {
   // Components
   display.barLine(display.white('Components'));
   for (const r of await checkAgents(projectRoot, meta)) printResult(r);
+  for (const r of await checkAgentDescription(projectRoot)) printResult(r);
   for (const r of await checkCommands(projectRoot)) printResult(r);
   for (const r of await checkSkills(projectRoot)) printResult(r);
+  for (const r of await checkSkillFormat(projectRoot)) printResult(r);
+  for (const r of await checkAgentCompleteness(projectRoot)) printResult(r);
   display.newline();
 
   // Docs
@@ -311,7 +573,7 @@ export async function doctorCommand() {
 
   // Summary
   if (metaResult.status === FAIL) {
-    display.error('Workflow is not installed. Run `worclaude init` to set up.');
+    display.info('Workflow is not installed. Run `worclaude init` to set up.');
   } else {
     display.success('Doctor complete. Review any warnings above.');
   }