worclaude 2.0.0 → 2.2.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": "2.0.0",
+  "version": "2.2.0",
   "description": "CLI tool that scaffolds a comprehensive Claude Code workflow into any project",
   "type": "module",
   "bin": {

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

@@ -177,59 +177,57 @@ async function checkAgents(projectRoot, meta) {
   return results;
 }
 
-async function checkAgentDescription(projectRoot) {
+async function readAgentFrontmatters(projectRoot) {
   const agentsDir = path.join(projectRoot, '.claude', 'agents');
-  const results = [];
-
   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 filePath = path.join(agentsDir, file.name);
-      const content = await readFile(filePath);
-
-      // Parse YAML frontmatter
-      const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-      if (!frontmatterMatch) {
-        results.push(
-          result(
-            FAIL,
-            `agents/${file.name}`,
-            'No YAML frontmatter — agent is invisible to Claude Code'
-          )
-        );
-        continue;
-      }
+      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 [];
+  }
+}
 
-      const frontmatter = frontmatterMatch[1];
-      const hasName = /^name:\s*.+/m.test(frontmatter);
-      const hasDescription = /^description:\s*.+/m.test(frontmatter);
-
-      if (!hasName) {
-        results.push(
-          result(FAIL, `agents/${file.name}`, 'Missing required "name" field in frontmatter')
-        );
-      } else if (!hasDescription) {
-        results.push(
-          result(
-            FAIL,
-            `agents/${file.name}`,
-            'Missing required "description" field — agent is invisible to Claude Code\'s /agents and routing'
-          )
-        );
-      }
+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;
     }
 
-    if (results.length === 0 && mdFiles.length > 0) {
+    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(PASS, `agents/ frontmatter (${mdFiles.length} agents have required fields)`, null)
+        result(
+          FAIL,
+          `agents/${name}`,
+          'Missing required "description" field — agent is invisible to Claude Code\'s /agents and routing'
+        )
       );
     }
-  } catch {
-    // agents/ doesn't exist — covered by existing component checks
   }
 
+  if (results.length === 0) {
+    results.push(
+      result(PASS, `agents/ frontmatter (${agents.length} agents have required fields)`, null)
+    );
+  }
   return results;
 }
 
@@ -385,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 {
@@ -429,6 +545,7 @@ export async function doctorCommand() {
 
   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();
@@ -440,6 +557,7 @@ export async function doctorCommand() {
   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
@@ -455,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.');
   }

package/src/commands/init.js

@@ -31,111 +31,137 @@ import { buildAgentRoutingSkill } from '../generators/agent-routing.js';
 
 // --- Helper functions ---
 
+const LANGUAGE_COMMANDS = {
+  python: {
+    heading: 'Python',
+    commands: [
+      'python -m pytest                # Run tests',
+      'ruff check .                    # Lint',
+      'ruff format .                   # Format',
+    ],
+  },
+  node: {
+    heading: 'Node.js / TypeScript',
+    commands: [
+      'npm test                        # Run tests',
+      'npx eslint .                    # Lint',
+      'npx prettier --write .          # Format',
+    ],
+  },
+  java: {
+    heading: 'Java',
+    commands: [
+      'mvn test                        # Run tests',
+      'mvn checkstyle:check            # Lint',
+      'mvn spotless:apply              # Format',
+    ],
+  },
+  csharp: {
+    heading: 'C# / .NET',
+    commands: [
+      'dotnet test                     # Run tests',
+      'dotnet format --verify-no-changes # Lint',
+      'dotnet format                   # Format',
+    ],
+  },
+  cpp: {
+    heading: 'C / C++',
+    commands: [
+      'cmake --build build && ctest    # Build & test',
+      'clang-tidy src/*.cpp            # Lint',
+      'clang-format -i src/*.[ch]pp    # Format',
+    ],
+  },
+  go: {
+    heading: 'Go',
+    commands: [
+      'go test ./...                   # Run tests',
+      'golangci-lint run               # Lint',
+      'gofmt -w .                      # Format',
+    ],
+  },
+  php: {
+    heading: 'PHP',
+    commands: [
+      'vendor/bin/phpunit              # Run tests',
+      'vendor/bin/phpstan analyse      # Lint',
+      'vendor/bin/php-cs-fixer fix .   # Format',
+    ],
+  },
+  ruby: {
+    heading: 'Ruby',
+    commands: [
+      'bundle exec rspec               # Run tests',
+      'rubocop                         # Lint',
+      'rubocop -A                      # Format',
+    ],
+  },
+  kotlin: {
+    heading: 'Kotlin',
+    commands: [
+      'gradle test                     # Run tests',
+      'detekt                          # Lint',
+      'ktlint -F                       # Format',
+    ],
+  },
+  swift: {
+    heading: 'Swift',
+    commands: [
+      'swift test                      # Run tests',
+      'swiftlint                       # Lint',
+      'swift-format format -r . -i     # Format',
+    ],
+  },
+  rust: {
+    heading: 'Rust',
+    commands: [
+      'cargo test                      # Run tests',
+      'cargo clippy                    # Lint',
+      'cargo fmt                       # Format',
+    ],
+  },
+  dart: {
+    heading: 'Dart / Flutter',
+    commands: [
+      'dart test                       # Run tests',
+      'dart analyze                    # Lint',
+      'dart format .                   # Format',
+    ],
+  },
+  scala: {
+    heading: 'Scala',
+    commands: [
+      'sbt test                        # Run tests',
+      'sbt scalafix                    # Lint',
+      'scalafmt                        # Format',
+    ],
+  },
+  elixir: {
+    heading: 'Elixir',
+    commands: [
+      'mix test                        # Run tests',
+      'mix credo                       # Lint',
+      'mix format                      # Format',
+    ],
+  },
+  zig: {
+    heading: 'Zig',
+    commands: [
+      'zig build test                  # Run tests',
+      'zig build                       # Build (lint via compiler)',
+      'zig fmt .                       # Format',
+    ],
+  },
+};
+
 function buildCommandsBlock(languages, useDocker) {
   const lines = ['```bash'];
-  if (languages.includes('python')) {
-    lines.push('# Python');
-    lines.push('python -m pytest                # Run tests');
-    lines.push('ruff check .                    # Lint');
-    lines.push('ruff format .                   # Format');
-  }
-  if (languages.includes('node')) {
-    if (lines.length > 1) lines.push('');
-    lines.push('# Node.js / TypeScript');
-    lines.push('npm test                        # Run tests');
-    lines.push('npx eslint .                    # Lint');
-    lines.push('npx prettier --write .          # Format');
-  }
-  if (languages.includes('java')) {
-    if (lines.length > 1) lines.push('');
-    lines.push('# Java');
-    lines.push('mvn test                        # Run tests');
-    lines.push('mvn checkstyle:check            # Lint');
-    lines.push('mvn spotless:apply              # Format');
-  }
-  if (languages.includes('csharp')) {
-    if (lines.length > 1) lines.push('');
-    lines.push('# C# / .NET');
-    lines.push('dotnet test                     # Run tests');
-    lines.push('dotnet format --verify-no-changes # Lint');
-    lines.push('dotnet format                   # Format');
-  }
-  if (languages.includes('cpp')) {
-    if (lines.length > 1) lines.push('');
-    lines.push('# C / C++');
-    lines.push('cmake --build build && ctest    # Build & test');
-    lines.push('clang-tidy src/*.cpp            # Lint');
-    lines.push('clang-format -i src/*.[ch]pp    # Format');
-  }
-  if (languages.includes('go')) {
-    if (lines.length > 1) lines.push('');
-    lines.push('# Go');
-    lines.push('go test ./...                   # Run tests');
-    lines.push('golangci-lint run               # Lint');
-    lines.push('gofmt -w .                      # Format');
-  }
-  if (languages.includes('php')) {
-    if (lines.length > 1) lines.push('');
-    lines.push('# PHP');
-    lines.push('vendor/bin/phpunit              # Run tests');
-    lines.push('vendor/bin/phpstan analyse      # Lint');
-    lines.push('vendor/bin/php-cs-fixer fix .   # Format');
-  }
-  if (languages.includes('ruby')) {
-    if (lines.length > 1) lines.push('');
-    lines.push('# Ruby');
-    lines.push('bundle exec rspec               # Run tests');
-    lines.push('rubocop                         # Lint');
-    lines.push('rubocop -A                      # Format');
-  }
-  if (languages.includes('kotlin')) {
-    if (lines.length > 1) lines.push('');
-    lines.push('# Kotlin');
-    lines.push('gradle test                     # Run tests');
-    lines.push('detekt                          # Lint');
-    lines.push('ktlint -F                       # Format');
-  }
-  if (languages.includes('swift')) {
-    if (lines.length > 1) lines.push('');
-    lines.push('# Swift');
-    lines.push('swift test                      # Run tests');
-    lines.push('swiftlint                       # Lint');
-    lines.push('swift-format format -r . -i     # Format');
-  }
-  if (languages.includes('rust')) {
-    if (lines.length > 1) lines.push('');
-    lines.push('# Rust');
-    lines.push('cargo test                      # Run tests');
-    lines.push('cargo clippy                    # Lint');
-    lines.push('cargo fmt                       # Format');
-  }
-  if (languages.includes('dart')) {
-    if (lines.length > 1) lines.push('');
-    lines.push('# Dart / Flutter');
-    lines.push('dart test                       # Run tests');
-    lines.push('dart analyze                    # Lint');
-    lines.push('dart format .                   # Format');
-  }
-  if (languages.includes('scala')) {
-    if (lines.length > 1) lines.push('');
-    lines.push('# Scala');
-    lines.push('sbt test                        # Run tests');
-    lines.push('sbt scalafix                    # Lint');
-    lines.push('scalafmt                        # Format');
-  }
-  if (languages.includes('elixir')) {
-    if (lines.length > 1) lines.push('');
-    lines.push('# Elixir');
-    lines.push('mix test                        # Run tests');
-    lines.push('mix credo                       # Lint');
-    lines.push('mix format                      # Format');
-  }
-  if (languages.includes('zig')) {
+  for (const lang of languages) {
+    const entry = LANGUAGE_COMMANDS[lang];
+    if (!entry) continue;
     if (lines.length > 1) lines.push('');
-    lines.push('# Zig');
-    lines.push('zig build test                  # Run tests');
-    lines.push('zig build                       # Build (lint via compiler)');
-    lines.push('zig fmt .                       # Format');
+    lines.push(`# ${entry.heading}`);
+    lines.push(...entry.commands);
   }
   if (useDocker) {
     if (lines.length > 1) lines.push('');

package/src/commands/status.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { readWorkflowMeta, workflowMetaExists, getPackageVersion } from '../core/config.js';
+import { requireWorkflowMeta, getPackageVersion } from '../core/config.js';
 import { hashFile } from '../utils/hash.js';
 import { fileExists, readFile, listFilesRecursive } from '../utils/file.js';
 import { getLatestNpmVersion } from '../utils/npm.js';
@@ -15,13 +15,12 @@ function countByPrefix(fileHashes, prefix) {
 export async function statusCommand() {
   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/upgrade.js

@@ -4,8 +4,7 @@ import inquirer from 'inquirer';
 import ora from 'ora';
 import {
   computeFileHashes,
-  readWorkflowMeta,
-  workflowMetaExists,
+  requireWorkflowMeta,
   writeWorkflowMeta,
   getPackageVersion,
 } from '../core/config.js';
@@ -70,16 +69,13 @@ export async function upgradeCommand() {
   }
 
   // 2. Check prerequisite
-  if (!(await workflowMetaExists(projectRoot))) {
-    display.error('No workflow installation found.');
-    display.info('Run `worclaude init` to set up the 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 invalid.');
-    display.info('Run `worclaude init` to reinstall (a backup will be created first).');
+  if (error === 'corrupted') {
+    display.error('workflow-meta.json is corrupted. Run `worclaude init` to reinstall.');
     return;
   }
 

package/src/core/config.js

@@ -59,6 +59,17 @@ export async function writeWorkflowMeta(projectRoot, meta) {
   await writeFile(metaPath, JSON.stringify(meta, null, 2));
 }
 
+export async function requireWorkflowMeta(projectRoot) {
+  if (!(await workflowMetaExists(projectRoot))) {
+    return { meta: null, error: 'not-installed' };
+  }
+  const meta = await readWorkflowMeta(projectRoot);
+  if (!meta) {
+    return { meta: null, error: 'corrupted' };
+  }
+  return { meta, error: null };
+}
+
 export async function computeFileHashes(projectRoot) {
   const claudeDir = path.join(projectRoot, '.claude');
   const allFiles = await listFilesRecursive(claudeDir);

package/src/utils/display.js

@@ -64,15 +64,6 @@ export const MODEL_BADGES = {
   haiku: badges.haiku,
 };
 
-export const CATEGORY_BADGES = {
-  Backend: badges.backend,
-  Frontend: badges.frontend,
-  DevOps: badges.devops,
-  Quality: badges.quality,
-  Documentation: badges.docs,
-  'Data / AI': badges.dataai,
-};
-
 export const STACK_BADGES = {
   Python: badges.python,
   'Node.js / TypeScript': badges.node,

package/templates/agents/optional/quality/security-reviewer.md

@@ -11,6 +11,9 @@ disallowedTools:
 maxTurns: 40
 omitClaudeMd: true
 memory: project
+skills:
+  - security-checklist
+criticalSystemReminder: "CRITICAL: You CANNOT edit files. Report vulnerabilities with remediation guidance only."
 ---
 
 You are a senior application security engineer performing a code

package/templates/agents/universal/plan-reviewer.md

@@ -10,6 +10,7 @@ disallowedTools:
   - Agent
 maxTurns: 30
 omitClaudeMd: true
+criticalSystemReminder: "CRITICAL: You CANNOT edit files. Review and report findings only."
 ---
 
 You are a senior staff engineer reviewing an implementation plan.

package/templates/agents/universal/test-writer.md

@@ -5,6 +5,8 @@ model: sonnet
 isolation: worktree
 maxTurns: 50
 memory: project
+skills:
+  - testing
 ---
 
 You are a test specialist. You write comprehensive, meaningful tests

package/templates/agents/universal/verify-app.md

@@ -5,6 +5,8 @@ model: sonnet
 isolation: worktree
 background: true
 maxTurns: 50
+initialPrompt: "/start"
+criticalSystemReminder: "CRITICAL: You are verification-only. Do NOT edit or fix code. Report findings with exact reproduction steps."
 ---
 
 You are a verification specialist. You test the actual running
@@ -110,6 +112,9 @@ You will feel the urge to skip checks. These are the excuses — recognize them:
 - **Config/Infrastructure**: validate syntax → dry-run where possible → check env vars
 - **Bug fixes**: reproduce original bug → verify fix → run regression tests
 - **Refactoring**: existing test suite must pass unchanged → diff public API surface
+- **Mobile (iOS/Android)**: clean build → install on simulator/emulator → dump accessibility/UI tree, tap by coords, re-dump to verify → check crash logs (logcat / device console)
+- **Database migrations**: run migration up → verify schema matches intent → run migration down (reversibility) → test against existing data, not just empty DB
+- **Data/ML pipeline**: run with sample input → verify output shape/schema/types → test empty input and NaN/null handling → check row counts in vs out for silent data loss
 
 ## Before Issuing PASS
 

package/templates/core/memory-md.md

@@ -7,23 +7,51 @@
 ## User
 
 <!-- Role, preferences, expertise — helps Claude tailor responses -->
+<!-- Example: - [Backend lead](user_role.md) — 8 years Python, new to this frontend -->
 
 ## Feedback
 
 <!-- What to do and what to avoid — both corrections AND confirmed approaches -->
 <!-- Format: rule, then **Why:** and **How to apply:** -->
+<!-- Example: - [No mocks in integration tests](feedback_testing.md) — burned by mock/prod divergence -->
 
 ## Project
 
 <!-- Ongoing work, goals, deadlines — convert relative dates to absolute -->
 <!-- Format: fact/decision, then **Why:** and **How to apply:** -->
+<!-- Example: - [Merge freeze 2026-03-05](project_release.md) — mobile team cutting release branch -->
 
 ## Reference
 
 <!-- Pointers to external systems — Linear boards, Slack channels, dashboards -->
+<!-- Example: - [Pipeline bugs](reference_linear.md) — tracked in Linear project "INGEST" -->
 
 ---
 
+## Memory File Format
+
+Each memory file in `.claude/memory/` uses this frontmatter:
+
+```markdown
+---
+name: descriptive-name
+description: one-line summary used to decide relevance in future sessions
+type: user | feedback | project | reference
+---
+
+Content here. For feedback/project types, structure as:
+Rule or fact.
+**Why:** the reason or context.
+**How to apply:** when and where this guidance applies.
+```
+
+## Drift and Verification
+
+- Memory records become stale over time. Before acting on a memory, verify it against the current state of the codebase.
+- If a memory names a file path, check the file still exists. If it names a function or flag, grep for it.
+- If a recalled memory conflicts with current information, trust what you observe now — update or remove the stale memory.
+- "The memory says X exists" is not the same as "X exists now."
+
 ## What NOT to save here
 
 - Code patterns, architecture, file paths — derivable from current project state
@@ -31,3 +59,12 @@
 - Debugging solutions — the fix is in the code, the context is in the commit message
 - Anything already in CLAUDE.md
 - Ephemeral task details — current conversation context, in-progress work
+
+These exclusions apply even when explicitly asked to save. If asked to save a PR list or activity summary, ask what was *surprising* or *non-obvious* about it — that is the part worth keeping.
+
+## Memory vs Plans vs Tasks
+
+Memory is for information useful across conversations. Don't use it for:
+- **Plans** — use a plan file or plan mode for implementation strategies within a session
+- **Tasks** — use the task system for tracking work steps within a session
+- **Session state** — current conversation context belongs in the conversation, not memory

package/templates/skills/universal/claude-md-maintenance.md

@@ -1,6 +1,7 @@
 ---
 description: "How Claude writes rules for itself, when to update CLAUDE.md, keeping it lean and effective"
 when_to_use: "When considering updates to CLAUDE.md, when the same mistake has happened twice, when CLAUDE.md is getting too long"
+version: "1.0.0"
 ---
 
 # CLAUDE.md Maintenance
@@ -99,6 +100,28 @@ The /update-claude-md command helps at session end:
 Always review proposed changes before applying. Not every mistake needs a rule.
 Only add rules for recurring problems.
 
+## The @include Directive
+
+When CLAUDE.md grows beyond the 50-line target, use `@include` to split content
+into separate files while keeping it loadable:
+
+```markdown
+# CLAUDE.md
+## Key Files
+@./docs/conventions.md
+@./docs/api-standards.md
+```
+
+- `@./relative` — relative to the file containing the directive
+- `@~/path` — relative to home directory
+- `@/absolute` — absolute path
+- Works in CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md, and CLAUDE.local.md
+- Does NOT work inside code blocks (only in leaf text nodes)
+- Non-existent files are silently ignored; circular references are prevented
+
+This is the recommended alternative to cramming everything into CLAUDE.md.
+Each included file still consumes context budget, so use judiciously.
+
 ## Gotchas
 
 - CLAUDE.md is read as system context, not as a document. Write it as instructions,

package/templates/skills/universal/context-management.md

@@ -1,6 +1,7 @@
 ---
 description: "Context budget awareness, when to compact, when to clear, subagent offloading"
 when_to_use: "When context is running low, before compaction decisions, when deciding whether to use subagents for context hygiene"
+version: "1.0.0"
 ---
 
 # Context Management
@@ -117,6 +118,29 @@ WORCLAUDE_HOOK_PROFILE=strict claude
 The default is `standard` if the variable is not set. You don't need to do
 anything for normal development — the default just works.
 
+## Token Budgets (Reference)
+
+Approximate values from Claude Code v2.1.88 source (March 2026). These may change between releases.
+
+| Resource | Budget |
+|---|---|
+| Context window (default) | 200,000 tokens |
+| Context window (Opus 4.6 / Sonnet 4.6 with 1M) | 1,000,000 tokens |
+| Max output tokens (Sonnet 4.6) | 32,000 default, 128,000 upper limit |
+| Max output tokens (Opus 4.6) | 64,000 default, 128,000 upper limit |
+| Tool presence overhead | ~500 tokens (added when any tools are enabled) |
+| Post-compact file restore | 5 files max, 50,000 token budget, 5,000 per file |
+| Post-compact skills restore | 25,000 token budget, 5,000 per skill |
+| Compact summary output | 20,000 tokens max |
+| CLAUDE.md total budget | ~40,000 characters across all loaded instruction files |
+| MEMORY.md | 200 lines / 25,000 bytes |
+
+Practical takeaways:
+- After compaction, only 5 files are restored at 5k tokens each. Structure your work
+  so the most important files are recently read.
+- Skills over 5k tokens get truncated after compaction. Keep skills focused.
+- The 70% rule still applies — these numbers help you estimate when you'll hit it.
+
 ## Gotchas
 
 - Compacting doesn't free as much context as you think. If you've read 20 large files,

package/templates/skills/universal/coordinator-mode.md

@@ -1,6 +1,7 @@
 ---
 description: 'Multi-agent orchestration patterns: when to use coordinator mode, worker prompts, parallel execution'
 when_to_use: 'When working with multiple agents or terminals in parallel, or when deciding how to break a large task into coordinated sub-tasks'
+version: "1.0.0"
 ---
 
 # Coordinator Mode
@@ -20,6 +21,25 @@ Don't use coordinator patterns when:
 - Steps are strictly sequential with no parallelism
 - The overhead of coordination exceeds the work itself
 
+## Phase-Based Workflow
+
+Most coordinated tasks follow four phases:
+
+| Phase | Who | Purpose |
+|-------|-----|---------|
+| Research | Workers (parallel) | Investigate codebase, find files, understand problem |
+| Synthesis | **You** (coordinator) | Read findings, understand the problem, craft implementation specs |
+| Implementation | Workers | Make targeted changes per spec, commit |
+| Verification | Workers | Test changes work, try to break them |
+
+The synthesis phase is the coordinator's most important job. When workers report
+research findings, **you must understand them before directing follow-up work**.
+Read the findings. Identify the approach. Then write a prompt that proves you
+understood by including specific file paths, line numbers, and exactly what to change.
+
+Never write "based on your findings" or "based on the research." These phrases
+delegate understanding to the worker instead of doing it yourself.
+
 ## Worker Prompt Best Practices
 
 Workers cannot see your conversation. Every prompt must be self-contained:

package/templates/skills/universal/git-conventions.md

@@ -1,6 +1,7 @@
 ---
 description: "Branch naming, commit message format, PR workflow, worktree conventions, versioning policy"
 when_to_use: "When creating branches, writing commit messages, creating PRs, or making versioning decisions"
+version: "1.0.0"
 ---
 
 # Git Conventions

package/templates/skills/universal/planning-with-files.md

@@ -1,6 +1,7 @@
 ---
 description: "How to structure implementation plans as files, progressive implementation, plan review process"
 when_to_use: "When starting a multi-step task that needs a written plan, or when reviewing an existing implementation plan"
+version: "1.0.0"
 ---
 
 # Planning with Files

package/templates/skills/universal/prompt-engineering.md

@@ -1,6 +1,7 @@
 ---
 description: "Effective prompting patterns for working with Claude, demanding quality, writing specs"
 when_to_use: "When writing or editing prompts, skills, agent definitions, or CLAUDE.md instructions"
+version: "1.0.0"
 ---
 
 # Prompt Engineering

package/templates/skills/universal/review-and-handoff.md

@@ -1,6 +1,7 @@
 ---
 description: "Session ending protocol, HANDOFF document format, seamless continuation between sessions"
 when_to_use: "When ending a session, writing handoff documents, or updating PROGRESS.md"
+version: "1.0.0"
 ---
 
 # Review and Handoff

package/templates/skills/universal/security-checklist.md

@@ -1,6 +1,7 @@
 ---
 description: "OWASP-based security checklist any agent can reference when reviewing or writing code"
 when_to_use: "When writing code that handles user input, authentication, authorization, file uploads, or external data"
+version: "1.0.0"
 paths:
   - "**/auth/**"
   - "**/security/**"

package/templates/skills/universal/subagent-usage.md

@@ -1,6 +1,7 @@
 ---
 description: "When to use subagents, how many, context hygiene, worktree isolation patterns"
 when_to_use: "When deciding whether to spawn a subagent, choosing between parallel and sequential execution, or giving subagent instructions"
+version: "1.0.0"
 ---
 
 # Subagent Usage

package/templates/skills/universal/testing.md

@@ -1,6 +1,7 @@
 ---
 description: "Test philosophy, coverage strategy, test-first patterns, what to test and what not to"
 when_to_use: "When writing, modifying, or reviewing tests, or when making decisions about test strategy and coverage"
+version: "1.0.0"
 paths:
   - "test/**"
   - "tests/**"

package/templates/skills/universal/verification.md

@@ -1,6 +1,7 @@
 ---
 description: "Domain-specific verification beyond tests, closing the feedback loop for web, API, CLI, data"
 when_to_use: "When verifying that implemented changes work correctly, after running automated tests, before committing"
+version: "1.0.0"
 paths:
   - "test/**"
   - "tests/**"