@really-knows-ai/foundry 3.0.1 → 3.1.0

package/README.md

@@ -142,16 +142,17 @@ Open OpenCode in your project repo and say:
 > run init-foundry
 ```
 
-Foundry scaffolds a `foundry/` directory, generates one `foundry-<model>` agent file
-per model available in your session, commits the structure, and then asks you to
-restart. All the foundational configuration directories are created; you will
-populate them next.
+Foundry scaffolds a `foundry/` directory, generates one `foundry-<model>` stage agent
+file per model available in your session, installs the user-facing `Foundry` guide
+agent, commits the structure, and asks you to restart.
 
-Restart OpenCode so the new `foundry-<model>` agents register — multi-model dispatch cannot route to agents it cannot discover.
+Restart OpenCode so the new agents register. After the restart, switch to the
+**Foundry** agent. The Foundry agent is the normal interface for authoring and
+running Foundry workflows.
 
-### Phase 3 — Build a flow without writing one
+### Phase 3 — Ask the Foundry agent for a flow
 
-Ask Foundry to set up a flow:
+With the **Foundry** agent active, ask it to set up a flow:
 
 ```
 > set up a flow that writes haikus

package/dist/.opencode/plugins/foundry-tools/config-law-tools.js

@@ -38,73 +38,47 @@ function findLawEnd(lines, startIdx) {
   return lines.length;
 }
 
-// Extract full markdown for a single law from file content
 function extractLawMarkdown(content, lawId) {
   const lines = content.split('\n');
   const startIdx = findLawStart(lines, lawId);
-
   if (startIdx < 0) return null;
-
   const endIdx = findLawEnd(lines, startIdx);
   const lawLines = lines.slice(startIdx, endIdx);
-  
-  while (lawLines.length > 0 && lawLines[lawLines.length - 1] === '') {
-    lawLines.pop();
-  }
-  
+  while (lawLines.length > 0 && lawLines[lawLines.length - 1] === '') lawLines.pop();
   return lawLines.join('\n') + '\n';
 }
 
 async function searchGlobalLaws(io, foundryDir, lawId) {
   const globalLawsDir = join(foundryDir, 'laws');
-  if (!(await io.exists(globalLawsDir))) {
-    return null;
-  }
-
+  if (!(await io.exists(globalLawsDir))) return null;
   const files = await io.readDir(globalLawsDir);
   for (const file of files) {
     if (!file.endsWith('.md')) continue;
     const path = join(globalLawsDir, file);
     const content = await io.readFile(path);
-    if (contentContainsLaw(content, lawId)) {
-      return { path, fullMarkdown: content, source: 'global' };
-    }
+    if (contentContainsLaw(content, lawId)) return { path, fullMarkdown: content, source: 'global' };
   }
-
   return null;
 }
 
 async function searchTypeSpecificLaws(io, foundryDir, lawId) {
   const artefactsDir = join(foundryDir, 'artefacts');
-  if (!(await io.exists(artefactsDir))) {
-    return null;
-  }
-
+  if (!(await io.exists(artefactsDir))) return null;
   const types = await io.readDir(artefactsDir);
   for (const typeId of types) {
     const typeLawsPath = join(artefactsDir, typeId, 'laws.md');
     if (!(await io.exists(typeLawsPath))) continue;
-
     const content = await io.readFile(typeLawsPath);
-    if (contentContainsLaw(content, lawId)) {
-      return { path: typeLawsPath, fullMarkdown: content, source: `type:${typeId}` };
-    }
+    if (contentContainsLaw(content, lawId)) return { path: typeLawsPath, fullMarkdown: content, source: `type:${typeId}` };
   }
-
   return null;
 }
 
 async function findLawByID(io, foundryDir, lawId) {
-  let result = await searchGlobalLaws(io, foundryDir, lawId);
-  if (result) {
-    return { found: true, ...result };
-  }
-
-  result = await searchTypeSpecificLaws(io, foundryDir, lawId);
-  if (result) {
-    return { found: true, ...result };
-  }
-
+  const global = await searchGlobalLaws(io, foundryDir, lawId);
+  if (global) return { found: true, ...global };
+  const typeSpec = await searchTypeSpecificLaws(io, foundryDir, lawId);
+  if (typeSpec) return { found: true, ...typeSpec };
   return { found: false };
 }
 
@@ -204,82 +178,92 @@ function computeTargetPath(target) {
 
 // --- add law executor --------------------------------------------------------
 
+function extractLawId(body) {
+  const match = body.match(/^## ([^\s]+)/m);
+  return match ? match[1] : null;
+}
+
+async function checkExistingLaw(io, path, lawId) {
+  if (!(await io.exists(path))) return { existedBefore: false, priorContent: null };
+  const priorContent = await io.readFile(path);
+  if (contentContainsLaw(priorContent, lawId)) {
+    return { error: `law id "${lawId}" already exists in ${path}; use foundry_config_edit_law to update it` };
+  }
+  return { existedBefore: true, priorContent };
+}
+
 async function validateAddLawPrerequisites(io, args) {
   const targetError = validateAddLawTarget(args.target);
-  if (targetError) {
-    return { error: targetError };
-  }
+  if (targetError) return { error: targetError };
 
   const path = computeTargetPath(args.target);
   const validation = await validateLaw({ body: args.body, io });
-  if (!validation.ok) {
-    return validation;
-  }
+  if (!validation.ok) return validation;
 
-  if (await io.exists(path)) {
-    return {
-      ok: false,
-      errors: [`${path} already exists; use foundry_config_edit_law to update an existing law in place`],
-    };
-  }
+  const lawId = extractLawId(args.body);
+  if (!lawId) return { error: 'could not determine law id from body (expected "## <law-id>" heading)' };
+
+  const existing = await checkExistingLaw(io, path, lawId);
+  if (existing.error) return { error: existing.error };
+  return { ok: true, path, lawId, ...existing };
+}
+
+function formatAddLawError(err) {
+  return err instanceof UnexpectedFilesError
+    ? JSON.stringify({ error: err.message, affected_files: err.files })
+    : errorJson(err);
+}
 
-  return { ok: true, path };
+function buildNextContent(existedBefore, priorContent, body) {
+  return existedBefore ? priorContent.trimEnd() + '\n\n' + body.trimStart() : body;
+}
+
+async function rollbackAddLaw(io, path, existedBefore, priorContent) {
+  if (existedBefore) await io.writeFile(path, priorContent);
+  else await io.rm(path);
 }
 
 async function executeAddLaw(args, context) {
   const io = makeAsyncIO(context.worktree);
   const execFile = makeExecFile(context.worktree);
+  let path, existedBefore, priorContent;
 
   try {
     const prereq = await validateAddLawPrerequisites(io, args);
-    if (prereq.error) {
-      return JSON.stringify({ ok: false, errors: [prereq.error] });
-    }
-    if (!prereq.ok) {
-      return JSON.stringify(prereq);
-    }
+    if (prereq.error) return JSON.stringify({ ok: false, errors: [prereq.error] });
+    if (!prereq.ok) return JSON.stringify(prereq);
 
-    const path = prereq.path;
+    ({ path, existedBefore, priorContent } = prereq);
+    const nextContent = buildNextContent(existedBefore, priorContent, args.body);
 
     await io.mkdirp(dirname(path));
-    await io.writeFile(path, args.body);
+    await io.writeFile(path, nextContent);
 
     const sha = commitWithPolicy({
       message: `config: add law ${args.name}\n\nvia foundry_config_add_law`,
       allowedPatterns: ['foundry/**'],
       execFile,
     });
-
     return JSON.stringify({ ok: true, path, sha });
   } catch (err) {
-    if (err instanceof UnexpectedFilesError) {
-      return JSON.stringify({ error: err.message, affected_files: err.files });
-    }
-    return errorJson(err);
+    if (path) await rollbackAddLaw(io, path, existedBefore, priorContent);
+    return formatAddLawError(err);
   }
 }
 
 // --- helper for preserving sibling laws -------------------------------------------------------
 
-// Replace a law in file content while preserving other laws
 function replaceLawInContent(content, lawId, newLawMarkdown) {
   const lines = content.split('\n');
   const startIdx = findLawStart(lines, lawId);
   if (startIdx < 0) return content.trimEnd() + '\n\n' + newLawMarkdown;
-  
   const endIdx = findLawEnd(lines, startIdx);
   const before = lines.slice(0, startIdx);
   const after = lines.slice(endIdx);
-  
-  // Trim trailing empty lines from before
   const beforeEnd = before.findLastIndex(l => l !== '') + 1;
   before.length = beforeEnd;
-  
-  // Trim leading empty lines from after  
   const afterStart = after.findIndex(l => l !== '');
   if (afterStart > 0) after.splice(0, afterStart);
-  
-  // newLawMarkdown includes trailing newline; split and rejoin without final empty string
   const newLines = newLawMarkdown.trimEnd().split('\n');
   return before.concat(newLines, after).join('\n') + '\n';
 }

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

@@ -94,14 +94,13 @@ function buildFoundryNotInitializedMessage() {
   return `<FOUNDRY_CONTEXT>
 Foundry is installed but not initialised in this project. There is no foundry/ directory.
 
-To set up Foundry, use the \`init-foundry\` skill. This will create the foundry/ directory structure
-and guide you through defining artefact types, laws, appraisers, cycles, and flows.
+To set up Foundry, initialise the project first. Initialisation creates the foundry/ directory structure, installs the user-facing Foundry agent, and generates model-routing stage agents. After initialisation, restart OpenCode and switch to the Foundry agent.
 </FOUNDRY_CONTEXT>`;
 }
 
 function buildFlowList(flows) {
   if (flows.length === 0) {
-    return '- (no flows defined yet — use the `add-flow` skill to create one)';
+    return '- (no flows defined yet — ask the Foundry agent to set one up)';
   }
   return flows.map(f => {
     const sc = f.startingCycles.length > 0 ? ` — starting cycles: ${f.startingCycles.join(', ')}` : '';
@@ -121,27 +120,19 @@ The pipeline: assay (populate memory) → forge (produce) → quench (determinis
 
 ${flowList}
 
-**CRITICAL ROUTING RULE:** When the user references any flow above — by id (e.g. "creative-flow"),
-by name (e.g. "Creative Flow"), or by clear paraphrase (e.g. "the creative flow", "use the creative pipeline") —
-invoke the \`flow\` skill DIRECTLY with that flow's id. Do NOT invoke brainstorming, do NOT explore the
-codebase, do NOT ask clarifying questions about what to build. The flow's cycles already define the
-work. The user's request text (e.g. "make a haiku about X") is the goal to pass to the flow.
+When the user references any flow above — by id (e.g. "creative-flow"),
+by name (e.g. "Creative Flow"), or by clear paraphrase (e.g. "the creative flow",
+"use the creative pipeline") — ask the Foundry agent to run that flow with the user's
+request as the goal. The Foundry agent handles cycle selection, work-branch creation, and
+orchestration automatically.
 
-Brainstorming applies to NEW features being added to foundry itself (new cycles, new artefact types,
-new skills). It does NOT apply to running an existing, defined flow.
+## Foundry agent capabilities
 
-## Available skills
-
-- **Pipeline:** assay, forge, quench, appraise, orchestrate, flow, human-appraise
-- **Authoring:** add-artefact-type, add-law, add-appraiser, add-cycle, add-flow, add-memory-entity-type, add-memory-edge-type, add-extractor, init-foundry
-- **Maintenance:** upgrade-foundry, refresh-agents, list-agents, init-memory, change-embedding-model, dry-run
-- **Memory Admin:** drop-memory-entity-type, drop-memory-edge-type, rename-memory-entity-type, rename-memory-edge-type, reset-memory
+The Foundry agent has internal workflows for pipeline execution, authoring, maintenance, memory administration, and dry-run trials. Present these capabilities as Foundry outcomes instead of naming internal skills.
 
 ## Multi-model routing
 
-Foundry uses \`foundry-*\` sub-agents defined as markdown files in \`.opencode/agents/\`.
-Run the \`refresh-agents\` skill to regenerate them after adding or removing providers.
-Cycle definitions can specify per-stage models via the \`models\` frontmatter map. Appraisers can override with their own \`model\` field.
+Foundry uses generated \`foundry-*\` stage agents for cycle stage dispatch. The user-facing \`Foundry\` agent is installed as \`.opencode/agents/foundry.md\` and should be used for authoring and running Foundry workflows.
 
 All user content lives under foundry/.
 Scripts are located at: ${path.join(packageRoot, 'scripts')}

package/dist/.opencode/plugins/foundry-tools/refresh-agents-tool.js

@@ -0,0 +1,88 @@
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { mkdirSync, readdirSync, writeFileSync, unlinkSync } from 'fs';
+
+const AGENT_FRONTMATTER_TEMPLATE = `---
+description: "Foundry stage agent using MODEL_ID"
+mode: subagent
+model: "MODEL_ID"
+hidden: true
+---
+You are a Foundry stage agent. Follow the skill instructions provided in your task prompt exactly.
+`;
+
+function makeSlug(modelId) {
+  return modelId.replace(/[/.]/g, '-');
+}
+
+function buildAgentContent(modelId) {
+  return AGENT_FRONTMATTER_TEMPLATE.replace(/MODEL_ID/g, modelId);
+}
+
+function listModels(worktree) {
+  const stdout = execFileSync('opencode', ['models'], {
+    cwd: worktree,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  return stdout
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => line.length > 0);
+}
+
+function deleteStaleAgents(agentsDir) {
+  let existing;
+  try {
+    existing = readdirSync(agentsDir);
+  } catch {
+    existing = [];
+  }
+  for (const entry of existing) {
+    if (entry.startsWith('foundry-') && entry.endsWith('.md')) {
+      unlinkSync(path.join(agentsDir, entry));
+    }
+  }
+}
+
+function writeAgentFiles(agentsDir, models) {
+  for (const modelId of models) {
+    const slug = makeSlug(modelId);
+    const filePath = path.join(agentsDir, `foundry-${slug}.md`);
+    writeFileSync(filePath, buildAgentContent(modelId), 'utf8');
+  }
+}
+
+function refreshAgents(worktree) {
+  const models = listModels(worktree);
+  if (models.length === 0) {
+    return { ok: false, error: 'No models returned by `opencode models`. Is the opencode CLI available?' };
+  }
+
+  const agentsDir = path.join(worktree, '.opencode', 'agents');
+  mkdirSync(agentsDir, { recursive: true });
+  deleteStaleAgents(agentsDir);
+  writeAgentFiles(agentsDir, models);
+
+  return { ok: true, count: models.length };
+}
+
+export function createRefreshAgentsTool({ tool }) {
+  return {
+    foundry_refresh_agents: tool({
+      description: 'Regenerate .opencode/agents/foundry-*.md stage-agent files from the currently available models.',
+      args: {},
+      async execute(_args, context) {
+        try {
+          const result = refreshAgents(context.worktree);
+          return JSON.stringify(result);
+        } catch (err) {
+          return JSON.stringify({
+            ok: false,
+            error: `foundry_refresh_agents: ${err.message ?? String(err)}`,
+          });
+        }
+      },
+    }),
+  };
+}

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

@@ -52,7 +52,7 @@ async function executeValidator(expanded, worktree, patterns) {
  *   JSON or missing required fields, `pattern-mismatch` for files that
  *   didn't match the artefact type's `file-patterns`.
  */
-async function runValidators(laws, patterns, patternSubstitution, worktree) {
+async function runValidators(laws, patterns, substitutions, worktree) {
   const results = {
     validatorsRun: 0,
     items: [],
@@ -61,7 +61,7 @@ async function runValidators(laws, patterns, patternSubstitution, worktree) {
 
   for (const law of laws) {
     if (!law.validators || law.validators.length === 0) continue;
-    await runLawValidators(law, patterns, patternSubstitution, worktree, results);
+    await runLawValidators(law, patterns, substitutions, worktree, results);
   }
 
   return results;
@@ -70,15 +70,15 @@ async function runValidators(laws, patterns, patternSubstitution, worktree) {
 /**
  * Run validators for a single law.
  */
-async function runLawValidators(law, patterns, patternSubstitution, worktree, results) {
+async function runLawValidators(law, patterns, substitutions, worktree, results) {
   for (const validator of law.validators) {
-    // Skip validators if pattern substitution is empty (no matching files)
-    // Self-resolving validators (npm test, tsc) omit {pattern}, so they still run
-    if (patternSubstitution === '' && validator.command.includes('{pattern}')) {
+    // Skip iff command uses {files} and there are no matching files.
+    // {pattern}-only and verbatim commands always run.
+    if (substitutions.files === '' && /(?:^|\s)\{files\}(?=\s|$)/.test(validator.command)) {
       continue;
     }
     results.validatorsRun++;
-    const expanded = expandValidatorCommand(validator.command, patternSubstitution);
+    const expanded = expandValidatorCommand(validator.command, substitutions);
     const parseResult = await executeValidator(expanded, worktree, patterns);
     collectValidatorResult(parseResult, law.id, validator.id, results);
   }
@@ -160,8 +160,11 @@ async function performValidation(args, context) {
  */
 async function runValidatorsAndReport(laws, patterns, worktree) {
   const expandedFiles = await expandPatterns(patterns, worktree);
-  const patternSubstitution = expandedFiles.map(shellQuote).join(' ');
-  const results = await runValidators(laws, patterns, patternSubstitution, worktree);
+  const substitutions = {
+    pattern: patterns.map(shellQuote).join(' '),
+    files: expandedFiles.map(shellQuote).join(' '),
+  };
+  const results = await runValidators(laws, patterns, substitutions, worktree);
 
   return JSON.stringify({
     ok: results.errors.length === 0,
@@ -235,29 +238,34 @@ async function expandPatterns(patterns, worktree) {
 }
 
 /**
- * Expand validator command by replacing {pattern} placeholder.
+ * Expand validator command by replacing {pattern} and {files} placeholders.
+ *
+ * - {pattern} → space-separated, shell-quoted globs from the artefact
+ *   type's `file-patterns:` array (e.g. "'haikus/*.md' 'drafts/*.md'").
+ * - {files}   → space-separated, shell-quoted matching file paths in the
+ *   worktree (e.g. "'haikus/one.md' 'haikus/two.md'").
  *
- * Only replaces {pattern} when it appears as a standalone token bounded by
- * whitespace or string start/end. This allows self-resolving validators
- * (e.g., npm test, tsc --noEmit) to omit the placeholder without risk of
- * accidental substitution if they contain the literal text "{pattern}" as part
- * of another string.
+ * Both placeholders are recognised only as standalone tokens, bounded
+ * by whitespace or start/end of string. Surrounding single or double
+ * quotes around the placeholder are stripped first so authors can
+ * write `rg "{pattern}"` for readability.
  *
- * @param {string} command - The validator command
- * @param {string} patternSubstitution - Shell-quoted file paths, space-separated
- * @returns {string} The expanded command
+ * @param {string} command
+ * @param {{ pattern: string, files: string }} substitutions
+ * @returns {string}
  */
-export function expandValidatorCommand(command, patternSubstitution) {
-  // First strip surrounding quotes around {pattern} to handle cases like
-  // rg "{pattern}" where authors add quotes for readability
-  const cmd = command
+export function expandValidatorCommand(command, { pattern, files }) {
+  let cmd = command
     .replace(/"\{pattern\}"/g, '{pattern}')
-    .replace(/'\{pattern\}'/g, '{pattern}');
+    .replace(/'\{pattern\}'/g, '{pattern}')
+    .replace(/"\{files\}"/g, '{files}')
+    .replace(/'\{files\}'/g, '{files}');
 
-  // Only substitute {pattern} when it appears as a standalone token
-  // (bounded by whitespace or start/end of string)
-  return cmd.replace(/(?:^|\s)\{pattern\}(?=\s|$)/g, (match) => {
-    const leadingSpace = match.startsWith('{') ? '' : ' ';
-    return leadingSpace + patternSubstitution;
-  });
+  cmd = cmd.replace(/(?:^|\s)\{pattern\}(?=\s|$)/g, (match) =>
+    match.startsWith('{') ? pattern : ' ' + pattern);
+
+  cmd = cmd.replace(/(?:^|\s)\{files\}(?=\s|$)/g, (match) =>
+    match.startsWith('{') ? files : ' ' + files);
+
+  return cmd;
 }

package/dist/.opencode/plugins/foundry.js

@@ -29,6 +29,7 @@ import { createMemoryTools } from './foundry-tools/memory-tools.js';
 import { createMemoryAdminTools } from './foundry-tools/memory-admin-tools.js';
 import { createSnapshotTools } from './foundry-tools/snapshot-tools.js';
 import { createAttestationTools } from './foundry-tools/attestation-tools.js';
+import { createRefreshAgentsTool } from './foundry-tools/refresh-agents-tool.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(__dirname, '../..');
@@ -55,6 +56,7 @@ function buildTools(createTool, pending) {
     ...createMemoryAdminTools({ tool: createTool }),
     ...createSnapshotTools({ tool: createTool }),
     ...createAttestationTools({ tool: createTool }),
+    ...createRefreshAgentsTool({ tool: createTool }),
   };
 }