@really-knows-ai/foundry 3.0.2 → 3.2.0

package/README.md

@@ -105,7 +105,7 @@ Add the plugin to `opencode.json`:
 
 Restart OpenCode so the plugin registers its tools and skills. You will see new
 tools and skills become available in OpenCode's command palette once the restart
-completes. The `init-foundry` skill and flow-management tools are now ready to use.
+completes. Flow-management tools are now ready to use.
 
 ---
 
@@ -132,26 +132,23 @@ Add the plugin to `opencode.json` (see Install section above):
 
 Then restart OpenCode so the plugin registers its tools and skills. You will see new
 tools and skills become available in OpenCode's command palette once the restart
-completes. The `init-foundry` skill and flow-management tools are now ready to use.
+completes. Flow-management tools are now ready to use.
 
 ### Phase 2 — Initialise
 
-Open OpenCode in your project repo and say:
+Restart OpenCode after adding the plugin. On boot, the plugin's config hook runs
+a decision tree: if `foundry/` is missing or its VERSION does not match the
+installed plugin version, it bootstraps the directory structure, generates
+`foundry-<model>` stage agent files, installs the user-facing `Foundry` guide
+agent, and tells you to restart again.
 
-```
-> 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.
-
-Restart OpenCode so the new `foundry-<model>` agents register — multi-model dispatch cannot route to agents it cannot discover.
+Restart OpenCode a second time 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/agent-refresh.js

@@ -0,0 +1,184 @@
+// Shared agent-refresh utility for the Foundry plugin.
+// Provides refreshAgents, detectChanges, and writeFoundryGuideAgent
+// used by both the config hook and the foundry_refresh_agents tool.
+
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, existsSync } from 'fs';
+import { createHash } from 'crypto';
+
+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');
+  }
+}
+
+/**
+ * Snapshot the current foundry-*.md agent files in the agents directory.
+ * Returns a plain object mapping filename → sha256 hex digest.
+ * Returns an empty object when the directory does not exist.
+ */
+function takeSnapshot(agentsDir) {
+  const snapshot = {};
+  try {
+    const entries = readdirSync(agentsDir)
+      .filter(e => e.startsWith('foundry-') && e.endsWith('.md'))
+      .sort();
+    for (const entry of entries) {
+      const content = readFileSync(path.join(agentsDir, entry));
+      snapshot[entry] = createHash('sha256').update(content).digest('hex');
+    }
+  } catch {
+    // Directory does not exist yet — empty snapshot
+  }
+  return snapshot;
+}
+
+/**
+ * Compare two snapshots for equality.
+ * Returns true when both have the same files with the same content hashes.
+ */
+function snapshotsEqual(a, b) {
+  const aKeys = Object.keys(a).sort();
+  const bKeys = Object.keys(b).sort();
+  if (aKeys.length !== bKeys.length) return false;
+  return aKeys.every(k => a[k] === b[k]);
+}
+
+/**
+ * Run `opencode models`, delete stale foundry-*.md agent files,
+ * and write new ones for each model returned.
+ *
+ * @param {string} worktree - Absolute path to the project worktree root.
+ * @returns {{ ok: true, count: number } | { ok: false, error: string }}
+ */
+export function refreshAgents(worktree) {
+  try {
+    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 };
+  } catch (err) {
+    return { ok: false, error: err.message ?? String(err) };
+  }
+}
+
+/**
+ * Snapshot the current foundry-*.md agent files, run refreshAgents,
+ * then compare the before/after file sets to detect changes.
+ *
+ * When refreshAgents returns { ok: false, error }, the error is
+ * propagated immediately without performing a comparison.
+ *
+ * @param {string} worktree - Absolute path to the project worktree root.
+ * @returns {{ ok: true, changed: boolean, count: number } | { ok: false, error: string }}
+ */
+export function detectChanges(worktree) {
+  const agentsDir = path.join(worktree, '.opencode', 'agents');
+  const before = takeSnapshot(agentsDir);
+
+  const result = refreshAgents(worktree);
+  if (!result.ok) {
+    return result;
+  }
+
+  const after = takeSnapshot(agentsDir);
+  const changed = !snapshotsEqual(before, after);
+
+  return { ok: true, changed, count: result.count };
+}
+
+/**
+ * Resolve the guide agent source path within the installed package.
+ * Prefers dist/agents/foundry.md and falls back to src/agents/foundry.md.
+ */
+function resolveGuideSource(packageRoot) {
+  const distPath = path.join(packageRoot, 'dist', 'agents', 'foundry.md');
+  if (existsSync(distPath)) return distPath;
+  return path.join(packageRoot, 'src', 'agents', 'foundry.md');
+}
+
+/**
+ * Copy the Foundry guide agent (foundry.md) from the installed package
+ * to the project's .opencode/agents/ directory.
+ *
+ * Resolves the source from `packageRoot/dist/agents/foundry.md` and
+ * falls back to `packageRoot/src/agents/foundry.md` when the dist
+ * path does not exist. Skips writing when the target file already
+ * exists (uses existsSync check).
+ *
+ * @param {string} worktree - Absolute path to the project worktree root.
+ * @param {string} packageRoot - Absolute path to the installed package root.
+ * @returns {{ ok: true, written: boolean } | { ok: false, error: string }}
+ */
+export function writeFoundryGuideAgent(worktree, packageRoot) {
+  const targetDir = path.join(worktree, '.opencode', 'agents');
+  const targetPath = path.join(targetDir, 'foundry.md');
+
+  if (existsSync(targetPath)) {
+    return { ok: true, written: false };
+  }
+
+  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)}` };
+  }
+}

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,34 +120,32 @@ 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')}
 </FOUNDRY_CONTEXT>`;
 }
 
-export function getBootstrapContent(directory, packageRoot) {
+export function getBootstrapContent(directory, packageRoot, restartNeeded = false) {
+  if (restartNeeded) {
+    return `<FOUNDRY_CONTEXT>
+Foundry initialised. Restart OpenCode so the Foundry agent and model-routing agents register. After restart, switch to the Foundry agent to author and run workflows.
+</FOUNDRY_CONTEXT>`;
+  }
+
   const foundryDir = path.join(directory, 'foundry');
   const foundryExists = existsSync(foundryDir) && statSync(foundryDir).isDirectory();
 

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

@@ -0,0 +1,27 @@
+import { refreshAgents } from './agent-refresh.js';
+
+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);
+          if (!result.ok) {
+            return JSON.stringify({
+              ok: false,
+              error: `foundry_refresh_agents: ${result.error}`,
+            });
+          }
+          return JSON.stringify(result);
+        } catch (err) {
+          return JSON.stringify({
+            ok: false,
+            error: `foundry_refresh_agents: ${err.message ?? String(err)}`,
+          });
+        }
+      },
+    }),
+  };
+}

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

@@ -1,17 +1,22 @@
 /**
  * Foundry plugin for OpenCode.ai
  *
- * All skills are always registered. Individual skills check for foundry/ dir.
- * - If foundry/ exists: pipeline context injected into first message
- * - If foundry/ does not exist: minimal prompt guiding user to init-foundry
- * Multi-model agents are managed as .opencode/agents/foundry-*.md files via the refresh-agents skill.
+ * The config hook runs a boot decision tree on every plugin load: if foundry/
+ * is missing or its VERSION mismatches, it bootstraps the directory structure,
+ * agent files, and guide agent, then sets a restartNeeded flag. If VERSION
+ * matches but the agent file set changed, only agents are refreshed. The
+ * message-transform hook injects either a restart prompt or the full Foundry
+ * context based on the restartNeeded flag. All skills are always registered;
+ * individual skills check for foundry/ dir.
  */
 
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { tool } from '@opencode-ai/plugin';
 import { createPendingStore } from '../../scripts/lib/pending.js';
 import { getBootstrapContent } from './foundry-tools/helpers.js';
+import { refreshAgents, detectChanges, writeFoundryGuideAgent } from './foundry-tools/agent-refresh.js';
 import { createHistoryTools } from './foundry-tools/history-tools.js';
 import { createStageTools } from './foundry-tools/stage-tools.js';
 import { createWorkfileTools } from './foundry-tools/workfile-tools.js';
@@ -29,11 +34,103 @@ 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, '../..');
 const allSkillsDir = path.join(packageRoot, 'skills');
 
+// Module-level flag shared between config and message-transform hooks.
+let restartNeeded = false;
+
+// -- Bootstrap helpers --
+
+function bootstrapDirectories(worktree) {
+  const foundryDir = path.join(worktree, 'foundry');
+  mkdirSync(foundryDir, { recursive: true });
+  for (const sub of ['artefacts', 'flows', 'cycles', 'laws', 'appraisers']) {
+    const subDir = path.join(foundryDir, sub);
+    mkdirSync(subDir, { recursive: true });
+    const gitkeep = path.join(subDir, '.gitkeep');
+    if (!existsSync(gitkeep)) {
+      writeFileSync(gitkeep, '', 'utf8');
+    }
+  }
+}
+
+function ensureNewlineSuffix(str) {
+  if (str !== '' && !str.endsWith('\n')) return str + '\n';
+  return str;
+}
+
+function bootstrapGitignore(worktree) {
+  const gitignorePath = path.join(worktree, '.gitignore');
+  let content = '';
+  if (existsSync(gitignorePath)) {
+    content = readFileSync(gitignorePath, 'utf8');
+  }
+  content = ensureNewlineSuffix(content);
+  const existingLines = content.split('\n').map(l => l.trim());
+  const lines = ['.snapshots/', 'node_modules/', '.DS_Store'];
+  for (const line of lines) {
+    if (existingLines.includes(line)) continue;
+    content += `${line}\n`;
+  }
+  writeFileSync(gitignorePath, content, 'utf8');
+}
+
+function runBootstrapSequence(worktree, pkgRoot) {
+  bootstrapDirectories(worktree);
+  bootstrapGitignore(worktree);
+  refreshAgents(worktree);
+  writeFoundryGuideAgent(worktree, pkgRoot);
+  const pkg = JSON.parse(readFileSync(path.join(pkgRoot, 'package.json'), 'utf8'));
+  writeFileSync(path.join(worktree, 'foundry', 'VERSION'), pkg.version, 'utf8');
+}
+
+function checkVersionMatch(foundryDir, pkgRoot) {
+  try {
+    const installedVersion = readFileSync(path.join(foundryDir, 'VERSION'), 'utf8').trim();
+    const pkg = JSON.parse(readFileSync(path.join(pkgRoot, 'package.json'), 'utf8'));
+    return installedVersion === pkg.version;
+  } catch {
+    return false;
+  }
+}
+
+function isFoundryPopulated(worktree) {
+  const foundryDir = path.join(worktree, 'foundry');
+  if (!existsSync(foundryDir)) return false;
+  return readdirSync(foundryDir).some(e => e !== '.gitkeep');
+}
+
+function ensureGuideAgent(worktree, pkgRoot) {
+  const guideAgentPath = path.join(worktree, '.opencode', 'agents', 'foundry.md');
+  if (!existsSync(guideAgentPath)) {
+    writeFoundryGuideAgent(worktree, pkgRoot);
+    return true;
+  }
+  return false;
+}
+
+function runConfigBootstrap(worktree, pkgRoot) {
+  if (!isFoundryPopulated(worktree)) {
+    runBootstrapSequence(worktree, pkgRoot);
+    return true;
+  }
+
+  const foundryDir = path.join(worktree, 'foundry');
+  if (!checkVersionMatch(foundryDir, pkgRoot)) {
+    runBootstrapSequence(worktree, pkgRoot);
+    return true;
+  }
+
+  const result = detectChanges(worktree);
+  const changed = result.ok && result.changed;
+  const guideWritten = ensureGuideAgent(worktree, pkgRoot);
+  return changed || guideWritten;
+}
+
 export { buildCyclePromptExtras } from './foundry-tools/helpers.js';
 
 function buildTools(createTool, pending) {
@@ -55,6 +152,7 @@ function buildTools(createTool, pending) {
     ...createMemoryAdminTools({ tool: createTool }),
     ...createSnapshotTools({ tool: createTool }),
     ...createAttestationTools({ tool: createTool }),
+    ...createRefreshAgentsTool({ tool: createTool }),
   };
 }
 
@@ -82,10 +180,17 @@ export const FoundryPlugin = async ({ directory }) => {
       if (!config.skills.paths.includes(allSkillsDir)) {
         config.skills.paths.push(allSkillsDir);
       }
+
+      // Boot decision tree: bootstrap or detect changes, then set restart flag
+      try {
+        restartNeeded = runConfigBootstrap(directory, packageRoot);
+      } catch (err) {
+        console.error('Foundry bootstrap error:', err.message);
+      }
     },
 
     'experimental.chat.messages.transform': async (_input, output) => {
-      const bootstrap = getBootstrapContent(directory, packageRoot);
+      const bootstrap = getBootstrapContent(directory, packageRoot, restartNeeded);
       if (!bootstrap) return;
 
       const firstUser = getFirstUserWithParts(output);
@@ -101,5 +206,9 @@ export const FoundryPlugin = async ({ directory }) => {
   };
 
   Object.defineProperty(plugin, Symbol.for('foundry.test.pending'), { value: pending });
+  Object.defineProperty(plugin, Symbol.for('foundry.test.restartNeeded'), {
+    get: () => restartNeeded,
+    configurable: true,
+  });
   return plugin;
 };

package/dist/CHANGELOG.md

@@ -1,5 +1,166 @@
 # Changelog
 
+## [3.2.0] - 2026-05-14
+
+Plugin auto-bootstrapping release. Foundry now ensures the guide agent is
+present on every plugin load and deletes the now-redundant `init-foundry`
+skill. The project also ships a publish-release skill and documented
+workflows for plans and git worktrees.
+
+### Added
+
+- **Bootstrap logic** (`src/plugin.js`). On every `detectChanges` call,
+  Foundry ensures the guide agent file (`foundry.md`) exists in
+  `.opencode/agents/`, running the same deterministic agent-refresh path
+  that the `foundry_refresh_agents` tool uses. If the guide agent is
+  newly created, a post-install restart message is injected into the
+  detection context.
+- **`publish-release` skill** (`.opencode/skills/publish-release/`). A
+  workflow skill that commits loose changes, runs the quality gate,
+  bumps the version, updates the changelog, tags, pushes, and publishes
+  to npm.
+
+### Changed
+
+- **`init-foundry` skill removed.** The manual installation step is
+  replaced by deterministic auto-bootstrapping on plugin load.
+  `init-foundry` was the last on-ramp skill; new users no longer need
+  to run any skill after `pnpm add`.
+- **Shared agent-refresh utility extracted** (`src/lib/agent-refresh.js`).
+  The deterministic agent generation logic that lived in
+  `scripts/tools/foundry_refresh_agents.js` is now a shared module,
+  consumed by both the tool and the `detectChanges` bootstrap path.
+- **Phase reviews run in parallel** with partitioned iteration via
+  parallel implementer agents.
+- **Implementer agent model** updated to `deepseek-v4-flash`.
+
+### Fixed
+
+- **Guide agent now always present after `detectChanges`.** Previously
+  the guide agent could be absent until `init-foundry` or
+  `foundry_refresh_agents` was explicitly run.
+- **Guide agent preserved during `foundry_refresh_agents`.** The refresh
+  tool now ensures `foundry.md` is generated alongside stage agents,
+  not just preserved.
+
+### Docs
+
+- Git worktrees in `.worktrees/` directory documented.
+- Plans directory workflow and phased planning skills documented.
+
+## [3.1.0] - 2026-05-11
+
+The Foundry guide agent release. Foundry now ships a user-facing agent that
+routes configuration authoring through Foundry concepts — users ask the Foundry
+agent for outcomes, and the agent composes dependent work internally rather than
+handing users a chain of individual tools and skills.
+
+### Added
+
+- **Foundry guide agent** (`src/agents/foundry.md`). A user-facing agent with
+  identity marker *"You are the Foundry agent"* that maps user requests to
+  Foundry concepts, routes through the standard config-branch workflow, and
+  delegates to authoring skills internally.
+- **`foundry_refresh_agents` tool.** Deterministic stage-agent generation: runs
+  `opencode models`, deletes stale `.opencode/agents/foundry-*.md` files, and
+  writes fresh agent files — one per available model. Replaces the prior
+  skill-only protocol where the LLM had to implement the logic with shell
+  commands.
+- **`init-foundry` installs the guide agent.** Step 5 creates
+  `.opencode/agents/foundry.md` (preferring `dist/agents/foundry.md`, falling
+  back to `src/agents/foundry.md`), then instructs the user to restart OpenCode
+  and switch to the Foundry agent.
+- **Comprehensive guidance audit tests.** `tests/skills/foundry-guidance-audit.test.js`
+  (357 lines) and `tests/skills/authoring-guidance.test.js` (45 lines) enforce
+  that skills avoid dead-end delegation patterns, route through the Foundry
+  agent, keep internal tool-call syntax out of normal user guidance, and handle
+  config branches and dependencies internally.
+- **Packaging test** (`tests/plugin/packaging.test.js`). Verifies the published
+  package ships `dist/agents/` so `init-foundry` can locate the guide agent
+  template in a packaged install.
+
+### Changed
+
+- **Authoring skills reworked around the Foundry agent.** `add-flow`,
+  `add-cycle`, `add-artefact-type`, `add-law`, and `add-appraiser` now include a
+  `## Foundry Agent Preflight` section; and frame user requests as Foundry
+  outcomes, compose missing dependencies internally in validation order, and
+  hide internal tool-call syntax from normal user guidance (`foundry_git_branch`,
+  `foundry_git_finish`, `foundry_config_create_*`).
+- **Memory/config skills handle branches and dependencies internally.**
+  `init-memory`, `reset-memory`, `add-memory-entity-type`, `add-memory-edge-type`,
+  `add-extractor`, and the `rename-memory-*` / `drop-memory-*` /
+  `change-embedding-model` skills no longer tell the user to create config
+  branches or run prerequisite skills. All use *"move to a suitable `config/*`
+  branch internally when the current branch is safe"* with `work/*` /
+  `dry-run/*/*` / uncommitted-change guards.
+- **`add-extractor` composes cycle wiring internally.** The skill updates
+  relevant cycle definitions rather than presenting manual frontmatter editing
+  as the normal outcome.
+- **`add-cycle` hides generated stage-agent files.** Model selection guidance
+  now references *"Available session models are listed in your session
+  configuration"* instead of exposing `.opencode/agents/foundry-*.md`.
+- **Existing-file recovery keeps the agent in the loop.** When
+  `foundry_config_create_*` returns `{ ok: false }` because the target file
+  already exists, `add-artefact-type`, `add-appraiser`, `add-law`, and
+  `add-cycle` now read the existing content, incorporate the user's requested
+  changes, propose the merged result, and commit — rather than telling the user
+  to *"edit by hand."*
+- **Bootstrap context** (`helpers.js`) presents capabilities as Foundry
+  outcomes (*"ask the Foundry agent to add flow memory"*, *"ask the Foundry
+  agent to run that flow"*) instead of listing internal skills.
+- **`getting-started.md` reworked.** The walkthrough now routes through the
+  Foundry agent, removes direct `foundry_git_branch({` /
+  `foundry_git_finish({` / `Run \`add-*\`` / `foundry_config_validate_*({` /
+  `foundry_config_create_*({` references, and uses `pnpm add -D
+  @really-knows-ai/foundry`.
+- **`README.md` quick-start** updated for the install → init → ask-agent
+  workflow (`pnpm add -D @really-knows-ai/foundry`, ask the Foundry agent
+  to add a haiku flow).
+- **`refresh-agents` skill** delegates to `foundry_refresh_agents()`. The skill
+  is now a thin wrapper around the deterministic tool.
+- **`init-foundry`, `list-agents`, `sort.js`, `upgrade-foundry`** updated to
+  reference the `foundry_refresh_agents` tool.
+- **Docs** (`architecture.md`, `concepts.md`, `tools.md`) updated to reference
+  guide-agent installation and the refresh tool. Tool count increased from 66 to
+  67.
+
+### Fixed
+
+- **`dist/agents/` added to the published package.** The build script already
+  copied `src/agents/` to `dist/agents/`, but the `files` array in
+  `package.json` excluded `dist/agents/`. `init-foundry` can now locate the
+  guide agent template in a packaged install.
+- **`foundry_refresh_agents` preserves the guide agent.** Only
+  `foundry-*.md` stage agents are regenerated; `.opencode/agents/foundry.md`
+  survives refresh.
+
+## [3.0.3] - 2026-05-11
+
+A patch release that makes agent-file generation deterministic by moving
+`refresh-agents` from a skill-only protocol into a tested plugin tool.
+
+### Added
+
+- **`foundry_refresh_agents` tool.** Runs `opencode models`, deletes stale
+  `.opencode/agents/foundry-*.md` files, and generates fresh agent files — one
+  per available model. The tool is idempotent, handles missing directories, and
+  returns `{ ok: true, count: <n> }` on success. This replaces the prior
+  skill-only protocol where the LLM had to implement the logic with shell
+  commands, which was error-prone and non-deterministic.
+
+### Changed
+
+- **`refresh-agents` skill** now simply calls `foundry_refresh_agents()` and
+  reports the result.
+- **`init-foundry` skill** step 4 now calls `foundry_refresh_agents()` instead
+  of instructing the LLM to run the `refresh-agents` skill.
+- **`list-agents` skill** error message now references the tool.
+- **`sort.js`** missing-agent error now references the tool.
+- **`helpers.js`** bootstrap message now references the tool.
+- **Docs** (`tools.md`, `getting-started.md`, `architecture.md`, `concepts.md`)
+  updated to reference the tool. Tool count increased from 65 to 66.
+
 ## [3.0.2] - 2026-05-11
 
 A documentation and tool-correctness patch driven by a failing