@minhpnq1807/contextos 0.5.9 → 0.5.10

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.5.10
+
+- Adds workflow discovery for `.claude/workflows/`, `.codex/workflows/`, `~/.claude/workflows/`, and `~/.codex/workflows/`.
+- Adds `ctx sync --workflows` to parse markdown workflow headings, agent chains, and warm workflow embeddings.
+- Injects prompt-relevant workflow hints into ContextOS prompt context and shows them in `ctx debug`.
+
 ## 0.5.9
 
 - Formats `ctx report`, `ctx evidence`, `ctx stats`, and `ctx benchmark` with sectioned terminal tables for easier scanning and analysis.

package/README.md

@@ -214,6 +214,25 @@ ctx sync --skills --agents codex,claude,agy
 
 After this, `ctx debug -- "task"` and prompt hooks can suggest skills from `~/.config/skillshare/skills/` plus agent-specific skill folders.
 
+## Workflow Discovery
+
+ContextOS can also index Claude/Codex workflow markdown files and suggest the right workflow for the current task:
+
+```bash
+ctx sync --workflows
+```
+
+It scans project workflows first, then global workflows:
+
+```text
+.claude/workflows/
+.codex/workflows/
+~/.claude/workflows/
+~/.codex/workflows/
+```
+
+Workflow files do not need YAML frontmatter. ContextOS reads the top `#` heading, section headings, and referenced agent names such as `planner`, `tester`, `code-reviewer`, and `docs-manager`, then warms semantic embeddings. Prompt hooks inject a `Suggested workflow for this task` section only when a workflow is relevant enough.
+
 ## Modes
 
 Injection mode is the default:
@@ -359,7 +378,8 @@ This warning comes from a transitive dependency in the local embedding/WASM stac
 | `ctx sync --skills --agents <list>` | Syncs skills only for selected agents. | You want to target a subset such as `codex,claude` or `codex,claude,agy`. | Runs `skillshare sync --agents <list>` with `agy` normalized to `antigravity`, then refreshes skill embeddings. |
 | `ctx sync --skills --dry-run` | Previews skillshare sync. | You want to inspect behavior before changing skill directories. | Runs `skillshare sync --dry-run` and skips embedding rebuild. |
 | `ctx sync --skills --no-collect` | Skips collecting existing agent skills into skillshare. | You already manage `~/.config/skillshare/skills` and only want to push it out. | Initializes/syncs skillshare without running `skillshare backup` or `skillshare collect --all`. |
-| `ctx embeddings warm -- "task"` | Prepares local semantic embedding caches. | First install, CI smoke checks, or after changing AGENTS.md/project files/skills. | Loads/downloads `Xenova/all-MiniLM-L6-v2` and writes rule, file-path, and skill vectors to `~/.ctx/contextos/embeddings.db`. |
+| `ctx sync --workflows` | Indexes agent workflow markdown files for prompt-time workflow suggestions. | You use `.claude/workflows/` or `.codex/workflows/` and want ContextOS to suggest the best workflow chain for each task. | Scans project/global workflow folders, parses headings and agent chain mentions, warms workflow embeddings, and makes `ctx debug`/prompt hooks show relevant workflow hints. |
+| `ctx embeddings warm -- "task"` | Prepares local semantic embedding caches. | First install, CI smoke checks, or after changing AGENTS.md/project files/skills/workflows. | Loads/downloads `Xenova/all-MiniLM-L6-v2` and writes rule, file-path, skill, and workflow vectors to `~/.ctx/contextos/embeddings.db`. |
 | `ctx ruler -- <args>` | Forwards args to the installed `ruler` CLI. | You need native Ruler commands such as `init`, `apply`, or `revert`. | Preserves Ruler stdout/stderr and exit status. |
 | `ctx skillshare -- <args>` | Forwards args to the installed `skillshare` CLI. | You need native skillshare commands such as `status`, `target list`, `doctor`, `push`, or `pull`. | Preserves skillshare stdout/stderr and exit status. |
 | `ctx --version` | Prints the installed ContextOS CLI version. | You want to confirm which npm version is being executed. | Prints the version from package metadata. |

package/bin/ctx.js

@@ -28,6 +28,7 @@ import { syncSkills } from "../plugins/ctx/lib/skillshare-sync.js";
 import { scanSkills, warmSkillEmbeddings } from "../plugins/ctx/lib/skill-discoverer.js";
 import { parsePassthroughArgs, runPassthrough } from "../plugins/ctx/lib/passthrough.js";
 import { parseAgentList, parseSetupArgs, setupSummaryLines } from "../plugins/ctx/lib/setup-wizard.js";
+import { syncWorkflows, warmWorkflowEmbeddings } from "../plugins/ctx/lib/workflow-discoverer.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(__dirname, "..");
@@ -61,6 +62,7 @@ Usage:
   ctx sync --rules --dry-run
   ctx sync --rules --no-import-codex-mcp
   ctx sync --skills
+  ctx sync --workflows
   ctx sync --skills --dry-run
   ctx sync --skills --no-collect
   ctx sync --skills --agents codex,claude,antigravity
@@ -186,6 +188,7 @@ async function install({ copy = false, inject = true, agent = "codex" } = {}) {
       console.log(`Embedding vectors cache: ${warmResult.cachePath}`);
       console.log(`File path embeddings warmed: ${warmResult.fileCount || 0}`);
       console.log(`Skill embeddings warmed: ${warmResult.skillCount || 0}`);
+      console.log(`Workflow embeddings warmed: ${warmResult.workflowCount || 0}`);
       console.log(`Prompt context injection: ${inject ? "enabled" : "quiet logging only"}`);
       console.log("Restart Claude Code if it was already running, then submit a task to trigger ContextOS.");
       return;
@@ -209,6 +212,7 @@ async function install({ copy = false, inject = true, agent = "codex" } = {}) {
       console.log(`Embedding vectors cache: ${warmResult.cachePath}`);
       console.log(`File path embeddings warmed: ${warmResult.fileCount || 0}`);
       console.log(`Skill embeddings warmed: ${warmResult.skillCount || 0}`);
+      console.log(`Workflow embeddings warmed: ${warmResult.workflowCount || 0}`);
       console.log(`Prompt context injection: ${inject ? "enabled" : "quiet logging only"}`);
       console.log("Restart Antigravity or agy if it was already running, then submit a task to trigger ContextOS.");
       return;
@@ -247,6 +251,7 @@ async function install({ copy = false, inject = true, agent = "codex" } = {}) {
     console.log(`Embedding vectors cache: ${warmResult.cachePath}`);
     console.log(`File path embeddings warmed: ${warmResult.fileCount || 0}`);
     console.log(`Skill embeddings warmed: ${warmResult.skillCount || 0}`);
+    console.log(`Workflow embeddings warmed: ${warmResult.workflowCount || 0}`);
     console.log(`Prompt context injection: ${inject ? "enabled" : "quiet logging only"}`);
     console.log("Restart Codex if it was already running, then submit a task to trigger ContextOS.");
   } catch (error) {
@@ -282,7 +287,12 @@ async function warmInstallEmbeddings() {
     dataDir,
     allowRemote: !modelReady
   });
-  return { ...result, modelAlreadyCached: modelReady, fileCount: fileResult.count, skillCount: skillResult.count };
+  const workflowResult = await warmWorkflowEmbeddings({
+    cwd: process.cwd(),
+    dataDir,
+    allowRemote: !modelReady
+  });
+  return { ...result, modelAlreadyCached: modelReady, fileCount: fileResult.count, skillCount: skillResult.count, workflowCount: workflowResult.count };
 }
 
 function tryRunCodex(args) {
@@ -340,7 +350,8 @@ async function debug(task) {
   const rules = scored.scoredRules;
   const relevantFiles = scored.suggestedFiles.slice(0, 3);
   const suggestedSkills = (scored.suggestedSkills || []).slice(0, 3);
-  const scheduled = scheduleContext({ rules, relevantFiles, suggestedSkills });
+  const suggestedWorkflows = (scored.suggestedWorkflows || []).slice(0, 2);
+  const scheduled = scheduleContext({ rules, relevantFiles, suggestedSkills, suggestedWorkflows });
 
   console.log("ContextOS debug");
   console.log(`cwd: ${cwd}`);
@@ -372,6 +383,15 @@ async function debug(task) {
   }
   if (!suggestedSkills.length) console.log("(none)");
   console.log("");
+  console.log("Suggested workflows:");
+  for (const workflow of suggestedWorkflows) {
+    const score = Number(workflow.score || 0).toFixed(2);
+    const chain = workflow.chain?.length ? ` chain:${workflow.chain.join(" -> ")}` : "";
+    const location = workflow.relativePath || workflow.path ? ` path:${workflow.relativePath || workflow.path}` : "";
+    console.log(`${score}  ${workflow.title || workflow.name}${chain}${location}`);
+  }
+  if (!suggestedWorkflows.length) console.log("(none)");
+  console.log("");
   console.log("Final additionalContext:");
   console.log(scheduled.additionalContext || "(empty)");
 }
@@ -397,9 +417,15 @@ async function warmEmbeddings(task) {
     dataDir: contextOSDataDir(),
     allowRemote: true
   });
+  const workflowResult = await warmWorkflowEmbeddings({
+    cwd,
+    dataDir: contextOSDataDir(),
+    allowRemote: true
+  });
   console.log(`Warmed ${result.count} embeddings`);
   console.log(`Warmed ${fileResult.count} file path embeddings`);
   console.log(`Warmed ${skillResult.count} skill embeddings`);
+  console.log(`Warmed ${workflowResult.count} workflow embeddings`);
   console.log(`Cache: ${result.cachePath}`);
 }
 
@@ -541,7 +567,13 @@ try {
     if (!task.trim()) throw new Error('Usage: ctx benchmark -- "task"');
     console.log(formatBenchmark(benchmarkWorkspace({ cwd: process.cwd(), task })));
   } else if (command === "sync") {
-    if (args.includes("--skills")) {
+    if (args.includes("--workflows")) {
+      await syncWorkflows({
+        cwd: process.cwd(),
+        dataDir: contextOSDataDir(),
+        allowRemote: !isModelCacheReady(contextOSDataDir())
+      });
+    } else if (args.includes("--skills")) {
       await syncSkills({
         cwd: process.cwd(),
         args: args.slice(1),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhpnq1807/contextos",
-  "version": "0.5.9",
+  "version": "0.5.10",
   "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex, Claude Code, and Antigravity.",
   "type": "module",
   "bin": {

package/plugins/ctx/lib/prompt-hook.js

@@ -35,7 +35,8 @@ export async function handlePromptPayload(
   const scoredRules = scored.scoredRules || [];
   const relevantFiles = (scored.suggestedFiles || []).slice(0, 3);
   const suggestedSkills = (scored.suggestedSkills || []).slice(0, 3);
-  const scheduled = scheduleContext({ rules: scoredRules, relevantFiles, suggestedSkills });
+  const suggestedWorkflows = (scored.suggestedWorkflows || []).slice(0, 2);
+  const scheduled = scheduleContext({ rules: scoredRules, relevantFiles, suggestedSkills, suggestedWorkflows });
 
   const runtime = {
     at: now.toISOString(),
@@ -48,11 +49,13 @@ export async function handlePromptPayload(
     },
     relevantFiles,
     suggestedSkills,
+    suggestedWorkflows,
     telemetry: {
       ...(scored.telemetry || {}),
       rulesInjected: (scheduled.highRules?.length || 0) + (scheduled.midRules?.length || 0),
       filesSuggested: relevantFiles.length,
-      skillsSuggested: suggestedSkills.length
+      skillsSuggested: suggestedSkills.length,
+      workflowsSuggested: suggestedWorkflows.length
     },
     scheduled,
     injected: injectContext,

package/plugins/ctx/lib/scheduler.js

@@ -1,6 +1,6 @@
 const MAX_CONTEXT_CHARS = 4000;
 
-export function scheduleContext({ rules = [], relevantFiles = [], suggestedSkills = [], maxChars = MAX_CONTEXT_CHARS } = {}) {
+export function scheduleContext({ rules = [], relevantFiles = [], suggestedSkills = [], suggestedWorkflows = [], maxChars = MAX_CONTEXT_CHARS } = {}) {
   const high = rules.filter((rule) => rule.score >= 0.5);
   const mid = rules.filter((rule) => rule.score >= 0.1 && rule.score < 0.5);
   const dropped = rules.filter((rule) => rule.score < 0.1);
@@ -15,6 +15,9 @@ export function scheduleContext({ rules = [], relevantFiles = [], suggestedSkill
   if (suggestedSkills.length) {
     sections.push(section("Skills to activate for this task", suggestedSkills.map(formatSkill)));
   }
+  if (suggestedWorkflows.length) {
+    sections.push(section("Suggested workflow for this task", suggestedWorkflows.map(formatWorkflow)));
+  }
   if (mid.length) {
     sections.push(section("Additional relevant rules", mid.slice(0, 8).map(formatRule)));
   }
@@ -29,6 +32,7 @@ export function scheduleContext({ rules = [], relevantFiles = [], suggestedSkill
     droppedRules: dropped,
     relevantFiles,
     suggestedSkills,
+    suggestedWorkflows,
     additionalContext
   };
 }
@@ -49,6 +53,15 @@ function formatSkill(skill) {
   return `- ${skill.name}${description}${location}`;
 }
 
+function formatWorkflow(workflow) {
+  const name = workflow.title || workflow.name;
+  const hint = workflow.hint ? `: ${workflow.hint}` : "";
+  const chain = workflow.chain?.length ? `\n  chain: ${workflow.chain.join(" -> ")}` : "";
+  const location = workflow.relativePath || workflow.path;
+  const source = location ? `\n  see: ${location}` : "";
+  return `- ${name}${hint}${chain}${source}`;
+}
+
 function trimToLimit(value, maxChars) {
   if (value.length <= maxChars) return value;
   return `${value.slice(0, Math.max(0, maxChars - 80)).trimEnd()}\n\n[ContextOS truncated context to ${maxChars} chars]`;

package/plugins/ctx/lib/score-context.js

@@ -4,6 +4,7 @@ import { readAgentsChain } from "./reader.js";
 import { filterActionableRules, parseRules, scoreRules, findRelevantFiles } from "./analyzer.js";
 import { enhanceRuleScoresWithEmbeddings } from "./embedding-scorer.js";
 import { scanSkills, suggestSkills } from "./skill-discoverer.js";
+import { scanWorkflows, suggestWorkflows } from "./workflow-discoverer.js";
 
 export async function scoreContext({
   cwd = process.cwd(),
@@ -12,7 +13,9 @@ export async function scoreContext({
   dataDir,
   maxFiles = 5,
   maxSkills = 3,
+  maxWorkflows = 2,
   skills = null,
+  workflows = null,
   embeddingTimeoutMs = 5000,
   fileEmbeddingTimeoutMs = Number(process.env.CONTEXTOS_FILE_EMBEDDING_TIMEOUT_MS || 80)
 } = {}) {
@@ -46,6 +49,13 @@ export async function scoreContext({
     dataDir,
     limit: maxSkills
   });
+  const workflowCatalog = Array.isArray(workflows) ? workflows : scanWorkflows({ cwd });
+  const suggestedWorkflows = await suggestWorkflows({
+    prompt,
+    workflows: workflowCatalog,
+    dataDir,
+    limit: maxWorkflows
+  });
 
   return {
     cwd,
@@ -53,6 +63,7 @@ export async function scoreContext({
     scoredRules,
     suggestedFiles,
     suggestedSkills,
+    suggestedWorkflows,
     telemetry: {
       elapsedMs: Date.now() - started,
       modelStatus: embedding.status,
@@ -64,6 +75,8 @@ export async function scoreContext({
       filesSuggested: suggestedFiles.length,
       skillsScanned: skillCatalog.length,
       skillsSuggested: suggestedSkills.length,
+      workflowsScanned: workflowCatalog.length,
+      workflowsSuggested: suggestedWorkflows.length,
       sources: merged.sources.map((source) => path.relative(cwd, source))
     }
   };

package/plugins/ctx/lib/skill-discoverer.js

@@ -8,6 +8,9 @@ const DEFAULT_LIMIT = 3;
 const DEFAULT_MAX_SKILLS = 2000;
 const DEFAULT_EMBEDDING_CANDIDATES = 120;
 const DEFAULT_SEMANTIC_CATALOG_LIMIT = 300;
+const SCAN_CACHE_TTL_MS = 5 * 60 * 1000;
+
+const scanCache = new Map();
 
 export function skillSearchRoots({ cwd = process.cwd(), home = os.homedir() } = {}) {
   return [
@@ -60,6 +63,12 @@ function firstParagraph(body) {
 }
 
 export function scanSkills({ cwd = process.cwd(), roots = skillSearchRoots({ cwd }), maxSkills = DEFAULT_MAX_SKILLS } = {}) {
+  const cacheKey = `${path.resolve(cwd)}\0${maxSkills}\0${roots.map((root) => path.resolve(root)).join("\0")}`;
+  const cached = scanCache.get(cacheKey);
+  if (cached && Date.now() - cached.createdAt < SCAN_CACHE_TTL_MS) {
+    return cached.skills;
+  }
+
   const skills = [];
   const seen = new Set();
   for (const root of roots) {
@@ -87,6 +96,7 @@ export function scanSkills({ cwd = process.cwd(), roots = skillSearchRoots({ cwd
       });
     }
   }
+  scanCache.set(cacheKey, { createdAt: Date.now(), skills });
   return skills;
 }
 

package/plugins/ctx/lib/workflow-discoverer.js

@@ -0,0 +1,308 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { enhanceRuleScoresWithEmbeddings, warmRuleEmbeddings } from "./embedding-scorer.js";
+
+const DEFAULT_LIMIT = 2;
+const MIN_WORKFLOW_BYTES = 100;
+const MAX_DESCRIPTION_CHARS = 500;
+const DEFAULT_EMBEDDING_CANDIDATES = 40;
+const KNOWN_AGENT_NAMES = new Set([
+  "planner",
+  "tester",
+  "code-reviewer",
+  "docs-manager",
+  "debugger",
+  "researcher",
+  "project-manager",
+  "mcp-manager",
+  "database-admin",
+  "ui-ux-designer",
+  "copywriter",
+  "scout",
+  "scout-external",
+  "journal-writer",
+  "git-manager",
+  "brainstormer"
+]);
+
+export function workflowSearchRoots({ cwd = process.cwd(), home = os.homedir() } = {}) {
+  return [
+    path.join(cwd, ".claude", "workflows"),
+    path.join(cwd, ".codex", "workflows"),
+    path.join(home, ".claude", "workflows"),
+    path.join(home, ".codex", "workflows")
+  ];
+}
+
+export function scanWorkflows({ cwd = process.cwd(), roots = workflowSearchRoots({ cwd }) } = {}) {
+  const workflows = [];
+  const seen = new Set();
+  for (const root of roots) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(root, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+      const filePath = path.join(root, entry.name);
+      const realPath = safeRealpath(filePath) || filePath;
+      if (seen.has(realPath)) continue;
+      seen.add(realPath);
+      const workflow = parseWorkflowFile(filePath, { cwd, root });
+      if (workflow) workflows.push(workflow);
+    }
+  }
+  return workflows;
+}
+
+export function parseWorkflowFile(filePath, { cwd = process.cwd(), root = path.dirname(filePath) } = {}) {
+  let stat;
+  let content;
+  try {
+    stat = fs.statSync(filePath);
+    if (stat.size < MIN_WORKFLOW_BYTES) return null;
+    content = fs.readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+
+  const body = stripFrontmatter(content);
+  const title = extractTitle(body) || titleFromFile(filePath);
+  const sectionTitles = extractSectionTitles(body);
+  const chain = extractAgentChain(body);
+  const description = buildWorkflowDescription({ title, sectionTitles, chain, body });
+  if (!description) return null;
+
+  return {
+    name: path.basename(filePath, ".md"),
+    title,
+    description,
+    chain,
+    path: filePath,
+    relativePath: path.relative(cwd, filePath),
+    root,
+    scope: isInsidePath(filePath, cwd) ? "project" : "global",
+    mtime: Math.round(stat.mtimeMs)
+  };
+}
+
+export async function suggestWorkflows({
+  prompt = "",
+  workflows = [],
+  dataDir,
+  limit = DEFAULT_LIMIT,
+  timeoutMs = Number(process.env.CONTEXTOS_WORKFLOW_EMBEDDING_TIMEOUT_MS || process.env.CONTEXTOS_EMBEDDING_TIMEOUT_MS || 800)
+} = {}) {
+  if (!String(prompt || "").trim() || !workflows.length) return [];
+  const base = scoreWorkflowsByKeyword({ prompt, workflows });
+  const embeddingCandidates = selectWorkflowEmbeddingCandidates(base);
+  if (!embeddingCandidates.length) return [];
+
+  const embedding = await enhanceRuleScoresWithEmbeddings(embeddingCandidates, prompt, {
+    dataDir,
+    sources: embeddingCandidates.map((workflow) => workflow.path).filter(Boolean),
+    timeoutMs,
+    allowRemote: false
+  });
+
+  return finalizeWorkflowScores(embedding.rules, limit);
+}
+
+function selectWorkflowEmbeddingCandidates(workflows) {
+  return workflows
+    .filter((workflow) => Number(workflow.keywordScore || 0) > 0)
+    .sort((a, b) => Number(b.keywordScore || 0) - Number(a.keywordScore || 0) || a.name.localeCompare(b.name))
+    .slice(0, DEFAULT_EMBEDDING_CANDIDATES);
+}
+
+export async function warmWorkflowEmbeddings({
+  cwd = process.cwd(),
+  dataDir,
+  allowRemote = true,
+  workflows = scanWorkflows({ cwd })
+} = {}) {
+  if (!dataDir || !workflows.length) return { count: 0, cachePath: null };
+  return warmRuleEmbeddings({
+    rules: workflows.map((workflow) => ({ content: workflowEmbeddingText(workflow) })),
+    task: "workflow discovery semantic retrieval feature implementation documentation testing",
+    dataDir,
+    sources: workflows.map((workflow) => workflow.path).filter(Boolean),
+    allowRemote
+  });
+}
+
+export async function syncWorkflows({
+  cwd = process.cwd(),
+  dataDir,
+  allowRemote = true,
+  logger = console.log
+} = {}) {
+  const workflows = scanWorkflows({ cwd });
+  logger("ContextOS workflow index");
+  logger(`Found workflows: ${workflows.length}`);
+  if (workflows.length) {
+    for (const workflow of workflows) {
+      logger(`- ${workflow.relativePath || workflow.path} (${workflow.chain.join(" -> ") || "no chain"})`);
+    }
+  }
+  const result = await warmWorkflowEmbeddings({ cwd, dataDir, allowRemote, workflows });
+  logger(`Indexed workflows: ${workflows.length}`);
+  if (result.cachePath) logger(`Cache: ${result.cachePath}`);
+  return { workflows, embeddings: result };
+}
+
+function stripFrontmatter(content) {
+  return String(content || "").replace(/^---\s*\r?\n[\s\S]*?\r?\n---\s*(?:\r?\n|$)/, "");
+}
+
+function extractTitle(content) {
+  const match = String(content || "").match(/^#\s+(.+?)\s*$/m);
+  return match ? match[1].trim() : "";
+}
+
+function extractSectionTitles(content) {
+  return [...String(content || "").matchAll(/^#{3,4}\s+(.+?)\s*$/gm)]
+    .map((match) => match[1].replace(/^\d+\.\s*/, "").trim())
+    .filter(Boolean);
+}
+
+function extractAgentChain(content) {
+  const names = [];
+  const add = (value) => {
+    const normalized = normalizeAgentName(value);
+    if (!normalized || !KNOWN_AGENT_NAMES.has(normalized) || names.includes(normalized)) return;
+    names.push(normalized);
+  };
+
+  for (const match of String(content || "").matchAll(/`([a-z][a-z0-9-]*(?:-agent)?)`/gi)) {
+    add(match[1]);
+  }
+  for (const name of KNOWN_AGENT_NAMES) {
+    if (new RegExp(`\\b${escapeRegExp(name)}\\b`, "i").test(content)) add(name);
+  }
+  return names;
+}
+
+function buildWorkflowDescription({ title, sectionTitles, chain, body }) {
+  const parts = [
+    title,
+    sectionTitles.join(", "),
+    chain.length ? `delegates to ${chain.join(", ")} agents` : "",
+    firstParagraph(body)
+  ].filter(Boolean);
+  return parts.join(" — ").replace(/\s+/g, " ").trim().slice(0, MAX_DESCRIPTION_CHARS);
+}
+
+function firstParagraph(body) {
+  return String(body || "")
+    .split(/\n\s*\n/)
+    .filter((part) => !/^\s*#/.test(part))
+    .map((part) => part.replace(/^#+\s*/gm, "").replace(/[*_`#>-]/g, "").replace(/\s+/g, " ").trim())
+    .find(Boolean) || "";
+}
+
+function titleFromFile(filePath) {
+  return path.basename(filePath, ".md").split(/[-_]+/).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+
+function scoreWorkflowsByKeyword({ prompt, workflows }) {
+  const normalizedPrompt = normalize(prompt);
+  const promptTokens = new Set(normalizedPrompt.split(/\s+/).filter(Boolean));
+  return workflows.map((workflow, index) => {
+    const content = workflowEmbeddingText(workflow);
+    const workflowTokens = new Set(normalize(content).split(/\s+/).filter(Boolean));
+    const matches = [...workflowTokens].filter((token) => promptTokens.has(token) && token.length > 2);
+    const nameHit = normalizedPrompt.includes(normalize(workflow.name)) || normalizedPrompt.includes(normalize(workflow.title));
+    const chainHit = workflow.chain.some((agent) => normalizedPrompt.includes(normalize(agent)));
+    const actionBonus = actionIntentBonus(normalizedPrompt, workflow);
+    const scopeBonus = workflow.scope === "project" ? 0.08 : 0;
+    const score = Math.min(1, (matches.length ? 0.22 + matches.length * 0.08 : 0) + (nameHit ? 0.22 : 0) + (chainHit ? 0.16 : 0) + actionBonus + scopeBonus);
+    return {
+      id: `workflow-${index + 1}`,
+      ...workflow,
+      content,
+      score,
+      keywordScore: score,
+      reasons: [
+        ...(matches.length ? [`keyword:${matches.slice(0, 5).join(",")}`] : []),
+        ...(nameHit ? ["name-match"] : []),
+        ...(chainHit ? ["chain-match"] : []),
+        ...(actionBonus ? ["workflow-intent"] : [])
+      ],
+      originalOrder: index
+    };
+  });
+}
+
+function actionIntentBonus(normalizedPrompt, workflow) {
+  const name = normalize(`${workflow.name} ${workflow.title} ${workflow.description}`);
+  const implementationIntent = /\b(implement|feature|build|create|fix|debug|test|ci|failing)\b/.test(normalizedPrompt);
+  const docsIntent = /\b(doc|docs|documentation|readme|changelog|roadmap)\b/.test(normalizedPrompt);
+  const orchestrationIntent = /\b(parallel|sequential|chain|delegate|agent|subagent|orchestrat)\b/.test(normalizedPrompt);
+  if (implementationIntent && /\b(primary|implementation|testing|debugging|quality)\b/.test(name)) return 0.35;
+  if (docsIntent && /\b(documentation|docs|changelog|roadmap)\b/.test(name)) return 0.35;
+  if (orchestrationIntent && /\b(orchestration|parallel|sequential|chaining)\b/.test(name)) return 0.35;
+  return 0;
+}
+
+function finalizeWorkflowScores(workflows, limit) {
+  return workflows
+    .map((workflow) => ({
+      name: workflow.name,
+      title: workflow.title,
+      description: workflow.description,
+      chain: workflow.chain || [],
+      path: workflow.path,
+      relativePath: workflow.relativePath,
+      scope: workflow.scope,
+      keywordScore: workflow.keywordScore,
+      score: Math.min(1, Number(workflow.score || 0)),
+      embeddingScore: workflow.embeddingScore,
+      reasons: workflow.reasons || [],
+      hint: workflowHint(workflow)
+    }))
+    .filter((workflow) => Number(workflow.score || 0) >= 0.4 || Number(workflow.embeddingScore || 0) >= 0.62)
+    .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+    .slice(0, limit);
+}
+
+function workflowHint(workflow) {
+  const text = normalize(`${workflow.name} ${workflow.title} ${workflow.description}`);
+  if (text.includes("documentation")) return "use when documentation, changelog, or roadmap updates are needed";
+  if (text.includes("orchestration")) return "use when chaining or parallelizing agents";
+  if (text.includes("development rules")) return "use for coding conventions and pre-commit discipline";
+  return "use for feature implementation, testing, review, and debugging";
+}
+
+function workflowEmbeddingText(workflow) {
+  return `${workflow.title || workflow.name} ${workflow.description || ""} ${(workflow.chain || []).join(" ")}`;
+}
+
+function normalize(value) {
+  return String(value || "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+
+function normalizeAgentName(value) {
+  return String(value || "").toLowerCase().replace(/-agent$/, "");
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function safeRealpath(filePath) {
+  try {
+    return fs.realpathSync(filePath);
+  } catch {
+    return null;
+  }
+}
+
+function isInsidePath(filePath, parentPath) {
+  const relative = path.relative(path.resolve(parentPath), path.resolve(filePath));
+  return relative && !relative.startsWith("..") && !path.isAbsolute(relative);
+}

package/plugins/ctx/mcp/contextos-server.js

@@ -18,16 +18,25 @@ export function createContextOSMcpServer({ dataDir }) {
       openFiles: z.array(z.string()).optional(),
       maxFiles: z.number().int().positive().max(20).optional(),
       maxSkills: z.number().int().positive().max(10).optional(),
+      maxWorkflows: z.number().int().positive().max(10).optional(),
       skills: z.array(z.object({
         name: z.string(),
         description: z.string(),
         path: z.string().optional()
+      })).optional(),
+      workflows: z.array(z.object({
+        name: z.string(),
+        title: z.string().optional(),
+        description: z.string(),
+        chain: z.array(z.string()).optional(),
+        path: z.string().optional()
       })).optional()
     },
     outputSchema: {
       scoredRules: z.array(z.any()),
       suggestedFiles: z.array(z.any()),
       suggestedSkills: z.array(z.any()),
+      suggestedWorkflows: z.array(z.any()),
       telemetry: z.record(z.string(), z.any())
     }
   }, async (args) => {
@@ -38,7 +47,9 @@ export function createContextOSMcpServer({ dataDir }) {
       dataDir,
       maxFiles: args.maxFiles || 5,
       maxSkills: args.maxSkills || 3,
-      skills: args.skills
+      maxWorkflows: args.maxWorkflows || 2,
+      skills: args.skills,
+      workflows: args.workflows
     });
     return {
       content: [
@@ -51,6 +62,7 @@ export function createContextOSMcpServer({ dataDir }) {
         scoredRules: result.scoredRules,
         suggestedFiles: result.suggestedFiles,
         suggestedSkills: result.suggestedSkills,
+        suggestedWorkflows: result.suggestedWorkflows,
         telemetry: result.telemetry
       }
     };

package/plugins/ctx/mcp/server.js

@@ -70,7 +70,9 @@ async function handleBridgeRequest(socket, raw) {
       dataDir,
       maxFiles: payload.maxFiles || 5,
       maxSkills: payload.maxSkills || 3,
-      skills: payload.skills
+      maxWorkflows: payload.maxWorkflows || 2,
+      skills: payload.skills,
+      workflows: payload.workflows
     });
     socket.end(JSON.stringify(result));
   } catch (error) {
@@ -79,6 +81,7 @@ async function handleBridgeRequest(socket, raw) {
       scoredRules: [],
       suggestedFiles: [],
       suggestedSkills: [],
+      suggestedWorkflows: [],
       telemetry: { elapsedMs: 0, modelStatus: "error" }
     }));
   }