@voybio/ace-swarm 0.1.0

package/dist/problem-triage.js

@@ -0,0 +1,448 @@
+import { safeWrite } from "./helpers.js";
+import { slugify } from "./shared.js";
+import { listSkillCatalogEntries, summarizeSkillCatalog, } from "./skill-catalog.js";
+const STOPWORDS = new Set([
+    "the",
+    "and",
+    "for",
+    "that",
+    "this",
+    "with",
+    "from",
+    "into",
+    "your",
+    "when",
+    "what",
+    "where",
+    "which",
+    "about",
+    "need",
+    "needs",
+    "should",
+    "would",
+    "could",
+    "have",
+    "has",
+    "been",
+    "being",
+    "just",
+    "task",
+    "asks",
+    "user",
+    "skill",
+    "skills",
+    "agent",
+    "agents",
+    "workflow",
+    "workflows",
+]);
+const CHANGE_HINTS = [
+    "improve",
+    "patch",
+    "fix",
+    "rewrite",
+    "split",
+    "add",
+    "update",
+    "extend",
+    "harden",
+    "implement",
+    "metadata",
+    "frontmatter",
+    "portable",
+    "portability",
+    "adapter",
+    "adapters",
+    "overlay",
+    "overlays",
+    "claude",
+    "cursor",
+    "codex",
+    "antigravity",
+    "turnkey",
+    "openai.yaml",
+    "openai yaml",
+    "canary",
+    "validation",
+    "references",
+];
+const REUSABLE_HINTS = [
+    "reusable",
+    "repeat",
+    "repeated",
+    "every time",
+    "keep seeing",
+    "standardize",
+    "new skill",
+    "should become a skill",
+    "candidate skill",
+    "front door",
+];
+const ONE_OFF_HINTS = [
+    "one-off",
+    "one off",
+    "just this once",
+    "single file",
+    "rename one",
+    "small tweak",
+    "ad hoc",
+];
+const BLOCKED_TOOL_HINTS = [
+    "missing tool",
+    "missing permission",
+    "permission",
+    "approval",
+    "api key",
+    "access token",
+    "credential",
+    "credentials",
+    "network access",
+    "mcp server",
+    "connector",
+    "not installed",
+    "blocked",
+];
+const MANUAL_SKILL_HINTS = {
+    "ace-orchestrator": [
+        "initiate ace",
+        "orchestrator",
+        "engineering snapshot",
+        "bootstrap engineering",
+        "swarm handoff",
+    ],
+    "astgrep-index": ["ast-grep index", "structural index", "discovery index", "astgrep"],
+    codemunch: ["codebase map", "understand codebase", "ast driven", "code comprehension"],
+    codesnipe: ["compare codebases", "dual codebase", "inspiration", "compare repo"],
+    "problem-triage": [
+        "problem triage",
+        "existing skill fits",
+        "needs patching",
+        "new skill warranted",
+        "one off task",
+        "missing tool or permission",
+    ],
+    "skill-auditor": [
+        "skill auditor",
+        "audit skills",
+        "skill quality",
+        "readiness rubric",
+        "portable skill contract",
+    ],
+    "schema-forge": ["schema", "contract", "compatibility", "migration"],
+    "risk-quant": ["risk", "probability impact", "mitigation"],
+    "state-auditor": ["state drift", "state audit", "status truth"],
+};
+function includesAny(text, patterns) {
+    return patterns.some((pattern) => text.includes(pattern));
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function normalizeText(value) {
+    return value.toLowerCase().replace(/\s+/g, " ").trim();
+}
+function extractTerms(value) {
+    return [...new Set(normalizeText(value)
+            .split(/[^a-z0-9-]+/g)
+            .map((term) => term.trim())
+            .filter((term) => term.length >= 3 && !STOPWORDS.has(term)))];
+}
+function candidateTerms(entry) {
+    const descriptionTerms = extractTerms(entry.description);
+    const headingTerms = entry.normalized_headings.flatMap((heading) => extractTerms(heading));
+    const nameTerms = entry.name.split("-").filter((term) => term.length >= 3);
+    return [...new Set([...nameTerms, ...descriptionTerms, ...headingTerms])];
+}
+function scoreSkillMatch(entry, request) {
+    const text = normalizeText(request);
+    const reasons = [];
+    let score = 0;
+    if (text.includes(entry.name.toLowerCase())) {
+        score += 14;
+        reasons.push(`Exact skill name match: ${entry.name}`);
+    }
+    for (const hint of MANUAL_SKILL_HINTS[entry.name] ?? []) {
+        if (text.includes(hint)) {
+            score += 5;
+            reasons.push(`Matched skill hint: "${hint}"`);
+        }
+    }
+    for (const term of candidateTerms(entry)) {
+        if (text.includes(term)) {
+            score += term.length >= 8 ? 3 : 2;
+            reasons.push(`Matched keyword: ${term}`);
+        }
+    }
+    return {
+        name: entry.name,
+        source: entry.source,
+        score,
+        reasons: [...new Set(reasons)].slice(0, 6),
+    };
+}
+function detectMissingRequirements(text) {
+    const requirements = [];
+    if (includesAny(text, ["permission", "approval", "blocked", "network access"]) &&
+        includesAny(text, BLOCKED_TOOL_HINTS)) {
+        requirements.push("permission_or_network_access");
+    }
+    if (includesAny(text, ["mcp server", "connector", "not installed", "missing tool"])) {
+        requirements.push("tooling_or_connector_install");
+    }
+    if (includesAny(text, ["api key", "access token", "credential", "credentials"])) {
+        requirements.push("runtime_credentials");
+    }
+    return [...new Set(requirements)];
+}
+function proposeSkillName(request) {
+    const terms = extractTerms(request).filter((term) => !["existing", "needs", "patching", "warranted", "missing", "permission"].includes(term));
+    if (terms.length < 2)
+        return undefined;
+    return slugify(terms.slice(0, 3).join("-"));
+}
+function buildNextSteps(route, topMatch, proposedSkillName) {
+    switch (route) {
+        case "existing_skill_fit":
+            return [
+                `Load \`${topMatch?.name ?? "the matched skill"}\` with \`ace-skill\` or \`get_skill_instructions\`.`,
+                "Execute the existing workflow before creating or patching a new skill.",
+            ];
+        case "existing_skill_needs_patch":
+            return [
+                `Patch \`${topMatch?.name ?? "the matched skill"}\` metadata/workflow instead of creating a duplicate.`,
+                "Add missing trigger phrases, portable SKILL.md semantics, explicit sections, and validation/canary coverage in the next remediation slice.",
+            ];
+        case "new_skill_warranted":
+            return [
+                `Draft a new skill spec${proposedSkillName ? ` with working name \`${proposedSkillName}\`` : ""}.`,
+                "Seed it with 2-3 concrete examples, portable semantics, and a validation path before promotion.",
+            ];
+        case "missing_tool_or_permission":
+            return [
+                "Resolve the missing permission/tooling/credential dependency before turning this into a reusable skill.",
+                "If the workflow still matters after the blocker clears, rerun problem triage with the dependency status included.",
+            ];
+        case "one_off_task":
+        default:
+            return [
+                "Handle this directly in the current task flow.",
+                "Promote it to a skill only if the same workflow repeats with stable inputs/outputs.",
+            ];
+    }
+}
+function computeConfidence(route, topMatch, secondMatch, missingRequirements) {
+    if (missingRequirements.length > 0) {
+        return 0.92;
+    }
+    if (!topMatch || topMatch.score === 0) {
+        return route === "one_off_task" ? 0.66 : 0.72;
+    }
+    let confidence = 0.58 + Math.min(topMatch.score / 30, 0.28);
+    if (topMatch.reasons.some((reason) => reason.startsWith("Exact skill name match"))) {
+        confidence += 0.12;
+    }
+    if (secondMatch && topMatch.score - secondMatch.score <= 3) {
+        confidence -= 0.1;
+    }
+    if (route === "existing_skill_needs_patch") {
+        confidence += 0.05;
+    }
+    return clamp(confidence, 0.45, 0.96);
+}
+export function triageProblemRequest(request, entries = listSkillCatalogEntries()) {
+    const text = normalizeText(request);
+    const missingRequirements = detectMissingRequirements(text);
+    const skillMatches = entries
+        .map((entry) => scoreSkillMatch(entry, request))
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 5);
+    const topMatch = skillMatches[0];
+    const secondMatch = skillMatches[1];
+    const catalogSummary = summarizeSkillCatalog(entries);
+    const mentionsPatch = includesAny(text, CHANGE_HINTS);
+    const mentionsReusableNeed = includesAny(text, REUSABLE_HINTS);
+    const looksOneOff = includesAny(text, ONE_OFF_HINTS);
+    const mentionsSkillSystem = includesAny(text, [
+        "skill",
+        "skills",
+        "frontmatter",
+        "portable",
+        "portability",
+        "adapter",
+        "adapters",
+        "overlay",
+        "overlays",
+        "claude",
+        "cursor",
+        "codex",
+        "antigravity",
+        "openai.yaml",
+        "openai yaml",
+        "trigger",
+        "canary",
+        "metadata",
+    ]);
+    let route;
+    const rationale = [];
+    if (missingRequirements.length > 0) {
+        route = "missing_tool_or_permission";
+        rationale.push(`Request is blocked by missing prerequisites: ${missingRequirements.join(", ")}.`);
+    }
+    else if (topMatch && topMatch.score >= 12 && mentionsPatch) {
+        route = "existing_skill_needs_patch";
+        rationale.push(`Strong overlap with existing skill \`${topMatch.name}\` suggests patching instead of creating a duplicate.`);
+    }
+    else if (topMatch && topMatch.score >= 12 && !mentionsReusableNeed) {
+        route = "existing_skill_fit";
+        rationale.push(`Existing skill \`${topMatch.name}\` already covers the request shape.`);
+    }
+    else if (mentionsReusableNeed ||
+        (mentionsSkillSystem && (!topMatch || topMatch.score < 12))) {
+        route = "new_skill_warranted";
+        rationale.push("Request describes a reusable decision/workflow surface that is not strongly covered by the current catalog.");
+    }
+    else if (looksOneOff || !mentionsSkillSystem) {
+        route = "one_off_task";
+        rationale.push("Request looks task-specific rather than reusable across repeated sessions.");
+    }
+    else {
+        route = topMatch ? "existing_skill_fit" : "one_off_task";
+        rationale.push("Falling back to the highest-signal route from the current catalog.");
+    }
+    if (topMatch) {
+        rationale.push(`Top skill match: \`${topMatch.name}\` (score=${topMatch.score}, source=${topMatch.source}).`);
+    }
+    if (route === "existing_skill_needs_patch" && topMatch) {
+        const entry = entries.find((candidate) => candidate.name === topMatch.name);
+        if (entry) {
+            const gaps = [
+                !entry.has_inputs_section ? "missing Inputs section" : "",
+                !entry.has_workflow_section ? "missing Workflow/Steps section" : "",
+                !entry.has_outputs_section ? "missing Outputs/Artifacts section" : "",
+                !entry.has_failure_policy ? "missing Failure/Troubleshooting section" : "",
+                !entry.has_use_cases_section ? "missing Canonical Use Cases section" : "",
+                !entry.has_validation_surface ? "missing Validation/Canary surface" : "",
+                entry.line_count > 500 && !entry.has_references_dir
+                    ? "needs references/ split for progressive disclosure"
+                    : "",
+                includesAny(text, [
+                    "portable",
+                    "portability",
+                    "adapter",
+                    "adapters",
+                    "overlay",
+                    "overlays",
+                    "claude",
+                    "cursor",
+                    "codex",
+                    "antigravity",
+                    "openai.yaml",
+                    "openai yaml",
+                ]) && !entry.has_portability_notes
+                    ? "missing vendor-neutral portability guidance"
+                    : "",
+                entry.has_optional_adapters && !entry.has_portability_notes
+                    ? "adapter overlays exist without portable parity guidance"
+                    : "",
+            ].filter(Boolean);
+            if (gaps.length > 0) {
+                rationale.push(`Patch focus areas: ${gaps.join(", ")}.`);
+            }
+            else {
+                const requestedFocusAreas = [
+                    includesAny(text, ["trigger", "metadata", "frontmatter"])
+                        ? "trigger metadata/frontmatter"
+                        : "",
+                    includesAny(text, ["portable", "portability"])
+                        ? "portable SKILL.md guidance"
+                        : "",
+                    includesAny(text, ["references", "split"])
+                        ? "references/ cleanup"
+                        : "",
+                    includesAny(text, ["validation", "canary"])
+                        ? "validation/canary coverage"
+                        : "",
+                ].filter(Boolean);
+                if (requestedFocusAreas.length > 0) {
+                    rationale.push(`Patch focus areas: ${requestedFocusAreas.join(", ")}.`);
+                }
+            }
+        }
+    }
+    if (includesAny(text, ["openai.yaml", "openai yaml", "claude", "cursor", "codex", "antigravity"])) {
+        rationale.push("Client-specific adapter files are optional overlays; core skill meaning must remain complete in portable SKILL.md content.");
+    }
+    if (catalogSummary.portable_contract_ready_skills < catalogSummary.total_skills) {
+        rationale.push(`Portable-skill readiness remains incomplete: ${catalogSummary.portable_contract_ready_skills}/${catalogSummary.total_skills} skills currently meet the core portable contract.`);
+    }
+    const proposedSkillName = route === "new_skill_warranted" ? proposeSkillName(request) : undefined;
+    const confidence = computeConfidence(route, topMatch, secondMatch, missingRequirements);
+    return {
+        request,
+        route,
+        confidence,
+        rationale,
+        skill_matches: skillMatches,
+        missing_requirements: missingRequirements,
+        suggested_next_steps: buildNextSteps(route, topMatch, proposedSkillName),
+        proposed_skill_name: proposedSkillName,
+        catalog_summary: catalogSummary,
+    };
+}
+export function renderProblemTriageReport(result) {
+    const lines = [
+        "# PROBLEM_TRIAGE",
+        "",
+        `Generated: ${new Date().toISOString()}`,
+        `Route: \`${result.route}\``,
+        `Confidence: \`${result.confidence.toFixed(2)}\``,
+        "",
+        "## Request",
+        result.request,
+        "",
+        "## Rationale",
+        ...result.rationale.map((entry) => `- ${entry}`),
+        "",
+        "## Top Skill Matches",
+        ...(result.skill_matches.length > 0
+            ? result.skill_matches.map((entry) => `- \`${entry.name}\` (${entry.source}, score=${entry.score}) — ${entry.reasons.join("; ")}`)
+            : ["- none"]),
+        "",
+        "## Catalog Signals",
+        `- total skills: \`${result.catalog_summary.total_skills}\``,
+        `- portable-contract-ready skills: \`${result.catalog_summary.portable_contract_ready_skills}\``,
+        `- skills with frontmatter: \`${result.catalog_summary.with_frontmatter}\``,
+        `- trigger-aware descriptions: \`${result.catalog_summary.trigger_aware_descriptions}\``,
+        `- skills with validation surface: \`${result.catalog_summary.with_validation_surface}\``,
+        `- skills with portability notes: \`${result.catalog_summary.with_portability_notes}\``,
+        `- skills with optional adapters: \`${result.catalog_summary.with_adapter_overlays}\``,
+        `- adapter clients observed: \`${result.catalog_summary.adapter_clients.length > 0
+            ? result.catalog_summary.adapter_clients.join(", ")
+            : "none"}\``,
+        `- legacy openai overlays observed: \`${result.catalog_summary.with_openai_yaml}\``,
+        `- long skills (>500 lines): ${result.catalog_summary.long_skills.length > 0
+            ? result.catalog_summary.long_skills
+                .map((entry) => `\`${entry.name}\` (${entry.line_count})`)
+                .join(", ")
+            : "`none`"}`,
+        "",
+    ];
+    if (result.missing_requirements.length > 0) {
+        lines.push("## Missing Requirements");
+        lines.push(...result.missing_requirements.map((entry) => `- ${entry}`));
+        lines.push("");
+    }
+    if (result.proposed_skill_name) {
+        lines.push("## Proposed Skill Name");
+        lines.push(`- \`${result.proposed_skill_name}\``);
+        lines.push("");
+    }
+    lines.push("## Next Steps");
+    lines.push(...result.suggested_next_steps.map((entry, index) => `${index + 1}. ${entry}`));
+    return lines.join("\n");
+}
+export function writeProblemTriageReport(result, targetPath = "agent-state/PROBLEM_TRIAGE.md") {
+    return safeWrite(targetPath, renderProblemTriageReport(result));
+}
+//# sourceMappingURL=problem-triage.js.map

package/dist/prompts.d.ts

@@ -0,0 +1,7 @@
+/**
+ * MCP Prompts – pre-built prompt templates for each ACE role,
+ * multi-agent workflows, and skill activation.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPrompts(server: McpServer): void;
+//# sourceMappingURL=prompts.d.ts.map