@guidobuilds/forge-ai 0.3.0 → 0.5.0

package/artifacts/using-forge/using-forge.md

@@ -46,6 +46,10 @@ Use the lightest safe routing for the current request. Common worker work types
 
 Use artifacts in `.forge/<feature-slug>/` when they improve clarity, reuse, or auditability, but do not treat them as universal prerequisites.
 
+## Route announcement
+
+Before the first dispatch, state the chosen route to the user: work types joined by arrows (e.g. `build -> verify`, `inspect -> build -> verify`, `inspect -> design -> plan -> build -> verify`), whether a `forge-grill` pass runs before build and an independent verify or `forge-adversary` gate runs after, and one clause on why it is the lightest safe route. Re-announce only when the route changes materially mid-flight.
+
 ## Dispatch strategies
 
 Choose between three dispatch strategies at runtime:
@@ -71,10 +75,17 @@ Avoid parallel dispatch when:
 
 - Never do worker work inline.
 - Translate the request into goal, constraints, and safest routing before delegating.
+- Announce the chosen route to the user before the first dispatch (see Route announcement).
+- Run `forge-grill` proactively: stress-test any plan or design before build when work is non-trivial, risk-bearing, multi-step, or carries unresolved assumptions. Skip for trivial, surgical, or read-only work.
 - Delegate all development and operational execution to `forge-worker`.
 - Prefer one bounded worker run when it is sufficient; add more runs only when they reduce ambiguity, risk, or elapsed time.
 - Do not let workers silently infer missing build-shaping goals.
 - If a worker returns `blocked`, decide whether to ask the user, refine the subgoal, or launch another worker run for more inspection.
+- Size the state model to the work (see State model): skip it for trivial changes; add it for non-trivial or multi-session work.
+- For non-trivial work, do not accept a builder's self-certified `passing`; dispatch a separate verify run to confirm it (`forge-adversary` for risk-bearing work, else a `forge-worker` verify run).
+- Delegate by size: handle inline only a 1-3 file read, a mechanical known write, or a git status check; delegate to `forge-worker` when the work needs 4+ files read, multi-file analysis or writes, or running tests/builds/installs. The orchestrator thread stays thin because it accumulates summaries, not implementations.
+- Assign an effort level per dispatch (see Effort routing).
+- When `.forge/repo-facts.md` or `.forge/lessons.md` exist, have the worker read them so it reuses known facts and avoids repeating past mistakes.
 
 ## Approval heuristics
 
@@ -87,16 +98,72 @@ Approvals depend on the action being authorized and the risk of that action, not
 - If the requested action is already explicit and low-risk, do not create artificial gates.
 - If a materially important decision is unresolved, use the worker contract to escalate it and keep the user thread in the orchestrator.
 
+## Effort routing
+
+Match model effort to the work, not the reverse — higher effort spends more reasoning and tool calls, not more speed, so over-spending wastes tokens and time for the same result. State an effort level in each dispatch:
+
+- **low**: `inspect`, `verify`, `operate`, and routine/mechanical `build`.
+- **medium**: most `build` and `plan`.
+- **high**: `design`, hard trade-offs, synthesis across many worker results, or genuinely novel build.
+
+When unsure, start low and escalate only if the result is insufficient. The host harness owns actual model selection; this is the routing intent the orchestrator states and the worker honors.
+
 ## Artifact toolkit
 
-Preferred durable artifacts remain:
+Preferred process artifacts (write when they help future runs or clarify approval state):
 
 - `.forge/<feature-slug>/explore.md`
 - `.forge/<feature-slug>/design.md`
 - `.forge/<feature-slug>/plan.md`
 - `.forge/<feature-slug>/build-log.md`
 
-Use them when they help future runs or clarify approval state. Skip them when they would add ceremony without reducing risk.
+State-model artifacts (the source of truth for non-trivial or multi-session work, see State model):
+
+- `.forge/<feature-slug>/feature-list.json` — unit-of-work ledger: `behavior` + `verification` + `state`
+- `.forge/<feature-slug>/verification.md` — recorded verification evidence (the Definition of Done store)
+- `.forge/<feature-slug>/progress.md` — session continuity log
+- `.forge/<feature-slug>/session-handoff.md` — cross-session / blocked handoff
+
+Project-scoped files (persist across features, not under a slug):
+
+- `.forge/repo-facts.md` — durable stack/commands/conventions/constraints (the standing "where to go" spec)
+- `.forge/lessons.md` — topic-keyed accumulated lessons (the Feedback ratchet)
+- `.forge/index.md` — one-line-per-slug cross-task ledger
+
+Skip any artifact when it would add ceremony without reducing risk. `forge-worker` owns the exact schema and templates.
+
+## State model (adaptive)
+
+Size the state model to the work so the lightest safe workflow stays the default.
+
+- **Trivial / surgical** (single-file, low-risk, obvious, no cross-session memory): no state artifacts. Route `build -> verify` (or `inspect -> build -> verify`). The builder may self-verify.
+- **Single non-trivial feature**: create `feature-list.json` and `verification.md`. A separate verify dispatch must record evidence before any feature reaches `passing`.
+- **Multi-feature / multi-session / blocked / handoff-likely**: also create `progress.md` and `session-handoff.md`; carry multiple `feature-list.json` entries with `dependencies`.
+
+Triggers:
+- Create `feature-list.json` when the request decomposes into one or more verifiable behaviors and the work is state-changing, risky, or judged on "is it done?".
+- Create `progress.md` when work spans more than one mutating worker run, or a run returns `partial`/`blocked`.
+- Create `session-handoff.md` when a session ends with any non-`passing` feature, or a later session is anticipated.
+- Bootstrap `.forge/repo-facts.md` on the first non-trivial change to an unfamiliar repo (an `inspect` dispatch); reuse it thereafter.
+- Record lessons in `.forge/lessons.md` after any run that made a decision, fixed a non-obvious bug, set a convention, or hit a failure.
+- Never create state artifacts for read-only inspection or one-shot obvious edits.
+
+Feature `state` is one of `not_started | active | blocked | passing`. The orchestrator owns transitions: a builder may move `not_started -> active`, but only a verify dispatch (`forge-adversary` or a `forge-worker` verify run) moves a feature to `passing` (or `-> blocked` on failure).
+
+Closure: when a feature reaches `passing`, the verify dispatch flushes durable lessons to `.forge/lessons.md` and appends a line to `.forge/index.md`. When all features in a slug are `passing` and their `archiveWhen` conditions hold, the slug may be archived under `.forge/_archive/<slug>/`.
+
+## Definition of Done
+
+A feature's `state` may become `passing` only when ALL hold:
+
+1. its `verification` command was actually run,
+2. the result is recorded in `.forge/<feature-slug>/verification.md` (command + output excerpt + pass verdict + timestamp),
+3. `evidence` in `feature-list.json` points to that entry,
+4. every `id` in its `dependencies` is already `passing`.
+
+No feature moves to `passing` on assertion alone, and never by weakening, deleting, skipping, or stubbing the check; the recorded output must actually exercise the named `behavior`. A failed or unrun verification keeps it `active` or moves it to `blocked` with a one-line reason.
+
+Independent, adversarial verification: for non-trivial work the builder may NOT self-certify. Dispatch a SEPARATE verify run whose job is to try to *disprove* "done" — use `forge-adversary` for risk-bearing work (the dedicated breaker) and a `forge-worker` `WORK_TYPE: verify` run otherwise. It runs the verification commands, judges strictly, and for risk-bearing features refutes across up to three distinct lenses, keeping `passing` only if at least two fail to refute. It writes `verification.md` (logging refuted/uncertain candidates too) and flips states. Build and verify are different instances. Trivial-tier work is exempt.
 
 ## Contract enforcement
 

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

@@ -0,0 +1,37 @@
+// Canonical tool names used in Grok Build agent-profile frontmatter (tools: / disallowedTools: fields).
+// The CLI --tools/--disallowed-tools flags use shorter aliases (e.g. "grep" for grep_search,
+// "bash" for run_terminal_cmd). Both forms are accepted here to avoid spurious warnings.
+export const knownGrokTools = new Set([
+    'read_file',
+    'search_replace',
+    'grep_search',
+    'grep', // CLI alias for grep_search
+    'list_dir',
+    'run_terminal_cmd',
+    'bash', // display alias for run_terminal_cmd
+    'web_search',
+    'web_fetch',
+    'todo_write',
+    'task',
+    'kill_task',
+    'get_task_output',
+    'memory_search',
+    'memory_get',
+    'search_tool',
+    'use_tool',
+    'lsp'
+]);
+export function isKnownGrokTool(name) {
+    return knownGrokTools.has(name);
+}
+export const knownGrokModels = new Set([
+    'inherit',
+    'grok-build',
+    'grok-build-plan',
+    'grok-composer-2.5-fast'
+]);
+const grokVersionedModelPattern = /^grok-[a-z0-9.-]+$/;
+const gatewayModelPattern = /^[a-z0-9-]+\/[a-z0-9.-]+$/;
+export function isKnownGrokModel(value) {
+    return knownGrokModels.has(value) || grokVersionedModelPattern.test(value) || gatewayModelPattern.test(value);
+}

package/dist/src/adapters/grok.js

@@ -0,0 +1,41 @@
+import { stringifyYaml } from '../frontmatter.js';
+import { diagnostic } from '../diagnostics.js';
+import { isKnownGrokModel, isKnownGrokTool } from './grok-known.js';
+import { isRecord, patternList, stringList } from './shared.js';
+export function renderGrokAgent(artifact) {
+    const diagnostics = [];
+    const fm = { name: artifact.name, description: artifact.description };
+    if (artifact.grok?.model) {
+        fm.model = artifact.grok.model;
+        if (!isKnownGrokModel(artifact.grok.model)) {
+            diagnostics.push(diagnostic('warning', 'GROK_UNKNOWN_MODEL', `Unknown Grok model "${artifact.grok.model}" for ${artifact.name}`, { platform: 'grok' }));
+        }
+    }
+    const permissions = artifact.grok?.permissions;
+    const tools = isRecord(permissions) ? stringList(permissions.tools) : stringList(permissions);
+    if (tools) {
+        fm.tools = tools; // YAML sequence — Grok expects tools as a list, not comma-joined
+        for (const tool of tools) {
+            if (!isKnownGrokTool(tool)) {
+                diagnostics.push(diagnostic('warning', 'GROK_UNKNOWN_TOOL', `Unknown Grok tool "${tool}" for ${artifact.name}`, { platform: 'grok' }));
+            }
+        }
+    }
+    else if (permissions !== undefined) {
+        diagnostics.push(diagnostic('info', 'GROK_AGENT_TOOLS_IGNORED', `Grok agent permissions must be a tools string list for ${artifact.name}`, { platform: 'grok' }));
+    }
+    const disallowedTools = isRecord(permissions) ? patternList(permissions['disallowedTools']) : undefined;
+    if (disallowedTools)
+        fm.disallowedTools = disallowedTools;
+    return { content: `${stringifyYaml(fm)}${artifact.body}\n`, diagnostics };
+}
+export function renderGrokSkill(artifact) {
+    const diagnostics = [];
+    if (artifact.grok?.permissions !== undefined) {
+        diagnostics.push(diagnostic('info', 'GROK_SKILL_PERMISSIONS_IGNORED', `Grok skill permissions are not emitted for ${artifact.name}`, { platform: 'grok' }));
+    }
+    if (artifact.grok?.model) {
+        diagnostics.push(diagnostic('info', 'GROK_SKILL_MODEL_IGNORED', `Grok skill model is not emitted for ${artifact.name}`, { platform: 'grok' }));
+    }
+    return { content: `${stringifyYaml({ name: artifact.name, description: artifact.description })}${artifact.body}\n`, diagnostics };
+}

package/dist/src/cli.js

@@ -8,6 +8,8 @@ import { fileURLToPath } from 'node:url';
 import { formatDiagnostic, hasErrors } from './diagnostics.js';
 import { buildManifest, classifyPruneEntries, loadManifest, pruneEntries, resolveBackupPath, resolveBackupRoot, resolveManifestLocation, saveManifest, staleEntries } from './manifest.js';
 import { buildWritePlan, parsePlatform, parseScope } from './processor.js';
+import { runSelfUpdate } from './self-update.js';
+import { checkLatestVersion, formatVersionNotice } from './version-check.js';
 import { writeOutputs } from './writer.js';
 import { hasPendingDecisions } from './model.js';
 const emptyPrunePlan = { deletable: [], modifiedWithConsent: [], skippedMissing: [] };
@@ -32,108 +34,129 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
         showUsage();
         return 1;
     }
-    const install = command === 'install' || command === 'update';
-    if (install && !options.sourceExplicit)
-        options.source = bundledSourceRoot();
-    if (command === 'update' || options.yes)
-        options.force = true;
-    const interactive = install && isInteractivePrompt(promptIO);
-    if (interactive)
-        p.intro(`${pc.bold('Forge AI')} ${pc.dim(command === 'update' ? 'updater' : 'installer')}`, clackIO(promptIO));
-    if (install) {
-        const prompted = await promptForMissingInstallOptions(options, promptIO);
-        if (!prompted) {
-            if (interactive)
-                p.cancel('Cancelled', clackIO(promptIO));
-            return 1;
-        }
-    }
-    const cwd = process.cwd();
-    const home = resolveHome(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);
+    if (command === 'self-update') {
+        return runSelfUpdate({
+            binaryPath: process.argv[1] ?? bundledSourceRoot(),
+            version: options.targetVersion,
+            dryRun: options.dryRun,
+            skipSpecUpdate: options.skipSpecUpdate,
+        });
     }
-    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 versionCheckPromise = shouldCheckForUpdates(options, promptIO)
+        ? checkLatestVersion({ current: readPackageVersion(), cachePath: path.join(resolveHome(promptIO), '.forge-ai', 'version-check.json') }).catch(() => undefined)
+        : Promise.resolve(undefined);
+    try {
+        const install = command === 'install' || command === 'update';
+        if (install && !options.sourceExplicit)
+            options.source = bundledSourceRoot();
+        if (command === 'update' || options.yes)
+            options.force = true;
+        const interactive = install && isInteractivePrompt(promptIO);
+        if (interactive)
+            p.intro(`${pc.bold('Forge AI')} ${pc.dim(command === 'update' ? 'updater' : 'installer')}`, clackIO(promptIO));
+        if (install) {
+            const prompted = await promptForMissingInstallOptions(options, promptIO);
+            if (!prompted) {
+                if (interactive)
+                    p.cancel('Cancelled', clackIO(promptIO));
+                return 1;
+            }
         }
-        const accepted = await promptForUpdate(plan, prunePlan, backupRoot, promptIO);
-        if (accepted === undefined) {
-            p.cancel('Cancelled', clackIO(promptIO));
-            return 1;
+        const cwd = process.cwd();
+        const home = resolveHome(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);
         }
-        if (!accepted) {
-            p.outro(pc.yellow('Forge was not installed.'), clackIO(promptIO));
+        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) {
+                p.cancel('Cancelled', clackIO(promptIO));
+                return 1;
+            }
+            if (!accepted) {
+                p.outro(pc.yellow('Forge was not installed.'), clackIO(promptIO));
+                return 1;
+            }
+        }
+        printPlan(command, plan.sourceCount, plan.files, plan.diagnostics, prunePlan);
+        if (hasErrors(plan.diagnostics)) {
+            if (interactive)
+                p.outro(pc.red('Forge was not installed.'), clackIO(promptIO));
             return 1;
         }
-    }
-    printPlan(command, plan.sourceCount, plan.files, plan.diagnostics, prunePlan);
-    if (hasErrors(plan.diagnostics)) {
-        if (interactive)
-            p.outro(pc.red('Forge was not installed.'), clackIO(promptIO));
-        return 1;
-    }
-    if (install && !options.dryRun) {
-        if (interactive) {
-            const spinner = p.spinner(clackIO(promptIO));
-            spinner.start(options.force ? 'Updating Forge files' : 'Installing Forge files');
-            try {
+        if (install && !options.dryRun) {
+            if (interactive) {
+                const spinner = p.spinner(clackIO(promptIO));
+                spinner.start(options.force ? 'Updating Forge files' : 'Installing Forge files');
+                try {
+                    await writeOutputs(plan.files);
+                    if (command === 'update' && options.prune)
+                        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) {
+                    spinner.error('Failed to write Forge files');
+                    throw error;
+                }
+            }
+            else {
                 await writeOutputs(plan.files);
                 if (command === 'update' && options.prune)
                     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) {
-                spinner.error('Failed to write Forge files');
-                throw error;
+                console.log(`Wrote ${plan.files.length} 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}.`);
             }
         }
-        else {
-            await writeOutputs(plan.files);
-            if (command === 'update' && options.prune)
-                await pruneEntries([...prunePlan.deletable, ...prunePlan.modifiedWithConsent]);
-            await saveManifest(manifestLocation.manifestPath, await buildManifest(manifestLocation, plan.files));
-            console.log(`Wrote ${plan.files.length} 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}.`);
+        else if (install && interactive) {
+            p.log.info(`Dry run only. ${plan.files.length} file(s) would be written.`, clackIO(promptIO));
         }
+        if (install && interactive) {
+            p.outro(options.dryRun ? pc.cyan('Dry run complete.') : pc.green('Forge is ready.'), clackIO(promptIO));
+        }
+        return 0;
     }
-    else if (install && interactive) {
-        p.log.info(`Dry run only. ${plan.files.length} file(s) would be written.`, clackIO(promptIO));
-    }
-    if (install && interactive) {
-        p.outro(options.dryRun ? pc.cyan('Dry run complete.') : pc.green('Forge is ready.'), clackIO(promptIO));
+    finally {
+        const result = await versionCheckPromise;
+        if (result) {
+            const notice = formatVersionNotice(result);
+            if (notice)
+                console.log(notice);
+        }
     }
-    return 0;
 }
 function parseArgs(argv) {
-    const options = { command: argv[0], platform: 'all', scope: 'user', source: '.', dryRun: false, force: false, prune: true, yes: false, platformExplicit: false, scopeExplicit: false, sourceExplicit: false };
+    const options = { command: argv[0], platform: 'all', scope: 'user', source: '.', dryRun: false, force: false, prune: true, yes: false, noUpdateCheck: false, skipSpecUpdate: false, platformExplicit: false, scopeExplicit: false, sourceExplicit: false };
     for (let index = 1; index < argv.length; index += 1) {
         const arg = argv[index];
         if (arg === '--dry-run')
@@ -144,6 +167,16 @@ function parseArgs(argv) {
             options.prune = false;
         else if (arg === '--yes' || arg === '-y')
             options.yes = true;
+        else if (arg === '--no-update-check')
+            options.noUpdateCheck = true;
+        else if (arg === '--skip-spec-update')
+            options.skipSpecUpdate = true;
+        else if (arg === '--to') {
+            const value = argv[++index];
+            if (!value)
+                return { error: 'Missing --to value' };
+            options.targetVersion = value;
+        }
         else if (arg === '--platform') {
             const value = argv[++index];
             const platform = value ? parsePlatform(value) : undefined;
@@ -176,6 +209,10 @@ function parseArgs(argv) {
         return { error: '--no-prune is only accepted for update' };
     if (command === 'validate' && (options.dryRun || options.force || options.yes || options.scopeExplicit))
         return { error: 'validate only accepts --platform and --source' };
+    if (command !== 'self-update' && (options.targetVersion !== undefined || options.skipSpecUpdate))
+        return { error: '--to and --skip-spec-update are only accepted for self-update' };
+    if (command === 'self-update' && (options.platformExplicit || options.scopeExplicit || options.sourceExplicit || options.force || options.yes))
+        return { error: 'self-update only accepts --to, --dry-run, --skip-spec-update' };
     return { options };
 }
 async function classifyPrune(oldManifest, files, backupRoot, scope, cwd, home) {
@@ -205,10 +242,11 @@ async function promptForMissingInstallOptions(options, promptIO) {
             message: 'Install Forge for which coding agent?',
             initialValue: 'all',
             options: [
-                { value: 'all', label: 'All supported agents', hint: 'OpenCode, Codex, and Claude Code' },
+                { value: 'all', label: 'All supported agents', hint: 'OpenCode, Codex, Claude Code, and Grok Build' },
                 { value: 'opencode', label: 'OpenCode' },
                 { value: 'codex', label: 'Codex' },
-                { value: 'claude', label: 'Claude Code' }
+                { value: 'claude', label: 'Claude Code' },
+                { value: 'grok', label: 'Grok Build' }
             ],
             ...io
         });
@@ -265,8 +303,23 @@ function normalizeCommand(command) {
         return 'update';
     if (command === 'validate')
         return 'validate';
+    if (command === 'self-update')
+        return 'self-update';
     return undefined;
 }
+function shouldCheckForUpdates(options, promptIO) {
+    if (options.noUpdateCheck)
+        return false;
+    const env = promptIO.env ?? process.env;
+    if (env.CI === 'true')
+        return false;
+    if (env.FORGE_NO_UPDATE_CHECK === '1' || env.FORGE_NO_UPDATE_CHECK === 'true')
+        return false;
+    // Skip in non-interactive runs (pipes, CI, scripts): the notice is a UX nudge for terminal users.
+    if (!isInteractivePrompt(promptIO))
+        return false;
+    return true;
+}
 function isInteractivePrompt(promptIO) {
     const env = promptIO.env ?? process.env;
     const interactive = promptIO.isInteractive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
@@ -291,9 +344,12 @@ function readPackageVersion() {
     }
 }
 function showUsage() {
-    console.log('Usage: forge-ai install [--platform opencode|claude|codex|all] [--scope user|project] [--source <dir>] [--dry-run] [--force] [--yes]');
-    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>]');
+    console.log('Usage: forge-ai install [--platform opencode|claude|codex|grok|all] [--scope user|project] [--source <dir>] [--dry-run] [--force] [--yes]');
+    console.log('       forge-ai update [--platform opencode|claude|codex|grok|all] [--scope user|project] [--source <dir>] [--dry-run] [--no-prune] [--yes]');
+    console.log('       forge-ai validate [--platform opencode|claude|codex|grok|all] [--source <dir>]');
+    console.log('       forge-ai self-update [--to <version>] [--dry-run] [--skip-spec-update]');
+    console.log('');
+    console.log('Global flags: --no-update-check (also FORGE_NO_UPDATE_CHECK=1 or CI=true)');
 }
 function printPlan(command, sourceCount, files, diagnostics, prunePlan) {
     console.log(`${command}: ${sourceCount} source(s), ${files.length} output(s)`);

package/dist/src/model.js

@@ -1,4 +1,4 @@
-export const platforms = ['opencode', 'claude', 'codex'];
+export const platforms = ['opencode', 'claude', 'codex', 'grok'];
 export function isPlatform(value) {
     return platforms.includes(value);
 }

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

@@ -3,6 +3,7 @@ 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';
@@ -10,12 +11,14 @@ 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', 'kind', 'claude', 'opencode', 'codex']);
+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];
 }
@@ -112,6 +115,10 @@ function convertSource(source, sourceRoot) {
         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', '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 };
     return {
@@ -124,7 +131,8 @@ function convertSource(source, sourceRoot) {
             sourcePath: path.relative(path.resolve(sourceRoot), source.sourcePath),
             claude: productConfig(data.claude),
             opencode: productConfig(data.opencode),
-            codex: productConfig(data.codex)
+            codex: productConfig(data.codex),
+            grok: productConfig(data.grok)
         }
     };
 }
@@ -133,8 +141,8 @@ function productConfig(value) {
 }
 function renderFile(platform, kind, artifact, options, diagnostics) {
     const rendered = kind === 'agent'
-        ? platform === 'opencode' ? renderOpenCodeAgent(artifact) : platform === 'claude' ? renderClaudeAgent(artifact) : renderCodexAgent(artifact)
-        : platform === 'opencode' ? renderOpenCodeSkill(artifact) : platform === 'claude' ? renderClaudeSkill(artifact) : renderCodexSkill(artifact);
+        ? 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: artifact.name, sourcePath: artifact.sourcePath, path: resolveOutputPath(platform, kind, options.scope, artifact.name, options.cwd, options.home), content: rendered.content };
 }

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 };
+}