@guidobuilds/forge-ai 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Versions prior to 0.3.0 are not reconstructed here; see git history for earlier changes.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-05-15
+
+### Added
+
+- Unified canonical **artifact** model: all sources live under `artifacts/<name>/<name>.md` and declare `kind: agent | skill` in frontmatter. Each per-platform block can override `kind`, so one artifact renders as an agent on one platform and a skill on another.
+- `forge` orchestrator installs as a Claude Code **skill** (`/forge`) on Claude Code, while remaining a primary agent on OpenCode and Codex. This fixes the previous setup where `forge` was installed as a Claude subagent and could not delegate to `forge-worker` (Claude subagents cannot call `Task`).
+- Installer **classifies each destination** as one of `new`, `managed-unmodified`, `managed-modified`, or `foreign`, and prints the status next to each file (`[refresh]`, `[overwrite, backup -> …]`, `[foreign overwrite]`, `[new]`).
+- **Automatic backups** of user-edited Forge files before overwrite or prune, stored under `~/.forge-ai/backups/<scope>/<ISO-timestamp>/<relative-path>`. A single timestamp directory groups all backups from one run.
+- **Combined confirmation prompt** in interactive mode listing every file that needs the user's decision (edited overwrites, edited deletions, foreign overwrites) with the destination backup directory.
+- Non-interactive installs refuse with exit code 1 when there are edited or foreign files and neither `--yes` nor `--force` is set, instead of silently overwriting.
+- New diagnostic codes: `MANAGED_FILE_OVERWRITE`, `FOREIGN_FILE_OVERWRITE`, `MISSING_KIND`, `INVALID_KIND`, `INVALID_PLATFORM_KIND`, `OPENCODE_MODE_ON_SKILL`, `SUPPORT_FILES_NOT_COPIED`.
+- Claude tool and model validation (`src/adapters/claude-known.ts`): unknown tools/models in agent frontmatter emit warnings instead of being silently accepted.
+- Skill source directories now allow sibling files (groundwork for future support-file bundling); detected files emit an `info` diagnostic noting that copying is not yet implemented.
+
+### Changed
+
+- Source layout: `agents/` and `skills/` directories are gone; everything moved to `artifacts/<name>/<name>.md`.
+- `forge-worker` agent and `forge-worker` skill (previously two files with the same name in separate namespaces) merged into a **single** `forge-worker` artifact rendered as a subagent on every platform. The artificial "thin agent loads a skill" indirection is removed.
+- `package.json` `files` now ships `artifacts/` instead of `agents/` + `skills/`.
+- Refreshing a managed-unmodified file is **silent** — no warning emitted. Previously every existing destination produced an indiscriminate `OVERWRITE_FORCED`.
+- Stale-managed files the user edited are now **backed up and deleted** during `update` (when `--yes`/`--force`); previously they were left on disk with a `CHECKSUM_MISMATCH` warning. Interactive runs prompt before backing up + deleting.
+- OpenCode `permissions` keys switched from boolean (`true`/`false`) to explicit strings (`allow`/`deny`); orchestrator now explicitly denies file/code operations.
+- Adapters consume a unified `CanonicalArtifact` type (with `body` field) instead of separate `CanonicalAgent`/`CanonicalSkill` types.
+- Frontmatter parsing now uses the `yaml` library (replaces the hand-rolled parser), with stricter spec compliance and better edge-case handling (colons in descriptions, horizontal rules in bodies, BOM, CRLF).
+- Claude agent `tools` and skill `allowed-tools` are emitted as comma-separated strings (matches Claude Code's native format).
+- Development tooling migrated from npm to **pnpm**: `packageManager: "pnpm@11.1.1"` pinned via Corepack (no global install needed); `pnpm.onlyBuiltDependencies: []` allowlist is explicit so postinstall script blocking is documented behavior. The published package is unaffected — consumers still install via `npx`.
+
+### Removed
+
+- `CanonicalAgent` and `CanonicalSkill` types (replaced by `CanonicalArtifact`).
+- `agents/` and `skills/` source directories.
+- `DESTINATION_EXISTS` error and `OVERWRITE_FORCED` warning (replaced by status-aware `MANAGED_FILE_OVERWRITE` and `FOREIGN_FILE_OVERWRITE`).
+- `CHECKSUM_MISMATCH` warning during prune (the file is now backed up and deleted on consent).
+- `package-lock.json` (replaced by `pnpm-lock.yaml`).
+
+### Fixed
+
+- `forge` orchestrator deployment to Claude Code now actually works: it is installed as a `/forge` skill in the main thread, which retains the `Task` tool and can delegate to the `forge-worker` subagent. The previous subagent install was inert because Claude subagents cannot call `Task`.
+- Installer no longer raises spurious overwrite warnings for files Forge installed itself and that have not been edited.
+
+### Security
+
+- Migrated the development workflow to pnpm. pnpm 10+ **blocks postinstall scripts by default** (`onlyBuiltDependencies` allowlist), enforces strict `node_modules` (no phantom dependencies), and uses an auditable text lockfile (`pnpm-lock.yaml`). The npm registry is the same, but install-time defaults are hardened.
+- User edits to Forge-managed files are **always backed up** before being overwritten or deleted, eliminating silent data loss when running `update` against a customized install.
+
+### Migration from 0.2.0
+
+- Run `npx @guidobuilds/forge-ai update` (not `install`) after upgrading. `update` prunes the now-orphaned `.claude/agents/forge.md` and the old standalone `forge-worker` skill from the previous layout. Local edits to any of those files are backed up automatically to `~/.forge-ai/backups/`.
+- `install` (without `update`) will leave the orphaned files on disk. They are harmless but unmanaged.

package/README.md

@@ -108,11 +108,13 @@ npx @guidobuilds/forge-ai validate --source .
 
 ## Local Development
 
+Forge uses [pnpm](https://pnpm.io) for development (pinned via `packageManager` in `package.json`, so `corepack enable` is enough — no global install needed). The published package is still consumed by end users via `npx`/npm, unchanged.
+
 From a local checkout:
 
 ```sh
-npm install
-npm run build
+pnpm install
+pnpm run build
 node bin/forge-ai.mjs install --source . --platform all --scope user
 ```
 
@@ -134,6 +136,8 @@ Forge replaces its managed agent and skill definitions in your supported agent c
 
 Forge records installed files in manifests under `~/.forge-ai/` so updates can safely remove files that are no longer bundled. `update` prunes stale managed files by default only when the current file still matches the recorded checksum; use `--no-prune` to keep stale managed files. `--dry-run` previews writes and deletes without changing files or manifests.
 
+Forge now routes a single canonical artifact to the right artifact kind per agent: the orchestrator installs as a Claude Code skill (`/forge`) but as an agent on OpenCode and Codex. If you installed an earlier version, run `update` (not `install`) so Forge prunes the now-stale `forge` agent and standalone `forge-worker` skill left by the previous layout.
+
 ## Uninstalling
 
 Remove Forge from the agent configuration directories for OpenCode, Codex, or Claude Code by deleting the installed Forge agent and skill entries.

package/{agents → artifacts/forge}/forge.md

@@ -1,15 +1,25 @@
 ---
 name: forge
 description: Forge orchestrator with dynamic runtime routing and a single worker type
+kind: agent
 claude:
-  permissions:
-    tools: [Task, AskUserQuestion, TodoWrite]
+  kind: skill
 opencode:
   mode: primary
   permissions:
-    task: true
-    question: true
-    todowrite: true
+    task: allow
+    question: allow
+    todowrite: allow
+    read: deny
+    write: deny
+    edit: deny
+    bash: deny
+    glob: deny
+    grep: deny
+    list: deny
+    patch: deny
+    skill: allow
+    webfetch: deny
 ---
 
 # Role

package/{skills/forge-grill/SKILL.md → artifacts/forge-grill/forge-grill.md}

@@ -1,6 +1,7 @@
 ---
 name: forge-grill
 description: Stress-test a plan or design through Forge orchestration, batching user questions while delegating codebase-answerable work to forge-worker.
+kind: skill
 ---
 
 # Forge Grill Skill

package/{skills/forge-worker/SKILL.md → artifacts/forge-worker/forge-worker.md}

@@ -1,15 +1,35 @@
 ---
 name: forge-worker
-description: Execute bounded Forge work across inspect, design, plan, build, operate, and verify modes.
+description: Forge universal worker for inspect, design, plan, build, operate, and verify work
+kind: agent
+claude:
+  permissions:
+    tools: [TodoWrite, Read, Write, Edit, Bash, Glob, Grep, LS, MultiEdit, WebFetch]
+opencode:
+  mode: subagent
+  permissions:
+    todowrite: allow
+    read: allow
+    write: allow
+    edit: allow
+    bash: allow
+    glob: allow
+    grep: allow
+    list: allow
+    patch: allow
+    skill: allow
+    webfetch: allow
 ---
 
-# Forge Worker Skill
+# Forge Worker
 
 ## Role
 Execute only the subgoal assigned by the Forge orchestrator.
 
 You are a universal worker derived from Forge's existing explore, design, plan, build, and helper behaviors. Treat those as internal modes, not mandatory phases.
 
+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, constraints, approval context, and expected validation

package/{skills/using-forge/SKILL.md → artifacts/using-forge/using-forge.md}

@@ -1,6 +1,7 @@
 ---
 name: using-forge
 description: Route work through the lightest safe Forge workflow using dynamic runtime routing.
+kind: skill
 ---
 
 # Using Forge Skill

package/dist/src/adapters/claude-known.js

@@ -0,0 +1,31 @@
+export const knownClaudeTools = new Set([
+    'Read',
+    'Write',
+    'Edit',
+    'MultiEdit',
+    'NotebookEdit',
+    'Bash',
+    'Glob',
+    'Grep',
+    'LS',
+    'Task',
+    'TodoWrite',
+    'WebFetch',
+    'WebSearch',
+    'AskUserQuestion',
+    'ExitPlanMode'
+]);
+const mcpToolPattern = /^mcp__[A-Za-z0-9_-]+__[A-Za-z0-9_*-]+$/;
+export function isKnownClaudeTool(name) {
+    return knownClaudeTools.has(name) || mcpToolPattern.test(name);
+}
+export const knownClaudeModels = new Set([
+    'sonnet',
+    'opus',
+    'haiku',
+    'inherit'
+]);
+const versionedModelPattern = /^claude-(?:sonnet|opus|haiku)-[A-Za-z0-9.-]+$/;
+export function isKnownClaudeModel(value) {
+    return knownClaudeModels.has(value) || versionedModelPattern.test(value);
+}

package/dist/src/adapters/claude.js

@@ -1,32 +1,44 @@
 import { stringifyYaml } from '../frontmatter.js';
 import { diagnostic } from '../diagnostics.js';
-import { isRecord, stringList } from './shared.js';
-export function renderClaudeAgent(agent) {
+import { isKnownClaudeModel, isKnownClaudeTool } from './claude-known.js';
+import { isRecord, patternList, stringList } from './shared.js';
+export function renderClaudeAgent(artifact) {
     const diagnostics = [];
-    const fm = { name: agent.name, description: agent.description };
-    if (agent.claude?.model)
-        fm.model = agent.claude.model;
-    const permissions = agent.claude?.permissions;
+    const fm = { name: artifact.name, description: artifact.description };
+    if (artifact.claude?.model) {
+        fm.model = artifact.claude.model;
+        if (!isKnownClaudeModel(artifact.claude.model)) {
+            diagnostics.push(diagnostic('warning', 'CLAUDE_UNKNOWN_MODEL', `Unknown Claude model "${artifact.claude.model}" for ${artifact.name}`, { platform: 'claude' }));
+        }
+    }
+    const permissions = artifact.claude?.permissions;
     const tools = isRecord(permissions) ? stringList(permissions.tools) : stringList(permissions);
-    if (tools)
-        fm.tools = tools;
-    else if (permissions !== undefined)
-        diagnostics.push(diagnostic('info', 'CLAUDE_AGENT_TOOLS_IGNORED', `Claude agent permissions must be a tools string list for ${agent.name}`, { platform: 'claude' }));
-    return { content: `${stringifyYaml(fm)}${agent.definition}\n`, diagnostics };
+    if (tools) {
+        fm.tools = tools.join(', ');
+        for (const tool of tools) {
+            if (!isKnownClaudeTool(tool)) {
+                diagnostics.push(diagnostic('warning', 'CLAUDE_UNKNOWN_TOOL', `Unknown Claude tool "${tool}" for ${artifact.name}`, { platform: 'claude' }));
+            }
+        }
+    }
+    else if (permissions !== undefined) {
+        diagnostics.push(diagnostic('info', 'CLAUDE_AGENT_TOOLS_IGNORED', `Claude agent permissions must be a tools string list for ${artifact.name}`, { platform: 'claude' }));
+    }
+    return { content: `${stringifyYaml(fm)}${artifact.body}\n`, diagnostics };
 }
-export function renderClaudeSkill(skill) {
+export function renderClaudeSkill(artifact) {
     const diagnostics = [];
-    const fm = { name: skill.name, description: skill.description };
-    const permissions = skill.claude?.permissions;
-    const allowedTools = isRecord(permissions) ? stringList(permissions['allowed-tools']) : undefined;
+    const fm = { name: artifact.name, description: artifact.description };
+    const permissions = artifact.claude?.permissions;
+    const allowedTools = isRecord(permissions) ? patternList(permissions['allowed-tools']) : undefined;
     if (allowedTools) {
-        fm['allowed-tools'] = allowedTools;
-        diagnostics.push(diagnostic('warning', 'CLAUDE_SKILL_ALLOWED_TOOLS', `Claude skill allowed-tools preapproves tools but does not universally restrict them for ${skill.name}`, { platform: 'claude' }));
+        fm['allowed-tools'] = allowedTools.join(', ');
+        diagnostics.push(diagnostic('warning', 'CLAUDE_SKILL_ALLOWED_TOOLS', `Claude skill allowed-tools preapproves tools but does not universally restrict them for ${artifact.name}`, { platform: 'claude' }));
     }
     else if (permissions !== undefined) {
-        diagnostics.push(diagnostic('info', 'CLAUDE_SKILL_PERMISSIONS_IGNORED', `Claude skill permissions are not emitted for ${skill.name}`, { platform: 'claude' }));
+        diagnostics.push(diagnostic('info', 'CLAUDE_SKILL_PERMISSIONS_IGNORED', `Claude skill permissions are not emitted for ${artifact.name}`, { platform: 'claude' }));
     }
-    if (skill.claude?.model)
-        diagnostics.push(diagnostic('info', 'CLAUDE_SKILL_MODEL_IGNORED', `Claude skill model is not emitted for ${skill.name}`, { platform: 'claude' }));
-    return { content: `${stringifyYaml(fm)}${skill.instructions}\n`, diagnostics };
+    if (artifact.claude?.model)
+        diagnostics.push(diagnostic('info', 'CLAUDE_SKILL_MODEL_IGNORED', `Claude skill model is not emitted for ${artifact.name}`, { platform: 'claude' }));
+    return { content: `${stringifyYaml(fm)}${artifact.body}\n`, diagnostics };
 }

package/dist/src/adapters/codex.js

@@ -2,28 +2,28 @@ import { stringifyYaml } from '../frontmatter.js';
 import { diagnostic } from '../diagnostics.js';
 import { isRecord, tomlString } from './shared.js';
 const safeSandboxModes = new Set(['read-only', 'workspace-write']);
-export function renderCodexAgent(agent) {
-    const diagnostics = [diagnostic('info', 'CODEX_PARTIAL_AGENT_SUPPORT', `Codex agent output is partial and does not generate AGENTS.md or profiles for ${agent.name}`, { platform: 'codex' })];
-    const lines = [`name = ${tomlString(agent.name)}`, `description = ${tomlString(agent.description)}`, `developer_instructions = ${tomlString(agent.definition)}`];
-    if (agent.codex?.model)
-        lines.push(`model = ${tomlString(agent.codex.model)}`);
-    const permissions = agent.codex?.permissions;
+export function renderCodexAgent(artifact) {
+    const diagnostics = [diagnostic('info', 'CODEX_PARTIAL_AGENT_SUPPORT', `Codex agent output is partial and does not generate AGENTS.md or profiles for ${artifact.name}`, { platform: 'codex' })];
+    const lines = [`name = ${tomlString(artifact.name)}`, `description = ${tomlString(artifact.description)}`, `developer_instructions = ${tomlString(artifact.body)}`];
+    if (artifact.codex?.model)
+        lines.push(`model = ${tomlString(artifact.codex.model)}`);
+    const permissions = artifact.codex?.permissions;
     if (isRecord(permissions) && typeof permissions.sandbox_mode === 'string') {
         if (safeSandboxModes.has(permissions.sandbox_mode))
             lines.push(`sandbox_mode = ${tomlString(permissions.sandbox_mode)}`);
         else
-            diagnostics.push(diagnostic('warning', 'CODEX_UNSAFE_SANDBOX_IGNORED', `Unsafe Codex sandbox_mode ignored for ${agent.name}`, { platform: 'codex' }));
+            diagnostics.push(diagnostic('warning', 'CODEX_UNSAFE_SANDBOX_IGNORED', `Unsafe Codex sandbox_mode ignored for ${artifact.name}`, { platform: 'codex' }));
     }
     else if (permissions !== undefined) {
-        diagnostics.push(diagnostic('info', 'CODEX_AGENT_PERMISSIONS_IGNORED', `Codex agent permissions are not emitted for ${agent.name}`, { platform: 'codex' }));
+        diagnostics.push(diagnostic('info', 'CODEX_AGENT_PERMISSIONS_IGNORED', `Codex agent permissions are not emitted for ${artifact.name}`, { platform: 'codex' }));
     }
     return { content: `${lines.join('\n')}\n`, diagnostics };
 }
-export function renderCodexSkill(skill) {
+export function renderCodexSkill(artifact) {
     const diagnostics = [];
-    if (skill.codex?.permissions)
-        diagnostics.push(diagnostic('info', 'CODEX_SKILL_PERMISSIONS_IGNORED', `Codex skill permissions are not emitted for ${skill.name}`, { platform: 'codex' }));
-    if (skill.codex?.model)
-        diagnostics.push(diagnostic('info', 'CODEX_SKILL_MODEL_IGNORED', `Codex skill model is not emitted for ${skill.name}`, { platform: 'codex' }));
-    return { content: `${stringifyYaml({ name: skill.name, description: skill.description })}${skill.instructions}\n`, diagnostics };
+    if (artifact.codex?.permissions)
+        diagnostics.push(diagnostic('info', 'CODEX_SKILL_PERMISSIONS_IGNORED', `Codex skill permissions are not emitted for ${artifact.name}`, { platform: 'codex' }));
+    if (artifact.codex?.model)
+        diagnostics.push(diagnostic('info', 'CODEX_SKILL_MODEL_IGNORED', `Codex skill model is not emitted for ${artifact.name}`, { platform: 'codex' }));
+    return { content: `${stringifyYaml({ name: artifact.name, description: artifact.description })}${artifact.body}\n`, diagnostics };
 }

package/dist/src/adapters/opencode.js

@@ -1,20 +1,20 @@
 import { stringifyYaml } from '../frontmatter.js';
 import { diagnostic } from '../diagnostics.js';
-export function renderOpenCodeAgent(agent) {
-    const fm = { description: agent.description };
-    if (agent.opencode?.mode)
-        fm.mode = agent.opencode.mode;
-    if (agent.opencode?.model)
-        fm.model = agent.opencode.model;
-    if (agent.opencode?.permissions)
-        fm.permission = agent.opencode.permissions;
-    return { content: `${stringifyYaml(fm)}${agent.definition}\n`, diagnostics: [] };
+export function renderOpenCodeAgent(artifact) {
+    const fm = { description: artifact.description };
+    if (artifact.opencode?.mode)
+        fm.mode = artifact.opencode.mode;
+    if (artifact.opencode?.model)
+        fm.model = artifact.opencode.model;
+    if (artifact.opencode?.permissions)
+        fm.permission = artifact.opencode.permissions;
+    return { content: `${stringifyYaml(fm)}${artifact.body}\n`, diagnostics: [] };
 }
-export function renderOpenCodeSkill(skill) {
+export function renderOpenCodeSkill(artifact) {
     const diagnostics = [];
-    if (skill.opencode?.permissions)
-        diagnostics.push(diagnostic('info', 'OPENCODE_SKILL_PERMISSIONS_IGNORED', `OpenCode skill permissions are not emitted for ${skill.name}`, { platform: 'opencode' }));
-    if (skill.opencode?.model)
-        diagnostics.push(diagnostic('info', 'OPENCODE_SKILL_MODEL_IGNORED', `OpenCode skill model is not emitted for ${skill.name}`, { platform: 'opencode' }));
-    return { content: `${stringifyYaml({ name: skill.name, description: skill.description })}${skill.instructions}\n`, diagnostics };
+    if (artifact.opencode?.permissions)
+        diagnostics.push(diagnostic('info', 'OPENCODE_SKILL_PERMISSIONS_IGNORED', `OpenCode skill permissions are not emitted for ${artifact.name}`, { platform: 'opencode' }));
+    if (artifact.opencode?.model)
+        diagnostics.push(diagnostic('info', 'OPENCODE_SKILL_MODEL_IGNORED', `OpenCode skill model is not emitted for ${artifact.name}`, { platform: 'opencode' }));
+    return { content: `${stringifyYaml({ name: artifact.name, description: artifact.description })}${artifact.body}\n`, diagnostics };
 }

package/dist/src/adapters/shared.js

@@ -1,8 +1,13 @@
 export function isRecord(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
+const toolNamePattern = /^[A-Za-z0-9_*-]+$/;
+const patternBodyPattern = /^[^,\n]+$/;
 export function stringList(value) {
-    return Array.isArray(value) && value.every((item) => typeof item === 'string' && /^[A-Za-z0-9_*.,:-]+$/.test(item)) ? value : undefined;
+    return Array.isArray(value) && value.every((item) => typeof item === 'string' && toolNamePattern.test(item)) ? value : undefined;
+}
+export function patternList(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string' && item.length > 0 && patternBodyPattern.test(item)) ? value : undefined;
 }
 export function tomlString(value) {
     return JSON.stringify(value);

package/dist/src/cli.js

@@ -6,9 +6,11 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { formatDiagnostic, hasErrors } from './diagnostics.js';
-import { buildManifest, classifyPruneEntries, loadManifest, pruneEntries, resolveManifestLocation, saveManifest, staleEntries } from './manifest.js';
+import { buildManifest, classifyPruneEntries, loadManifest, pruneEntries, resolveBackupPath, resolveBackupRoot, resolveManifestLocation, saveManifest, staleEntries } from './manifest.js';
 import { buildWritePlan, parsePlatform, parseScope } from './processor.js';
 import { writeOutputs } from './writer.js';
+import { hasPendingDecisions } from './model.js';
+const emptyPrunePlan = { deletable: [], modifiedWithConsent: [], skippedMissing: [] };
 export async function main(argv = process.argv.slice(2), promptIO = {}) {
     if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
         showUsage();
@@ -48,27 +50,46 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
     }
     const cwd = process.cwd();
     const home = resolveHome(promptIO);
-    let plan = await buildWritePlan({ source: options.source, platform: options.platform, scope: options.scope, cwd, home, checkCollisions: install && !options.dryRun, force: options.force });
-    if (install && !options.dryRun && !options.force && canOfferUpdate(plan.diagnostics)) {
-        const accepted = await promptForUpdate(plan, promptIO);
+    const now = new Date();
+    let manifestLocation;
+    let oldManifest;
+    let backupRoot;
+    if (install) {
+        manifestLocation = await resolveManifestLocation(options.scope, cwd, home);
+        oldManifest = await loadManifest(manifestLocation.manifestPath);
+        backupRoot = resolveBackupRoot(manifestLocation, now);
+    }
+    const plan = await buildWritePlan({
+        source: options.source,
+        platform: options.platform,
+        scope: options.scope,
+        cwd,
+        home,
+        manifest: oldManifest,
+        backupRoot,
+        checkCollisions: install,
+    });
+    let prunePlan = emptyPrunePlan;
+    if (install && command === 'update' && options.prune) {
+        prunePlan = await classifyPrune(oldManifest, plan.files, backupRoot, options.scope, cwd, home);
+    }
+    const needsConfirm = install && !options.force && (hasPendingDecisions(plan.pending) || prunePlan.modifiedWithConsent.length > 0);
+    if (install && !options.dryRun && needsConfirm) {
+        if (!interactive) {
+            printPlan(command, plan.sourceCount, plan.files, plan.diagnostics, prunePlan);
+            console.error('Forge needs your decision on edited or untracked files; re-run with --yes or --force to accept overwrites + backups.');
+            return 1;
+        }
+        const accepted = await promptForUpdate(plan, prunePlan, backupRoot, promptIO);
         if (accepted === undefined) {
-            if (interactive)
-                p.cancel('Cancelled', clackIO(promptIO));
+            p.cancel('Cancelled', clackIO(promptIO));
             return 1;
         }
-        if (accepted) {
-            options.force = true;
-            plan = await buildWritePlan({ source: options.source, platform: options.platform, scope: options.scope, cwd, home, checkCollisions: true, force: true });
+        if (!accepted) {
+            p.outro(pc.yellow('Forge was not installed.'), clackIO(promptIO));
+            return 1;
         }
     }
-    let prunePlan = { deletable: [], skipped: [] };
-    let manifestLocation;
-    if (install) {
-        manifestLocation = await resolveManifestLocation(options.scope, cwd, home);
-        const oldManifest = await loadManifest(manifestLocation.manifestPath);
-        if (command === 'update' && options.prune)
-            prunePlan = await classifyPruneEntries(staleEntries(oldManifest, plan.files));
-    }
     printPlan(command, plan.sourceCount, plan.files, plan.diagnostics, prunePlan);
     if (hasErrors(plan.diagnostics)) {
         if (interactive)
@@ -82,8 +103,8 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
             try {
                 await writeOutputs(plan.files);
                 if (command === 'update' && options.prune)
-                    await pruneEntries(prunePlan.deletable);
-                await saveManifest(manifestLocation.manifestPath, buildManifest(manifestLocation, plan.files));
+                    await pruneEntries([...prunePlan.deletable, ...prunePlan.modifiedWithConsent]);
+                await saveManifest(manifestLocation.manifestPath, await buildManifest(manifestLocation, plan.files));
                 spinner.stop(`Wrote ${plan.files.length} file(s).`);
             }
             catch (error) {
@@ -94,11 +115,12 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
         else {
             await writeOutputs(plan.files);
             if (command === 'update' && options.prune)
-                await pruneEntries(prunePlan.deletable);
-            await saveManifest(manifestLocation.manifestPath, buildManifest(manifestLocation, plan.files));
+                await pruneEntries([...prunePlan.deletable, ...prunePlan.modifiedWithConsent]);
+            await saveManifest(manifestLocation.manifestPath, await buildManifest(manifestLocation, plan.files));
             console.log(`Wrote ${plan.files.length} file(s).`);
-            if (command === 'update' && options.prune && prunePlan.deletable.length > 0)
-                console.log(`Deleted ${prunePlan.deletable.length} stale file(s).`);
+            const totalDeleted = prunePlan.deletable.length + prunePlan.modifiedWithConsent.length;
+            if (command === 'update' && options.prune && totalDeleted > 0)
+                console.log(`Deleted ${totalDeleted} stale file(s).`);
             console.log(`Updated manifest ${manifestLocation.manifestPath}.`);
         }
     }
@@ -156,6 +178,20 @@ function parseArgs(argv) {
         return { error: 'validate only accepts --platform and --source' };
     return { options };
 }
+async function classifyPrune(oldManifest, files, backupRoot, scope, cwd, home) {
+    const stale = staleEntries(oldManifest, files);
+    const classified = await classifyPruneEntries(stale);
+    const anchor = scope === 'user' ? home : cwd;
+    const modifiedWithConsent = [];
+    const skippedMissing = [];
+    for (const item of classified.skipped) {
+        if (item.reason === 'checksum-mismatch')
+            modifiedWithConsent.push({ ...item, backupPath: resolveBackupPath(backupRoot, item.path, anchor) });
+        else
+            skippedMissing.push(item);
+    }
+    return { deletable: classified.deletable, modifiedWithConsent, skippedMissing };
+}
 async function promptForMissingInstallOptions(options, promptIO) {
     if (options.yes)
         return true;
@@ -196,18 +232,27 @@ async function promptForMissingInstallOptions(options, promptIO) {
     }
     return true;
 }
-async function promptForUpdate(plan, promptIO) {
+async function promptForUpdate(plan, prunePlan, backupRoot, promptIO) {
     if (!isInteractivePrompt(promptIO))
         return false;
-    const existing = plan.diagnostics.filter((item) => item.code === 'DESTINATION_EXISTS');
-    const count = existing.length;
-    p.log.warn(`${count} Forge output${count === 1 ? '' : 's'} already exist.`, clackIO(promptIO));
+    const io = clackIO(promptIO);
+    const sections = [];
+    if (plan.pending.modifiedOverwrites.length > 0) {
+        sections.push(`${pc.yellow('Edited by you, will be overwritten (backup):')}\n${plan.pending.modifiedOverwrites.map((file) => `  - ${file.path}`).join('\n')}`);
+    }
+    if (prunePlan.modifiedWithConsent.length > 0) {
+        sections.push(`${pc.yellow('Edited by you, will be deleted (backup):')}\n${prunePlan.modifiedWithConsent.map((entry) => `  - ${entry.path}`).join('\n')}`);
+    }
+    if (plan.pending.foreignOverwrites.length > 0) {
+        sections.push(`${pc.yellow('Untracked files in Forge install paths, will be overwritten:')}\n${plan.pending.foreignOverwrites.map((file) => `  - ${file.path}`).join('\n')}`);
+    }
+    p.log.warn(`The following actions need your confirmation:\n\n${sections.join('\n\n')}\n\nBackups → ${backupRoot ?? '(none)'}`, io);
     const accepted = await p.confirm({
-        message: 'Update the existing Forge files?',
-        active: 'Update',
+        message: 'Continue with overwrites + backups?',
+        active: 'Continue',
         inactive: 'Cancel',
         initialValue: false,
-        ...clackIO(promptIO)
+        ...io
     });
     if (p.isCancel(accepted))
         return undefined;
@@ -222,10 +267,6 @@ function normalizeCommand(command) {
         return 'validate';
     return undefined;
 }
-function canOfferUpdate(diagnostics) {
-    const errors = diagnostics.filter((item) => item.severity === 'error');
-    return errors.length > 0 && errors.every((item) => item.code === 'DESTINATION_EXISTS');
-}
 function isInteractivePrompt(promptIO) {
     const env = promptIO.env ?? process.env;
     const interactive = promptIO.isInteractive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
@@ -254,19 +295,32 @@ function showUsage() {
     console.log('       forge-ai update [--platform opencode|claude|codex|all] [--scope user|project] [--source <dir>] [--dry-run] [--no-prune] [--yes]');
     console.log('       forge-ai validate [--platform opencode|claude|codex|all] [--source <dir>]');
 }
-function printPlan(command, sourceCount, files, diagnostics, prunePlan = { deletable: [], skipped: [] }) {
+function printPlan(command, sourceCount, files, diagnostics, prunePlan) {
     console.log(`${command}: ${sourceCount} source(s), ${files.length} output(s)`);
     for (const file of files)
-        console.log(`- ${file.platform} ${file.kind} ${file.name} -> ${file.path}`);
-    for (const file of prunePlan.deletable)
-        console.log(`- delete stale ${file.platform} ${file.kind} ${file.name} -> ${file.path}`);
-    for (const file of prunePlan.skipped) {
-        if (file.reason === 'checksum-mismatch')
-            console.log(`warning CHECKSUM_MISMATCH: Skipping stale managed file with local changes ${file.path}`);
-    }
+        console.log(`- ${file.platform} ${file.kind} ${file.name} -> ${file.path}${statusSuffix(file)}`);
+    for (const item of prunePlan.deletable)
+        console.log(`- delete stale ${item.platform} ${item.kind} ${item.name} -> ${item.path}`);
+    for (const item of prunePlan.modifiedWithConsent)
+        console.log(`- delete stale ${item.platform} ${item.kind} ${item.name} -> ${item.path} [backup -> ${item.backupPath}]`);
+    for (const item of prunePlan.skippedMissing)
+        console.log(`- skip missing ${item.platform} ${item.kind} ${item.name} -> ${item.path}`);
     for (const item of diagnostics)
         console.log(formatDiagnostic(item));
 }
+function statusSuffix(file) {
+    if (file.status === 'managed-modified' && file.backupPath)
+        return ` [overwrite, backup -> ${file.backupPath}]`;
+    if (file.status === 'managed-modified')
+        return ' [overwrite]';
+    if (file.status === 'foreign')
+        return ' [foreign overwrite]';
+    if (file.status === 'managed-unmodified')
+        return ' [refresh]';
+    if (file.status === 'new')
+        return ' [new]';
+    return '';
+}
 if (import.meta.url === `file://${process.argv[1]}`) {
     main().then((code) => { process.exitCode = code; }, (error) => { console.error(error); process.exitCode = 1; });
 }

package/dist/src/discovery.js

@@ -6,35 +6,33 @@ export async function discoverSources(source) {
     const root = path.resolve(source);
     const sources = [];
     const diagnostics = [];
-    await discoverAgents(root, sources, diagnostics);
-    await discoverSkills(root, sources, diagnostics);
+    await discoverArtifacts(root, sources, diagnostics);
     if (sources.length === 0)
-        diagnostics.push(diagnostic('error', 'NO_SOURCES', 'No canonical agents or skills found', { sourcePath: root }));
+        diagnostics.push(diagnostic('error', 'NO_SOURCES', 'No canonical artifacts found', { sourcePath: root }));
     sources.sort((a, b) => a.sourcePath.localeCompare(b.sourcePath));
     return { sources, diagnostics };
 }
-async function discoverAgents(root, sources, diagnostics) {
-    const dir = path.join(root, 'agents');
-    for (const entry of await safeReaddir(dir)) {
-        if (!entry.isFile() || !entry.name.endsWith('.md'))
-            continue;
-        const sourcePath = path.join(dir, entry.name);
-        await readSource('agent', sourcePath, path.basename(entry.name, '.md'), sources, diagnostics);
-    }
-}
-async function discoverSkills(root, sources, diagnostics) {
-    const dir = path.join(root, 'skills');
+async function discoverArtifacts(root, sources, diagnostics) {
+    const dir = path.join(root, 'artifacts');
     for (const entry of await safeReaddir(dir)) {
         if (!entry.isDirectory())
             continue;
-        const sourcePath = path.join(dir, entry.name, 'SKILL.md');
-        await readSource('skill', sourcePath, entry.name, sources, diagnostics);
+        const name = entry.name;
+        const artifactDir = path.join(dir, name);
+        const mainFile = `${name}.md`;
+        const supportFiles = (await safeReaddir(artifactDir))
+            .filter((file) => file.isFile() && file.name !== mainFile)
+            .map((file) => path.join(artifactDir, file.name));
+        await readSource(path.join(artifactDir, mainFile), name, supportFiles, sources, diagnostics);
     }
 }
-async function readSource(kind, sourcePath, expectedName, sources, diagnostics) {
+async function readSource(sourcePath, expectedName, supportFiles, sources, diagnostics) {
     try {
         const parsed = parseFrontmatter(await readFile(sourcePath, 'utf8'));
-        sources.push({ kind, sourcePath, expectedName, data: parsed.data, body: parsed.body });
+        sources.push({ sourcePath, expectedName, data: parsed.data, body: parsed.body, supportFiles: supportFiles.length > 0 ? supportFiles : undefined });
+        if (supportFiles.length > 0) {
+            diagnostics.push(diagnostic('info', 'SUPPORT_FILES_NOT_COPIED', `Support files alongside ${expectedName} are not copied yet`, { sourcePath }));
+        }
     }
     catch (error) {
         diagnostics.push(diagnostic('error', 'PARSE_ERROR', error instanceof Error ? error.message : String(error), { sourcePath }));

package/dist/src/frontmatter.js

@@ -1,5 +1,6 @@
+import { parse, stringify } from 'yaml';
 export function parseFrontmatter(content) {
-    const normalized = content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+    const normalized = content.replace(/^/, '').replace(/\r\n/g, '\n');
     if (!normalized.startsWith('---\n')) {
         return { data: {}, body: normalized.trim() };
     }
@@ -8,74 +9,13 @@ export function parseFrontmatter(content) {
         throw new Error('Missing closing frontmatter delimiter');
     const rawYaml = normalized.slice(4, end);
     const body = normalized.slice(normalized.indexOf('\n', end + 1) + 1).trim();
-    return { data: parseSimpleYaml(rawYaml), body };
-}
-export function parseSimpleYaml(input) {
-    const root = {};
-    const stack = [{ indent: -1, object: root }];
-    const lines = input.split('\n');
-    for (let index = 0; index < lines.length; index += 1) {
-        const raw = lines[index];
-        if (!raw.trim() || raw.trimStart().startsWith('#'))
-            continue;
-        const indent = raw.match(/^ */)?.[0].length ?? 0;
-        const trimmed = raw.trim();
-        const match = trimmed.match(/^([A-Za-z0-9_-]+):(?:\s*(.*))?$/);
-        if (!match)
-            throw new Error(`Invalid YAML at line ${index + 1}`);
-        while (stack.length > 1 && indent <= stack[stack.length - 1].indent)
-            stack.pop();
-        const parent = stack[stack.length - 1].object;
-        const key = match[1];
-        const value = match[2] ?? '';
-        if (value === '') {
-            const child = {};
-            parent[key] = child;
-            stack.push({ indent, object: child });
-        }
-        else {
-            parent[key] = parseScalar(value);
-        }
-    }
-    return root;
-}
-function parseScalar(value) {
-    const trimmed = value.trim();
-    if (trimmed === 'true')
-        return true;
-    if (trimmed === 'false')
-        return false;
-    if (trimmed === 'null')
-        return null;
-    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
-        const inner = trimmed.slice(1, -1).trim();
-        if (!inner)
-            return [];
-        return inner.split(',').map((item) => String(parseScalar(item.trim())));
-    }
-    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
-        return trimmed.slice(1, -1);
+    const parsed = rawYaml.trim() === '' ? {} : parse(rawYaml);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('Frontmatter must be a YAML mapping');
     }
-    return trimmed;
+    return { data: parsed, body };
 }
 export function stringifyYaml(data) {
-    const lines = Object.entries(data).flatMap(([key, value]) => stringifyYamlValue(key, value, 0));
-    return `---\n${lines.join('\n')}\n---\n\n`;
-}
-function stringifyYamlValue(key, value, indent) {
-    const prefix = ' '.repeat(indent);
-    if (value && typeof value === 'object' && !Array.isArray(value)) {
-        return [`${prefix}${key}:`, ...Object.entries(value).flatMap(([childKey, childValue]) => stringifyYamlValue(childKey, childValue, indent + 2))];
-    }
-    if (Array.isArray(value))
-        return [`${prefix}${key}: [${value.map(formatScalar).join(', ')}]`];
-    return [`${prefix}${key}: ${formatScalar(value)}`];
-}
-function formatScalar(value) {
-    if (typeof value === 'boolean')
-        return value ? 'true' : 'false';
-    if (typeof value === 'number')
-        return String(value);
-    const text = String(value ?? '');
-    return /^[A-Za-z0-9_./,@* -]+$/.test(text) && text !== '' ? text : JSON.stringify(text);
+    const yaml = stringify(data, { lineWidth: 0, defaultKeyType: 'PLAIN' });
+    return `---\n${yaml}---\n\n`;
 }

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

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

package/dist/src/processor.js

@@ -1,4 +1,4 @@
-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';
@@ -6,14 +6,16 @@ import { renderCodexAgent, renderCodexSkill } from './adapters/codex.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 allowedTopLevel = new Set(['name', 'description', 'kind', 'claude', 'opencode', 'codex']);
+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']);
 export function resolvePlatforms(platform) {
     return platform === 'all' ? platforms : [platform];
 }
@@ -25,45 +27,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 +76,95 @@ 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 }));
+    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)
+        }
+    };
 }
 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) : renderCodexAgent(artifact)
+        : platform === 'opencode' ? renderOpenCodeSkill(artifact) : platform === 'claude' ? renderClaudeSkill(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/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.3.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.