@kynetic-ai/spec 0.1.2 → 0.3.0

package/dist/merge/parse.js

@@ -0,0 +1,78 @@
+/**
+ * Parsing utilities for merge driver.
+ *
+ * Handles reading and parsing all three versions (base, ours, theirs)
+ * of a YAML file, with graceful fallback when parsing fails.
+ */
+import * as fs from "node:fs/promises";
+import { parseYaml } from "../parser/yaml.js";
+/**
+ * Parse all three versions of a YAML file.
+ *
+ * AC: @yaml-merge-driver ac-1
+ * Parses base, ours, and theirs as structured data instead of text.
+ *
+ * AC: @yaml-merge-driver ac-11
+ * Returns parse failure if any file cannot be parsed.
+ *
+ * @param basePath Path to base version (common ancestor)
+ * @param oursPath Path to ours version (current branch)
+ * @param theirsPath Path to theirs version (incoming branch)
+ * @returns ParseResult with parsed versions or error
+ */
+export async function parseYamlVersions(basePath, oursPath, theirsPath) {
+    try {
+        // Read all three files
+        const [baseContent, oursContent, theirsContent] = await Promise.all([
+            fs.readFile(basePath, "utf-8"),
+            fs.readFile(oursPath, "utf-8"),
+            fs.readFile(theirsPath, "utf-8"),
+        ]);
+        // Parse all three versions
+        let base;
+        let ours;
+        let theirs;
+        try {
+            base = parseYaml(baseContent);
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `Failed to parse base: ${err instanceof Error ? err.message : String(err)}`,
+                failedFile: "base",
+            };
+        }
+        try {
+            ours = parseYaml(oursContent);
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `Failed to parse ours: ${err instanceof Error ? err.message : String(err)}`,
+                failedFile: "ours",
+            };
+        }
+        try {
+            theirs = parseYaml(theirsContent);
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `Failed to parse theirs: ${err instanceof Error ? err.message : String(err)}`,
+                failedFile: "theirs",
+            };
+        }
+        return {
+            success: true,
+            versions: { base, ours, theirs },
+        };
+    }
+    catch (err) {
+        // File read error
+        return {
+            success: false,
+            error: `Failed to read files: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+//# sourceMappingURL=parse.js.map

package/dist/merge/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/merge/parse.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAG9C;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAgB,EAChB,QAAgB,EAChB,UAAkB;IAElB,IAAI,CAAC;QACH,uBAAuB;QACvB,MAAM,CAAC,WAAW,EAAE,WAAW,EAAE,aAAa,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAClE,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;YAC9B,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;YAC9B,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;SACjC,CAAC,CAAC;QAEH,2BAA2B;QAC3B,IAAI,IAAa,CAAC;QAClB,IAAI,IAAa,CAAC;QAClB,IAAI,MAAe,CAAC;QAEpB,IAAI,CAAC;YACH,IAAI,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,yBAAyB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;gBAClF,UAAU,EAAE,MAAM;aACnB,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,IAAI,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,yBAAyB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;gBAClF,UAAU,EAAE,MAAM;aACnB,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,MAAM,GAAG,SAAS,CAAC,aAAa,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,2BAA2B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;gBACpF,UAAU,EAAE,QAAQ;aACrB,CAAC;QACJ,CAAC;QAED,OAAO;YACL,OAAO,EAAE,IAAI;YACb,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE;SACjC,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,kBAAkB;QAClB,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,yBAAyB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;SACnF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/merge/resolve.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Conflict resolution for semantic YAML merge.
+ *
+ * Handles interactive prompts for conflicts and formatting
+ * conflicts as YAML comments in non-interactive mode.
+ */
+import type { ConflictInfo } from "./types.js";
+import * as readline from "node:readline/promises";
+/**
+ * Resolution choice for a conflict
+ */
+export type ResolutionChoice = "ours" | "theirs" | "skip";
+/**
+ * Result of resolving a single conflict
+ */
+export interface ConflictResolution {
+    /** The conflict that was resolved */
+    conflict: ConflictInfo;
+    /** The choice made */
+    choice: ResolutionChoice;
+    /** The resolved value (undefined if skipped) */
+    value?: unknown;
+}
+/**
+ * AC: @yaml-merge-driver ac-4
+ * Prompt user interactively to resolve a scalar field conflict.
+ *
+ * @param conflict The conflict to resolve
+ * @param createInterface Optional readline factory for testing
+ * @returns The resolution choice and value
+ */
+export declare function promptScalarConflict(conflict: ConflictInfo, createInterface?: typeof readline.createInterface): Promise<ConflictResolution>;
+/**
+ * AC: @yaml-merge-driver ac-8
+ * Prompt user to choose between deletion and keeping modified version.
+ *
+ * @param conflict The delete-modify conflict to resolve
+ * @param createInterface Optional readline factory for testing
+ * @returns The resolution choice
+ */
+export declare function promptDeleteModifyConflict(conflict: ConflictInfo, createInterface?: typeof readline.createInterface): Promise<ConflictResolution>;
+/**
+ * Resolve multiple conflicts interactively.
+ *
+ * @param conflicts Array of conflicts to resolve
+ * @returns Array of resolutions
+ */
+export declare function resolveConflictsInteractive(conflicts: ConflictInfo[]): Promise<ConflictResolution[]>;
+/**
+ * AC: @yaml-merge-driver ac-10
+ * Format a conflict as a YAML comment for non-interactive mode.
+ *
+ * Example output:
+ * ```yaml
+ * # CONFLICT: Field "title" modified with different values in both branches
+ * # Path: tasks[0].title
+ * # Ours: "Fix authentication bug"
+ * # Theirs: "Fix auth issue"
+ * title: "Fix authentication bug"  # Using ours
+ * ```
+ *
+ * @param conflict The conflict to format
+ * @returns YAML comment lines
+ */
+export declare function formatConflictComment(conflict: ConflictInfo): string[];
+//# sourceMappingURL=resolve.d.ts.map

package/dist/merge/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/merge/resolve.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,QAAQ,MAAM,wBAAwB,CAAC;AAGnD;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,QAAQ,EAAE,YAAY,CAAC;IACvB,sBAAsB;IACtB,MAAM,EAAE,gBAAgB,CAAC;IACzB,gDAAgD;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,YAAY,EACtB,eAAe,CAAC,EAAE,OAAO,QAAQ,CAAC,eAAe,GAChD,OAAO,CAAC,kBAAkB,CAAC,CAoC7B;AAED;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,YAAY,EACtB,eAAe,CAAC,EAAE,OAAO,QAAQ,CAAC,eAAe,GAChD,OAAO,CAAC,kBAAkB,CAAC,CA6C7B;AAED;;;;;GAKG;AACH,wBAAsB,2BAA2B,CAC/C,SAAS,EAAE,YAAY,EAAE,GACxB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAuB/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,EAAE,CAetE"}

package/dist/merge/resolve.js

@@ -0,0 +1,189 @@
+/**
+ * Conflict resolution for semantic YAML merge.
+ *
+ * Handles interactive prompts for conflicts and formatting
+ * conflicts as YAML comments in non-interactive mode.
+ */
+import * as readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+/**
+ * AC: @yaml-merge-driver ac-4
+ * Prompt user interactively to resolve a scalar field conflict.
+ *
+ * @param conflict The conflict to resolve
+ * @param createInterface Optional readline factory for testing
+ * @returns The resolution choice and value
+ */
+export async function promptScalarConflict(conflict, createInterface) {
+    const factory = createInterface || readline.createInterface;
+    const rl = factory({ input, output });
+    try {
+        console.log(`\n${conflict.description}`);
+        console.log(`Path: ${conflict.path}`);
+        console.log(`  [1] Ours:   ${formatValue(conflict.oursValue)}`);
+        console.log(`  [2] Theirs: ${formatValue(conflict.theirsValue)}`);
+        console.log(`  [3] Skip (leave unresolved)`);
+        const answer = await rl.question("\nChoose [1/2/3]: ");
+        switch (answer.trim()) {
+            case "1":
+                return {
+                    conflict,
+                    choice: "ours",
+                    value: conflict.oursValue,
+                };
+            case "2":
+                return {
+                    conflict,
+                    choice: "theirs",
+                    value: conflict.theirsValue,
+                };
+            case "3":
+            default:
+                return {
+                    conflict,
+                    choice: "skip",
+                };
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * AC: @yaml-merge-driver ac-8
+ * Prompt user to choose between deletion and keeping modified version.
+ *
+ * @param conflict The delete-modify conflict to resolve
+ * @param createInterface Optional readline factory for testing
+ * @returns The resolution choice
+ */
+export async function promptDeleteModifyConflict(conflict, createInterface) {
+    const factory = createInterface || readline.createInterface;
+    const rl = factory({ input, output });
+    try {
+        console.log(`\n${conflict.description}`);
+        console.log(`Path: ${conflict.path}`);
+        // Determine which side deleted
+        const deletedInOurs = conflict.oursValue === undefined;
+        if (deletedInOurs) {
+            console.log(`  [1] Delete (ours deleted this)`);
+            console.log(`  [2] Keep modified version: ${formatValue(conflict.theirsValue)}`);
+        }
+        else {
+            console.log(`  [1] Keep modified version: ${formatValue(conflict.oursValue)}`);
+            console.log(`  [2] Delete (theirs deleted this)`);
+        }
+        console.log(`  [3] Skip (leave unresolved)`);
+        const answer = await rl.question("\nChoose [1/2/3]: ");
+        switch (answer.trim()) {
+            case "1":
+                return {
+                    conflict,
+                    choice: "ours",
+                    value: deletedInOurs ? undefined : conflict.oursValue,
+                };
+            case "2":
+                return {
+                    conflict,
+                    choice: "theirs",
+                    value: deletedInOurs ? conflict.theirsValue : undefined,
+                };
+            case "3":
+            default:
+                return {
+                    conflict,
+                    choice: "skip",
+                };
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Resolve multiple conflicts interactively.
+ *
+ * @param conflicts Array of conflicts to resolve
+ * @returns Array of resolutions
+ */
+export async function resolveConflictsInteractive(conflicts) {
+    const resolutions = [];
+    for (const conflict of conflicts) {
+        let resolution;
+        switch (conflict.type) {
+            case "scalar_field":
+                resolution = await promptScalarConflict(conflict);
+                break;
+            case "delete_modify":
+                resolution = await promptDeleteModifyConflict(conflict);
+                break;
+            case "nested_conflict":
+                // Nested conflicts should have been flattened to scalar conflicts
+                resolution = await promptScalarConflict(conflict);
+                break;
+        }
+        resolutions.push(resolution);
+    }
+    return resolutions;
+}
+/**
+ * AC: @yaml-merge-driver ac-10
+ * Format a conflict as a YAML comment for non-interactive mode.
+ *
+ * Example output:
+ * ```yaml
+ * # CONFLICT: Field "title" modified with different values in both branches
+ * # Path: tasks[0].title
+ * # Ours: "Fix authentication bug"
+ * # Theirs: "Fix auth issue"
+ * title: "Fix authentication bug"  # Using ours
+ * ```
+ *
+ * @param conflict The conflict to format
+ * @returns YAML comment lines
+ */
+export function formatConflictComment(conflict) {
+    const lines = [];
+    lines.push(`# CONFLICT: ${conflict.description}`);
+    lines.push(`# Path: ${conflict.path}`);
+    if (conflict.ulid) {
+        lines.push(`# ULID: ${conflict.ulid}`);
+    }
+    lines.push(`# Ours:   ${formatValue(conflict.oursValue)}`);
+    lines.push(`# Theirs: ${formatValue(conflict.theirsValue)}`);
+    lines.push(`# Resolution: Using ours (run merge interactively to resolve)`);
+    return lines;
+}
+/**
+ * Format a value for display in prompts or comments.
+ * Handles primitives, arrays, and objects concisely.
+ */
+function formatValue(value) {
+    if (value === undefined)
+        return "<deleted>";
+    if (value === null)
+        return "null";
+    if (typeof value === "string")
+        return `"${value}"`;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return "[]";
+        if (value.length <= 3) {
+            return `[${value.map(formatValue).join(", ")}]`;
+        }
+        return `[${value.length} items]`;
+    }
+    if (typeof value === "object") {
+        const keys = Object.keys(value);
+        if (keys.length === 0)
+            return "{}";
+        if (keys.length === 1) {
+            return `{${keys[0]}}`;
+        }
+        return `{${keys.length} fields}`;
+    }
+    return String(value);
+}
+//# sourceMappingURL=resolve.js.map

package/dist/merge/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/merge/resolve.ts"],"names":[],"mappings":"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"}

package/dist/merge/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Types for semantic YAML merge driver.
+ *
+ * The merge driver parses kspec YAML files and merges them semantically,
+ * understanding the structure of tasks, items, and other entities.
+ */
+/**
+ * Result of a merge operation
+ */
+export interface MergeResult {
+    /** The merged YAML content */
+    content: string;
+    /** Whether conflicts were detected */
+    hasConflicts: boolean;
+    /** Conflict information (empty if no conflicts) */
+    conflicts: ConflictInfo[];
+    /** Whether parsing failed (triggers fallback) */
+    parseFailed: boolean;
+    /** Error message if parse failed */
+    parseError?: string;
+}
+/**
+ * Information about a conflict that requires resolution
+ */
+export interface ConflictInfo {
+    /** Type of conflict */
+    type: ConflictType;
+    /** Path to the conflicting field (e.g., "tasks[0].title") */
+    path: string;
+    /** ULID of the item with conflict (if applicable) */
+    ulid?: string;
+    /** Value from "ours" branch */
+    oursValue: unknown;
+    /** Value from "theirs" branch */
+    theirsValue: unknown;
+    /** Description of the conflict */
+    description: string;
+}
+/**
+ * Types of conflicts that can occur during merge
+ */
+export type ConflictType = "scalar_field" | "delete_modify" | "nested_conflict";
+/**
+ * Options for merge operations
+ */
+export interface MergeOptions {
+    /** Whether to run in non-interactive mode (no prompts) */
+    nonInteractive?: boolean;
+    /** Output file path for merged result */
+    outputPath: string;
+    /** Path to "base" version (common ancestor) */
+    basePath: string;
+    /** Path to "ours" version (current branch) */
+    oursPath: string;
+    /** Path to "theirs" version (incoming branch) */
+    theirsPath: string;
+}
+/**
+ * Parsed versions of a file for merging
+ */
+export interface ParsedVersions {
+    /** Common ancestor version */
+    base: unknown;
+    /** Current branch version */
+    ours: unknown;
+    /** Incoming branch version */
+    theirs: unknown;
+}
+/**
+ * Result of parsing all three versions
+ */
+export interface ParseResult {
+    /** Whether parsing succeeded */
+    success: boolean;
+    /** Parsed versions (undefined if parse failed) */
+    versions?: ParsedVersions;
+    /** Error message if parse failed */
+    error?: string;
+    /** Which file failed to parse (if applicable) */
+    failedFile?: "base" | "ours" | "theirs";
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/merge/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/merge/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,YAAY,EAAE,OAAO,CAAC;IACtB,mDAAmD;IACnD,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,iDAAiD;IACjD,WAAW,EAAE,OAAO,CAAC;IACrB,oCAAoC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uBAAuB;IACvB,IAAI,EAAE,YAAY,CAAC;IACnB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,SAAS,EAAE,OAAO,CAAC;IACnB,iCAAiC;IACjC,WAAW,EAAE,OAAO,CAAC;IACrB,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,cAAc,GACd,eAAe,GACf,iBAAiB,CAAC;AAEtB;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,IAAI,EAAE,OAAO,CAAC;IACd,6BAA6B;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,8BAA8B;IAC9B,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;CACzC"}

package/dist/merge/types.js

@@ -0,0 +1,8 @@
+/**
+ * Types for semantic YAML merge driver.
+ *
+ * The merge driver parses kspec YAML files and merges them semantically,
+ * understanding the structure of tasks, items, and other entities.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/merge/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/merge/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/parser/agent-data-sections.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Auto-generated data sections for agent instructions.
+ *
+ * Library functions that generate markdown sections from kspec meta data:
+ * skills table, conventions summary, and workflows summary.
+ *
+ * AC: @agent-data-sections ac-1 - generateSkillsTable returns markdown table
+ * AC: @agent-data-sections ac-2 - generateConventionsSummary returns markdown section
+ * AC: @agent-data-sections ac-3 - generateWorkflowsSummary returns markdown section
+ */
+import type { LoadedConvention, LoadedSkill, LoadedWorkflow } from "./meta.js";
+/**
+ * Generate a markdown table for skills.
+ *
+ * AC: @agent-data-sections ac-1
+ * Given: skills in meta with varying names and descriptions
+ * When: generateSkillsTable is called
+ * Then: a markdown table is returned with columns for skill name, description, and invocation
+ *
+ * @param skills - Array of loaded skills from meta
+ * @returns Markdown table string with columns: name (as description), description, invocation
+ */
+export declare function generateSkillsTable(skills: LoadedSkill[]): string;
+/**
+ * Intro paragraph for the conventions section.
+ * Extracted as a constant for future configurability.
+ */
+export declare const CONVENTIONS_INTRO = "These are the project's agreed-upon conventions. Follow them in all contributions to maintain consistency.";
+/**
+ * Generate a markdown section summarizing conventions by domain.
+ *
+ * AC: @agent-data-sections ac-2
+ * Given: conventions in meta with rules arrays
+ * When: generateConventionsSummary is called
+ * Then: a markdown section is returned listing each domain with its rules
+ *
+ * @param conventions - Array of loaded conventions from meta
+ * @returns Markdown section string with domain headers, rules as list items, and examples
+ */
+export declare function generateConventionsSummary(conventions: LoadedConvention[]): string;
+/**
+ * Generate a markdown section summarizing workflows.
+ *
+ * AC: @agent-data-sections ac-3
+ * Given: workflows in meta with triggers and descriptions
+ * When: generateWorkflowsSummary is called
+ * Then: a markdown section is returned listing each workflow with its trigger
+ *
+ * @param workflows - Array of loaded workflows from meta
+ * @returns Markdown section string with workflow list including triggers
+ */
+export declare function generateWorkflowsSummary(workflows: LoadedWorkflow[]): string;
+//# sourceMappingURL=agent-data-sections.d.ts.map

package/dist/parser/agent-data-sections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-data-sections.d.ts","sourceRoot":"","sources":["../../src/parser/agent-data-sections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,CA4BjE;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,+GACgF,CAAC;AAE/G;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,gBAAgB,EAAE,GAC9B,MAAM,CAsCR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,MAAM,CAiB5E"}

package/dist/parser/agent-data-sections.js

@@ -0,0 +1,118 @@
+/**
+ * Auto-generated data sections for agent instructions.
+ *
+ * Library functions that generate markdown sections from kspec meta data:
+ * skills table, conventions summary, and workflows summary.
+ *
+ * AC: @agent-data-sections ac-1 - generateSkillsTable returns markdown table
+ * AC: @agent-data-sections ac-2 - generateConventionsSummary returns markdown section
+ * AC: @agent-data-sections ac-3 - generateWorkflowsSummary returns markdown section
+ */
+/**
+ * Generate a markdown table for skills.
+ *
+ * AC: @agent-data-sections ac-1
+ * Given: skills in meta with varying names and descriptions
+ * When: generateSkillsTable is called
+ * Then: a markdown table is returned with columns for skill name, description, and invocation
+ *
+ * @param skills - Array of loaded skills from meta
+ * @returns Markdown table string with columns: name (as description), description, invocation
+ */
+export function generateSkillsTable(skills) {
+    if (skills.length === 0) {
+        return "";
+    }
+    const lines = [
+        "## Finding Information",
+        "",
+        "Use skills and CLI help for detailed documentation:",
+        "",
+        "| Need | Where to look |",
+        "|------|---------------|",
+    ];
+    for (const skill of skills) {
+        const description = skill.description || skill.name;
+        // Core skills in plugin system are invoked as /kspec:<id>, project skills as /<id>
+        const invocation = skill.origin === "core" ? `kspec:${skill.id}` : skill.id;
+        lines.push(`| ${description} | \`/${invocation}\` skill |`);
+    }
+    lines.push("");
+    lines.push("Skills inject their full documentation when invoked — you don't need to memorize their contents.");
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Intro paragraph for the conventions section.
+ * Extracted as a constant for future configurability.
+ */
+export const CONVENTIONS_INTRO = "These are the project's agreed-upon conventions. Follow them in all contributions to maintain consistency.";
+/**
+ * Generate a markdown section summarizing conventions by domain.
+ *
+ * AC: @agent-data-sections ac-2
+ * Given: conventions in meta with rules arrays
+ * When: generateConventionsSummary is called
+ * Then: a markdown section is returned listing each domain with its rules
+ *
+ * @param conventions - Array of loaded conventions from meta
+ * @returns Markdown section string with domain headers, rules as list items, and examples
+ */
+export function generateConventionsSummary(conventions) {
+    if (conventions.length === 0) {
+        return "";
+    }
+    const lines = ["## Conventions", "", CONVENTIONS_INTRO, ""];
+    for (const convention of conventions) {
+        lines.push(`### ${convention.domain}`);
+        lines.push("");
+        for (const rule of convention.rules) {
+            lines.push(`- ${rule}`);
+        }
+        // Render examples when present
+        if (convention.examples && convention.examples.length > 0) {
+            lines.push("");
+            lines.push("**Examples:**");
+            for (const example of convention.examples) {
+                const combinedLength = example.good.length + example.bad.length;
+                if (combinedLength > 80) {
+                    // Long format: quoted, separate lines
+                    lines.push(`- Good: "${example.good}"`);
+                    lines.push(`- Bad: "${example.bad}"`);
+                }
+                else {
+                    // Short format: inline code with em-dash
+                    lines.push(`- Good: \`${example.good}\` — Bad: \`${example.bad}\``);
+                }
+            }
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Generate a markdown section summarizing workflows.
+ *
+ * AC: @agent-data-sections ac-3
+ * Given: workflows in meta with triggers and descriptions
+ * When: generateWorkflowsSummary is called
+ * Then: a markdown section is returned listing each workflow with its trigger
+ *
+ * @param workflows - Array of loaded workflows from meta
+ * @returns Markdown section string with workflow list including triggers
+ */
+export function generateWorkflowsSummary(workflows) {
+    if (workflows.length === 0) {
+        return "";
+    }
+    const lines = ["## Workflows", "", "Available workflows:", ""];
+    for (const workflow of workflows) {
+        const description = workflow.description || workflow.trigger;
+        lines.push(`- **${workflow.id}**: ${description}`);
+    }
+    lines.push("");
+    lines.push("Use `kspec workflow start @workflow-id` to start a workflow.");
+    lines.push("");
+    return lines.join("\n");
+}
+//# sourceMappingURL=agent-data-sections.js.map

package/dist/parser/agent-data-sections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-data-sections.js","sourceRoot":"","sources":["../../src/parser/agent-data-sections.ts"],"names":[],"mappings":"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"}

package/dist/parser/alignment.d.ts

@@ -4,9 +4,9 @@
  * Provides bidirectional mapping from spec items to implementing tasks,
  * and detects alignment issues like orphaned specs or stale implementation status.
  */
-import type { LoadedSpecItem, LoadedTask, KspecContext } from './yaml.js';
-import type { ReferenceIndex } from './refs.js';
-import type { ImplementationStatus } from '../schema/index.js';
+import type { ImplementationStatus } from "../schema/index.js";
+import type { ReferenceIndex } from "./refs.js";
+import type { KspecContext, LoadedSpecItem, LoadedTask } from "./yaml.js";
 /**
  * Summary of a spec item's implementation status based on linked tasks
  */
@@ -31,7 +31,7 @@ export interface LinkedTaskSummary {
  * Alignment warning
  */
 export interface AlignmentWarning {
-    type: 'orphaned_spec' | 'status_mismatch' | 'stale_implementation';
+    type: "orphaned_spec" | "status_mismatch" | "stale_implementation";
     specUlid?: string;
     specTitle?: string;
     taskUlid?: string;