@guidobuilds/forge-ai 0.1.0 → 0.3.0

package/dist/src/processor.js

@@ -1,18 +1,21 @@
-import { access } from 'node:fs/promises';
+import { access, readFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
+import path from 'node:path';
 import { renderClaudeAgent, renderClaudeSkill } from './adapters/claude.js';
 import { renderCodexAgent, renderCodexSkill } from './adapters/codex.js';
 import { 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];
 }
@@ -24,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);
+        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) {
+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 }));
@@ -75,53 +76,95 @@ function convertSource(source) {
             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, 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, 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.1.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.

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.