@cleocode/core 2026.4.9 → 2026.4.11

package/dist/skills/injection/subagent.js

@@ -0,0 +1,195 @@
+/**
+ * Subagent protocol injection.
+ * Ports lib/skills/subagent-inject.sh.
+ *
+ * Guarantees protocol compliance for all subagent spawns by automatically
+ * injecting the RFC 2119 protocol base from skills/_shared/subagent-protocol-base.md.
+ *
+ * Injection pattern:
+ *   [SKILL CONTENT]
+ *   ---
+ *   ## SUBAGENT PROTOCOL (RFC 2119)
+ *   [Content from subagent-protocol-base.md with tokens resolved]
+ *   ---
+ *   [TASK CONTEXT]
+ *
+ * @epic T4454
+ * @task T4521
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ExitCode } from '@cleocode/contracts';
+import { CleoError } from '../../errors.js';
+import { getProjectRoot } from '../../paths.js';
+import { findSkill } from '../discovery.js';
+import { injectTokens } from './token.js';
+// ============================================================================
+// Protocol Base
+// ============================================================================
+/**
+ * Get the path to the subagent protocol base file.
+ */
+function getProtocolBasePath(cwd) {
+    return join(getProjectRoot(cwd), 'skills', '_shared', 'subagent-protocol-base.md');
+}
+/**
+ * Load the subagent protocol base content.
+ * @task T4521
+ */
+export function loadProtocolBase(cwd) {
+    const path = getProtocolBasePath(cwd);
+    if (!existsSync(path))
+        return null;
+    return readFileSync(path, 'utf-8');
+}
+// ============================================================================
+// Task Context
+// ============================================================================
+/**
+ * Build task context block for injection into a subagent prompt.
+ * @task T4521
+ */
+export async function buildTaskContext(taskId, cwd) {
+    const { getAccessor } = await import('../../store/data-accessor.js');
+    const acc = await getAccessor(cwd);
+    const task = await acc.loadSingleTask(taskId);
+    if (!task) {
+        return `## Task Context\n\n**Task**: ${taskId}\n**Status**: not found\n`;
+    }
+    const lines = [
+        '## Task Context',
+        '',
+        `**Task**: ${task.id}`,
+        `**Title**: ${task.title}`,
+        `**Status**: ${task.status}`,
+    ];
+    if (task.description) {
+        lines.push(`**Description**: ${task.description}`);
+    }
+    if (task.parentId) {
+        lines.push(`**Epic**: ${task.parentId}`);
+    }
+    if (task.depends?.length) {
+        lines.push(`**Dependencies**: ${task.depends.join(', ')}`);
+    }
+    if (task.labels?.length) {
+        lines.push(`**Labels**: ${task.labels.join(', ')}`);
+    }
+    if (task.priority) {
+        lines.push(`**Priority**: ${task.priority}`);
+    }
+    return lines.join('\n');
+}
+// ============================================================================
+// Tier Filtering
+// ============================================================================
+/**
+ * Filter protocol content by MVI tier.
+ * Extracts sections based on <!-- TIER:X --> markers.
+ * - tier 0: header + minimal only + footer
+ * - tier 1: header + minimal + standard + footer
+ * - tier 2: header + all tiers + footer (full content)
+ *
+ * Header = content before first TIER marker.
+ * Footer = content after last /TIER marker.
+ *
+ * @task T5155
+ */
+export function filterProtocolByTier(content, tier) {
+    // If no tier markers, return content as-is
+    if (!content.includes('<!-- TIER:')) {
+        return content;
+    }
+    const tierNames = {
+        0: ['minimal'],
+        1: ['minimal', 'standard'],
+        2: ['minimal', 'standard', 'orchestrator'],
+    };
+    const allowedTiers = tierNames[tier];
+    // Extract header (before first TIER marker)
+    const firstTierMatch = content.match(/<!-- TIER:\w+ -->/);
+    const header = firstTierMatch ? content.slice(0, firstTierMatch.index).trimEnd() : '';
+    // Extract footer (after last /TIER marker)
+    const lastCloseTierRegex = /<!-- \/TIER:\w+ -->/g;
+    let lastMatch = null;
+    for (const m of content.matchAll(lastCloseTierRegex)) {
+        lastMatch = m;
+    }
+    const footer = lastMatch ? content.slice(lastMatch.index + lastMatch[0].length).trimStart() : '';
+    // Extract each allowed tier block
+    const tierBlocks = [];
+    for (const tierName of allowedTiers) {
+        const openTag = `<!-- TIER:${tierName} -->`;
+        const closeTag = `<!-- /TIER:${tierName} -->`;
+        const openIdx = content.indexOf(openTag);
+        const closeIdx = content.indexOf(closeTag);
+        if (openIdx !== -1 && closeIdx !== -1) {
+            const blockContent = content.slice(openIdx + openTag.length, closeIdx).trim();
+            tierBlocks.push(blockContent);
+        }
+    }
+    // Compose: header + tier blocks + footer
+    const parts = [header, ...tierBlocks, footer].filter((p) => p.length > 0);
+    return parts.join('\n\n');
+}
+// ============================================================================
+// Injection
+// ============================================================================
+/**
+ * Inject the subagent protocol into skill content.
+ * Composes: skill content + protocol base + task context.
+ * @task T4521
+ */
+export async function injectProtocol(skillContent, taskId, tokenValues, cwd, tier) {
+    const protocolBase = loadProtocolBase(cwd);
+    const taskContext = await buildTaskContext(taskId, cwd);
+    // Inject tokens into skill content
+    const resolvedSkill = injectTokens(skillContent, tokenValues);
+    // Compose the full prompt
+    const parts = [resolvedSkill];
+    if (protocolBase) {
+        // Apply tier filtering if specified
+        const filteredProtocol = tier !== undefined ? filterProtocolByTier(protocolBase, tier) : protocolBase;
+        const resolvedProtocol = injectTokens(filteredProtocol, tokenValues);
+        parts.push('\n---\n');
+        parts.push('## SUBAGENT PROTOCOL (RFC 2119)\n\n');
+        parts.push(resolvedProtocol);
+    }
+    parts.push('\n---\n');
+    parts.push(taskContext);
+    return parts.join('\n');
+}
+/**
+ * Full orchestrator spawn workflow (skill-based).
+ * High-level function that loads the skill, injects protocol, and returns the prompt.
+ * @task T4521
+ */
+export async function orchestratorSpawnSkill(taskId, skillName, tokenValues, cwd, tier) {
+    // Find the skill
+    const skill = findSkill(skillName, cwd);
+    if (!skill || !skill.content) {
+        throw new CleoError(ExitCode.NOT_FOUND, `Skill not found: ${skillName}`, {
+            fix: `Check skills directory for ${skillName}/SKILL.md`,
+        });
+    }
+    return injectProtocol(skill.content, taskId, tokenValues, cwd, tier);
+}
+/**
+ * Prepare standard token values for a task spawn.
+ * @task T4521
+ */
+export function prepareTokenValues(taskId, topicSlug, epicId, _cwd) {
+    const dateToday = new Date().toISOString().split('T')[0];
+    const values = {
+        TASK_ID: taskId,
+        DATE: dateToday,
+        TOPIC_SLUG: topicSlug,
+        RESEARCH_ID: `${topicSlug}-${dateToday}`,
+        TITLE: topicSlug.replace(/-/g, ' '),
+    };
+    if (epicId) {
+        values['EPIC_ID'] = epicId;
+    }
+    return values;
+}
+//# sourceMappingURL=subagent.js.map

package/dist/skills/injection/subagent.js.map

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

package/dist/skills/injection/token.js

@@ -0,0 +1,260 @@
+/**
+ * Token injection library for subagent templates.
+ * Ports lib/skills/token-inject.sh.
+ *
+ * Implements strict token replacement with validation to prevent hallucination.
+ * All tokens use {{TOKEN_NAME}} format.
+ *
+ * @epic T4454
+ * @task T4521
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getProjectRoot } from '../../paths.js';
+// ============================================================================
+// Required Tokens
+// ============================================================================
+const REQUIRED_TOKENS = ['TASK_ID', 'DATE', 'TOPIC_SLUG'];
+/** Validation patterns for required tokens. */
+const TOKEN_PATTERNS = {
+    TASK_ID: /^T\d+$/,
+    DATE: /^\d{4}-\d{2}-\d{2}$/,
+    TOPIC_SLUG: /^[a-zA-Z0-9_-]+$/,
+    EPIC_ID: /^T\d+$/,
+    PARENT_ID: /^T\d+$/,
+    SESSION_ID: /^session[-_]\d{8}[-_]\d{6}[-_][a-f0-9]+$/,
+};
+// ============================================================================
+// Default Values
+// ============================================================================
+/** CLEO command defaults. */
+const CLEO_DEFAULTS = {
+    TASK_SHOW_CMD: 'cleo show',
+    TASK_START_CMD: 'cleo start',
+    TASK_CURRENT_CMD: 'cleo current',
+    TASK_COMPLETE_CMD: 'cleo complete',
+    TASK_LINK_CMD: 'cleo research link',
+    TASK_LIST_CMD: 'cleo list',
+    TASK_FIND_CMD: 'cleo find',
+    TASK_ADD_CMD: 'cleo add',
+    TASK_EXISTS_CMD: 'cleo exists',
+    TASK_PHASE_CMD: 'cleo phase show',
+    TASK_TREE_CMD: 'cleo list --tree',
+    SESSION_LIST_CMD: 'cleo session list',
+    SESSION_START_CMD: 'cleo session start',
+    SESSION_END_CMD: 'cleo session end',
+    SESSION_GC_CMD: 'cleo session gc',
+    RESEARCH_LIST_CMD: 'cleo research list',
+    RESEARCH_SHOW_CMD: 'cleo research show',
+    RESEARCH_PENDING_CMD: 'cleo research pending',
+    RESEARCH_INJECT_CMD: 'cleo research inject',
+    DASH_CMD: 'cleo dash',
+    OUTPUT_DIR: '.cleo/agent-outputs',
+    MANIFEST_PATH: '.cleo/agent-outputs/MANIFEST.jsonl',
+};
+// ============================================================================
+// Token Loading
+// ============================================================================
+/**
+ * Load token definitions from placeholders.json.
+ * @task T4521
+ */
+export function loadPlaceholders(cwd) {
+    const projectRoot = getProjectRoot(cwd);
+    const path = join(projectRoot, 'skills', '_shared', 'placeholders.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build the full default values map (merging placeholders.json with hardcoded defaults).
+ * @task T4521
+ */
+export function buildDefaults(cwd) {
+    const defaults = { ...CLEO_DEFAULTS };
+    const config = loadPlaceholders(cwd);
+    if (config) {
+        // Merge defaults from all sections
+        const sections = [
+            config.context,
+            config.taskCommands?.tokens,
+            config.taskContext?.tokens,
+            config.skillSpecific?.tokens,
+        ];
+        for (const section of sections) {
+            if (!Array.isArray(section))
+                continue;
+            for (const def of section) {
+                if (def.default !== undefined && def.default !== '') {
+                    defaults[def.token] = def.default;
+                }
+            }
+        }
+    }
+    return defaults;
+}
+// ============================================================================
+// Token Validation
+// ============================================================================
+/**
+ * Validate a single token value against its pattern.
+ * @task T4521
+ */
+export function validateTokenValue(token, value) {
+    const pattern = TOKEN_PATTERNS[token];
+    if (!pattern)
+        return { valid: true }; // No pattern = always valid
+    if (!value) {
+        return { valid: false, error: `Token ${token} is empty` };
+    }
+    if (!pattern.test(value)) {
+        return {
+            valid: false,
+            error: `Token ${token} value "${value}" does not match pattern ${pattern}`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validate all required tokens are present and valid.
+ * @task T4521
+ */
+export function validateRequired(values) {
+    const missing = [];
+    const invalid = [];
+    for (const token of REQUIRED_TOKENS) {
+        const value = values[token];
+        if (!value) {
+            missing.push(token);
+            continue;
+        }
+        const result = validateTokenValue(token, value);
+        if (!result.valid) {
+            invalid.push({ token, error: result.error });
+        }
+    }
+    return {
+        valid: missing.length === 0 && invalid.length === 0,
+        missing,
+        invalid,
+    };
+}
+/**
+ * Validate all tokens in a values map (required + optional).
+ * @task T4521
+ */
+export function validateAllTokens(values) {
+    const errors = [];
+    for (const [token, value] of Object.entries(values)) {
+        if (!value)
+            continue; // Empty optional tokens are ok
+        const result = validateTokenValue(token, value);
+        if (!result.valid) {
+            errors.push({ token, error: result.error });
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+// ============================================================================
+// Token Injection
+// ============================================================================
+/**
+ * Inject token values into a template string.
+ * Replaces all {{TOKEN_NAME}} patterns with corresponding values.
+ * Unresolved tokens are left as-is (for debugging).
+ * @task T4521
+ */
+export function injectTokens(template, values) {
+    // Merge with defaults (explicit values override defaults)
+    const merged = { ...CLEO_DEFAULTS, ...values };
+    return template.replace(/\{\{(\w+)\}\}/g, (match, token) => {
+        const value = merged[token];
+        if (value !== undefined && value !== '') {
+            return value;
+        }
+        // Return the token as-is if not resolved (helps debugging)
+        return match;
+    });
+}
+/**
+ * Check if a template has unresolved tokens after injection.
+ * @task T4521
+ */
+export function hasUnresolvedTokens(content) {
+    const matches = content.match(/\{\{(\w+)\}\}/g) ?? [];
+    return [...new Set(matches.map((m) => m.replace(/\{\{|\}\}/g, '')))];
+}
+/**
+ * Load a skill template and inject tokens.
+ * @task T4521
+ */
+export function loadAndInject(templatePath, values) {
+    if (!existsSync(templatePath)) {
+        throw new Error(`Template not found: ${templatePath}`);
+    }
+    const template = readFileSync(templatePath, 'utf-8');
+    const content = injectTokens(template, values);
+    const unresolvedTokens = hasUnresolvedTokens(content);
+    return { content, unresolvedTokens };
+}
+// ============================================================================
+// Full Context Resolution
+// ============================================================================
+/**
+ * Build a complete TokenValues map from a task, resolving all standard tokens.
+ * Ports ti_set_full_context from lib/skills/token-inject.sh.
+ *
+ * This is the primary entry point for orchestrators to prepare token values
+ * before spawning subagents. It populates: TASK_ID, DATE, TOPIC_SLUG, EPIC_ID,
+ * TITLE, TASK_TITLE, TASK_DESCRIPTION, TOPICS_JSON, DEPENDS_LIST, RESEARCH_ID,
+ * OUTPUT_DIR, MANIFEST_PATH, and all command defaults.
+ *
+ * @task T4712
+ * @epic T4663
+ */
+export function setFullContext(task, options) {
+    const dateToday = options?.date ?? new Date().toISOString().split('T')[0];
+    const topicSlug = options?.topicSlug ??
+        (task.title
+            .replace(/[^a-zA-Z0-9]+/g, '-')
+            .toLowerCase()
+            .replace(/^-|-$/g, '') ||
+            `task-${task.id}`);
+    const outputDir = options?.outputDir ?? '.cleo/agent-outputs';
+    const manifestPath = options?.manifestPath ?? `${outputDir}/MANIFEST.jsonl`;
+    const values = {
+        // Required tokens
+        TASK_ID: task.id,
+        DATE: dateToday,
+        TOPIC_SLUG: topicSlug,
+        // Context tokens
+        EPIC_ID: task.parentId ?? '',
+        PARENT_ID: task.parentId ?? '',
+        TITLE: task.title,
+        TASK_TITLE: task.title,
+        TASK_NAME: task.title,
+        TASK_DESCRIPTION: task.description ?? '',
+        RESEARCH_ID: `${topicSlug}-${dateToday}`,
+        // Output tokens
+        OUTPUT_DIR: outputDir,
+        MANIFEST_PATH: manifestPath,
+        MANIFEST_ID: `${topicSlug}-${dateToday}`,
+        MANIFEST_FILE: `${dateToday}_${topicSlug}.md`,
+        MANIFEST_TITLE: task.title,
+    };
+    // Task-specific tokens
+    if (task.labels?.length) {
+        values['TOPICS_JSON'] = JSON.stringify(task.labels);
+    }
+    if (task.depends?.length) {
+        values['DEPENDS_LIST'] = task.depends.join(', ');
+    }
+    // Merge with CLEO command defaults
+    return { ...buildDefaults(), ...values };
+}
+//# sourceMappingURL=token.js.map

package/dist/skills/injection/token.js.map

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

package/dist/skills/install.js

@@ -0,0 +1,40 @@
+/**
+ * Skills installation functions.
+ * Delegates installation to CAAMP.
+ *
+ * @epic T4454
+ * @task T4521
+ */
+import { installSkill as caampInstallSkill, getInstalledProviders } from '@cleocode/caamp';
+/**
+ * Install a single skill via CAAMP.
+ */
+export async function installSkill(skillName, projectDir) {
+    try {
+        const providers = getInstalledProviders();
+        if (providers.length === 0) {
+            return { installed: false, path: '', error: 'No target providers found' };
+        }
+        const source = `library:${skillName}`;
+        const result = await caampInstallSkill(source, skillName, providers, true, projectDir);
+        if (!result.success) {
+            return {
+                installed: false,
+                path: result.canonicalPath,
+                error: result.errors.join('; ') || 'Install failed',
+            };
+        }
+        return {
+            installed: true,
+            path: result.canonicalPath,
+        };
+    }
+    catch (err) {
+        return {
+            installed: false,
+            path: '',
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+//# sourceMappingURL=install.js.map

package/dist/skills/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/skills/install.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,IAAI,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE3F;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,SAAiB,EACjB,UAAmB;IAEnB,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,qBAAqB,EAAE,CAAC;QAC1C,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,2BAA2B,EAAE,CAAC;QAC5E,CAAC;QAED,MAAM,MAAM,GAAG,WAAW,SAAS,EAAE,CAAC;QACtC,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;QACvF,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO;gBACL,SAAS,EAAE,KAAK;gBAChB,IAAI,EAAE,MAAM,CAAC,aAAa;gBAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,gBAAgB;aACpD,CAAC;QACJ,CAAC;QAED,OAAO;YACL,SAAS,EAAE,IAAI;YACf,IAAI,EAAE,MAAM,CAAC,aAAa;SAC3B,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,SAAS,EAAE,KAAK;YAChB,IAAI,EAAE,EAAE;YACR,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACxD,CAAC;IACJ,CAAC;AACH,CAAC"}