@jterrats/open-orchestra 0.1.0 → 0.3.0

package/dist/skills.js

@@ -0,0 +1,665 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { FILES } from "./constants.js";
+import { exists, readJson, resolveWorkflowPath, writeJson, } from "./fs-utils.js";
+import { appendEvent, loadWorkspace, writeArtifact } from "./workspace.js";
+const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const defaultSkills = [
+    {
+        id: "prompt-registry",
+        name: "Prompt Registry",
+        summary: "Read and update .generated-prompts registers for substantial AI-generated artifacts.",
+        triggers: [
+            "prompt",
+            "generated",
+            "artifact",
+            "code",
+            "ui",
+            "docs",
+            "diagram",
+            "eval",
+        ],
+        roles: [
+            "parent",
+            "developer",
+            "tech_lead",
+            "frontend_specialist",
+            "backend_specialist",
+            "mobile_specialist",
+            "sdet",
+            "qa",
+            "technical_writer",
+            "ai_evaluation_engineer",
+        ],
+        capabilities: [
+            "prompt-memory",
+            "artifact-traceability",
+            "context-continuity",
+        ],
+        riskAreas: ["maintainability", "governance"],
+        sourceGroups: ["agent-memory", "codebase"],
+        entry: "skills/prompt-registry/SKILL.md",
+        assets: [],
+        evidence: ["file"],
+        loadBudget: "small",
+        instructions: [
+            "Before substantial generation, read the relevant .generated-prompts register.",
+            "After substantial changes, update one entry with task, role, decisions, evidence, and prompt summary.",
+            "Do not update the register for typo-only, formatting-only, or single-line mechanical fixes.",
+        ],
+    },
+    {
+        id: "diagram-export",
+        name: "Diagram Export",
+        summary: "Create, validate, and export architecture, workflow, and sequence diagrams.",
+        triggers: [
+            "diagram",
+            "mermaid",
+            "architecture",
+            "flow",
+            "sequence",
+            "draw.io",
+            "lucid",
+        ],
+        roles: [
+            "architect",
+            "business_analyst",
+            "product_manager",
+            "tech_lead",
+            "technical_writer",
+        ],
+        capabilities: ["diagramming", "architecture-communication"],
+        riskAreas: ["architecture", "documentation"],
+        sourceGroups: ["architecture", "product-backlog", "agent-memory"],
+        entry: "skills/diagram-export/SKILL.md",
+        assets: [],
+        evidence: ["file", "report"],
+        loadBudget: "normal",
+        instructions: [
+            "Identify the diagram purpose and authoritative architecture sources before drawing.",
+            "Choose the diagram style from the decision matrix before drafting.",
+            "Prefer text-native diagrams such as Mermaid unless the project requires another format.",
+            "Run orchestra diagrams lint --file <diagram.mmd> before sharing Mermaid diagrams.",
+            "Attach lint evidence to the workflow when the diagram supports delivery.",
+        ],
+    },
+    {
+        id: "static-analysis",
+        name: "Static Analysis",
+        summary: "Run and interpret local quality, type, dependency, secret, and security checks.",
+        triggers: [
+            "lint",
+            "typecheck",
+            "secret",
+            "sast",
+            "precommit",
+            "dependency",
+            "scan",
+            "eslint",
+            "test",
+        ],
+        roles: [
+            "developer",
+            "tech_lead",
+            "qa",
+            "sdet",
+            "security",
+            "devops",
+            "platform_engineer",
+        ],
+        capabilities: ["quality-gate", "security-review", "commit-readiness"],
+        riskAreas: ["security", "release", "maintainability"],
+        sourceGroups: ["codebase", "quality-security", "agent-memory"],
+        entry: "skills/static-analysis/SKILL.md",
+        assets: ["skills/static-analysis/checklist.md"],
+        evidence: ["command", "report"],
+        loadBudget: "normal",
+        instructions: [
+            "Inspect configured local checks before inventing commands.",
+            "Run the smallest relevant check first, then the full gate before handoff or commit.",
+            "Record command evidence and treat failed required checks as blockers unless explicitly deferred.",
+        ],
+    },
+    {
+        id: "pr-review",
+        name: "PR Review",
+        summary: "Produce review findings, PR summaries, risks, rollout notes, and missing-test gaps.",
+        triggers: [
+            "pr",
+            "pull request",
+            "review",
+            "diff",
+            "merge",
+            "release summary",
+        ],
+        roles: [
+            "reviewer_critic",
+            "tech_lead",
+            "qa",
+            "security",
+            "release_manager",
+            "architect",
+        ],
+        capabilities: ["review", "risk-summary", "change-summary"],
+        riskAreas: ["release", "security", "maintainability"],
+        sourceGroups: [
+            "codebase",
+            "quality-security",
+            "product-backlog",
+            "agent-memory",
+        ],
+        entry: "skills/pr-review/SKILL.md",
+        assets: [],
+        evidence: ["file", "report"],
+        loadBudget: "normal",
+        instructions: [
+            "Review behavior, tests, risks, rollout, rollback, and missing evidence before summaries.",
+            "Lead with findings and blockers, then summarize changes.",
+            "Reference local files, task context, reviews, and evidence rather than generated claims.",
+        ],
+    },
+    {
+        id: "playwright-evidence",
+        name: "Playwright Evidence",
+        summary: "Plan browser automation and attach screenshots, traces, videos, and reports.",
+        triggers: [
+            "playwright",
+            "browser",
+            "e2e",
+            "screenshot",
+            "trace",
+            "video",
+            "responsive",
+            "web",
+            "ui",
+        ],
+        roles: [
+            "qa",
+            "sdet",
+            "frontend_specialist",
+            "ux_ui_designer",
+            "ux_researcher_accessibility",
+        ],
+        capabilities: ["e2e-testing", "browser-evidence", "accessibility-check"],
+        riskAreas: ["ux", "release"],
+        sourceGroups: [
+            "quality-security",
+            "codebase",
+            "product-backlog",
+            "agent-memory",
+        ],
+        entry: "skills/playwright-evidence/SKILL.md",
+        assets: [],
+        evidence: ["screenshot", "trace", "video", "report"],
+        loadBudget: "normal",
+        instructions: [
+            "Plan user-value scenarios from acceptance criteria before writing tests.",
+            "Use resilient locators and page objects for repeated flows.",
+            "Attach screenshots, traces, videos, or reports as evidence for release decisions.",
+        ],
+    },
+    {
+        id: "backlog-sync",
+        name: "Backlog Sync",
+        summary: "Keep GitHub issues, local stories, and workflow tasks aligned.",
+        triggers: [
+            "backlog",
+            "issue",
+            "story",
+            "epic",
+            "github",
+            "acceptance criteria",
+            "refine",
+        ],
+        roles: [
+            "product_manager",
+            "product_owner",
+            "business_analyst",
+            "planner",
+            "parent",
+        ],
+        capabilities: ["backlog-management", "story-refinement", "scope-control"],
+        riskAreas: ["governance", "scope"],
+        sourceGroups: ["product-backlog", "project-instructions", "agent-memory"],
+        entry: "skills/backlog-sync/SKILL.md",
+        assets: [],
+        evidence: ["file", "report"],
+        loadBudget: "small",
+        instructions: [
+            "Confirm backlog IDs and acceptance criteria before implementation.",
+            "Keep local tasks, docs, and GitHub issues aligned when one changes.",
+            "Surface missing refinement as a blocker instead of guessing scope.",
+        ],
+    },
+    {
+        id: "release-readiness",
+        name: "Release Readiness",
+        summary: "Validate gates, rollback, observability, support, and customer-impact evidence.",
+        triggers: [
+            "release",
+            "deploy",
+            "rollback",
+            "go-live",
+            "readiness",
+            "downtime",
+            "observability",
+        ],
+        roles: [
+            "release_manager",
+            "devops",
+            "sre",
+            "platform_engineer",
+            "support_customer_ops",
+            "security",
+        ],
+        capabilities: ["release-gate", "rollback-review", "operational-readiness"],
+        riskAreas: ["release", "sre", "devops", "security"],
+        sourceGroups: ["devops-runtime", "quality-security", "agent-memory"],
+        entry: "skills/release-readiness/SKILL.md",
+        assets: [],
+        evidence: ["command", "report", "file"],
+        loadBudget: "normal",
+        instructions: [
+            "Validate gates, evidence, locks, reviews, rollback, observability, and support readiness.",
+            "Treat missing rollback or unresolved critical QA/security/SRE findings as blockers.",
+            "Record release evidence and accepted residual risks explicitly.",
+        ],
+    },
+    {
+        id: "model-evaluation",
+        name: "Model Evaluation",
+        summary: "Run prompt, model, provider-routing, fallback, and rubric evaluations.",
+        triggers: [
+            "model",
+            "llm",
+            "prompt",
+            "provider",
+            "fallback",
+            "eval",
+            "rubric",
+            "routing",
+        ],
+        roles: ["ai_evaluation_engineer", "toolsmith", "architect", "parent"],
+        capabilities: ["llm-evaluation", "provider-routing", "prompt-quality"],
+        riskAreas: ["governance", "quality"],
+        sourceGroups: ["vendor-docs", "agent-memory", "quality-security"],
+        entry: "skills/model-evaluation/SKILL.md",
+        assets: [],
+        evidence: ["report", "file"],
+        loadBudget: "normal",
+        instructions: [
+            "Define eval objectives, cases, rubric, and expected behavior before changing prompts or routing.",
+            "Compare model/provider behavior for material changes and record disagreements.",
+            "Avoid storing raw sensitive prompts or responses in provenance artifacts.",
+        ],
+    },
+    {
+        id: "source-of-truth",
+        name: "Source of Truth",
+        summary: "Select authoritative project, vendor, and workflow sources before acting.",
+        triggers: [
+            "source",
+            "documentation",
+            "docs",
+            "official",
+            "verify",
+            "truth",
+            "context",
+        ],
+        roles: [
+            "parent",
+            "planner",
+            "context_curator",
+            "architect",
+            "developer",
+            "qa",
+            "security",
+            "devops",
+        ],
+        capabilities: ["context-selection", "provenance", "source-resolution"],
+        riskAreas: ["governance", "accuracy"],
+        sourceGroups: [
+            "project-instructions",
+            "product-backlog",
+            "architecture",
+            "codebase",
+            "vendor-docs",
+            "agent-memory",
+        ],
+        entry: "skills/source-of-truth/SKILL.md",
+        assets: [],
+        evidence: ["file", "report"],
+        loadBudget: "small",
+        instructions: [
+            "Select source groups before acting and load only sources relevant to the task.",
+            "Prefer local project sources first and official vendor docs for current APIs or tools.",
+            "If sources conflict, record the conflict as a blocker or decision.",
+        ],
+    },
+    {
+        id: "agent-learning",
+        name: "Agent Learning",
+        summary: "Record reusable failure lessons and promote repeated lessons into skills or rules.",
+        triggers: [
+            "failure",
+            "failed",
+            "error",
+            "syntax",
+            "escaping",
+            "permission",
+            "lesson",
+            "learn",
+        ],
+        roles: ["parent", "context_curator", "toolsmith", "developer", "qa"],
+        capabilities: ["failure-learning", "memory-hygiene", "repeat-prevention"],
+        riskAreas: ["maintainability", "governance"],
+        sourceGroups: ["agent-memory", "codebase"],
+        entry: "skills/agent-learning/SKILL.md",
+        assets: [],
+        evidence: ["file"],
+        loadBudget: "small",
+        instructions: [
+            "Search relevant lessons before repeating risky operations.",
+            "After reusable failures, record operation, error signature, root cause, fix, prevention, and verification.",
+            "Promote repeated lessons into versioned skills or rules after review.",
+        ],
+    },
+];
+export function listSkills() {
+    return defaultSkills.map((skill) => ({
+        ...skill,
+        instructions: [...skill.instructions],
+    }));
+}
+export async function planSkillsForTask(taskId, root = process.cwd()) {
+    const workspace = await loadWorkspace(root);
+    const task = workspace.tasks.find((candidate) => candidate.id === taskId);
+    if (!task) {
+        throw new Error(`unknown task: ${taskId}`);
+    }
+    const role = workspace.roles.find((candidate) => candidate.id === task.ownerRole);
+    const scored = listSkills().map((skill) => scoreSkill(skill, task, role?.capabilities ?? []));
+    const selected = scored
+        .filter((item) => item.score > 0 || item.skill.id === "source-of-truth")
+        .sort((left, right) => right.score - left.score || left.skill.id.localeCompare(right.skill.id));
+    const skipped = scored
+        .filter((item) => !selected.some((selectedItem) => selectedItem.skill.id === item.skill.id))
+        .map(({ skill }) => ({
+        skill,
+        score: 0,
+        rationale: ["No matching task signal, role, capability, or risk area."],
+    }));
+    return {
+        taskId,
+        selected: selected.map(toPlanItem),
+        skipped: skipped.map(toPlanItem),
+        sourceGroups: unique(selected.flatMap((item) => item.skill.sourceGroups)),
+    };
+}
+export async function renderSkills({ target, taskId, skillIds, root = process.cwd(), }) {
+    const skills = await resolveRenderSkills({ taskId, skillIds, root });
+    const sourceGroups = unique(skills.flatMap((skill) => skill.sourceGroups));
+    return {
+        target,
+        taskId,
+        skills,
+        sourceGroups,
+        content: renderForTarget(target, skills, sourceGroups, taskId),
+    };
+}
+async function resolveRenderSkills({ taskId, skillIds, root, }) {
+    if (skillIds && skillIds.length > 0) {
+        const catalog = listSkills();
+        return skillIds.map((id) => {
+            const skill = catalog.find((candidate) => candidate.id === id);
+            if (!skill) {
+                throw new Error(`unknown skill: ${id}`);
+            }
+            return skill;
+        });
+    }
+    if (!taskId) {
+        throw new Error("missing --task or --skills");
+    }
+    const plan = await planSkillsForTask(taskId, root);
+    return plan.selected.map((item) => item.skill);
+}
+function scoreSkill(skill, task, roleCapabilities) {
+    const text = taskText(task);
+    const rationale = [];
+    let score = 0;
+    if (skill.roles.includes(task.ownerRole)) {
+        score += 3;
+        rationale.push(`owner role matches ${task.ownerRole}`);
+    }
+    const matchedTriggers = skill.triggers.filter((trigger) => text.includes(trigger.toLowerCase()));
+    if (matchedTriggers.length > 0) {
+        score += matchedTriggers.length * 2;
+        rationale.push(`task text matches triggers: ${matchedTriggers.join(", ")}`);
+    }
+    const risks = [
+        ...(task.risks ?? []),
+        ...(task.riskGate?.impactAreas ?? []),
+    ].map((risk) => risk.toLowerCase());
+    const matchedRisks = skill.riskAreas.filter((risk) => risks.some((taskRisk) => taskRisk.includes(risk)));
+    if (matchedRisks.length > 0) {
+        score += matchedRisks.length * 2;
+        rationale.push(`risk areas match: ${matchedRisks.join(", ")}`);
+    }
+    const matchedCapabilities = skill.capabilities.filter((capability) => roleCapabilities.includes(capability));
+    if (matchedCapabilities.length > 0) {
+        score += matchedCapabilities.length;
+        rationale.push(`role capabilities match: ${matchedCapabilities.join(", ")}`);
+    }
+    if (skill.id === "prompt-registry" && (task.paths?.length ?? 0) > 0) {
+        score += 1;
+        rationale.push("task touches files, so prompt registry can preserve artifact intent");
+    }
+    if (skill.id === "source-of-truth" && score === 0) {
+        rationale.push("baseline source selection should run for every task");
+    }
+    return { skill, score, rationale };
+}
+function toPlanItem({ skill, score, rationale, }) {
+    return { skill, score, rationale };
+}
+function taskText(task) {
+    return [
+        task.id,
+        task.title,
+        task.backlogItem,
+        task.goal,
+        task.scope,
+        task.testStrategy,
+        ...(task.acceptanceCriteria ?? []),
+        ...(task.assumptions ?? []),
+        ...(task.risks ?? []),
+        ...(task.paths ?? []),
+    ]
+        .filter(Boolean)
+        .join(" ")
+        .toLowerCase();
+}
+function renderForTarget(target, skills, sourceGroups, taskId) {
+    if (target === "cursor") {
+        return renderMarkdown(skills, sourceGroups, taskId, "Cursor Skill Context", "Use these Open Orchestra skills as task-scoped Cursor rules.");
+    }
+    if (target === "windsurf") {
+        return renderMarkdown(skills, sourceGroups, taskId, "Windsurf Skill Context", "Use these Open Orchestra skills as task-scoped Windsurf rules.");
+    }
+    if (target === "claude") {
+        return renderMarkdown(skills, sourceGroups, taskId, "Claude Skill Context", "Load only these Open Orchestra skills for this task.");
+    }
+    if (target === "codex") {
+        return renderMarkdown(skills, sourceGroups, taskId, "Codex Skill Context", "Apply these Open Orchestra skills while preserving AGENTS.md instructions.");
+    }
+    if (target === "vscode") {
+        return JSON.stringify({ taskId, sourceGroups, skills }, null, 2);
+    }
+    return renderMarkdown(skills, sourceGroups, taskId, "Open Orchestra Skill Context", "Provider-agnostic skill context for this task.");
+}
+function renderMarkdown(skills, sourceGroups, taskId, title, intro) {
+    const lines = [
+        `# ${title}`,
+        "",
+        intro,
+        "",
+        `Task: ${taskId ?? "explicit skill selection"}`,
+        "",
+        "## Source Groups",
+        "",
+        ...sourceGroups.map((group) => `- ${group}`),
+        "",
+    ];
+    for (const skill of skills) {
+        lines.push(`## ${skill.name}`, "", `ID: ${skill.id}`, "", skill.summary, "", "### Load From", "", `- ${skill.entry}`, "", "### Procedure", "", ...skill.instructions.map((instruction) => `- ${instruction}`), "", "### Evidence", "", ...skill.evidence.map((evidence) => `- ${evidence}`), "");
+    }
+    return lines.join("\n");
+}
+export async function readAgentLessons(root = process.cwd()) {
+    const lessonsPath = resolveWorkflowPath(root, FILES.agentLessons);
+    if (!(await exists(lessonsPath))) {
+        return [];
+    }
+    return (await readFile(lessonsPath, "utf8"))
+        .split("\n")
+        .filter((line) => line.trim() !== "");
+}
+export async function readSourceOfTruth(root = process.cwd()) {
+    return readJson(path.join(root, ".agent-workflow", FILES.sourceOfTruth), []);
+}
+export async function validateSkills(root = PACKAGE_ROOT) {
+    const errors = [];
+    const warnings = [];
+    const ids = new Set();
+    for (const skill of listSkills()) {
+        if (ids.has(skill.id)) {
+            errors.push(`duplicate skill id: ${skill.id}`);
+        }
+        ids.add(skill.id);
+        if (!(await exists(path.join(root, skill.entry)))) {
+            errors.push(`missing skill entry: ${skill.entry}`);
+        }
+        const manifestPath = path.join(root, "skills", skill.id, "manifest.json");
+        if (!(await exists(manifestPath))) {
+            errors.push(`missing skill manifest: skills/${skill.id}/manifest.json`);
+            continue;
+        }
+        const manifest = await readJson(manifestPath, {});
+        if (manifest.id !== skill.id) {
+            errors.push(`manifest id mismatch for ${skill.id}`);
+        }
+        for (const required of [
+            "name",
+            "summary",
+            "triggers",
+            "roles",
+            "capabilities",
+            "sourceGroups",
+            "entry",
+            "evidence",
+            "loadBudget",
+        ]) {
+            if (!(required in manifest)) {
+                errors.push(`manifest ${skill.id} missing ${required}`);
+            }
+        }
+        if (skill.instructions.length === 0) {
+            warnings.push(`skill ${skill.id} has no instructions`);
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}
+export async function recordSkillPlan(plan, root = process.cwd()) {
+    if (!(await hasInitializedWorkflowState(root))) {
+        return;
+    }
+    await appendEvent(root, {
+        type: "SKILLS_PLANNED",
+        taskId: plan.taskId,
+        actor: "parent",
+        summary: `Selected ${plan.selected.length} skills for ${plan.taskId}`,
+        metadata: {
+            selectedSkillIds: plan.selected.map((item) => item.skill.id),
+            sourceGroups: plan.sourceGroups,
+            rationale: Object.fromEntries(plan.selected.map((item) => [item.skill.id, item.rationale])),
+        },
+    });
+}
+export async function recordSkillRender(rendered, root = process.cwd()) {
+    if (!(await hasInitializedWorkflowState(root))) {
+        return;
+    }
+    await appendEvent(root, removeUndefined({
+        type: "SKILLS_RENDERED",
+        taskId: rendered.taskId,
+        actor: "parent",
+        summary: `Rendered ${rendered.skills.length} skills for ${rendered.target}`,
+        metadata: {
+            target: rendered.target,
+            selectedSkillIds: rendered.skills.map((skill) => skill.id),
+            sourceGroups: rendered.sourceGroups,
+        },
+    }));
+}
+async function hasInitializedWorkflowState(root) {
+    return exists(resolveWorkflowPath(root, FILES.config));
+}
+export async function addAgentLesson(input, root = process.cwd()) {
+    const lesson = { timestamp: new Date().toISOString(), ...input };
+    await writeFile(resolveWorkflowPath(root, FILES.agentLessons), `${JSON.stringify(lesson)}\n`, { flag: "a" });
+    await appendEvent(root, removeUndefined({
+        type: "LESSON_RECORDED",
+        taskId: lesson.taskId,
+        actor: lesson.actor,
+        summary: `Recorded lesson: ${lesson.errorSignature}`,
+        metadata: { operation: lesson.operation, appliesTo: lesson.appliesTo },
+    }));
+    return lesson;
+}
+export async function listAgentLessons(root = process.cwd()) {
+    const lines = await readAgentLessons(root);
+    return lines.map((line) => JSON.parse(line));
+}
+export async function promoteAgentLessons({ to, filter, root = process.cwd(), }) {
+    const lessons = (await listAgentLessons(root)).filter((lesson) => {
+        if (!filter) {
+            return true;
+        }
+        const text = JSON.stringify(lesson).toLowerCase();
+        return text.includes(filter.toLowerCase());
+    });
+    const content = [
+        `# Promoted Agent Lessons (${to})`,
+        "",
+        ...lessons.flatMap((lesson) => [
+            `## ${lesson.operation}`,
+            `- Error: ${lesson.errorSignature}`,
+            `- Root cause: ${lesson.rootCause}`,
+            `- Fix: ${lesson.fix}`,
+            `- Prevention: ${lesson.prevention}`,
+            "",
+        ]),
+    ].join("\n");
+    const artifact = await writeArtifact(root, "decisions", `promoted-lessons-${to}.md`, content);
+    await appendEvent(root, {
+        type: "LESSON_PROMOTED",
+        actor: "parent",
+        summary: `Promoted ${lessons.length} lessons to ${to}`,
+        artifacts: [artifact],
+        metadata: { to, filter, lessonCount: lessons.length },
+    });
+    return { artifact, lessons };
+}
+export async function writeSourceOfTruth(entries, root = process.cwd()) {
+    await writeJson(path.join(root, ".agent-workflow", FILES.sourceOfTruth), entries);
+}
+function removeUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+function unique(values) {
+    return [...new Set(values)].sort();
+}
+//# sourceMappingURL=skills.js.map