@really-knows-ai/foundry 3.7.3 → 3.8.0

package/dist/.opencode/plugins/foundry-tools/agent-refresh.js

@@ -46,12 +46,15 @@ function deleteStaleAgents(agentsDir) {
     existing = [];
   }
   for (const entry of existing) {
-    if (entry.startsWith('foundry-') && entry.endsWith('.md')) {
-      unlinkSync(path.join(agentsDir, entry));
-    }
+    if (isModelledAgent(entry)) unlinkSync(path.join(agentsDir, entry));
   }
 }
 
+function isModelledAgent(entry) {
+  return entry.startsWith('foundry-') && entry.endsWith('.md')
+    && entry !== 'foundry-forge.md' && entry !== 'foundry-appraise.md';
+}
+
 function writeAgentFiles(agentsDir, models) {
   for (const modelId of models) {
     const slug = makeSlug(modelId);
@@ -60,6 +63,23 @@ function writeAgentFiles(agentsDir, models) {
   }
 }
 
+const DEFAULT_AGENT = `---
+description: "Default Foundry STAGE stage agent"
+mode: subagent
+hidden: true
+---
+You are a Foundry stage agent. Follow the skill instructions provided in your task prompt exactly.
+`;
+
+function writeDefaultAgents(agentsDir) {
+  for (const stage of ['forge', 'appraise']) {
+    const filePath = path.join(agentsDir, `foundry-${stage}.md`);
+    if (!existsSync(filePath)) {
+      writeFileSync(filePath, DEFAULT_AGENT.replace('STAGE', stage), 'utf8');
+    }
+  }
+}
+
 /**
  * Snapshot the current foundry-*.md agent files in the agents directory.
  * Returns a plain object mapping filename → sha256 hex digest.
@@ -110,6 +130,7 @@ export function refreshAgents(worktree) {
     mkdirSync(agentsDir, { recursive: true });
     deleteStaleAgents(agentsDir);
     writeAgentFiles(agentsDir, models);
+    writeDefaultAgents(agentsDir);
 
     return { ok: true, count: models.length };
   } catch (err) {
@@ -155,18 +176,23 @@ function resolveGuideSource(packageRoot) {
 export function writeFoundryGuideAgent(worktree, packageRoot) {
   const targetDir = path.join(worktree, '.opencode', 'agents');
   const targetPath = path.join(targetDir, 'foundry.md');
+  let written = false;
+
+  if (!existsSync(targetPath)) {
+    const sourcePath = resolveGuideSource(packageRoot);
+    try {
+      const content = readFileSync(sourcePath, 'utf8');
+      mkdirSync(targetDir, { recursive: true });
+      writeFileSync(targetPath, content, 'utf8');
+      written = true;
+    } catch (err) {
+      return { ok: false, error: `Failed to write guide agent: ${err.message ?? String(err)}` };
+    }
+  }
 
-  if (existsSync(targetPath)) return { ok: true, written: false };
+  writeDefaultAgents(targetDir);
 
-  const sourcePath = resolveGuideSource(packageRoot);
-  try {
-    const content = readFileSync(sourcePath, 'utf8');
-    mkdirSync(targetDir, { recursive: true });
-    writeFileSync(targetPath, content, 'utf8');
-    return { ok: true, written: true };
-  } catch (err) {
-    return { ok: false, error: `Failed to write guide agent: ${err.message ?? String(err)}` };
-  }
+  return { ok: true, written };
 }
 
 function resolveSkillsSource(packageRoot) {

package/dist/.opencode/plugins/foundry-tools/orchestrate-tool.js

@@ -11,9 +11,9 @@ import { requireNotFailed } from '../../../scripts/lib/failed-flow.js';
 import { requireOnFlowBranch } from '../../../scripts/lib/branch-guard.js';
 
 function createMint(secret, pending) {
-  return ({ route, cycle, exp }) => {
+  return ({ route, cycle, exp, model }) => {
     const nonce = randomUUID();
-    const payload = { route, cycle, nonce, exp };
+    const payload = model ? { route, cycle, nonce, exp, model } : { route, cycle, nonce, exp };
     pending.add(nonce, payload);
     return signToken(payload, secret);
   };

package/dist/.opencode/plugins/foundry-tools/stage-tools.js

@@ -41,13 +41,18 @@ function resolveBaseSha(worktree) {
   }
 }
 
-function verifyStageToken(token, secret, stage, cycle) {
+function verifyStageToken(token, secret, stage, cycle, agent) {
   const v = verifyToken(token, secret);
   if (!v.ok) return { error: `foundry_stage_begin: token ${v.reason}` };
   if (v.payload.route !== stage || v.payload.cycle !== cycle) {
     return { error: `foundry_stage_begin: token payload mismatch (route=${v.payload.route}, cycle=${v.payload.cycle})` };
   }
-  return { payload: v.payload };
+  return checkTokenAgentBinding(v.payload, agent);
+}
+
+function checkTokenAgentBinding(payload, agent) {
+  if (!payload.model || !agent || payload.model === agent) return { payload };
+  return { error: `foundry_stage_begin: token is scoped to subagent '${payload.model}', not '${agent}'. Dispatch forge via task(), not inline.` };
 }
 
 async function executeStageBegin(args, context, pending) {
@@ -59,7 +64,7 @@ async function executeStageBegin(args, context, pending) {
     return JSON.stringify({ error: `foundry_stage_begin requires no active stage; current: ${current.stage}` });
   }
 
-  const tokenResult = verifyStageToken(args.token, secret, args.stage, args.cycle);
+  const tokenResult = verifyStageToken(args.token, secret, args.stage, args.cycle, context.agent);
   if (tokenResult.error) return JSON.stringify({ error: tokenResult.error });
 
   const baseSha = resolveBaseSha(context.worktree);

package/dist/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [3.8.0] - 2026-05-27
+
+### Added
+
+- Default `foundry-forge` and `foundry-appraise` subagents: hidden, model-less stage agents created during bootstrap and preserved across model refreshes. When a cycle has no model overrides, these agents handle forge and appraise dispatch, ensuring tokens are always scoped to a known subagent type.
+
+- Stage token agent binding: `foundry_stage_begin` now verifies the calling agent matches the token's scoped subagent. The main Foundry agent cannot use tokens issued for `foundry-forge` or `foundry-opencode-*` — it must dispatch via `task()`. This enforces the subagent dispatch model at the protocol level.
+
+### Fixed
+
+- Cycle-level `models.appraise` now correctly flows into appraise dispatch as the default model when individual appraisers lack an explicit `model` field. Previously the value was read for agent-file validation but discarded before dispatch, causing all appraisers to run on the session default.
+
+- Forge and orchestrate skill guidance clarify that stage skills are subagent-only and must not be run inline. The `forge` SKILL.md opens with an explicit "This skill is subagent-only" warning.
+
 ## [3.7.3] - 2026-05-27
 
 ### Added

package/dist/scripts/appraise-module.js

@@ -127,9 +127,8 @@ function addTasksForArtefact(tasks, artefact, entry, ctx) {
  * Map an appraiser's model to a subagent type string.
  */
 function resolveSubagentType(appraiser, ctx) {
-  const name = appraiser.model || ctx.defaultModel || 'general';
-  if (name === 'general') return 'general';
-
+  const name = appraiser.model || ctx.defaultModel || 'appraise';
+  if (name === 'appraise') return 'foundry-appraise';
   return `foundry-${name.replace(/[/.]/g, '-')}`;
 }
 

package/dist/scripts/orchestrate.js

@@ -10,6 +10,7 @@ import { ulid as defaultUlid } from './lib/ulid.js';
 import { computeArtefactVersion } from './lib/artefacts.js';
 import { enforceForgeContract } from './lib/forge-contract.js';
 import { loadHistory } from './lib/history.js';
+import { getCycleDefinition } from './lib/config.js';
 import {
   readCycleTargets,
   readForgeFilePatterns,
@@ -109,15 +110,23 @@ function buildQuenchContext(cycleId, args, io) {
     feedback: buildFeedback(cycleId, stageId, io) };
 }
 
-function buildAppraiseCtx(cycleId, args, io) {
+async function buildAppraiseCtx(cycleId, args, io) {
   const stageId = `appraise:${cycleId}`;
+  const defaultModel = args.defaultModel ?? await readAppraiseModel(cycleId, io);
   return { cycleId, io, git: args.git, finalize: buildFinalizeWrapper(cycleId, args, io),
-    foundryDir: 'foundry', defaultModel: args.defaultModel,
+    foundryDir: 'foundry', defaultModel,
     baseBranch: args.baseBranch ?? 'main', cwd: args.cwd ?? process.cwd(),
     activeStage: readActiveStage(io), lastStage: readLastStage(io),
     feedback: buildFeedback(cycleId, stageId, io) };
 }
 
+async function readAppraiseModel(cycleId, io) {
+  try {
+    const cd = await getCycleDefinition('foundry', cycleId, io);
+    return cd.frontmatter?.models?.appraise;
+  } catch { return undefined; }
+}
+
 function resolveBaseSha(io) {
   try {
     const sha = io.exec(['git', 'rev-parse', 'HEAD']);
@@ -222,13 +231,13 @@ async function dispatchAppraiseOrConsolidate(sortResult, preCheck, args, io, res
 
 async function handleAppraiseGatherRoute(sortResult, preCheck, args, io) {
   writeStageRecord(io, preCheck.cycleId, sortResult.route);
-  const result = await gatherAppraiseContext(buildAppraiseCtx(preCheck.cycleId, args, io));
+  const result = await gatherAppraiseContext(await buildAppraiseCtx(preCheck.cycleId, args, io));
   if (result.action === 'violation') { clearActiveStage(io); return result; }
   return dispatchAppraiseOrConsolidate(sortResult, preCheck, args, io, result);
 }
 
 async function handleAppraiseConsolidateRoute(sortResult, preCheck, args, io) {
-  const ctx = buildAppraiseCtx(preCheck.cycleId, args, io);
+  const ctx = await buildAppraiseCtx(preCheck.cycleId, args, io);
   const result = await consolidateAppraise(ctx, args.lastResults);
   if (result.action === 'violation') {
     clearActiveStage(io);

package/dist/scripts/sort.js

@@ -165,9 +165,15 @@ function resolveModelId(routeBase, models, defaultModel) {
 }
 
 function pickModelId(route, frontmatter, defaultModel) {
-  const models = frontmatter.models;
-  if (!models) return defaultModel || null;
-  return resolveModelId(baseStage(route), models, defaultModel) || null;
+  const routeBase = baseStage(route);
+  const resolved = frontmatter.models ? resolveModelId(routeBase, frontmatter.models, defaultModel) : null;
+  return resolved || defaultModel || defaultForStage(routeBase);
+}
+
+function defaultForStage(routeBase) {
+  if (routeBase === 'forge') return 'forge';
+  if (routeBase === 'appraise') return 'appraise';
+  return null;
 }
 
 function resolveModel(route, frontmatter, agentsDir, io, defaultModel) {
@@ -177,6 +183,7 @@ function resolveModel(route, frontmatter, agentsDir, io, defaultModel) {
   const model = `foundry-${modelId.replace(/[/.]/g, '-')}`;
   const agentPath = `${agentsDir}/${model}.md`;
   if (!io.exists(agentPath)) {
+    if (modelId === 'forge' || modelId === 'appraise') return model;
     return {
       error: `Missing required subagent: ${model}.md is not present in ${agentsDir}/. `
         + `Call foundry_refresh_agents() to regenerate agent files, then restart.`,
@@ -194,7 +201,7 @@ function checkModel(route, frontmatter, agentsDir, io, defaultModel) {
 function mintToken({ route, model, mint, cycle, now, ulid, reason }) {
   const result = { route, ...(model ? { model } : {}), reason };
   if (mint && isDispatchableRoute(route)) {
-    const token = mint({ route, cycle, exp: now + 10 * 60 * 1000, nonce: ulid(now) });
+    const token = mint({ route, cycle, exp: now + 10 * 60 * 1000, nonce: ulid(now), model });
     if (token) result.token = token;
   }
   return result;

package/dist/skills/forge/SKILL.md

@@ -6,6 +6,8 @@ description: Produces or revises an artefact, guided by WORK.md and the foundry
 
 # Forge
 
+**This skill is subagent-only.** It describes the protocol a forge subagent follows when dispatched via `task()` from the orchestrate loop. Do NOT load this skill and run forge inline — the orchestrate skill returns a `dispatch` action with a pre-built prompt; call `task()` with it.
+
 You produce or revise artefacts. You read the work file to understand the goal and follow the feedback item in the dispatch prompt, and read the foundry cycle definition to understand what you're producing and what inputs you can read.
 
 ## Prerequisites

package/dist/skills/orchestrate/SKILL.md

@@ -37,7 +37,13 @@ Loop until `foundry_orchestrate` returns a terminal action (`done`, `blocked`, o
 
 Payload: `{stage, subagent_type, prompt}`.
 
-Call the `task` tool:
+Call the `task` tool. Do NOT load the forge, quench, or appraise skills yourself — the subagent will use them internally:
+
+```
+task tool:
+  subagent_type: <subagent_type-from-payload>
+  description: "Run <stage> for <cycle>"
+  prompt: <prompt-from-payload — pass verbatim>
 ```
 task tool:
   subagent_type: <subagent_type-from-payload>
@@ -51,7 +57,7 @@ When the task returns, call `foundry_orchestrate({lastResult: {ok: true}})`. If
 
 Payload: `{stage, cycle, tasks}`.
 
-Fire all tasks in parallel by making multiple `task` tool calls in a single response:
+Fire all tasks in parallel by making multiple `task` tool calls in a single response. Do NOT load stage skills yourself:
 
 ```
 task tool:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "3.7.3",
+  "version": "3.8.0",
   "description": "A skill-driven framework for governed artefact generation with AI coding tools. Define your own artefact types, laws, and flows — Foundry handles the forge → quench → appraise pipeline with deterministic routing, quality gates, and iterative refinement.",
   "type": "module",
   "main": "dist/.opencode/plugins/foundry.js",