@sweny-ai/core 0.1.27 → 0.1.29

package/dist/__tests__/executor.test.js

@@ -66,7 +66,7 @@ describe("executor", () => {
             },
         });
         const events = [];
-        const results = await execute(linearWorkflow, { alert: "test" }, {
+        const { results } = await execute(linearWorkflow, { alert: "test" }, {
             skills: createSkillMap([fileSkill]),
             claude,
             observer: (e) => events.push(e),
@@ -92,7 +92,7 @@ describe("executor", () => {
             },
             routes: { check: "high" },
         });
-        const results = await execute(branchingWorkflow, { alert: "cpu" }, {
+        const { results } = await execute(branchingWorkflow, { alert: "cpu" }, {
             skills: createSkillMap([]),
             claude,
             config: {},
@@ -111,7 +111,7 @@ describe("executor", () => {
             },
             routes: { check: "low" },
         });
-        const results = await execute(branchingWorkflow, { alert: "minor" }, {
+        const { results } = await execute(branchingWorkflow, { alert: "minor" }, {
             skills: createSkillMap([]),
             claude,
             config: {},
@@ -154,7 +154,7 @@ describe("executor", () => {
                 c: { data: {} },
             },
         });
-        const results = await execute(linearWorkflow, {}, {
+        const { results } = await execute(linearWorkflow, {}, {
             skills: createSkillMap([]),
             claude,
             observer: () => {
@@ -193,7 +193,7 @@ describe("executor", () => {
         const claude = new MockClaude({
             responses: { only: { data: { result: "done" } } },
         });
-        const results = await execute(singleNode, {}, {
+        const { results } = await execute(singleNode, {}, {
             skills: createSkillMap([]),
             claude,
             config: {},
@@ -252,7 +252,7 @@ describe("executor", () => {
             claude,
         })).rejects.toThrow("Missing required config");
         // Should succeed with override
-        const results = await execute(linearWorkflow, {}, {
+        const { results } = await execute(linearWorkflow, {}, {
             skills: createSkillMap([skillWithConfig]),
             claude,
             config: { MY_KEY: "provided" },
@@ -267,7 +267,7 @@ describe("executor", () => {
                 c: { data: {} },
             },
         });
-        const results = await execute(linearWorkflow, {}, {
+        const { results } = await execute(linearWorkflow, {}, {
             skills: createSkillMap([]),
             claude,
             config: {},
@@ -316,13 +316,20 @@ describe("executor", () => {
                 return opts.choices[0].id;
             },
         };
-        const results = await execute(retryWorkflow, {}, { skills: createSkillMap([]), claude: mockClaude, config: {} });
+        const { results, trace } = await execute(retryWorkflow, {}, { skills: createSkillMap([]), claude: mockClaude, config: {} });
         // extract ran twice (initial + 1 retry), judge ran twice, done ran once
         expect(extractCount).toBe(2);
         expect(judgeCount).toBe(2);
         expect(results.has("done")).toBe(true);
         // The second extract result overwrites the first
         expect(results.get("extract")?.data.attempt).toBe(2);
+        // Trace captures the full execution path including loops
+        expect(trace.steps).toHaveLength(5); // extract, judge, extract(retry), judge, done
+        expect(trace.steps[0]).toEqual({ node: "extract", status: "success", iteration: 1 });
+        expect(trace.steps[2]).toEqual({ node: "extract", status: "success", iteration: 2 });
+        // Trace edges include the retry loop
+        const retryEdge = trace.edges.find((e) => e.from === "judge" && e.to === "extract");
+        expect(retryEdge).toBeDefined();
     });
     it("respects max_iterations=1 as single retry", async () => {
         const singleRetry = {
@@ -356,7 +363,7 @@ describe("executor", () => {
                 return opts.choices[0].id;
             },
         };
-        const results = await execute(singleRetry, {}, { skills: createSkillMap([]), claude: mockClaude, config: {} });
+        const { results } = await execute(singleRetry, {}, { skills: createSkillMap([]), claude: mockClaude, config: {} });
         // A runs twice (once initially, once via retry), then edge is exhausted → falls to "end"
         expect(aCount).toBe(2);
         expect(results.has("end")).toBe(true);
@@ -371,7 +378,7 @@ describe("executor", () => {
                 return "nonexistent_node"; // invalid target
             },
         };
-        const results = await execute(branchingWorkflow, {}, {
+        const { results } = await execute(branchingWorkflow, {}, {
             skills: createSkillMap([]),
             claude: badRouteClaude,
             config: {},

package/dist/__tests__/integration/e2e-workflow.integration.test.js

@@ -47,7 +47,7 @@ describe.runIf(available.claude)("e2e workflow with real Claude", () => {
             maxTurns: 3,
         });
         const events = [];
-        const results = await execute(analysisWorkflow, {
+        const { results } = await execute(analysisWorkflow, {
             alert: "CPU usage at 98% for 15 minutes on production server web-03",
             service: "api-gateway",
             timestamp: "2025-03-25T08:00:00Z",

package/dist/__tests__/skills.test.js

@@ -1,10 +1,14 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
 import { github } from "../skills/github.js";
 import { linear } from "../skills/linear.js";
 import { slack } from "../skills/slack.js";
 import { sentry } from "../skills/sentry.js";
 import { datadog } from "../skills/datadog.js";
 import { notification } from "../skills/notification.js";
+import { loadCustomSkills, configuredSkills, createSkillMap } from "../skills/index.js";
 // ─── Helpers ─────────────────────────────────────────────────────
 const mockCtx = (config = {}) => ({
     config,
@@ -294,3 +298,119 @@ describe("notification skill", () => {
         expect(fetchMock.mock.calls[0][1].signal).toBeDefined();
     });
 });
+// ─── Custom skill discovery tests ──────────────────────────────
+describe("loadCustomSkills", () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = mkdtempSync(join(tmpdir(), "sweny-skills-test-"));
+    });
+    afterEach(() => {
+        rmSync(tmpDir, { recursive: true, force: true });
+    });
+    function writeSkill(dirName, content) {
+        const dir = join(tmpDir, ".claude", "skills", dirName);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, "SKILL.md"), content);
+    }
+    it("returns empty array when .claude/skills/ does not exist", () => {
+        const skills = loadCustomSkills(tmpDir);
+        expect(skills).toEqual([]);
+    });
+    it("returns empty array when .claude/skills/ is empty", () => {
+        mkdirSync(join(tmpDir, ".claude", "skills"), { recursive: true });
+        const skills = loadCustomSkills(tmpDir);
+        expect(skills).toEqual([]);
+    });
+    it("discovers a valid custom skill from SKILL.md frontmatter", () => {
+        writeSkill("my-skill", `---
+name: my-skill
+description: A test skill
+---
+
+Instructions for Claude go here.
+`);
+        const skills = loadCustomSkills(tmpDir);
+        expect(skills).toHaveLength(1);
+        expect(skills[0]).toMatchObject({
+            id: "my-skill",
+            name: "my-skill",
+            description: "A test skill",
+            category: "general",
+        });
+        expect(skills[0].tools).toEqual([]);
+        expect(skills[0].config).toEqual({});
+    });
+    it("discovers multiple skills", () => {
+        writeSkill("skill-a", `---\nname: skill-a\ndescription: First\n---\nBody`);
+        writeSkill("skill-b", `---\nname: skill-b\ndescription: Second\n---\nBody`);
+        const skills = loadCustomSkills(tmpDir);
+        expect(skills).toHaveLength(2);
+        const ids = skills.map((s) => s.id).sort();
+        expect(ids).toEqual(["skill-a", "skill-b"]);
+    });
+    it("skips directories without SKILL.md", () => {
+        mkdirSync(join(tmpDir, ".claude", "skills", "no-skill-file"), { recursive: true });
+        writeFileSync(join(tmpDir, ".claude", "skills", "no-skill-file", "README.md"), "not a skill");
+        const skills = loadCustomSkills(tmpDir);
+        expect(skills).toEqual([]);
+    });
+    it("skips SKILL.md without frontmatter", () => {
+        writeSkill("no-frontmatter", "Just plain text, no YAML frontmatter.");
+        const skills = loadCustomSkills(tmpDir);
+        expect(skills).toEqual([]);
+    });
+    it("skips SKILL.md with frontmatter missing name field", () => {
+        writeSkill("no-name", `---\ndescription: Missing name\n---\nBody`);
+        const skills = loadCustomSkills(tmpDir);
+        expect(skills).toEqual([]);
+    });
+    it("uses fallback description when description is missing", () => {
+        writeSkill("name-only", `---\nname: name-only\n---\nBody`);
+        const skills = loadCustomSkills(tmpDir);
+        expect(skills).toHaveLength(1);
+        expect(skills[0].description).toBe("Custom skill: name-only");
+    });
+    it("skips malformed YAML in frontmatter", () => {
+        writeSkill("bad-yaml", `---\n: [invalid yaml\n---\nBody`);
+        const skills = loadCustomSkills(tmpDir);
+        expect(skills).toEqual([]);
+    });
+});
+describe("configuredSkills with custom skills", () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = mkdtempSync(join(tmpdir(), "sweny-configured-test-"));
+    });
+    afterEach(() => {
+        rmSync(tmpDir, { recursive: true, force: true });
+    });
+    function writeSkill(dirName, content) {
+        const dir = join(tmpDir, ".claude", "skills", dirName);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, "SKILL.md"), content);
+    }
+    it("includes custom skills alongside configured built-ins", () => {
+        writeSkill("my-custom", `---\nname: my-custom\ndescription: Custom\n---\nBody`);
+        // Provide a notification webhook so at least one built-in is configured
+        const skills = configuredSkills({ NOTIFICATION_WEBHOOK_URL: "https://example.com" }, tmpDir);
+        const ids = skills.map((s) => s.id);
+        expect(ids).toContain("my-custom");
+        expect(ids).toContain("notification");
+    });
+    it("built-in skills take precedence over custom skills with same ID", () => {
+        // notification is configured when a webhook URL is set
+        writeSkill("notification", `---\nname: notification\ndescription: Custom override attempt\n---\nBody`);
+        const skills = configuredSkills({ NOTIFICATION_WEBHOOK_URL: "https://example.com" }, tmpDir);
+        const notif = skills.filter((s) => s.id === "notification");
+        expect(notif).toHaveLength(1);
+        // Should be the built-in (has tools), not the custom one (tools: [])
+        expect(notif[0].tools.length).toBeGreaterThan(0);
+    });
+    it("custom skills are usable in createSkillMap", () => {
+        writeSkill("extract-colors", `---\nname: extract-colors\ndescription: Route color extraction\n---\nBody`);
+        const skills = configuredSkills({}, tmpDir);
+        const map = createSkillMap(skills);
+        expect(map.has("extract-colors")).toBe(true);
+        expect(map.get("extract-colors").tools).toEqual([]);
+    });
+});

package/dist/cli/main.js

@@ -194,7 +194,7 @@ triageCmd.action(async (options) => {
         console.log(formatBanner(config, version));
     }
     // ── Build skill map + MCP servers + Claude client ──────────
-    const skills = createSkillMap(configuredSkills());
+    const skills = createSkillMap(configuredSkills(process.env, process.cwd()));
     const mcpAutoConfig = buildMcpAutoConfig(config);
     const mcpServers = buildAutoMcpServers(mcpAutoConfig);
     const claude = new ClaudeClient({
@@ -358,7 +358,7 @@ triageCmd.action(async (options) => {
         contextUrls,
     };
     try {
-        const results = await execute(triageWorkflow, workflowInput, {
+        const { results } = await execute(triageWorkflow, workflowInput, {
             skills,
             claude,
             observer,
@@ -412,7 +412,7 @@ implementCmd.action(async (issueId, options) => {
             fileConfig["output-dir"] ||
             ".sweny/output",
     };
-    const skills = createSkillMap(configuredSkills());
+    const skills = createSkillMap(configuredSkills(process.env, process.cwd()));
     const mcpAutoConfig = buildMcpAutoConfig(config);
     const mcpServers = buildAutoMcpServers(mcpAutoConfig);
     const claude = new ClaudeClient({
@@ -474,7 +474,7 @@ implementCmd.action(async (issueId, options) => {
         contextUrls,
     };
     try {
-        const results = await execute(implementWorkflow, workflowInput, {
+        const { results } = await execute(implementWorkflow, workflowInput, {
             skills,
             claude,
             observer,
@@ -546,7 +546,7 @@ export async function workflowRunAction(file, options) {
     const config = parseCliInputs(options, fileConfig);
     const isJson = Boolean(options.json);
     const isTTY = !isJson && (process.stderr.isTTY ?? false);
-    const skills = createSkillMap(configuredSkills());
+    const skills = createSkillMap(configuredSkills(process.env, process.cwd()));
     const mcpAutoConfig = buildMcpAutoConfig(config);
     const mcpServers = buildAutoMcpServers(mcpAutoConfig);
     const claude = new ClaudeClient({
@@ -624,7 +624,7 @@ export async function workflowRunAction(file, options) {
         };
     }
     try {
-        const results = await execute(workflow, workflowInput, {
+        const { results, trace } = await execute(workflow, workflowInput, {
             skills,
             claude,
             observer,
@@ -642,7 +642,7 @@ export async function workflowRunAction(file, options) {
             for (const [nodeId, result] of results) {
                 state[nodeId] = result.status === "success" ? "success" : result.status === "failed" ? "failed" : "skipped";
             }
-            process.stdout.write(toMermaidBlock(workflow, { state, title: workflow.name }) + "\n");
+            process.stdout.write(toMermaidBlock(workflow, { state, trace, title: workflow.name }) + "\n");
         }
         const hasFailed = [...results.values()].some((r) => r.status === "failed");
         if (hasFailed) {

package/dist/executor.d.ts

@@ -12,7 +12,7 @@
  *
  * This replaces ~8k lines of engine + recipe step code.
  */
-import type { Workflow, Skill, Claude, Observer, NodeResult, Logger } from "./types.js";
+import type { Workflow, Skill, Claude, Observer, Logger, ExecutionResult } from "./types.js";
 export interface ExecuteOptions {
     /** Registered skills (id → Skill) */
     skills: Map<string, Skill>;
@@ -28,6 +28,8 @@ export interface ExecuteOptions {
 /**
  * Execute a workflow from entry to completion.
  *
- * Returns a map of node ID → result for every node that ran.
+ * Returns an ExecutionResult with:
+ * - `results`: map of node ID → final result (last execution if retried)
+ * - `trace`: full ordered execution trace including loops and routing decisions
  */
-export declare function execute(workflow: Workflow, input: unknown, options: ExecuteOptions): Promise<Map<string, NodeResult>>;
+export declare function execute(workflow: Workflow, input: unknown, options: ExecuteOptions): Promise<ExecutionResult>;

package/dist/executor.js

@@ -16,7 +16,9 @@ import { consoleLogger } from "./types.js";
 /**
  * Execute a workflow from entry to completion.
  *
- * Returns a map of node ID → result for every node that ran.
+ * Returns an ExecutionResult with:
+ * - `results`: map of node ID → final result (last execution if retried)
+ * - `trace`: full ordered execution trace including loops and routing decisions
  */
 export async function execute(workflow, input, options) {
     const { skills, claude, observer } = options;
@@ -24,6 +26,8 @@ export async function execute(workflow, input, options) {
     const logger = options.logger ?? consoleLogger;
     const results = new Map();
     const edgeCounts = new Map(); // "from→to" → times followed
+    const nodeRunCounts = new Map(); // node → times executed
+    const trace = { steps: [], edges: [] };
     validate(workflow, skills);
     safeObserve(observer, { type: "workflow:start", workflow: workflow.id }, logger);
     let currentId = workflow.entry;
@@ -31,6 +35,8 @@ export async function execute(workflow, input, options) {
         const node = workflow.nodes[currentId];
         if (!node)
             throw new Error(`Unknown node: "${currentId}"`);
+        const iteration = (nodeRunCounts.get(currentId) ?? 0) + 1;
+        nodeRunCounts.set(currentId, iteration);
         safeObserve(observer, { type: "node:enter", node: currentId, instruction: node.instruction }, logger);
         logger.info(`→ ${node.name}`, { node: currentId });
         // Gather tools from the node's skills
@@ -64,6 +70,7 @@ export async function execute(workflow, input, options) {
             },
         });
         results.set(currentId, result);
+        trace.steps.push({ node: currentId, status: result.status, iteration });
         safeObserve(observer, { type: "node:exit", node: currentId, result }, logger);
         logger.info(`  ✓ ${result.status}`, { node: currentId, toolCalls: result.toolCalls.length });
         // Dry run hard gate — stop at the first conditional routing decision.
@@ -80,13 +87,20 @@ export async function execute(workflow, input, options) {
             }
         }
         // Resolve next node via edge conditions
+        const prevId = currentId;
         currentId = await resolveNext(workflow, currentId, results, input, claude, observer, edgeCounts, logger);
+        // Record the routing decision in the trace
+        if (currentId) {
+            const edgeKey = `${prevId}→${currentId}`;
+            const reason = workflow.edges.find((e) => e.from === prevId && e.to === currentId)?.when ?? "only path";
+            trace.edges.push({ from: prevId, to: currentId, reason });
+        }
     }
     safeObserve(observer, {
         type: "workflow:end",
         results: Object.fromEntries(results),
     }, logger);
-    return results;
+    return { results, trace };
 }
 // ─── Internals ───────────────────────────────────────────────────
 /**
@@ -119,7 +133,12 @@ function buildNodeInstruction(baseInstruction, input) {
         return baseInstruction;
     return `${sections.join("\n\n")}\n\n---\n\n${baseInstruction}`;
 }
-/** Call observer without letting exceptions crash the workflow */
+/**
+ * Call observer without letting exceptions crash the workflow.
+ *
+ * Accepts a typed ExecutionEvent so TypeScript catches mistakes in
+ * event construction at compile time rather than silently at runtime.
+ */
 function safeObserve(observer, event, logger) {
     if (!observer)
         return;

package/dist/executor.test.js

@@ -167,7 +167,7 @@ describe("executor", () => {
             },
         });
         const events = [];
-        const results = await execute(simpleWorkflow, { alert: "test" }, {
+        const { results } = await execute(simpleWorkflow, { alert: "test" }, {
             skills,
             claude,
             observer: (e) => events.push(e),
@@ -202,7 +202,7 @@ describe("executor", () => {
                 check: "handle_high", // Route to high severity handler
             },
         });
-        const results = await execute(branchingWorkflow, { alert: "cpu spike" }, {
+        const { results } = await execute(branchingWorkflow, { alert: "cpu spike" }, {
             skills,
             claude,
             config: {},
@@ -224,7 +224,7 @@ describe("executor", () => {
                 check: "handle_low",
             },
         });
-        const results = await execute(branchingWorkflow, { alert: "minor" }, {
+        const { results } = await execute(branchingWorkflow, { alert: "minor" }, {
             skills,
             claude,
             config: {},

package/dist/index.d.ts

@@ -21,7 +21,7 @@
  * })
  * ```
  */
-export type { Skill, SkillCategory, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, } from "./types.js";
+export type { Skill, SkillCategory, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, TraceStep, TraceEdge, ExecutionTrace, ExecutionResult, } from "./types.js";
 export { consoleLogger } from "./types.js";
 export { execute } from "./executor.js";
 export type { ExecuteOptions } from "./executor.js";

package/dist/mermaid.d.ts

@@ -6,13 +6,16 @@
  * VS Code preview, documentation sites, and anywhere Mermaid is supported.
  *
  * Accepts optional execution state to color nodes by status
- * (current/success/failed/skipped).
+ * (current/success/failed/skipped) and optional execution trace
+ * to highlight which edges were taken and show loop iterations.
  */
-import type { Workflow } from "./types.js";
+import type { Workflow, ExecutionTrace } from "./types.js";
 export type NodeStatus = "current" | "success" | "failed" | "skipped";
 export interface MermaidOptions {
     /** Execution state — nodes not in this map render as default (pending) */
     state?: Record<string, NodeStatus>;
+    /** Execution trace — highlights taken/not-taken edges and loop counts */
+    trace?: ExecutionTrace;
     /** Graph direction: TB (top-bottom) or LR (left-right). Default: TB */
     direction?: "TB" | "LR";
     /** Title rendered above the diagram */
@@ -27,6 +30,7 @@ export interface MermaidOptions {
  *
  * const md = toMermaid(workflow, {
  *   state: { triage: 'success', investigate: 'current' },
+ *   trace: executionResult.trace,
  * });
  * // Wrap in ```mermaid fence for GitHub rendering
  * ```

package/dist/mermaid.js

@@ -6,7 +6,8 @@
  * VS Code preview, documentation sites, and anywhere Mermaid is supported.
  *
  * Accepts optional execution state to color nodes by status
- * (current/success/failed/skipped).
+ * (current/success/failed/skipped) and optional execution trace
+ * to highlight which edges were taken and show loop iterations.
  */
 /**
  * Convert a Workflow to a Mermaid flowchart diagram string.
@@ -17,12 +18,13 @@
  *
  * const md = toMermaid(workflow, {
  *   state: { triage: 'success', investigate: 'current' },
+ *   trace: executionResult.trace,
  * });
  * // Wrap in ```mermaid fence for GitHub rendering
  * ```
  */
 export function toMermaid(workflow, options = {}) {
-    const { state = {}, direction = "TB", title } = options;
+    const { state = {}, trace, direction = "TB", title } = options;
     const lines = [];
     if (title) {
         lines.push("---");
@@ -30,45 +32,80 @@ export function toMermaid(workflow, options = {}) {
         lines.push("---");
     }
     lines.push(`graph ${direction}`);
+    // Build node iteration counts from trace
+    const nodeIterations = new Map();
+    if (trace) {
+        for (const step of trace.steps) {
+            nodeIterations.set(step.node, Math.max(nodeIterations.get(step.node) ?? 0, step.iteration));
+        }
+    }
     // Nodes
     for (const [id, node] of Object.entries(workflow.nodes)) {
-        const label = escapeLabel(node.name);
+        let label = escapeLabel(node.name);
         const isEntry = id === workflow.entry;
         const entryTag = isEntry ? " \\u25B6" : "";
-        // Use stadium shape ([...]) for entry, rounded ([(...)])  for others
+        // Show iteration count for nodes that ran multiple times
+        const iterations = nodeIterations.get(id);
+        const iterTag = iterations && iterations > 1 ? ` ×${iterations}` : "";
         if (isEntry) {
-            lines.push(`    ${sanitizeId(id)}([${label}${entryTag}])`);
+            lines.push(`    ${sanitizeId(id)}([${label}${entryTag}${iterTag}])`);
         }
         else {
-            lines.push(`    ${sanitizeId(id)}[${label}]`);
+            lines.push(`    ${sanitizeId(id)}[${label}${iterTag}]`);
         }
     }
     lines.push("");
-    // Edges
+    // Build set of taken edges from trace for lookup
+    const takenEdges = new Set();
+    const edgeTakenCounts = new Map();
+    if (trace) {
+        for (const te of trace.edges) {
+            const key = `${te.from}→${te.to}`;
+            takenEdges.add(key);
+            edgeTakenCounts.set(key, (edgeTakenCounts.get(key) ?? 0) + 1);
+        }
+    }
+    // Edges — track index for linkStyle directives
+    const takenIndices = [];
+    const notTakenIndices = [];
+    let edgeIndex = 0;
     for (const edge of workflow.edges) {
         const from = sanitizeId(edge.from);
         const to = sanitizeId(edge.to);
-        if (edge.when) {
-            const label = escapeLabel(edge.when);
-            if (edge.max_iterations) {
-                lines.push(`    ${from} -->|"${label} (max ${edge.max_iterations}x)"| ${to}`);
-            }
-            else {
-                lines.push(`    ${from} -->|"${label}"| ${to}`);
-            }
-        }
-        else if (edge.max_iterations) {
-            lines.push(`    ${from} -->|"max ${edge.max_iterations}x"| ${to}`);
+        const key = `${edge.from}→${edge.to}`;
+        const taken = takenEdges.has(key);
+        const takenCount = edgeTakenCounts.get(key) ?? 0;
+        // Build label parts
+        const labelParts = [];
+        if (edge.when)
+            labelParts.push(edge.when);
+        if (edge.max_iterations)
+            labelParts.push(`max ${edge.max_iterations}x`);
+        // Show how many times this edge was actually followed
+        if (takenCount > 1)
+            labelParts.push(`taken ${takenCount}x`);
+        if (labelParts.length > 0) {
+            const label = escapeLabel(labelParts.join(" · "));
+            lines.push(`    ${from} -->|"${label}"| ${to}`);
         }
         else {
             lines.push(`    ${from} --> ${to}`);
         }
+        // Track edge indices for styling
+        if (trace) {
+            if (taken) {
+                takenIndices.push(edgeIndex);
+            }
+            else {
+                notTakenIndices.push(edgeIndex);
+            }
+        }
+        edgeIndex++;
     }
-    // Status styling
+    // Node status styling
     const statusNodes = groupByStatus(state);
     if (statusNodes.size > 0) {
         lines.push("");
-        // Define style classes
         lines.push("    classDef current fill:#3b82f6,stroke:#2563eb,color:#fff,stroke-width:2px");
         lines.push("    classDef success fill:#22c55e,stroke:#16a34a,color:#fff,stroke-width:2px");
         lines.push("    classDef failed fill:#ef4444,stroke:#dc2626,color:#fff,stroke-width:2px");
@@ -78,6 +115,16 @@ export function toMermaid(workflow, options = {}) {
             lines.push(`    class ${sanitized} ${status}`);
         }
     }
+    // Edge styling — taken edges bold green, not-taken edges dashed gray
+    if (trace) {
+        lines.push("");
+        if (takenIndices.length > 0) {
+            lines.push(`    linkStyle ${takenIndices.join(",")} stroke:#22c55e,stroke-width:3px`);
+        }
+        if (notTakenIndices.length > 0) {
+            lines.push(`    linkStyle ${notTakenIndices.join(",")} stroke:#6b7280,stroke-width:1px,stroke-dasharray:5 5`);
+        }
+    }
     return lines.join("\n");
 }
 /**

package/dist/mermaid.test.js

@@ -72,7 +72,7 @@ describe("toMermaid", () => {
     });
     it("renders max_iterations on edges", () => {
         const result = toMermaid(withLoop);
-        expect(result).toContain('a -->|"needs retry (max 3x)"| a');
+        expect(result).toContain('a -->|"needs retry · max 3x"| a');
         expect(result).toContain("a --> b");
     });
     it("renders max_iterations without condition", () => {
@@ -168,6 +168,43 @@ describe("toMermaid", () => {
         expect(result).toContain("class a,b success");
         expect(result).toContain("class c current");
     });
+    it("highlights taken edges and dims not-taken edges with trace", () => {
+        const trace = {
+            steps: [
+                { node: "triage", status: "success", iteration: 1 },
+                { node: "investigate", status: "success", iteration: 1 },
+                { node: "close", status: "success", iteration: 1 },
+            ],
+            edges: [
+                { from: "triage", to: "investigate", reason: "severity is high or critical" },
+                { from: "investigate", to: "close", reason: "only path" },
+            ],
+        };
+        const result = toMermaid(branching, { trace });
+        // Taken edges get green bold styling (edges 0 and 2 in the workflow)
+        expect(result).toContain("linkStyle");
+        expect(result).toContain("stroke:#22c55e,stroke-width:3px");
+        // Not-taken edges get dashed gray
+        expect(result).toContain("stroke:#6b7280,stroke-width:1px,stroke-dasharray:5 5");
+    });
+    it("shows iteration count on nodes and edges from trace", () => {
+        const trace = {
+            steps: [
+                { node: "a", status: "success", iteration: 1 },
+                { node: "a", status: "success", iteration: 2 },
+                { node: "b", status: "success", iteration: 1 },
+            ],
+            edges: [
+                { from: "a", to: "a", reason: "needs retry" },
+                { from: "a", to: "b", reason: "only path" },
+            ],
+        };
+        const result = toMermaid(withLoop, { trace });
+        // Node a ran twice — should show ×2
+        expect(result).toContain("×2");
+        // Node b ran once — no iteration tag
+        expect(result).not.toContain("Done ×");
+    });
 });
 describe("builtin workflows", () => {
     it("renders triage workflow", () => {

package/dist/schema.d.ts

@@ -238,7 +238,11 @@ export interface WorkflowError {
  * - All edge sources and targets reference existing nodes
  * - No self-loops
  * - All nodes are reachable from entry
+ * - Unbounded cycles (cycles with no max_iterations guard)
  * - (optional) All referenced skills exist in the provided skill set
+ *
+ * Note: nodes with no outgoing edges are valid terminal nodes — the executor
+ * returns null when it reaches one, ending the workflow cleanly.
  */
 export declare function validateWorkflow(workflow: z.infer<typeof workflowZ>, knownSkills?: Set<string>): WorkflowError[];
 /**

package/dist/schema.js

@@ -65,7 +65,11 @@ export function parseWorkflow(raw) {
  * - All edge sources and targets reference existing nodes
  * - No self-loops
  * - All nodes are reachable from entry
+ * - Unbounded cycles (cycles with no max_iterations guard)
  * - (optional) All referenced skills exist in the provided skill set
+ *
+ * Note: nodes with no outgoing edges are valid terminal nodes — the executor
+ * returns null when it reaches one, ending the workflow cleanly.
  */
 export function validateWorkflow(workflow, knownSkills) {
     const errors = [];

package/dist/skills/index.d.ts

@@ -14,6 +14,15 @@ import { notification } from "./notification.js";
 import { supabase } from "./supabase.js";
 export declare const builtinSkills: Skill[];
 export { github, linear, slack, sentry, datadog, betterstack, notification, supabase };
+/**
+ * Load custom skills from a `.claude/skills/` directory.
+ *
+ * Custom skills are instruction-only (no tools or config) — they provide
+ * guidance documents that the coding agent reads from the filesystem.
+ * Registering them here ensures workflow validation recognises the skill IDs
+ * so nodes referencing them don't produce spurious warnings.
+ */
+export declare function loadCustomSkills(cwd?: string): Skill[];
 /**
  * Build a skill map from an array of skills.
  * Pass to `execute()` as the `skills` option.
@@ -39,9 +48,10 @@ export declare function allSkills(): Map<string, Skill>;
  */
 export declare function isSkillConfigured(skill: Skill, env?: Record<string, string | undefined>): boolean;
 /**
- * From all builtins, return only the skills that have their required env vars set.
+ * From all builtins + custom repo skills, return only the skills that are usable.
+ * Built-in skills are filtered by env vars; custom skills are always included.
  */
-export declare function configuredSkills(env?: Record<string, string | undefined>): Skill[];
+export declare function configuredSkills(env?: Record<string, string | undefined>, cwd?: string): Skill[];
 /**
  * Validate that a workflow's skill requirements are satisfiable.
  *

package/dist/skills/index.js

@@ -3,6 +3,9 @@
  *
  * All built-in skills + helpers to build a skill map from config.
  */
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import YAML from "yaml";
 import { github } from "./github.js";
 import { linear } from "./linear.js";
 import { slack } from "./slack.js";
@@ -14,6 +17,65 @@ import { supabase } from "./supabase.js";
 // ─── Built-in skill catalog ─────────────────────────────────────
 export const builtinSkills = [github, linear, slack, sentry, datadog, betterstack, notification, supabase];
 export { github, linear, slack, sentry, datadog, betterstack, notification, supabase };
+// ─── Custom skill discovery ─────────────────────────────────────
+/**
+ * Load custom skills from a `.claude/skills/` directory.
+ *
+ * Custom skills are instruction-only (no tools or config) — they provide
+ * guidance documents that the coding agent reads from the filesystem.
+ * Registering them here ensures workflow validation recognises the skill IDs
+ * so nodes referencing them don't produce spurious warnings.
+ */
+export function loadCustomSkills(cwd = process.cwd()) {
+    const skillsDir = join(cwd, ".claude", "skills");
+    if (!existsSync(skillsDir))
+        return [];
+    const skills = [];
+    let entries;
+    try {
+        entries = readdirSync(skillsDir, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name);
+    }
+    catch {
+        return [];
+    }
+    for (const dirName of entries) {
+        const skillFile = join(skillsDir, dirName, "SKILL.md");
+        if (!existsSync(skillFile))
+            continue;
+        try {
+            const content = readFileSync(skillFile, "utf-8");
+            const frontmatter = parseFrontmatter(content);
+            if (!frontmatter?.name)
+                continue;
+            skills.push({
+                id: frontmatter.name,
+                name: frontmatter.name,
+                description: frontmatter.description ?? `Custom skill: ${frontmatter.name}`,
+                category: "general",
+                config: {},
+                tools: [],
+            });
+        }
+        catch {
+            // Skip malformed skill files
+        }
+    }
+    return skills;
+}
+/** Extract YAML frontmatter from a markdown file (between --- delimiters). */
+function parseFrontmatter(content) {
+    const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!match)
+        return null;
+    try {
+        return YAML.parse(match[1]);
+    }
+    catch {
+        return null;
+    }
+}
 // ─── Registry helpers ───────────────────────────────────────────
 /**
  * Build a skill map from an array of skills.
@@ -62,10 +124,21 @@ export function isSkillConfigured(skill, env = process.env) {
     return envFields.some((f) => env[f.env]);
 }
 /**
- * From all builtins, return only the skills that have their required env vars set.
+ * From all builtins + custom repo skills, return only the skills that are usable.
+ * Built-in skills are filtered by env vars; custom skills are always included.
  */
-export function configuredSkills(env = process.env) {
-    return builtinSkills.filter((s) => isSkillConfigured(s, env));
+export function configuredSkills(env = process.env, cwd) {
+    const configured = builtinSkills.filter((s) => isSkillConfigured(s, env));
+    const custom = loadCustomSkills(cwd);
+    // Deduplicate: built-in skills take precedence over custom skills with the same ID
+    const ids = new Set(configured.map((s) => s.id));
+    for (const skill of custom) {
+        if (!ids.has(skill.id)) {
+            configured.push(skill);
+            ids.add(skill.id);
+        }
+    }
+    return configured;
 }
 export function validateWorkflowSkills(workflow, available) {
     const configured = [];

package/dist/types.d.ts

@@ -107,6 +107,36 @@ export type ExecutionEvent = {
     results: Record<string, NodeResult>;
 };
 export type Observer = (event: ExecutionEvent) => void;
+/** A single node execution within the trace */
+export interface TraceStep {
+    /** Node ID */
+    node: string;
+    /** Outcome of this execution */
+    status: "success" | "failed" | "skipped";
+    /** 1-based iteration count (2 = second time this node ran) */
+    iteration: number;
+}
+/** A routing decision between nodes */
+export interface TraceEdge {
+    from: string;
+    to: string;
+    /** Why this edge was chosen (condition text or "only path") */
+    reason: string;
+}
+/** Full execution trace — ordered steps + edges taken */
+export interface ExecutionTrace {
+    /** Ordered list of node executions (includes repeats from retry loops) */
+    steps: TraceStep[];
+    /** Ordered list of routing decisions */
+    edges: TraceEdge[];
+}
+/** Result of execute() — final node results + full execution trace */
+export interface ExecutionResult {
+    /** Final result per node (last execution if retried) */
+    results: Map<string, NodeResult>;
+    /** Full execution trace including loops and routing decisions */
+    trace: ExecutionTrace;
+}
 export interface Claude {
     /** Run a node: give Claude an instruction, context, and tools */
     run(opts: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sweny-ai/core",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "type": "module",
   "bin": {
     "sweny": "./dist/cli/main.js"