worclaude 2.5.0 → 2.6.0

package/src/core/merger.js

@@ -10,6 +10,7 @@ import {
   scaffoldPluginJson,
   scaffoldMemoryDocs,
 } from './scaffolder.js';
+import { workflowRefRelPath } from './file-categorizer.js';
 import { promptHookConflict } from '../prompts/conflict-resolution.js';
 import {
   detectMissingSections,
@@ -124,10 +125,11 @@ async function mergeSkills(projectRoot, existingScan, variables, report, selecti
     const existsAsFlat = existingScan.existingSkills.includes(`${skill.name}.md`);
 
     if (existsAsDir || existsAsFlat) {
-      // Tier 2: conflict — save as .workflow-ref.md
+      // Tier 2: conflict — save under .claude/workflow-ref/ so the live
+      // SKILL.md stays authoritative and the ref cannot shadow it.
       await scaffoldFile(
         skill.templatePath,
-        path.join('.claude', 'skills', skill.name, 'SKILL.workflow-ref.md'),
+        workflowRefRelPath(`skills/${skill.name}/SKILL.md`),
         skill.vars,
         projectRoot
       );
@@ -147,7 +149,7 @@ async function mergeSkills(projectRoot, existingScan, variables, report, selecti
 
   if (routingExistsAsDir || routingExistsAsFlat) {
     await writeFile(
-      path.join(projectRoot, skillsDir, 'agent-routing', 'SKILL.workflow-ref.md'),
+      path.join(projectRoot, workflowRefRelPath('skills/agent-routing/SKILL.md')),
       routingContent
     );
     report.conflicts.skills.push('agent-routing');
@@ -166,7 +168,7 @@ async function mergeAgents(projectRoot, existingScan, selectedAgents, report) {
     if (existingScan.existingAgents.includes(filename)) {
       await scaffoldFile(
         `agents/universal/${agent}.md`,
-        path.join(destDir, `${agent}.workflow-ref.md`),
+        workflowRefRelPath(`agents/${filename}`),
         {},
         projectRoot
       );
@@ -191,7 +193,7 @@ async function mergeAgents(projectRoot, existingScan, selectedAgents, report) {
     if (existingScan.existingAgents.includes(filename)) {
       await scaffoldFile(
         `agents/optional/${category}/${agent}.md`,
-        path.join(destDir, `${agent}.workflow-ref.md`),
+        workflowRefRelPath(`agents/${filename}`),
         {},
         projectRoot
       );
@@ -216,7 +218,7 @@ async function mergeCommands(projectRoot, existingScan, report) {
     if (existingScan.existingCommands.includes(filename)) {
       await scaffoldFile(
         `commands/${cmd}.md`,
-        path.join(destDir, `${cmd}.workflow-ref.md`),
+        workflowRefRelPath(`commands/${filename}`),
         {},
         projectRoot
       );
@@ -431,7 +433,12 @@ async function mergeAgentsMd(projectRoot, existingScan, variables, report) {
     await scaffoldFile('core/agents-md.md', 'AGENTS.md', variables, projectRoot);
     report.agentsMdHandling = 'created';
   } else {
-    await scaffoldFile('core/agents-md.md', 'AGENTS.md.workflow-ref', variables, projectRoot);
+    await scaffoldFile(
+      'core/agents-md.md',
+      workflowRefRelPath('root/AGENTS.md'),
+      variables,
+      projectRoot
+    );
     report.agentsMdHandling = 'saved-alongside';
   }
 }

package/src/core/migration.js

@@ -1,7 +1,16 @@
 import path from 'node:path';
 import { AGENT_CATALOG } from '../data/agents.js';
-import { readFile, writeFile, dirExists, moveFile, listFiles } from '../utils/file.js';
+import {
+  fileExists,
+  readFile,
+  writeFile,
+  dirExists,
+  moveFile,
+  listFiles,
+  listFilesRecursive,
+} from '../utils/file.js';
 import { hashFile } from '../utils/hash.js';
+import { WORKFLOW_REF_DIR } from './file-categorizer.js';
 
 // --- Version comparison ---
 
@@ -142,3 +151,70 @@ export async function patchAgentDescriptions(projectRoot, meta, promptFn) {
 
   return report;
 }
+
+// --- Workflow-ref relocation (v2.5.1) ---
+
+const LEGACY_ROOT_REFS = ['CLAUDE.md.workflow-ref.md', 'AGENTS.md.workflow-ref'];
+
+// Legacy ref files could only live inside these subdirs. Scoping the scan
+// here instead of walking all of .claude/ matters because `sessions/` and
+// `learnings/` can accumulate hundreds of files that will never be refs.
+const LEGACY_REF_SUBDIRS = ['commands', 'agents', 'skills'];
+
+function legacyClaudeRefTarget(relKey) {
+  // relKey is relative to .claude/, e.g. "commands/sync.workflow-ref.md".
+  // Lookahead `(?=\.[^.]+$)` ensures ".workflow-ref" is stripped only when
+  // followed by a final extension — so "sync.workflow-ref.md" → "sync.md",
+  // but a hypothetical "sync.workflow-ref" (no final ext) wouldn't match.
+  const parts = relKey.split('/');
+  const name = parts.pop();
+  parts.push(name.replace(/\.workflow-ref(?=\.[^.]+$)/, ''));
+  return path.join(WORKFLOW_REF_DIR, ...parts);
+}
+
+export async function migrateWorkflowRefLocation(projectRoot) {
+  const report = { moved: 0, names: [], skipped: [] };
+  const claudeDir = path.join(projectRoot, '.claude');
+  const refDir = path.join(claudeDir, WORKFLOW_REF_DIR);
+
+  // 1. Scan only the subdirs where legacy `.workflow-ref.md` siblings could
+  //    live. Walking all of .claude/ would re-stat hundreds of session files
+  //    on every upgrade for no benefit.
+  for (const subdir of LEGACY_REF_SUBDIRS) {
+    const scanRoot = path.join(claudeDir, subdir);
+    if (!(await dirExists(scanRoot))) continue;
+
+    const allFiles = await listFilesRecursive(scanRoot);
+    for (const fp of allFiles) {
+      const rel = path.relative(claudeDir, fp).split(path.sep).join('/');
+      if (!rel.endsWith('.workflow-ref.md')) continue;
+
+      const target = path.join(claudeDir, legacyClaudeRefTarget(rel));
+      if (await fileExists(target)) {
+        report.skipped.push(rel);
+        continue;
+      }
+      await moveFile(fp, target);
+      report.moved++;
+      report.names.push(rel);
+    }
+  }
+
+  // 2. Legacy root-level refs (CLAUDE.md.workflow-ref.md, AGENTS.md.workflow-ref).
+  for (const legacyName of LEGACY_ROOT_REFS) {
+    const src = path.join(projectRoot, legacyName);
+    if (!(await fileExists(src))) continue;
+
+    const original = legacyName.replace(/\.workflow-ref(?:\.md)?$/, '');
+    const target = path.join(refDir, original);
+    if (await fileExists(target)) {
+      report.skipped.push(legacyName);
+      continue;
+    }
+    await moveFile(src, target);
+    report.moved++;
+    report.names.push(legacyName);
+  }
+
+  return report;
+}

package/src/core/project-scanner/detectors/ci.js

@@ -0,0 +1,51 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { fileExists, dirExists } from '../../../utils/file.js';
+
+export default async function detectCi(projectRoot) {
+  const results = [];
+
+  const workflowsDir = path.join(projectRoot, '.github', 'workflows');
+  if (await dirExists(workflowsDir)) {
+    try {
+      const entries = await fs.readdir(workflowsDir, { withFileTypes: true });
+      const workflows = entries
+        .filter((e) => e.isFile() && /\.ya?ml$/.test(e.name))
+        .map((e) => e.name)
+        .sort();
+      if (workflows.length > 0) {
+        results.push({
+          field: 'ci',
+          value: { provider: 'GitHub Actions', workflows },
+          confidence: 'high',
+          source: '.github/workflows/',
+          candidates: null,
+        });
+      }
+    } catch {
+      /* missing or unreadable — non-fatal */
+    }
+  }
+
+  const other = [
+    { file: '.gitlab-ci.yml', provider: 'GitLab CI' },
+    { file: '.circleci/config.yml', provider: 'CircleCI' },
+    { file: 'azure-pipelines.yml', provider: 'Azure Pipelines' },
+    { file: 'Jenkinsfile', provider: 'Jenkins' },
+    { file: '.drone.yml', provider: 'Drone' },
+    { file: 'bitbucket-pipelines.yml', provider: 'Bitbucket Pipelines' },
+  ];
+  for (const { file, provider } of other) {
+    if (await fileExists(path.join(projectRoot, file))) {
+      results.push({
+        field: 'ci',
+        value: { provider, workflows: [path.basename(file)] },
+        confidence: 'high',
+        source: file,
+        candidates: null,
+      });
+    }
+  }
+
+  return results;
+}

package/src/core/project-scanner/detectors/deployment.js

@@ -0,0 +1,32 @@
+import path from 'node:path';
+import { fileExists } from '../../../utils/file.js';
+
+const DEPLOYMENTS = [
+  { file: 'vercel.json', target: 'Vercel' },
+  { file: 'netlify.toml', target: 'Netlify' },
+  { file: 'Dockerfile', target: 'Docker' },
+  { file: 'fly.toml', target: 'Fly.io' },
+  { file: 'railway.toml', target: 'Railway' },
+  { file: 'app.yaml', target: 'Google App Engine' },
+  { file: 'serverless.yml', target: 'Serverless Framework' },
+  { file: 'render.yaml', target: 'Render' },
+  { file: '.platform.app.yaml', target: 'Platform.sh' },
+  { file: 'wrangler.toml', target: 'Cloudflare Workers' },
+  { file: 'amplify.yml', target: 'AWS Amplify' },
+];
+
+export default async function detectDeployment(projectRoot) {
+  const results = [];
+  for (const { file, target } of DEPLOYMENTS) {
+    if (await fileExists(path.join(projectRoot, file))) {
+      results.push({
+        field: 'deployment',
+        value: target,
+        confidence: 'high',
+        source: file,
+        candidates: null,
+      });
+    }
+  }
+  return results;
+}

package/src/core/project-scanner/detectors/env-variables.js

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import { fileExists, readFile } from '../../../utils/file.js';
+import { getAllDeps, depMatches } from '../manifests.js';
+
+const ENV_FILES = ['.env.example', '.env.template', '.env.sample'];
+
+const SDK_SERVICES = [
+  { sdkPrefix: '@stripe/', service: 'Stripe', envPrefix: 'STRIPE_' },
+  { sdkPrefix: 'stripe', service: 'Stripe', envPrefix: 'STRIPE_' },
+  { sdkPrefix: '@aws-sdk/', service: 'AWS', envPrefix: 'AWS_' },
+  { sdkPrefix: '@sendgrid/', service: 'SendGrid', envPrefix: 'SENDGRID_' },
+  { sdkPrefix: 'twilio', service: 'Twilio', envPrefix: 'TWILIO_' },
+  { sdkPrefix: 'openai', service: 'OpenAI', envPrefix: 'OPENAI_' },
+  { sdkPrefix: '@anthropic-ai/', service: 'Anthropic', envPrefix: 'ANTHROPIC_' },
+  { sdkPrefix: '@google-cloud/', service: 'Google Cloud', envPrefix: 'GOOGLE_' },
+  { sdkPrefix: '@slack/', service: 'Slack', envPrefix: 'SLACK_' },
+  { sdkPrefix: 'postmark', service: 'Postmark', envPrefix: 'POSTMARK_' },
+  { sdkPrefix: 'resend', service: 'Resend', envPrefix: 'RESEND_' },
+  { sdkPrefix: '@sentry/', service: 'Sentry', envPrefix: 'SENTRY_' },
+];
+
+function parseEnvNames(content) {
+  const names = [];
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line === '' || line.startsWith('#')) continue;
+    const match = line.match(/^(?:export\s+)?([A-Z_][A-Z0-9_]*)\s*=/);
+    if (match) names.push(match[1]);
+  }
+  return names;
+}
+
+export default async function detectEnvVariables(projectRoot) {
+  let sourceFile = null;
+  let content = null;
+  for (const f of ENV_FILES) {
+    const p = path.join(projectRoot, f);
+    if (await fileExists(p)) {
+      sourceFile = f;
+      content = await readFile(p);
+      break;
+    }
+  }
+  if (!sourceFile) return [];
+
+  const names = parseEnvNames(content);
+  if (names.length === 0) {
+    return [
+      {
+        field: 'envVariables',
+        value: { names: [], inferredServices: [] },
+        confidence: 'high',
+        source: sourceFile,
+        candidates: null,
+      },
+    ];
+  }
+
+  const { js, py } = await getAllDeps(projectRoot);
+  const allDeps = { ...js, ...py };
+  const inferredServices = new Set();
+  for (const { sdkPrefix, service, envPrefix } of SDK_SERVICES) {
+    const pattern = sdkPrefix.endsWith('/') ? `${sdkPrefix}*` : sdkPrefix;
+    if (depMatches(allDeps, pattern) && names.some((n) => n.startsWith(envPrefix))) {
+      inferredServices.add(service);
+    }
+  }
+
+  return [
+    {
+      field: 'envVariables',
+      value: { names, inferredServices: Array.from(inferredServices) },
+      confidence: 'high',
+      source: sourceFile,
+      candidates: null,
+    },
+  ];
+}

package/src/core/project-scanner/detectors/external-apis.js

@@ -0,0 +1,45 @@
+import { getAllDeps, depMatches } from '../manifests.js';
+
+const SDK_MAP = [
+  { match: 'stripe', service: 'Stripe' },
+  { match: '@sendgrid/', service: 'SendGrid' },
+  { match: '@aws-sdk/', service: 'AWS' },
+  { match: 'twilio', service: 'Twilio' },
+  { match: 'openai', service: 'OpenAI' },
+  { match: '@anthropic-ai/sdk', service: 'Anthropic' },
+  { match: '@google-cloud/', service: 'Google Cloud' },
+  { match: '@slack/', service: 'Slack' },
+  { match: 'postmark', service: 'Postmark' },
+  { match: 'resend', service: 'Resend' },
+  { match: 'algoliasearch', service: 'Algolia' },
+  { match: 'pusher', service: 'Pusher' },
+  { match: 'posthog-js', service: 'PostHog' },
+  { match: 'posthog-node', service: 'PostHog' },
+  { match: '@sentry/', service: 'Sentry' },
+  { match: 'mixpanel', service: 'Mixpanel' },
+  { match: 'mixpanel-browser', service: 'Mixpanel' },
+];
+
+export default async function detectExternalApis(projectRoot) {
+  const { js, py, hasPackageJson, hasPyproject } = await getAllDeps(projectRoot);
+  if (!hasPackageJson && !hasPyproject) return [];
+
+  const allDeps = { ...js, ...py };
+  const services = new Set();
+  for (const { match, service } of SDK_MAP) {
+    const pattern = match.endsWith('/') ? `${match}*` : match;
+    if (depMatches(allDeps, pattern)) services.add(service);
+  }
+
+  if (services.size === 0) return [];
+
+  return [
+    {
+      field: 'externalApis',
+      value: Array.from(services),
+      confidence: 'high',
+      source: hasPackageJson ? 'package.json' : 'pyproject.toml',
+      candidates: null,
+    },
+  ];
+}

package/src/core/project-scanner/detectors/frameworks.js

@@ -0,0 +1,56 @@
+import { getAllDeps } from '../manifests.js';
+
+const FRAMEWORKS = [
+  { dep: 'next', name: 'Next.js' },
+  { dep: 'nuxt', name: 'Nuxt' },
+  { dep: 'astro', name: 'Astro' },
+  { dep: 'remix', name: 'Remix' },
+  { dep: 'sveltekit', name: 'SvelteKit' },
+  { dep: '@sveltejs/kit', name: 'SvelteKit' },
+  { dep: 'react', name: 'React' },
+  { dep: 'vue', name: 'Vue' },
+  { dep: 'svelte', name: 'Svelte' },
+  { dep: 'solid-js', name: 'SolidJS' },
+  { dep: 'express', name: 'Express' },
+  { dep: 'fastify', name: 'Fastify' },
+  { dep: 'hono', name: 'Hono' },
+  { dep: 'koa', name: 'Koa' },
+  { dep: '@nestjs/core', name: 'NestJS' },
+  { dep: 'fastapi', name: 'FastAPI' },
+  { dep: 'starlette', name: 'Starlette' },
+  { dep: 'django', name: 'Django' },
+  { dep: 'flask', name: 'Flask' },
+];
+
+export default async function detectFrameworks(projectRoot) {
+  const { js, py, hasPackageJson, hasPyproject } = await getAllDeps(projectRoot);
+  if (!hasPackageJson && !hasPyproject) return [];
+
+  const detected = [];
+  const sources = new Set();
+  const seen = new Set();
+  for (const { dep, name } of FRAMEWORKS) {
+    if (seen.has(name)) continue;
+    if (js[dep] !== undefined) {
+      detected.push({ name, version: typeof js[dep] === 'string' ? js[dep] : '' });
+      sources.add('package.json');
+      seen.add(name);
+    } else if (py[dep] !== undefined) {
+      detected.push({ name, version: typeof py[dep] === 'string' ? py[dep] : '' });
+      sources.add('pyproject.toml');
+      seen.add(name);
+    }
+  }
+
+  if (detected.length === 0) return [];
+
+  return [
+    {
+      field: 'frameworks',
+      value: detected,
+      confidence: 'high',
+      source: Array.from(sources).join(', '),
+      candidates: null,
+    },
+  ];
+}

package/src/core/project-scanner/detectors/language.js

@@ -0,0 +1,131 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { fileExists } from '../../../utils/file.js';
+
+async function hasAnyJsFile(projectRoot) {
+  try {
+    const entries = await fs.readdir(projectRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && /\.(js|mjs|cjs)$/.test(entry.name)) return true;
+    }
+    const srcDir = path.join(projectRoot, 'src');
+    if (await fileExists(srcDir)) {
+      const srcEntries = await fs.readdir(srcDir, { withFileTypes: true });
+      for (const entry of srcEntries) {
+        if (entry.isFile() && /\.(js|mjs|cjs)$/.test(entry.name)) return true;
+      }
+    }
+  } catch {
+    /* missing or unreadable — non-fatal */
+  }
+  return false;
+}
+
+async function hasTsFiles(projectRoot) {
+  try {
+    const srcDir = path.join(projectRoot, 'src');
+    if (await fileExists(srcDir)) {
+      const entries = await fs.readdir(srcDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isFile() && /\.(ts|tsx)$/.test(entry.name)) return true;
+      }
+    }
+  } catch {
+    /* missing or unreadable — non-fatal */
+  }
+  return false;
+}
+
+export default async function detectLanguage(projectRoot) {
+  const results = [];
+  const has = async (f) => fileExists(path.join(projectRoot, f));
+
+  if (await has('tsconfig.json')) {
+    results.push({
+      field: 'language',
+      value: 'TypeScript',
+      confidence: 'high',
+      source: 'tsconfig.json',
+      candidates: null,
+    });
+  } else if (await has('jsconfig.json')) {
+    results.push({
+      field: 'language',
+      value: 'JavaScript',
+      confidence: 'high',
+      source: 'jsconfig.json',
+      candidates: null,
+    });
+  } else if ((await hasAnyJsFile(projectRoot)) && !(await hasTsFiles(projectRoot))) {
+    results.push({
+      field: 'language',
+      value: 'JavaScript',
+      confidence: 'high',
+      source: '*.js files',
+      candidates: null,
+    });
+  }
+
+  const pythonFiles = ['pyproject.toml', 'setup.py', 'requirements.txt'];
+  for (const f of pythonFiles) {
+    if (await has(f)) {
+      results.push({
+        field: 'language',
+        value: 'Python',
+        confidence: 'high',
+        source: f,
+        candidates: null,
+      });
+      break;
+    }
+  }
+  if (!results.some((r) => r.value === 'Python')) {
+    try {
+      const entries = await fs.readdir(projectRoot, { withFileTypes: true });
+      const reqFile = entries.find((e) => e.isFile() && /^requirements.*\.txt$/.test(e.name));
+      if (reqFile) {
+        results.push({
+          field: 'language',
+          value: 'Python',
+          confidence: 'high',
+          source: reqFile.name,
+          candidates: null,
+        });
+      }
+    } catch {
+      /* missing or unreadable — non-fatal */
+    }
+  }
+
+  if (await has('Cargo.toml')) {
+    results.push({
+      field: 'language',
+      value: 'Rust',
+      confidence: 'high',
+      source: 'Cargo.toml',
+      candidates: null,
+    });
+  }
+
+  if (await has('go.mod')) {
+    results.push({
+      field: 'language',
+      value: 'Go',
+      confidence: 'high',
+      source: 'go.mod',
+      candidates: null,
+    });
+  }
+
+  if (await has('Gemfile')) {
+    results.push({
+      field: 'language',
+      value: 'Ruby',
+      confidence: 'high',
+      source: 'Gemfile',
+      candidates: null,
+    });
+  }
+
+  return results;
+}

package/src/core/project-scanner/detectors/linting.js

@@ -0,0 +1,58 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { fileExists } from '../../../utils/file.js';
+import { readPyprojectToml } from '../manifests.js';
+
+const CONFIGS = [
+  { tool: 'ESLint', patterns: [/^\.eslintrc(\..+)?$/, /^eslint\.config\.(js|ts|mjs|cjs)$/] },
+  { tool: 'Prettier', patterns: [/^\.prettierrc(\..+)?$/, /^prettier\.config\.(js|ts|mjs|cjs)$/] },
+  { tool: 'Biome', patterns: [/^biome\.jsonc?$/] },
+  { tool: 'Stylelint', patterns: [/^\.stylelintrc(\..+)?$/] },
+  { tool: 'RuboCop', patterns: [/^\.rubocop\.ya?ml$/] },
+];
+
+async function rootFiles(projectRoot) {
+  try {
+    const entries = await fs.readdir(projectRoot, { withFileTypes: true });
+    return entries.filter((e) => e.isFile()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+export default async function detectLinting(projectRoot) {
+  const files = await rootFiles(projectRoot);
+  const tools = new Set();
+  const sources = [];
+
+  for (const { tool, patterns } of CONFIGS) {
+    const match = files.find((f) => patterns.some((p) => p.test(f)));
+    if (match) {
+      tools.add(tool);
+      sources.push(match);
+    }
+  }
+
+  if (await fileExists(path.join(projectRoot, 'ruff.toml'))) {
+    tools.add('Ruff');
+    sources.push('ruff.toml');
+  } else {
+    const pyproject = await readPyprojectToml(projectRoot);
+    if (pyproject && pyproject.tool && pyproject.tool.ruff) {
+      tools.add('Ruff');
+      sources.push('pyproject.toml');
+    }
+  }
+
+  if (tools.size === 0) return [];
+
+  return [
+    {
+      field: 'linting',
+      value: Array.from(tools),
+      confidence: 'high',
+      source: sources.join(', '),
+      candidates: null,
+    },
+  ];
+}