@guidobuilds/forge-ai 0.1.0

package/dist/src/discovery.js

@@ -0,0 +1,50 @@
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseFrontmatter } from './frontmatter.js';
+import { diagnostic } from './diagnostics.js';
+export async function discoverSources(source) {
+    const root = path.resolve(source);
+    const sources = [];
+    const diagnostics = [];
+    await discoverAgents(root, sources, diagnostics);
+    await discoverSkills(root, sources, diagnostics);
+    if (sources.length === 0)
+        diagnostics.push(diagnostic('error', 'NO_SOURCES', 'No canonical agents or skills found', { sourcePath: root }));
+    sources.sort((a, b) => a.sourcePath.localeCompare(b.sourcePath));
+    return { sources, diagnostics };
+}
+async function discoverAgents(root, sources, diagnostics) {
+    const dir = path.join(root, 'agents');
+    for (const entry of await safeReaddir(dir)) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        const sourcePath = path.join(dir, entry.name);
+        await readSource('agent', sourcePath, path.basename(entry.name, '.md'), sources, diagnostics);
+    }
+}
+async function discoverSkills(root, sources, diagnostics) {
+    const dir = path.join(root, 'skills');
+    for (const entry of await safeReaddir(dir)) {
+        if (!entry.isDirectory())
+            continue;
+        const sourcePath = path.join(dir, entry.name, 'SKILL.md');
+        await readSource('skill', sourcePath, entry.name, sources, diagnostics);
+    }
+}
+async function readSource(kind, sourcePath, expectedName, sources, diagnostics) {
+    try {
+        const parsed = parseFrontmatter(await readFile(sourcePath, 'utf8'));
+        sources.push({ kind, sourcePath, expectedName, data: parsed.data, body: parsed.body });
+    }
+    catch (error) {
+        diagnostics.push(diagnostic('error', 'PARSE_ERROR', error instanceof Error ? error.message : String(error), { sourcePath }));
+    }
+}
+async function safeReaddir(dir) {
+    try {
+        return await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}

package/dist/src/frontmatter.js

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

package/dist/src/index.js

@@ -0,0 +1,3 @@
+export * from './model.js';
+export * from './processor.js';
+export * from './writer.js';

package/dist/src/model.js

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

package/dist/src/paths.js

@@ -0,0 +1,24 @@
+import os from 'node:os';
+import path from 'node:path';
+export function resolveOutputPath(platform, kind, scope, name, cwd = process.cwd(), home = os.homedir()) {
+    const base = scope === 'user' ? userBase(platform, kind, home) : projectBase(platform, kind, cwd);
+    return kind === 'agent' && platform === 'codex'
+        ? path.join(base, `${name}.toml`)
+        : kind === 'agent'
+            ? path.join(base, `${name}.md`)
+            : path.join(base, name, 'SKILL.md');
+}
+function userBase(platform, kind, home) {
+    if (platform === 'opencode')
+        return path.join(home, '.config', 'opencode', kind === 'agent' ? 'agents' : 'skills');
+    if (platform === 'claude')
+        return path.join(home, '.claude', kind === 'agent' ? 'agents' : 'skills');
+    return kind === 'agent' ? path.join(home, '.codex', 'agents') : path.join(home, '.agents', 'skills');
+}
+function projectBase(platform, kind, cwd) {
+    if (platform === 'opencode')
+        return path.join(cwd, '.opencode', kind === 'agent' ? 'agents' : 'skills');
+    if (platform === 'claude')
+        return path.join(cwd, '.claude', kind === 'agent' ? 'agents' : 'skills');
+    return kind === 'agent' ? path.join(cwd, '.codex', 'agents') : path.join(cwd, '.agents', 'skills');
+}

package/dist/src/processor.js

@@ -0,0 +1,127 @@
+import { access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+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 { 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 allowedOpenCodeKeys = new Set([...allowedProductKeys, 'mode']);
+const openCodeModes = new Set(['primary', 'subagent', 'all']);
+export function resolvePlatforms(platform) {
+    return platform === 'all' ? platforms : [platform];
+}
+export function parsePlatform(value) {
+    return value === 'all' || isPlatform(value) ? value : undefined;
+}
+export function parseScope(value) {
+    return value === 'user' || value === 'project' ? value : undefined;
+}
+export async function buildWritePlan(options) {
+    const { sources, diagnostics } = await discoverSources(options.source);
+    const agents = [];
+    const skills = [];
+    const seenAgents = new Set();
+    const seenSkills = new Set();
+    for (const source of sources) {
+        const converted = convertSource(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 }));
+            continue;
+        }
+        seen.add(converted.item.name);
+        if (source.kind === 'agent')
+            agents.push(converted.item);
+        else
+            skills.push(converted.item);
+    }
+    const files = [];
+    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));
+        }
+        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)));
+    }
+    return { files, diagnostics, sourceCount: sources.length };
+}
+function convertSource(source) {
+    const diagnostics = [];
+    const data = source.data;
+    const name = typeof data.name === 'string' ? data.name : undefined;
+    const description = typeof data.description === 'string' ? data.description : undefined;
+    for (const key of Object.keys(data)) {
+        if (!allowedTopLevel.has(key))
+            diagnostics.push(diagnostic('error', 'UNSUPPORTED_FIELD', `Unsupported canonical field ${key}`, { sourcePath: source.sourcePath }));
+    }
+    for (const platform of platformKeys) {
+        const config = data[platform];
+        if (config === undefined)
+            continue;
+        if (!config || typeof config !== 'object' || Array.isArray(config)) {
+            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;
+            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') {
+            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 (!name)
+        diagnostics.push(diagnostic('error', 'MISSING_NAME', `${source.kind} 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 }));
+    if (name && name !== source.expectedName)
+        diagnostics.push(diagnostic('error', 'NAME_MISMATCH', `${source.kind} name must match ${source.expectedName}`, { sourcePath: source.sourcePath }));
+    if (!description)
+        diagnostics.push(diagnostic('error', 'MISSING_DESCRIPTION', `${source.kind} description is required`, { 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'))
+        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 } };
+}
+function productConfig(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function renderFile(platform, kind, item, 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);
+    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 };
+}
+async function collisionDiagnostics(files, force) {
+    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 }));
+        }
+        catch {
+            // Missing destination is safe.
+        }
+    }
+    return diagnostics;
+}

package/dist/src/writer.js

@@ -0,0 +1,8 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export async function writeOutputs(files) {
+    for (const file of files) {
+        await mkdir(path.dirname(file.path), { recursive: true });
+        await writeFile(file.path, file.content, 'utf8');
+    }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@guidobuilds/forge-ai",
+  "version": "0.1.0",
+  "description": "Forge AI framework",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "forge-ai": "bin/forge-ai.mjs"
+  },
+  "files": [
+    "bin",
+    "dist/src",
+    "agents",
+    "skills",
+    "README.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"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "picocolors": "^1.1.1"
+  }
+}

package/skills/forge-build/SKILL.md

@@ -0,0 +1,80 @@
+---
+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

@@ -0,0 +1,104 @@
+---
+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

@@ -0,0 +1,65 @@
+---
+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

@@ -0,0 +1,46 @@
+---
+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.