@winspan/claude-forge 8.13.1 → 8.16.0

package/dist/agents/definition.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Agent definition types
+ *
+ * Agents are distinct from skills: agents are invocable units (called via
+ * Claude's Task tool with subagent_type) while skills are methodology
+ * recommendations injected as systemMessage.
+ */
+/**
+ * Agent category drives routing and UI grouping.
+ */
+export type AgentCategory = 'core' | 'pipeline' | 'specialist' | 'quality' | 'research' | 'documentation' | 'workflow' | 'supplementary';
+/**
+ * Source layer of an agent (resolution order: project > user > preset > builtin)
+ */
+export type AgentSource = 'builtin' | 'user' | 'project' | 'preset';
+export interface AgentDefinition {
+    /** Unique slug, used as subagent_type */
+    name: string;
+    /** One-line description, written to frontmatter */
+    description: string;
+    /** Category for routing/grouping */
+    category: AgentCategory;
+    /** Semver; bump on content change to allow `cf agents sync` */
+    version: string;
+    /** Claude Code tool allowlist (joined into frontmatter `tools` field) */
+    tools: string[];
+    /** Suggested model slug (sonnet/opus/haiku); optional */
+    model?: string;
+    /** Full markdown body that lands in ~/.claude/agents/<name>.md */
+    content: string;
+}
+/**
+ * Runtime record loaded by AgentRegistry (definition + source + filesystem path).
+ */
+export interface AgentRecord {
+    name: string;
+    description: string;
+    category: AgentCategory;
+    version: string;
+    tools: string[];
+    model?: string;
+    content: string;
+    source: AgentSource;
+    /** Absolute path if loaded from disk, '<builtin>' for embedded */
+    path: string;
+    /** Preset package name if source === 'preset' */
+    owner?: string;
+}
+/**
+ * Serialize agent to the markdown+frontmatter format Claude Code expects.
+ */
+export declare function renderAgentMarkdown(def: AgentDefinition): string;
+//# sourceMappingURL=definition.d.ts.map

package/dist/agents/definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/agents/definition.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,UAAU,GACV,YAAY,GACZ,SAAS,GACT,UAAU,GACV,eAAe,GACf,UAAU,GACV,eAAe,CAAC;AAEpB;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEpE,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,QAAQ,EAAE,aAAa,CAAC;IACxB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,WAAW,CAAC;IACpB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAWhE"}

package/dist/agents/definition.js

@@ -0,0 +1,24 @@
+/**
+ * Agent definition types
+ *
+ * Agents are distinct from skills: agents are invocable units (called via
+ * Claude's Task tool with subagent_type) while skills are methodology
+ * recommendations injected as systemMessage.
+ */
+/**
+ * Serialize agent to the markdown+frontmatter format Claude Code expects.
+ */
+export function renderAgentMarkdown(def) {
+    const fm = [
+        '---',
+        `name: ${def.name}`,
+        `description: ${JSON.stringify(def.description)}`,
+        `version: ${def.version}`,
+        `tools: ${def.tools.join(', ')}`,
+    ];
+    if (def.model)
+        fm.push(`model: ${def.model}`);
+    fm.push('---', '');
+    return fm.join('\n') + def.content.trimStart();
+}
+//# sourceMappingURL=definition.js.map

package/dist/agents/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../src/agents/definition.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAuDH;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAoB;IACtD,MAAM,EAAE,GAAa;QACnB,KAAK;QACL,SAAS,GAAG,CAAC,IAAI,EAAE;QACnB,gBAAgB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE;QACjD,YAAY,GAAG,CAAC,OAAO,EAAE;QACzB,UAAU,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;KACjC,CAAC;IACF,IAAI,GAAG,CAAC,KAAK;QAAE,EAAE,CAAC,IAAI,CAAC,UAAU,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;IAC9C,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACnB,OAAO,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;AACjD,CAAC"}

package/dist/agents/distributor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * AgentDistributor — writes official agents to ~/.claude/agents/ on `cf init`
+ * and updates via `cf agents sync`.
+ *
+ * Conflict policy (aligns with §8.5):
+ *   - Unmodified (hash matches last installed) → overwrite
+ *   - Modified by user → skip with warning, backup to ~/.claude-forge/backups/
+ *   - New file → write
+ */
+export interface InstallReport {
+    written: string[];
+    skipped: string[];
+    backedUp: string[];
+}
+export declare function installOfficialAgents(opts?: {
+    force?: boolean;
+}): InstallReport;
+/**
+ * Hash of a locally stored agent file, used by `cf agents list` to mark
+ * "modified by user" entries.
+ */
+export declare function localAgentHash(name: string): string | null;
+//# sourceMappingURL=distributor.d.ts.map

package/dist/agents/distributor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"distributor.d.ts","sourceRoot":"","sources":["../../src/agents/distributor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAcH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA4BD,wBAAgB,qBAAqB,CAAC,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,aAAa,CAwCnF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI1D"}

package/dist/agents/distributor.js

@@ -0,0 +1,85 @@
+/**
+ * AgentDistributor — writes official agents to ~/.claude/agents/ on `cf init`
+ * and updates via `cf agents sync`.
+ *
+ * Conflict policy (aligns with §8.5):
+ *   - Unmodified (hash matches last installed) → overwrite
+ *   - Modified by user → skip with warning, backup to ~/.claude-forge/backups/
+ *   - New file → write
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { homedir } from 'node:os';
+import matter from 'gray-matter';
+import { logger } from '../core/utils/logger.js';
+import { OFFICIAL_AGENTS } from './official-agents.js';
+import { renderAgentMarkdown } from './definition.js';
+const USER_AGENTS_DIR = path.join(homedir(), '.claude', 'agents');
+const BACKUP_ROOT = path.join(homedir(), '.claude-forge', 'backups', 'agents');
+function sha256(s) {
+    return crypto.createHash('sha256').update(s).digest('hex');
+}
+function ensureDir(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+}
+function readFrontmatterVersion(filePath) {
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const v = matter(raw).data?.version;
+        return typeof v === 'string' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+function backup(filePath) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const dest = path.join(BACKUP_ROOT, ts, path.basename(filePath));
+    ensureDir(path.dirname(dest));
+    fs.copyFileSync(filePath, dest);
+    return dest;
+}
+export function installOfficialAgents(opts = {}) {
+    ensureDir(USER_AGENTS_DIR);
+    const report = { written: [], skipped: [], backedUp: [] };
+    for (const def of OFFICIAL_AGENTS) {
+        const target = path.join(USER_AGENTS_DIR, `${def.name}.md`);
+        const next = renderAgentMarkdown(def);
+        if (!fs.existsSync(target)) {
+            fs.writeFileSync(target, next, 'utf-8');
+            report.written.push(def.name);
+            continue;
+        }
+        const current = fs.readFileSync(target, 'utf-8');
+        if (current === next) {
+            report.skipped.push(def.name);
+            continue;
+        }
+        const existingVersion = readFrontmatterVersion(target);
+        const isOlderVersion = existingVersion && existingVersion !== def.version;
+        if (opts.force || isOlderVersion) {
+            const backupPath = backup(target);
+            fs.writeFileSync(target, next, 'utf-8');
+            report.written.push(def.name);
+            report.backedUp.push(backupPath);
+            logger.info(`[AgentDistributor] Updated ${def.name} (backup at ${backupPath})`);
+        }
+        else {
+            report.skipped.push(def.name);
+            logger.info(`[AgentDistributor] Skipped ${def.name}: local version differs, use --force to overwrite`);
+        }
+    }
+    return report;
+}
+/**
+ * Hash of a locally stored agent file, used by `cf agents list` to mark
+ * "modified by user" entries.
+ */
+export function localAgentHash(name) {
+    const p = path.join(USER_AGENTS_DIR, `${name}.md`);
+    if (!fs.existsSync(p))
+        return null;
+    return sha256(fs.readFileSync(p, 'utf-8'));
+}
+//# sourceMappingURL=distributor.js.map

package/dist/agents/distributor.js.map

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

package/dist/agents/index.d.ts

@@ -0,0 +1,5 @@
+export * from './definition.js';
+export * from './registry.js';
+export * from './distributor.js';
+export { OFFICIAL_AGENTS, findOfficialAgent } from './official-agents.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/agents/index.js

@@ -0,0 +1,5 @@
+export * from './definition.js';
+export * from './registry.js';
+export * from './distributor.js';
+export { OFFICIAL_AGENTS, findOfficialAgent } from './official-agents.js';
+//# sourceMappingURL=index.js.map

package/dist/agents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/agents/official-agents.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Built-in official agents for claude-forge.
+ *
+ * Phase 1 ships `planner` and `coder` to validate the routing pipeline
+ * without the extra variables introduced by pipeline-type agents that spawn
+ * downstream Tasks. Subsequent phases fill in the remaining 10 agents.
+ */
+import type { AgentDefinition } from './definition.js';
+export declare const OFFICIAL_AGENTS: AgentDefinition[];
+/**
+ * Lookup helper used by the routing layer.
+ */
+export declare function findOfficialAgent(name: string): AgentDefinition | undefined;
+//# sourceMappingURL=official-agents.d.ts.map

package/dist/agents/official-agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"official-agents.d.ts","sourceRoot":"","sources":["../../src/agents/official-agents.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AA4ZvD,eAAO,MAAM,eAAe,EAAE,eAAe,EAiG5C,CAAC;AAEF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAE3E"}