@guidobuilds/forge-ai 0.1.0 → 0.2.0

package/README.md

@@ -77,7 +77,7 @@ The same operating model is shared across all supported agents so the workflow s
 The primary installer is the npm CLI:
 
 ```sh
-npx forge-ai install
+npx @guidobuilds/forge-ai install
 ```
 
 The installer prompts for the target agent platform and whether Forge should be installed globally for your user or locally for the current project.
@@ -85,25 +85,25 @@ The installer prompts for the target agent platform and whether Forge should be
 To update an existing install:
 
 ```sh
-npx forge-ai update
+npx @guidobuilds/forge-ai update
 ```
 
 For non-interactive environments:
 
 ```sh
-npx forge-ai install --platform all --scope user --yes
+npx @guidobuilds/forge-ai install --platform all --scope user --yes
 ```
 
 Preview the files without writing them:
 
 ```sh
-npx forge-ai install --platform all --scope user --dry-run
+npx @guidobuilds/forge-ai install --platform all --scope user --dry-run
 ```
 
 Validate a local Forge source tree:
 
 ```sh
-npx forge-ai validate --source .
+npx @guidobuilds/forge-ai validate --source .
 ```
 
 ## Local Development
@@ -127,11 +127,13 @@ node bin/forge-ai.mjs install --source . --platform all --scope project --dry-ru
 Run the npm updater:
 
 ```sh
-npx forge-ai update
+npx @guidobuilds/forge-ai update
 ```
 
 Forge replaces its managed agent and skill definitions in your supported agent configuration directories.
 
+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.
+
 ## Uninstalling
 
 Remove Forge from the agent configuration directories for OpenCode, Codex, or Claude Code by deleting the installed Forge agent and skill entries.

package/dist/src/cli.js

@@ -2,9 +2,11 @@
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { readFileSync } from 'node:fs';
+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 { buildWritePlan, parsePlatform, parseScope } from './processor.js';
 import { writeOutputs } from './writer.js';
 export async function main(argv = process.argv.slice(2), promptIO = {}) {
@@ -44,7 +46,9 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
             return 1;
         }
     }
-    let plan = await buildWritePlan({ source: options.source, platform: options.platform, scope: options.scope, checkCollisions: install && !options.dryRun, force: options.force });
+    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);
         if (accepted === undefined) {
@@ -54,10 +58,18 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
         }
         if (accepted) {
             options.force = true;
-            plan = await buildWritePlan({ source: options.source, platform: options.platform, scope: options.scope, checkCollisions: true, force: true });
+            plan = await buildWritePlan({ source: options.source, platform: options.platform, scope: options.scope, cwd, home, checkCollisions: true, force: true });
         }
     }
-    printPlan(command, plan.sourceCount, plan.files, plan.diagnostics);
+    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)
             p.outro(pc.red('Forge was not installed.'), clackIO(promptIO));
@@ -69,6 +81,9 @@ export async function main(argv = process.argv.slice(2), 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);
+                await saveManifest(manifestLocation.manifestPath, buildManifest(manifestLocation, plan.files));
                 spinner.stop(`Wrote ${plan.files.length} file(s).`);
             }
             catch (error) {
@@ -78,7 +93,13 @@ 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));
             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).`);
+            console.log(`Updated manifest ${manifestLocation.manifestPath}.`);
         }
     }
     else if (install && interactive) {
@@ -90,13 +111,15 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
     return 0;
 }
 function parseArgs(argv) {
-    const options = { command: argv[0], platform: 'all', scope: 'user', source: '.', dryRun: false, force: false, 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, platformExplicit: false, scopeExplicit: false, sourceExplicit: false };
     for (let index = 1; index < argv.length; index += 1) {
         const arg = argv[index];
         if (arg === '--dry-run')
             options.dryRun = true;
         else if (arg === '--force')
             options.force = true;
+        else if (arg === '--no-prune')
+            options.prune = false;
         else if (arg === '--yes' || arg === '-y')
             options.yes = true;
         else if (arg === '--platform') {
@@ -127,6 +150,8 @@ function parseArgs(argv) {
         }
     }
     const command = normalizeCommand(options.command);
+    if (command !== 'update' && !options.prune)
+        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' };
     return { options };
@@ -209,6 +234,9 @@ function isInteractivePrompt(promptIO) {
 function clackIO(promptIO) {
     return { input: promptIO.input, output: promptIO.output };
 }
+function resolveHome(promptIO) {
+    return promptIO.env?.HOME || os.homedir();
+}
 function bundledSourceRoot() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 }
@@ -223,13 +251,19 @@ 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] [--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>]');
 }
-function printPlan(command, sourceCount, files, diagnostics) {
+function printPlan(command, sourceCount, files, diagnostics, prunePlan = { deletable: [], skipped: [] }) {
     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}`);
+    }
     for (const item of diagnostics)
         console.log(formatDiagnostic(item));
 }

package/dist/src/manifest.js

@@ -0,0 +1,101 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { access, mkdir, readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export async function resolveManifestLocation(scope, cwd = process.cwd(), home) {
+    const stateRoot = path.join(home, '.forge-ai');
+    if (scope === 'user')
+        return { stateRoot, manifestPath: path.join(stateRoot, 'user-manifest.json'), scope };
+    const projectPath = await canonicalProjectPath(cwd);
+    const projectPathHash = hashProjectPath(projectPath);
+    return { stateRoot, manifestPath: path.join(stateRoot, 'projects', projectPathHash, 'manifest.json'), scope, projectPath, projectPathHash };
+}
+export async function loadManifest(manifestPath) {
+    try {
+        return JSON.parse(await readFile(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+export function buildManifest(location, files, now = new Date()) {
+    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)
+        }))
+    };
+}
+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 staleEntries(oldManifest, files) {
+    if (!oldManifest)
+        return [];
+    const currentPaths = new Set(files.map((file) => file.path));
+    return oldManifest.entries.filter((entry) => !currentPaths.has(entry.path));
+}
+export async function classifyPruneEntries(entries) {
+    const deletable = [];
+    const skipped = [];
+    for (const entry of entries) {
+        let content;
+        try {
+            content = await readFile(entry.path, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                skipped.push({ ...entry, reason: 'missing' });
+            else
+                throw error;
+            continue;
+        }
+        if (sha256(content) === entry.checksum)
+            deletable.push(entry);
+        else
+            skipped.push({ ...entry, reason: 'checksum-mismatch' });
+    }
+    return { deletable, skipped };
+}
+export async function pruneEntries(entries) {
+    for (const entry of entries) {
+        await rm(entry.path, { force: true });
+        if (entry.kind === 'skill')
+            await removeEmptyParent(path.dirname(entry.path));
+    }
+}
+export function sha256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+export function hashProjectPath(projectPath) {
+    return sha256(projectPath).slice(0, 32);
+}
+async function canonicalProjectPath(cwd) {
+    try {
+        return await realpath(cwd);
+    }
+    catch {
+        return path.resolve(cwd);
+    }
+}
+async function removeEmptyParent(directory) {
+    try {
+        await access(directory, constants.F_OK);
+        await rm(directory);
+    }
+    catch {
+        // Directory does not exist or is not empty; both are safe to ignore.
+    }
+}

package/dist/src/processor.js

@@ -1,5 +1,6 @@
 import { access } from 'node:fs/promises';
 import { constants } from 'node:fs';
+import path from 'node:path';
 import { renderClaudeAgent, renderClaudeSkill } from './adapters/claude.js';
 import { renderCodexAgent, renderCodexSkill } from './adapters/codex.js';
 import { renderOpenCodeAgent, renderOpenCodeSkill } from './adapters/opencode.js';
@@ -29,7 +30,7 @@ export async function buildWritePlan(options) {
     const seenAgents = new Set();
     const seenSkills = new Set();
     for (const source of sources) {
-        const converted = convertSource(source);
+        const converted = convertSource(source, options.source);
         diagnostics.push(...converted.diagnostics);
         if (!converted.item)
             continue;
@@ -58,7 +59,7 @@ export async function buildWritePlan(options) {
     }
     return { files, diagnostics, sourceCount: sources.length };
 }
-function convertSource(source) {
+function convertSource(source, sourceRoot) {
     const diagnostics = [];
     const data = source.data;
     const name = typeof data.name === 'string' ? data.name : undefined;
@@ -99,7 +100,7 @@ function convertSource(source) {
         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'))
         return { diagnostics };
-    const base = { name, description, claude: productConfig(data.claude), opencode: productConfig(data.opencode), codex: productConfig(data.codex) };
+    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 } };
 }
 function productConfig(value) {
@@ -110,7 +111,7 @@ function renderFile(platform, kind, item, options, diagnostics) {
         ? platform === 'opencode' ? renderOpenCodeAgent(item) : platform === 'claude' ? renderClaudeAgent(item) : renderCodexAgent(item)
         : platform === 'opencode' ? renderOpenCodeSkill(item) : platform === 'claude' ? renderClaudeSkill(item) : renderCodexSkill(item);
     diagnostics.push(...rendered.diagnostics);
-    return { platform, kind, scope: options.scope, name: item.name, path: resolveOutputPath(platform, kind, options.scope, item.name, options.cwd, options.home), content: rendered.content };
+    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 };
 }
 async function collisionDiagnostics(files, force) {
     const diagnostics = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guidobuilds/forge-ai",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Forge AI framework",
   "license": "MIT",
   "type": "module",

package/skills/forge-grill/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: forge-grill
+description: Stress-test a plan or design through Forge orchestration, batching user questions while delegating codebase-answerable work to forge-worker.
+---
+
+# Forge Grill Skill
+
+## Role
+
+Use this skill when the user wants Forge to stress-test, challenge, or "grill" a plan, design, proposal, or implementation approach.
+
+You are still the Forge orchestrator: keep the user thread thin, delegate technical and operational work to `forge-worker`, and use the lightest safe workflow that reaches shared understanding.
+
+## Core behavior
+
+- Build a decision tree for the plan or design under review.
+- Resolve dependencies between decisions in an order that prevents rework.
+- Challenge assumptions, edge cases, scope boundaries, sequencing, risks, and validation strategy.
+- Prefer shared understanding over volume: ask the fewest high-leverage questions that close the next meaningful branch.
+- Do not perform worker work inline.
+
+## Question policy
+
+- Use the `question` tool for questions that require the user's judgment, preference, product intent, approval, or risk tolerance.
+- Group related questions into small batches, usually 2-4 questions, instead of asking one question at a time.
+- For each question or option, include Forge's recommended answer and a brief rationale so the user can accept or correct it quickly.
+- Keep each batch focused on one decision branch or tightly related set of branches.
+- Do not ask the user questions that can be answered by inspecting the repository, existing artifacts, logs, tests, or documentation available in the workspace.
+
+## Delegation policy
+
+When a question can be answered by exploring the codebase or existing Forge artifacts, launch `forge-worker` instead of asking the user.
+
+Use `forge-worker` for:
+
+- repository inspection
+- artifact review
+- validation checks
+- feasibility or integration discovery
+- implementation-plan consistency checks
+- technical risk investigation
+
+Keep each worker prompt bounded and explicit about:
+
+- the plan/design branch being tested
+- what facts to inspect
+- what is out of scope
+- expected validation or evidence
+- that the worker must not ask the user directly
+
+## Worker contract enforcement
+
+Every delegated worker run must return exactly the Forge worker contract:
+
+```text
+STATUS: success|partial|blocked
+WORK_TYPE: inspect|design|plan|build|operate|verify|mixed
+FEATURE_SLUG: <kebab-case>
+ARTIFACTS:
+- <path or None>
+SUMMARY:
+- <point>
+NEXT_RECOMMENDED: inspect|design|plan|build|operate|verify|ask-user|none
+RISKS:
+- <risk or None>
+QUESTIONS:
+1) <question>
+```
+
+`QUESTIONS` must appear only when `STATUS: blocked`.
+
+If a worker response is malformed, request one reformat retry for the same task. If it is malformed again, stop and surface an actionable orchestration error.
+
+## Grill workflow
+
+1. Restate the goal, known constraints, and the plan/design surface being grilled.
+2. Identify decision branches and separate them into:
+   - repo-answerable facts for `forge-worker`
+   - user-owned decisions for the `question` tool
+   - safe assumptions that can be stated and revisited
+3. Delegate repo-answerable inspection before asking the user about the same branch.
+4. Ask small batches of user-owned questions with a recommended answer for each.
+5. After each batch or worker result, update the decision tree and resolve dependent branches.
+6. Stop when the remaining unknowns are either resolved, explicitly accepted as risks, or safely deferred.
+
+## Output style to the user
+
+- Be direct and rigorous, but not performative.
+- Explain why each question matters.
+- Include recommendations in actionable language, such as "Recommended: choose A because...".
+- Make unresolved risk visible before moving to build, plan, or approval-seeking work.
+- If grilling reveals implementation work is needed, route it through the normal Forge worker model instead of doing it inline.

package/skills/forge-build/SKILL.md

@@ -1,80 +0,0 @@
----
-name: forge-build
-description: Implement approved scope from design and plan artifacts, then write build-log.md.
----
-
-# Forge Build Skill
-
-## Role
-Implement only approved scope.
-
-Build is for approved code implementation only.
-
-## Inputs
-
-- Orchestrator prompt with the approved implementation scope
-- Optional: `.forge/<feature-slug>/explore.md`
-- Optional: `.forge/<feature-slug>/design.md`
-- Optional: `.forge/<feature-slug>/plan.md`
-
-## Required output file
-
-`.forge/<feature-slug>/build-log.md`
-
-## Build log format
-
-- Executed plan steps
-- Files changed
-- Validation run and result
-- Deviations from plan and rationale
-- Follow-ups
-
-## Build rules
-
-- If a plan exists, do not expand scope beyond plan.
-- Before implementing, check whether `.forge/<feature-slug>/plan.md` exists.
-- If a plan exists, review it critically before touching code.
-- If a plan exists, require the orchestrator prompt to include evidence that the user explicitly approved starting build for that planned scope.
-- If a plan exists and that approval is absent or ambiguous, stop and return `STATUS: blocked` with approval questions instead of implementing.
-- If a plan exists and contains placeholders, missing dependencies, or non-buildable tasks, stop and return `STATUS: blocked` instead of guessing.
-- If no plan exists, treat the orchestrator prompt as the approved scope and keep the change tightly bounded.
-- If no plan exists, the direct-build path is allowed only when the orchestrator prompt clearly marks the request as a lightweight implementation.
-- Non-development operational tasks are out of scope for build.
-- Route non-development execution tasks such as git commit or git push to `forge-helper`.
-- If a step is materially ambiguous during execution, stop and return blocked with questions.
-- When a plan exists, record build-log progress against the reviewed plan rather than silently reshaping it.
-- Implement the minimum code necessary to satisfy the approved design and plan.
-- Do not perform adjacent refactors, cleanup passes, or abstraction work unless explicitly approved or required to complete the approved scope.
-- Prefer existing patterns over introducing new layers, frameworks, or indirection.
-
-## Pre-implementation checklist
-
-Before editing files, confirm:
-
-- the goal being implemented
-- the files expected to change
-- the validation that should prove the goal
-
-Apply this checklist on both plan-backed builds and lightweight direct-build paths.
-
-## Contract (strict)
-
-Return only:
-
-```text
-STATUS: success|partial|blocked
-PHASE: BUILD
-FEATURE_SLUG: <kebab-case>
-ARTIFACTS:
-- .forge/<feature-slug>/build-log.md
-SUMMARY:
-- <brief point>
-NEXT_RECOMMENDED: none
-RISKS:
-- <risk or None>
-QUESTIONS:
-1) <question>
-2) <question>
-```
-
-Include `QUESTIONS` only when blocked.

package/skills/forge-design/SKILL.md

@@ -1,104 +0,0 @@
----
-name: forge-design
-description: Create the canonical design artifact that merges product and technical design into design.md.
----
-
-# Forge Design Skill
-
-## Role
-Close critical design decisions and then produce the single design artifact for the work item.
-
-`design.md` is the default source of truth for both intended behavior and technical shape. There is no separate `tech.md` in this flow.
-
-## Inputs
-
-- `.forge/<feature-slug>/explore.md`
-- Feature request and user clarifications
-
-## Required output file
-
-`.forge/<feature-slug>/design.md`, but only after the clarification gate is fully closed.
-
-## Clarification gate
-
-Before writing `design.md`, review:
-
-- `.forge/<feature-slug>/explore.md`
-- the user request
-- prior user clarifications in the current thread
-
-Classify open questions into:
-
-- critical decisions that materially change behavior, scope, interface, or technical shape
-- non-critical details that can be fixed by a reasonable default
-
-Rules:
-
-- Resolve all critical decisions before writing `design.md`.
-- Do not ask questions that can be answered from the repo, existing artifacts, or docs.
-- Ask the smallest useful batch of independent questions.
-- Every question must include:
-  - the decision to resolve
-  - a recommended answer
-  - brief impact of that recommendation
-- If critical decisions remain, return `STATUS: blocked`, `NEXT_RECOMMENDED: design`, and do not write `design.md` yet.
-
-## Design format
-
-The document must stay compact and optimized for LLM consumption.
-
-Expected content:
-- Objective
-- Non-objectives
-- Decision Log
-- Requirements with stable `TASK-*` identifiers
-- Technical shape for those same `TASK-*` items
-- Constraints and dependencies that materially affect implementation
-- Acceptance checks
-
-## Design rules
-
-- Merge product and technical design into one artifact, but keep those concerns clearly separated by section.
-- Include only resolved design-relevant decisions in the `Decision Log`.
-- Reuse stable `TASK-*` identifiers across the artifact.
-- Be concrete about files, modules, integration points, and constraints when they materially shape implementation.
-- Do not turn `design.md` into an execution checklist; sequencing belongs in `plan.md`.
-- Use reasonable defaults only for non-critical details.
-- Do not write `design.md` with unresolved critical decisions.
-- Prefer the simplest design that satisfies the requested outcome and acceptance checks.
-- Avoid speculative abstractions or new indirection unless the request or current architecture requires them.
-- Record the important tradeoffs and defaults that downstream planning and build must preserve.
-- Escalate only decisions that materially change behavior, scope, interface, or technical shape.
-- If a heavier alternative was considered and rejected because it would expand scope or complexity, note that briefly when it helps preserve the approved shape.
-
-## Phase intent
-
-- `design.md` answers: what should change, and what is the intended technical shape?
-- It is the design source of truth for downstream planning and implementation after the clarification gate has been closed.
-
-## Contract (strict)
-
-Return only:
-
-```text
-STATUS: success|partial|blocked
-PHASE: DESIGN
-FEATURE_SLUG: <kebab-case>
-ARTIFACTS:
-- .forge/<feature-slug>/design.md | None
-SUMMARY:
-- <brief point>
-NEXT_RECOMMENDED: design|plan
-RISKS:
-- <risk or None>
-QUESTIONS:
-1) Decision: <decision>
-   Recommendation: <recommended answer>
-   Impact: <brief why>
-2) Decision: <decision>
-   Recommendation: <recommended answer>
-   Impact: <brief why>
-```
-
-Use `STATUS: blocked` when critical decisions still require user input.
-Include `QUESTIONS` only when blocked.

package/skills/forge-explore/SKILL.md

@@ -1,65 +0,0 @@
----
-name: forge-explore
-description: Explore the requested feature and write the baseline exploration artifact.
----
-
-# Forge Explore Skill
-
-## Role
-Explore the repository and produce a compact baseline for downstream design, planning, or build work.
-
-## Inputs
-
-- Work item request from the orchestrator prompt
-- Repository code and docs
-
-## Required output file
-
-`.forge/<feature-slug>/explore.md`
-
-## Exploration rules
-
-- Think before broadening the search. Prefer narrow reading and searching around likely files and symbols before wider repo scans.
-- Distinguish observed facts from inferred conclusions.
-- Capture assumptions, unknowns, tradeoffs, and critical decisions explicitly.
-- Record only the repo intersections that materially shape later design or implementation.
-- Escalate only missing information that meaningfully blocks design or safe execution.
-- Do not redesign the solution in `explore`; identify what exists, what is missing, and what decisions remain.
-
-## Explore format
-
-Keep the artifact compact and optimized for downstream LLM consumption.
-
-Expected content:
-- Problem framing
-- What already exists and current state
-- Relevant codepaths, modules, systems, and docs
-- Intersections with adjacent areas that may be affected
-- Assumptions
-- Unknowns
-- Tradeoffs
-- Critical decisions
-- Non-critical unknowns
-
-## Contract (strict)
-
-Return only:
-
-```text
-STATUS: success|partial|blocked
-PHASE: EXPLORE
-FEATURE_SLUG: <kebab-case>
-ARTIFACTS:
-- .forge/<feature-slug>/explore.md
-SUMMARY:
-- <brief point>
-NEXT_RECOMMENDED: design
-RISKS:
-- <risk or None>
-QUESTIONS:
-1) <question>
-2) <question>
-```
-
-Use `STATUS: blocked` only if missing information blocks meaningful exploration.
-Include `QUESTIONS` only when blocked.

package/skills/forge-helper/SKILL.md

@@ -1,46 +0,0 @@
----
-name: forge-helper
-description: Execute non-development helper tasks for the orchestrator.
----
-
-# Forge Helper Skill
-
-## Role
-Execute bounded non-development tasks for the orchestrator.
-
-## Scope rules
-
-- Do only the requested operational action.
-- Do not write code, edit source files, or broaden into software-development implementation work.
-- If the request is actually explore, design, plan, or build work, stop and tell the orchestrator to route it to the appropriate phase agent.
-- Keep execution tightly bounded to the requested helper task.
-- If the action could mutate protected or remote state, require explicit confirmation unless the orchestrator prompt already contains clear user intent for that exact action.
-- Do not broaden into workflow advice or extra repo operations unless asked.
-
-## Typical examples
-
-- create a git commit
-- push a branch
-- inspect non-development execution status needed by the orchestrator
-
-## Contract (strict)
-
-Return only:
-
-```text
-STATUS: success|partial|blocked
-PHASE: HELPER
-FEATURE_SLUG: <kebab-case>
-ARTIFACTS:
-- <path or None>
-SUMMARY:
-- <brief point>
-NEXT_RECOMMENDED: none
-RISKS:
-- <risk or None>
-QUESTIONS:
-1) <question>
-2) <question>
-```
-
-Include `QUESTIONS` only when blocked.

package/skills/forge-plan/SKILL.md

@@ -1,81 +0,0 @@
----
-name: forge-plan
-description: Create an execution plan from explore and design artifacts.
----
-
-# Forge Plan Skill
-
-## Role
-Create the execution plan from the approved design work.
-
-## Inputs
-
-- `.forge/<feature-slug>/explore.md`
-- `.forge/<feature-slug>/design.md`
-
-## Required output file
-
-`.forge/<feature-slug>/plan.md`
-
-## Plan format
-
-The plan defines execution order using building tasks.
-
-A building task is a unit of work that must be implementable and testable.
-
-The plan must include:
-- Scope for the current delivery
-- File Map covering the likely files or modules to touch and why
-- Building tasks to execute
-- Execution order of those building tasks
-- Expected result of each building task
-- Files or components touched by each building task
-- Verification for each building task
-- References to relevant `TASK-*` items when they clarify scope, sequencing, or dependencies
-
-The plan must not include:
-- Design definitions that belong in `design.md`
-- Rationale for why a solution was chosen over another
-- Code blocks
-- Unresolved questions inside the plan document
-- Placeholder language such as `TBD`, `TODO`, `implement later`, `adjust as needed`, or catch-all steps that hide concrete work
-
-## Planning rules
-
-- Use `design.md` as the source of truth for behavior and technical shape.
-- Do not plan from a design artifact that still has unresolved critical decisions.
-- Sequence delivery work without redefining the design.
-- Make each building task buildable without guesswork.
-- Prefer finer-grained tasks than the current format, but do not break work into trivial micro-steps.
-- Ask questions only when uncertainty materially changes execution strategy or task ordering.
-- A completed plan does not authorize implementation by itself.
-- Default to `NEXT_RECOMMENDED: plan` when the plan is ready but waiting for user approval to build.
-- Return `NEXT_RECOMMENDED: build` only when the orchestrator prompt explicitly states that the user has already approved implementation.
-- Keep tasks surgically scoped to the approved goal; optional cleanup belongs outside the plan unless explicitly requested.
-- The file map must justify why each listed file or module is expected to be touched.
-- Prefer existing patterns and minimum necessary changes over broader structural rewrites.
-- Each task must include minimal verification tied to the requested goal, not just a generic test step.
-- If execution would require guesswork about assumptions, unknowns, or missing dependencies, stop and block instead of padding the plan with placeholders.
-
-## Contract (strict)
-
-Return only:
-
-```text
-STATUS: success|partial|blocked
-PHASE: PLAN
-FEATURE_SLUG: <kebab-case>
-ARTIFACTS:
-- .forge/<feature-slug>/plan.md
-SUMMARY:
-- <brief point>
-NEXT_RECOMMENDED: plan|build
-RISKS:
-- <risk or None>
-QUESTIONS:
-1) <question>
-2) <question>
-```
-
-Use `STATUS: blocked` when planning cannot continue due to missing critical decisions.
-Include `QUESTIONS` only when blocked.