@guidobuilds/forge-ai 0.2.0 → 0.5.0

package/dist/src/manifest.js

@@ -20,27 +20,31 @@ export async function loadManifest(manifestPath) {
         throw error;
     }
 }
-export function buildManifest(location, files, now = new Date()) {
+export async function buildManifest(location, files, now = new Date()) {
+    const entries = await Promise.all(files.map(async (file) => ({
+        platform: file.platform,
+        kind: file.kind,
+        name: file.name,
+        path: file.path,
+        sourcePath: file.sourcePath,
+        checksum: sha256(await readFile(file.path, 'utf8'))
+    })));
     return {
         schemaVersion: 1,
         scope: location.scope,
         projectPath: location.projectPath,
         projectPathHash: location.projectPathHash,
         updatedAt: now.toISOString(),
-        entries: files.map((file) => ({
-            platform: file.platform,
-            kind: file.kind,
-            name: file.name,
-            path: file.path,
-            sourcePath: file.sourcePath,
-            checksum: sha256(file.content)
-        }))
+        entries
     };
 }
 export async function saveManifest(manifestPath, manifest) {
     await mkdir(path.dirname(manifestPath), { recursive: true });
     await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
 }
+export function lookupEntryByPath(manifest, filePath) {
+    return manifest?.entries.find((entry) => entry.path === filePath);
+}
 export function staleEntries(oldManifest, files) {
     if (!oldManifest)
         return [];
@@ -71,17 +75,46 @@ export async function classifyPruneEntries(entries) {
 }
 export async function pruneEntries(entries) {
     for (const entry of entries) {
+        if (entry.backupPath) {
+            try {
+                const content = await readFile(entry.path, 'utf8');
+                await backupFile(entry.backupPath, content);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                // Source file is already gone; nothing to back up.
+            }
+        }
         await rm(entry.path, { force: true });
         if (entry.kind === 'skill')
             await removeEmptyParent(path.dirname(entry.path));
     }
 }
+export function resolveBackupRoot(location, now) {
+    const scopeKey = location.scope === 'user' ? 'user' : path.join('projects', location.projectPathHash ?? 'unknown');
+    return path.join(location.stateRoot, 'backups', scopeKey, isoTimestamp(now));
+}
+export function resolveBackupPath(backupRoot, originalAbsolutePath, anchor) {
+    const rel = path.relative(anchor, originalAbsolutePath);
+    const safe = rel.startsWith('..') || path.isAbsolute(rel)
+        ? originalAbsolutePath.replace(/^[\/\\]+/, '')
+        : rel;
+    return path.join(backupRoot, safe);
+}
+export async function backupFile(backupPath, content) {
+    await mkdir(path.dirname(backupPath), { recursive: true });
+    await writeFile(backupPath, content, 'utf8');
+}
 export function sha256(content) {
     return createHash('sha256').update(content).digest('hex');
 }
 export function hashProjectPath(projectPath) {
     return sha256(projectPath).slice(0, 32);
 }
+function isoTimestamp(now) {
+    return now.toISOString().replace(/[:.]/g, '-');
+}
 async function canonicalProjectPath(cwd) {
     try {
         return await realpath(cwd);

package/dist/src/model.js

@@ -1,4 +1,7 @@
-export const platforms = ['opencode', 'claude', 'codex'];
+export const platforms = ['opencode', 'claude', 'codex', 'grok'];
 export function isPlatform(value) {
     return platforms.includes(value);
 }
+export function hasPendingDecisions(pending) {
+    return pending.modifiedOverwrites.length > 0 || pending.foreignOverwrites.length > 0;
+}

package/dist/src/paths.js

@@ -13,6 +13,8 @@ function userBase(platform, kind, home) {
         return path.join(home, '.config', 'opencode', kind === 'agent' ? 'agents' : 'skills');
     if (platform === 'claude')
         return path.join(home, '.claude', kind === 'agent' ? 'agents' : 'skills');
+    if (platform === 'grok')
+        return path.join(home, '.grok', kind === 'agent' ? 'agents' : 'skills');
     return kind === 'agent' ? path.join(home, '.codex', 'agents') : path.join(home, '.agents', 'skills');
 }
 function projectBase(platform, kind, cwd) {
@@ -20,5 +22,7 @@ function projectBase(platform, kind, cwd) {
         return path.join(cwd, '.opencode', kind === 'agent' ? 'agents' : 'skills');
     if (platform === 'claude')
         return path.join(cwd, '.claude', kind === 'agent' ? 'agents' : 'skills');
+    if (platform === 'grok')
+        return path.join(cwd, '.grok', kind === 'agent' ? 'agents' : 'skills');
     return kind === 'agent' ? path.join(cwd, '.codex', 'agents') : path.join(cwd, '.agents', 'skills');
 }

package/dist/src/processor.js

@@ -1,19 +1,24 @@
-import { access } from 'node:fs/promises';
+import { access, readFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import path from 'node:path';
 import { renderClaudeAgent, renderClaudeSkill } from './adapters/claude.js';
 import { renderCodexAgent, renderCodexSkill } from './adapters/codex.js';
+import { renderGrokAgent, renderGrokSkill } from './adapters/grok.js';
 import { renderOpenCodeAgent, renderOpenCodeSkill } from './adapters/opencode.js';
 import { diagnostic } from './diagnostics.js';
 import { discoverSources } from './discovery.js';
+import { lookupEntryByPath, resolveBackupPath, sha256 } from './manifest.js';
 import { resolveOutputPath } from './paths.js';
 import { isPlatform, platforms } from './model.js';
 const namePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-const platformKeys = new Set(['claude', 'opencode', 'codex']);
-const allowedTopLevel = new Set(['name', 'description', 'claude', 'opencode', 'codex']);
-const allowedProductKeys = new Set(['permissions', 'model']);
+const platformKeys = new Set(['claude', 'opencode', 'codex', 'grok']);
+const allowedTopLevel = new Set(['name', 'description', 'kind', 'claude', 'opencode', 'codex', 'grok']);
+const allowedProductKeys = new Set(['permissions', 'model', 'kind']);
 const allowedOpenCodeKeys = new Set([...allowedProductKeys, 'mode']);
 const openCodeModes = new Set(['primary', 'subagent', 'all']);
+const artifactKinds = new Set(['agent', 'skill']);
+const defaultBodyBudget = 200;
+const bodyLineBudgets = { forge: 90, 'using-forge': 220, 'forge-worker': 300, 'forge-grill': 120, 'forge-adversary': 200 };
 export function resolvePlatforms(platform) {
     return platform === 'all' ? platforms : [platform];
 }
@@ -25,45 +30,43 @@ export function parseScope(value) {
 }
 export async function buildWritePlan(options) {
     const { sources, diagnostics } = await discoverSources(options.source);
-    const agents = [];
-    const skills = [];
-    const seenAgents = new Set();
-    const seenSkills = new Set();
+    const artifacts = [];
+    const seen = new Set();
     for (const source of sources) {
         const converted = convertSource(source, options.source);
         diagnostics.push(...converted.diagnostics);
         if (!converted.item)
             continue;
-        const seen = source.kind === 'agent' ? seenAgents : seenSkills;
         if (seen.has(converted.item.name)) {
-            diagnostics.push(diagnostic('error', 'DUPLICATE_NAME', `Duplicate ${source.kind} name ${converted.item.name}`, { sourcePath: source.sourcePath }));
+            diagnostics.push(diagnostic('error', 'DUPLICATE_NAME', `Duplicate artifact name ${converted.item.name}`, { sourcePath: source.sourcePath }));
             continue;
         }
         seen.add(converted.item.name);
-        if (source.kind === 'agent')
-            agents.push(converted.item);
-        else
-            skills.push(converted.item);
+        artifacts.push(converted.item);
     }
     const files = [];
+    const pending = { modifiedOverwrites: [], foreignOverwrites: [] };
     if (!diagnostics.some((item) => item.severity === 'error')) {
         for (const platform of resolvePlatforms(options.platform)) {
-            for (const agent of agents)
-                files.push(renderFile(platform, 'agent', agent, options, diagnostics));
-            for (const skill of skills)
-                files.push(renderFile(platform, 'skill', skill, options, diagnostics));
+            for (const artifact of artifacts) {
+                const effectiveKind = artifact[platform]?.kind ?? artifact.kind;
+                files.push(renderFile(platform, effectiveKind, artifact, options, diagnostics));
+            }
         }
         files.sort((a, b) => `${a.platform}:${a.kind}:${a.name}`.localeCompare(`${b.platform}:${b.kind}:${b.name}`));
-        if (options.checkCollisions)
-            diagnostics.push(...await collisionDiagnostics(files, Boolean(options.force)));
+        if (options.checkCollisions) {
+            const anchor = options.scope === 'user' ? (options.home ?? '') : (options.cwd ?? '');
+            diagnostics.push(...await classifyDestinations(files, options.manifest, options.backupRoot, anchor, pending));
+        }
     }
-    return { files, diagnostics, sourceCount: sources.length };
+    return { files, diagnostics, pending, sourceCount: sources.length };
 }
 function convertSource(source, sourceRoot) {
     const diagnostics = [];
     const data = source.data;
     const name = typeof data.name === 'string' ? data.name : undefined;
     const description = typeof data.description === 'string' ? data.description : undefined;
+    const kind = data.kind;
     for (const key of Object.keys(data)) {
         if (!allowedTopLevel.has(key))
             diagnostics.push(diagnostic('error', 'UNSUPPORTED_FIELD', `Unsupported canonical field ${key}`, { sourcePath: source.sourcePath }));
@@ -76,53 +79,100 @@ function convertSource(source, sourceRoot) {
             diagnostics.push(diagnostic('error', 'INVALID_PLATFORM_BLOCK', `${platform} must be an object`, { sourcePath: source.sourcePath, platform: platform }));
             continue;
         }
-        for (const key of Object.keys(config)) {
-            const allowedKeys = platform === 'opencode' && source.kind === 'agent' ? allowedOpenCodeKeys : allowedProductKeys;
+        const record = config;
+        for (const key of Object.keys(record)) {
+            const allowedKeys = platform === 'opencode' ? allowedOpenCodeKeys : allowedProductKeys;
             if (!allowedKeys.has(key))
                 diagnostics.push(diagnostic('error', 'UNSUPPORTED_PLATFORM_FIELD', `${platform}.${key} is not supported in the MVP`, { sourcePath: source.sourcePath, platform: platform }));
         }
-        if ('model' in config && typeof config.model !== 'string') {
+        if ('model' in record && typeof record.model !== 'string') {
             diagnostics.push(diagnostic('error', 'INVALID_PLATFORM_MODEL', `${platform}.model must be a string`, { sourcePath: source.sourcePath, platform: platform }));
         }
-        if (platform === 'opencode' && source.kind === 'agent' && 'mode' in config && !openCodeModes.has(config.mode)) {
-            diagnostics.push(diagnostic('error', 'INVALID_OPENCODE_MODE', 'opencode.mode must be one of primary, subagent, all', { sourcePath: source.sourcePath, platform: 'opencode' }));
+        if ('kind' in record && !artifactKinds.has(record.kind)) {
+            diagnostics.push(diagnostic('error', 'INVALID_PLATFORM_KIND', `${platform}.kind must be one of agent, skill`, { sourcePath: source.sourcePath, platform: platform }));
+        }
+        if (platform === 'opencode' && 'mode' in record) {
+            if (!openCodeModes.has(record.mode)) {
+                diagnostics.push(diagnostic('error', 'INVALID_OPENCODE_MODE', 'opencode.mode must be one of primary, subagent, all', { sourcePath: source.sourcePath, platform: 'opencode' }));
+            }
+            const effectiveKind = record.kind ?? kind;
+            if (effectiveKind !== 'agent') {
+                diagnostics.push(diagnostic('error', 'OPENCODE_MODE_ON_SKILL', 'opencode.mode is only valid when the OpenCode artifact kind is agent', { sourcePath: source.sourcePath, platform: 'opencode' }));
+            }
         }
     }
     if (!name)
-        diagnostics.push(diagnostic('error', 'MISSING_NAME', `${source.kind} name is required`, { sourcePath: source.sourcePath }));
+        diagnostics.push(diagnostic('error', 'MISSING_NAME', 'artifact name is required', { sourcePath: source.sourcePath }));
     if (name && !namePattern.test(name))
-        diagnostics.push(diagnostic('error', 'INVALID_NAME', `${source.kind} name must be kebab-case`, { sourcePath: source.sourcePath }));
+        diagnostics.push(diagnostic('error', 'INVALID_NAME', 'artifact name must be kebab-case', { sourcePath: source.sourcePath }));
     if (name && name !== source.expectedName)
-        diagnostics.push(diagnostic('error', 'NAME_MISMATCH', `${source.kind} name must match ${source.expectedName}`, { sourcePath: source.sourcePath }));
+        diagnostics.push(diagnostic('error', 'NAME_MISMATCH', `artifact name must match ${source.expectedName}`, { sourcePath: source.sourcePath }));
     if (!description)
-        diagnostics.push(diagnostic('error', 'MISSING_DESCRIPTION', `${source.kind} description is required`, { sourcePath: source.sourcePath }));
+        diagnostics.push(diagnostic('error', 'MISSING_DESCRIPTION', 'artifact description is required', { sourcePath: source.sourcePath }));
+    if (kind === undefined)
+        diagnostics.push(diagnostic('error', 'MISSING_KIND', 'artifact kind is required (agent or skill)', { sourcePath: source.sourcePath }));
+    else if (!artifactKinds.has(kind))
+        diagnostics.push(diagnostic('error', 'INVALID_KIND', 'artifact kind must be one of agent, skill', { sourcePath: source.sourcePath }));
     if (!source.body.trim())
-        diagnostics.push(diagnostic('error', 'EMPTY_BODY', `${source.kind} body is required`, { sourcePath: source.sourcePath }));
-    if (!name || !description || !source.body.trim() || diagnostics.some((item) => item.severity === 'error'))
+        diagnostics.push(diagnostic('error', 'EMPTY_BODY', 'artifact body is required', { sourcePath: source.sourcePath }));
+    const bodyLines = source.body.split('\n').length;
+    const bodyBudget = bodyLineBudgets[name ?? source.expectedName] ?? defaultBodyBudget;
+    if (bodyLines > bodyBudget)
+        diagnostics.push(diagnostic('info', 'BODY_OVER_BUDGET', `artifact body is ${bodyLines} lines (soft budget ${bodyBudget}); keep always-loaded harness files small`, { sourcePath: source.sourcePath }));
+    if (!name || !description || !artifactKinds.has(kind) || !source.body.trim() || diagnostics.some((item) => item.severity === 'error'))
         return { diagnostics };
-    const base = { name, description, sourcePath: path.relative(path.resolve(sourceRoot), source.sourcePath), claude: productConfig(data.claude), opencode: productConfig(data.opencode), codex: productConfig(data.codex) };
-    return { diagnostics, item: source.kind === 'agent' ? { ...base, definition: source.body } : { ...base, instructions: source.body } };
+    return {
+        diagnostics,
+        item: {
+            name,
+            description,
+            kind: kind,
+            body: source.body,
+            sourcePath: path.relative(path.resolve(sourceRoot), source.sourcePath),
+            claude: productConfig(data.claude),
+            opencode: productConfig(data.opencode),
+            codex: productConfig(data.codex),
+            grok: productConfig(data.grok)
+        }
+    };
 }
 function productConfig(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
 }
-function renderFile(platform, kind, item, options, diagnostics) {
+function renderFile(platform, kind, artifact, options, diagnostics) {
     const rendered = kind === 'agent'
-        ? platform === 'opencode' ? renderOpenCodeAgent(item) : platform === 'claude' ? renderClaudeAgent(item) : renderCodexAgent(item)
-        : platform === 'opencode' ? renderOpenCodeSkill(item) : platform === 'claude' ? renderClaudeSkill(item) : renderCodexSkill(item);
+        ? platform === 'opencode' ? renderOpenCodeAgent(artifact) : platform === 'claude' ? renderClaudeAgent(artifact) : platform === 'grok' ? renderGrokAgent(artifact) : renderCodexAgent(artifact)
+        : platform === 'opencode' ? renderOpenCodeSkill(artifact) : platform === 'claude' ? renderClaudeSkill(artifact) : platform === 'grok' ? renderGrokSkill(artifact) : renderCodexSkill(artifact);
     diagnostics.push(...rendered.diagnostics);
-    return { platform, kind, scope: options.scope, name: item.name, sourcePath: item.sourcePath ?? '', path: resolveOutputPath(platform, kind, options.scope, item.name, options.cwd, options.home), content: rendered.content };
+    return { platform, kind, scope: options.scope, name: artifact.name, sourcePath: artifact.sourcePath, path: resolveOutputPath(platform, kind, options.scope, artifact.name, options.cwd, options.home), content: rendered.content };
 }
-async function collisionDiagnostics(files, force) {
+async function classifyDestinations(files, manifest, backupRoot, anchor, pending) {
     const diagnostics = [];
     for (const file of files) {
-        try {
-            await access(file.path, constants.F_OK);
-            diagnostics.push(diagnostic(force ? 'warning' : 'error', force ? 'OVERWRITE_FORCED' : 'DESTINATION_EXISTS', force ? `--force will overwrite ${file.path}` : `Destination exists; use --force to overwrite ${file.path}`, { platform: file.platform }));
+        const status = await classifyFile(file.path, manifest);
+        file.status = status;
+        if (status === 'managed-modified' && backupRoot) {
+            file.backupPath = resolveBackupPath(backupRoot, file.path, anchor);
+            pending.modifiedOverwrites.push(file);
+            diagnostics.push(diagnostic('warning', 'MANAGED_FILE_OVERWRITE', `Will overwrite locally edited Forge file ${file.path}; backup → ${file.backupPath}`, { platform: file.platform }));
         }
-        catch {
-            // Missing destination is safe.
+        else if (status === 'foreign') {
+            pending.foreignOverwrites.push(file);
+            diagnostics.push(diagnostic('warning', 'FOREIGN_FILE_OVERWRITE', `Will overwrite untracked file at ${file.path}`, { platform: file.platform }));
         }
     }
     return diagnostics;
 }
+async function classifyFile(filePath, manifest) {
+    try {
+        await access(filePath, constants.F_OK);
+    }
+    catch {
+        return 'new';
+    }
+    const entry = lookupEntryByPath(manifest, filePath);
+    if (!entry)
+        return 'foreign';
+    const content = await readFile(filePath, 'utf8');
+    return sha256(content) === entry.checksum ? 'managed-unmodified' : 'managed-modified';
+}

package/dist/src/self-update.js

@@ -0,0 +1,70 @@
+import { realpathSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+const PACKAGE = '@guidobuilds/forge-ai';
+export function detectInstallMethod(realPath) {
+    if (/[/\\]\.npm[/\\]_npx[/\\]/.test(realPath))
+        return 'npx';
+    if (/[/\\]pnpm[/\\]/.test(realPath))
+        return 'pnpm-global';
+    if (/[/\\]homebrew[/\\]/i.test(realPath) && /[/\\]node_modules[/\\]/.test(realPath))
+        return 'npm-global-homebrew';
+    if (/[/\\]node_modules[/\\]/.test(realPath))
+        return 'npm-global';
+    return 'unknown';
+}
+export function buildUpdateCommand(method, version = 'latest') {
+    const target = `${PACKAGE}@${version}`;
+    switch (method) {
+        case 'pnpm-global':
+            return { command: 'pnpm', args: ['add', '-g', target, '--prefer-online'], description: 'pnpm global' };
+        case 'npm-global':
+            return { command: 'npm', args: ['install', '-g', target], description: 'npm global' };
+        case 'npm-global-homebrew':
+            return { command: '/opt/homebrew/bin/npm', args: ['install', '-g', target], description: 'npm global (Homebrew)' };
+        case 'npx':
+            return { command: '', args: [], description: 'npx (no global install)', instructions: `No global install to update. Re-run with: npx ${target} update` };
+        case 'unknown':
+            return { command: '', args: [], description: 'unknown install method', instructions: `Could not detect install method. Update manually: pnpm add -g ${target} --prefer-online` };
+    }
+}
+export async function runSelfUpdate(options) {
+    const log = options.log ?? ((message) => console.log(message));
+    const resolver = options.realPathResolver ?? ((p) => realpathSync(p));
+    const spawner = options.spawner ?? defaultSpawner;
+    let realPath;
+    try {
+        realPath = resolver(options.binaryPath);
+    }
+    catch {
+        realPath = options.binaryPath;
+    }
+    // Try the symlink path first (catches `pnpm link --global` and similar dev setups);
+    // fall back to the resolved real path (catches standard global installs whose bin dir is generic).
+    const symlinkMethod = detectInstallMethod(options.binaryPath);
+    const method = symlinkMethod !== 'unknown' ? symlinkMethod : detectInstallMethod(realPath);
+    const cmd = buildUpdateCommand(method, options.version ?? 'latest');
+    log(`Detected install: ${cmd.description} at ${realPath}`);
+    if (cmd.instructions) {
+        log(cmd.instructions);
+        return 1;
+    }
+    log(`Running: ${cmd.command} ${cmd.args.join(' ')}`);
+    if (options.dryRun) {
+        log('(dry-run, not executing)');
+        return 0;
+    }
+    const updateResult = spawner(cmd.command, cmd.args);
+    if (updateResult.status !== 0) {
+        log(`CLI update failed with exit code ${updateResult.status}`);
+        return updateResult.status ?? 1;
+    }
+    if (options.skipSpecUpdate)
+        return 0;
+    log('\nApplying spec kit with the updated CLI...');
+    const specResult = spawner('forge-ai', ['update']);
+    return specResult.status ?? 1;
+}
+function defaultSpawner(command, args) {
+    const result = spawnSync(command, args, { stdio: 'inherit' });
+    return { status: result.status };
+}

package/dist/src/version-check.js

@@ -0,0 +1,75 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+const REGISTRY_URL = 'https://registry.npmjs.org/@guidobuilds/forge-ai/latest';
+const DEFAULT_TTL_MS = 60 * 60 * 1000;
+const DEFAULT_FETCH_TIMEOUT_MS = 1500;
+export async function checkLatestVersion(options) {
+    const ttl = options.ttlMs ?? DEFAULT_TTL_MS;
+    const now = options.now ?? new Date();
+    const cached = await readCache(options.cachePath);
+    if (cached && now.getTime() - new Date(cached.checkedAt).getTime() < ttl) {
+        return makeResult(options.current, cached.latest);
+    }
+    const fetched = await fetchLatest(options.registryUrl ?? REGISTRY_URL, options.fetcher ?? fetch, options.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS);
+    if (fetched === undefined)
+        return cached ? makeResult(options.current, cached.latest) : undefined;
+    await writeCache(options.cachePath, { checkedAt: now.toISOString(), latest: fetched });
+    return makeResult(options.current, fetched);
+}
+export function formatVersionNotice(result) {
+    if (!result.isOutdated)
+        return '';
+    return `forge-ai v${result.current} (v${result.latest} available — run \`forge-ai self-update\` to upgrade)`;
+}
+export function compareSemver(a, b) {
+    const pa = a.split('.').map((part) => parseInt(part, 10) || 0);
+    const pb = b.split('.').map((part) => parseInt(part, 10) || 0);
+    for (let index = 0; index < Math.max(pa.length, pb.length); index += 1) {
+        const diff = (pa[index] ?? 0) - (pb[index] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+function makeResult(current, latest) {
+    return { current, latest, isOutdated: compareSemver(current, latest) < 0 };
+}
+async function fetchLatest(url, fetcher, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetcher(url, { signal: controller.signal });
+        if (!response.ok)
+            return undefined;
+        const json = await response.json();
+        return typeof json.version === 'string' ? json.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function readCache(cachePath) {
+    try {
+        const content = await readFile(cachePath, 'utf8');
+        const parsed = JSON.parse(content);
+        if (typeof parsed.checkedAt === 'string' && typeof parsed.latest === 'string') {
+            return { checkedAt: parsed.checkedAt, latest: parsed.latest };
+        }
+    }
+    catch {
+        // Cache missing or malformed; treat as no cache.
+    }
+    return undefined;
+}
+async function writeCache(cachePath, data) {
+    try {
+        await mkdir(path.dirname(cachePath), { recursive: true });
+        await writeFile(cachePath, `${JSON.stringify(data)}\n`, 'utf8');
+    }
+    catch {
+        // Cache write failures are non-fatal.
+    }
+}

package/dist/src/writer.js

@@ -1,7 +1,19 @@
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { backupFile } from './manifest.js';
 export async function writeOutputs(files) {
     for (const file of files) {
+        if (file.backupPath) {
+            try {
+                const existing = await readFile(file.path, 'utf8');
+                await backupFile(file.backupPath, existing);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                // Original file disappeared between classification and write; no backup needed.
+            }
+        }
         await mkdir(path.dirname(file.path), { recursive: true });
         await writeFile(file.path, file.content, 'utf8');
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guidobuilds/forge-ai",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Forge AI framework",
   "license": "MIT",
   "type": "module",
@@ -10,18 +10,11 @@
   "files": [
     "bin",
     "dist/src",
-    "agents",
-    "skills",
+    "artifacts",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "build:test": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build:test && node --test dist/tests/*.test.js",
-    "prepack": "npm run build"
-  },
   "engines": {
     "node": ">=20"
   },
@@ -31,6 +24,13 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.2.0",
-    "picocolors": "^1.1.1"
+    "picocolors": "^1.1.1",
+    "yaml": "^2.8.4"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:test": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build:test && node --test dist/tests/*.test.js"
   }
-}
+}

package/agents/forge-worker.md

@@ -1,60 +0,0 @@
----
-name: forge-worker
-description: Forge universal worker for inspect, design, plan, build, operate, and verify work
-claude:
-  permissions:
-    tools: [TodoWrite, Read, Write, Edit, Bash, Glob, Grep, LS, MultiEdit, WebFetch]
-opencode:
-  mode: subagent
-  permissions:
-    todowrite: true
-    read: true
-    write: true
-    edit: true
-    bash: true
-    glob: true
-    grep: true
-    list: true
-    patch: true
-    skill: true
-    webfetch: true
----
-
-You are the Forge worker.
-
-Load and follow the `forge-worker` skill before doing work.
-
-You are the only worker type in Forge. The orchestrator may launch multiple instances of you in parallel or sequence.
-
-## Inputs
-- Orchestrator prompt with the assigned subgoal, expected boundaries, and any approval context.
-- Optional: `.forge/<feature-slug>/explore.md`
-- Optional: `.forge/<feature-slug>/design.md`
-- Optional: `.forge/<feature-slug>/plan.md`
-- Optional: `.forge/<feature-slug>/build-log.md`
-
-The skill defines routing by work type, artifact guidance, approval handling, bounded execution, escalation rules, and validation expectations.
-
-## Contract (strict)
-Return only:
-
-```text
-STATUS: success|partial|blocked
-WORK_TYPE: inspect|design|plan|build|operate|verify|mixed
-FEATURE_SLUG: <kebab-case>
-ARTIFACTS:
-- <path or None>
-SUMMARY:
-- <brief point>
-NEXT_RECOMMENDED: inspect|design|plan|build|operate|verify|ask-user|none
-RISKS:
-- <risk or None>
-QUESTIONS:
-1) <question>
-2) <question>
-```
-
-Include `QUESTIONS` only when blocked.
-
-Do not interact directly with the user. Escalate open decisions back to the orchestrator through the contract.
-Do not add extra format outside the defined worker contract.