@really-knows-ai/foundry 3.1.0 → 3.2.1

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,23 +132,19 @@ 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>` 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 agents register. After the restart, switch to the
-**Foundry** agent. The Foundry agent is the normal interface for authoring and
-running Foundry workflows.
+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 — Ask the Foundry agent for a flow
 

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

@@ -0,0 +1,185 @@
+// 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'],
+    env: { ...process.env, FOUNDRY_SKIP_BOOTSTRAP: '1' },
+  });
+  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

@@ -139,7 +139,13 @@ 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

@@ -1,71 +1,4 @@
-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 };
-}
+import { refreshAgents } from './agent-refresh.js';
 
 export function createRefreshAgentsTool({ tool }) {
   return {
@@ -75,6 +8,12 @@ export function createRefreshAgentsTool({ tool }) {
       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({

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';
@@ -35,6 +40,109 @@ 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;
+}
+
+function runPluginBootstrap(worktree, pkgRoot) {
+  // Skip if FOUNDRY_SKIP_BOOTSTRAP is set to prevent infinite recursion
+  // when this plugin spawns `opencode models` as a child process.
+  if (process.env.FOUNDRY_SKIP_BOOTSTRAP === '1') return false;
+  try {
+    return runConfigBootstrap(worktree, pkgRoot);
+  } catch (err) {
+    console.error('Foundry bootstrap error:', err.message);
+    return false;
+  }
+}
+
 export { buildCyclePromptExtras } from './foundry-tools/helpers.js';
 
 function buildTools(createTool, pending) {
@@ -84,10 +192,12 @@ export const FoundryPlugin = async ({ directory }) => {
       if (!config.skills.paths.includes(allSkillsDir)) {
         config.skills.paths.push(allSkillsDir);
       }
+
+      restartNeeded = runPluginBootstrap(directory, packageRoot);
     },
 
     '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);
@@ -103,5 +213,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,65 @@
 # Changelog
 
+## [3.2.1] - 2026-05-14
+
+### Fixed
+
+- **Plugin hangs on startup due to infinite recursion.** The config hook's
+  `refreshAgents` call spawns `opencode models` via `execFileSync`. When the
+  project directory has the foundry plugin configured, the child process
+  loads plugins too, triggering another `opencode models` — infinite
+  synchronous recursion that hangs the parent. The plugin now sets
+  `FOUNDRY_SKIP_BOOTSTRAP=1` in the child process environment and skips the
+  bootstrap in the config hook when that variable is set.
+
+## [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

package/dist/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,23 +132,19 @@ 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>` 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 agents register. After the restart, switch to the
-**Foundry** agent. The Foundry agent is the normal interface for authoring and
-running Foundry workflows.
+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 — Ask the Foundry agent for a flow
 

package/dist/docs/README.md

@@ -10,7 +10,7 @@ Getting oriented with Foundry means understanding both the concepts it uses and
 
 **Reading order:** Work through them in order; [getting-started.md](getting-started.md) builds hands-on confidence, and [concepts.md](concepts.md) provides reference depth. Most implementers spend 1–2 hours on getting-started before moving to Reference materials.
 
-- **getting-started.md** — Complete end-to-end installation, bootstrap (`init-foundry`), and first flow walkthrough. Read this immediately after installing the plugin and before authoring any of your own configuration. 
+- **getting-started.md** — Complete end-to-end installation, auto-bootstrapping, and first flow walkthrough. Read this immediately after installing the plugin and before authoring any of your own configuration. 
 
   It establishes the operating model, directory structure, and practical confidence in one pass. Includes hands-on guidance on authoring the five foundational concepts (artefact types, laws, appraisers, cycles, flows) with worked examples you can run against real code. Also covers the optional flow-memory path: initialise memory, declare vocabulary, add extractors, and opt a cycle into assay for codebase-aware flows.
 

package/dist/docs/architecture.md

@@ -300,7 +300,7 @@ Different stages can run on different models for cognitive diversity. Cycle defi
 
 ### Agent files
 
-The user-facing `Foundry` agent is installed by `init-foundry` as `.opencode/agents/foundry.md`. Users switch to this agent after restarting OpenCode. It guides authoring and flow execution while generated `foundry-*` stage agents remain hidden routing targets for specific models.
+The user-facing `Foundry` agent is installed by the plugin's `config` hook as `.opencode/agents/foundry.md`. Users switch to this agent after restarting OpenCode. It guides authoring and flow execution while generated `foundry-*` stage agents remain hidden routing targets for specific models.
 
 `foundry_refresh_agents()` generates a `foundry-<slug>.md` agent file in `.opencode/agents/` for every model available in the session, where `<slug>` is the model ID with both `/` and `.` replaced by `-` (e.g. `anthropic-claude-opus-4-7.md`).
 
@@ -330,7 +330,7 @@ Implementation: `src/plugin/tools/helpers.js` (`buildCyclePromptExtras`) and `sr
 │   │   ├── quench/
 │   │   ├── appraise/
 │   │   ├── human-appraise/
-│   │   ├── init-foundry/       # authoring
+│   │   ├── add-artefact-type/  # authoring
 │   │   ├── add-artefact-type/
 │   │   ├── add-law/
 │   │   ├── add-appraiser/
@@ -391,7 +391,7 @@ Implementation: `src/plugin/tools/helpers.js` (`buildCyclePromptExtras`) and `sr
 └── README.md
 ```
 
-### User project (after `init-foundry`)
+### User project (after auto-bootstrapping)
 
 ```
 your-project/

package/dist/docs/concepts.md

@@ -252,7 +252,7 @@ plain-files directory at `.snapshots/<runId>/` on the parent
 - `trace.jsonl` — the full tool-call trace.
 
 `runId` is `<branch-slug>-<ulid>`. Snapshots are gitignored
-(`.snapshots/` is added to `.gitignore` by `init-foundry`) and
+(`.snapshots/` is added to `.gitignore` by the plugin's auto-bootstrapping) and
 accumulate locally; `foundry_snapshot_list` enumerates them,
 `foundry_snapshot_show` returns a structured summary,
 `foundry_snapshot_delete` removes one, and

package/dist/docs/getting-started.md

@@ -31,11 +31,9 @@ pnpm add -D @really-knows-ai/foundry
 
 ## Initialise
 
-Run the `init-foundry` skill.
+Restart OpenCode after adding the plugin. On boot, the plugin's config hook checks project state: if `foundry/` is missing or its VERSION does not match the installed plugin version, it bootstraps the directory structure, generates model-routing `foundry-*` stage agents, installs the user-facing `Foundry` guide agent, and prompts a second restart.
 
-Initialisation installs the user-facing `Foundry` agent at `.opencode/agents/foundry.md` and generates model-routing `foundry-*` stage agents for any models available in your OpenCode session.
-
-Restart OpenCode after initialisation. Then switch to the **Foundry** agent before authoring flows. The Foundry agent understands Foundry's authoring workflow and handles dependent setup such as artefact types, laws, validators, appraisers, cycles, and config branches.
+Restart OpenCode again so the new agents register. Then switch to the **Foundry** agent before authoring flows. The Foundry agent understands Foundry's authoring workflow and handles dependent setup such as artefact types, laws, validators, appraisers, cycles, and config branches.
 
 The `.foundry/` runtime directory (holding `.secret` for stage tokens) is created automatically on first plugin boot and added to `.gitignore`.
 

package/dist/scripts/lib/foundational-guards.js

@@ -8,6 +8,6 @@ export function requireFoundryRoot(io) {
   if (io.exists('foundry')) return { ok: true };
   return {
     ok: false,
-    error: 'foundry/ directory not found at worktree root. Run the init-foundry skill to scaffold it.',
+    error: 'foundry/ directory not found at worktree root. Restart OpenCode to initialise Foundry.',
   };
 }

package/dist/scripts/lib/memory/admin/init.js

@@ -87,7 +87,7 @@ function buildSchema(embeddingsEnabled, model, dimensions) {
 
 async function validatePrerequisites(io, p) {
   if (!(await io.exists('foundry'))) {
-    throw new Error('foundry/ does not exist; run init-foundry first');
+    throw new Error('foundry/ does not exist. Restart OpenCode to initialise Foundry.');
   }
   if (await io.exists(p.root)) {
     throw new Error('foundry/memory/ already exists');

package/dist/skills/add-extractor/SKILL.md

@@ -15,9 +15,7 @@ Before running this skill, verify all of the following:
 1. The `foundry/` directory exists in the project root. If it does not
    exist, stop and tell the user:
 
-   > Foundry is not initialized in this project. Run the
-   > `init-foundry` skill first to create the foundry/ directory
-   > structure.
+   > Restart OpenCode to initialise Foundry, then retry this command.
 
 2. The current git branch is a `config/*` branch. Run
    `git rev-parse --abbrev-ref HEAD` and confirm it matches

package/dist/skills/add-memory-edge-type/SKILL.md

@@ -13,9 +13,7 @@ Before running this skill, verify all of the following:
 1. The `foundry/` directory exists in the project root. If it does not
    exist, stop and tell the user:
 
-   > Foundry is not initialized in this project. Run the
-   > `init-foundry` skill first to create the foundry/ directory
-   > structure.
+   > Restart OpenCode to initialise Foundry, then retry this command.
 
 2. The current git branch is a `config/*` branch. Run
    `git rev-parse --abbrev-ref HEAD` and confirm it matches

package/dist/skills/add-memory-entity-type/SKILL.md

@@ -16,9 +16,7 @@ Before running this skill, verify all of the following:
 1. The `foundry/` directory exists in the project root. If it does not
    exist, stop and tell the user:
 
-   > Foundry is not initialized in this project. Run the
-   > `init-foundry` skill first to create the foundry/ directory
-   > structure.
+   > Restart OpenCode to initialise Foundry, then retry this command.
 
 2. The current git branch is a `config/*` branch. Run
    `git rev-parse --abbrev-ref HEAD` and confirm it matches

package/dist/skills/appraise/SKILL.md

@@ -12,7 +12,7 @@ You orchestrate subjective appraisal of an artefact by dispatching independent s
 
 Before running this skill, verify that the `foundry/` directory exists in the project root. If it does not exist, stop and tell the user:
 
-> Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+> Restart OpenCode to initialise Foundry, then retry this command.
 
 ## Stage lifecycle (mandatory)
 

package/dist/skills/change-embedding-model/SKILL.md

@@ -16,9 +16,7 @@ Before running this skill, verify all of the following:
 1. The `foundry/` directory exists in the project root. If it does not
    exist, stop and tell the user:
 
-   > Foundry is not initialized in this project. Run the
-   > `init-foundry` skill first to create the foundry/ directory
-   > structure.
+   > Restart OpenCode to initialise Foundry, then retry this command.
 
 2. The current git branch is a `config/*` branch. Run
    `git rev-parse --abbrev-ref HEAD` and confirm it matches

package/dist/skills/drop-memory-edge-type/SKILL.md

@@ -15,9 +15,7 @@ Before running this skill, verify all of the following:
 1. The `foundry/` directory exists in the project root. If it does not
    exist, stop and tell the user:
 
-   > Foundry is not initialized in this project. Run the
-   > `init-foundry` skill first to create the foundry/ directory
-   > structure.
+   > Restart OpenCode to initialise Foundry, then retry this command.
 
 2. The current git branch is a `config/*` branch. Run
    `git rev-parse --abbrev-ref HEAD` and confirm it matches

package/dist/skills/drop-memory-entity-type/SKILL.md

@@ -16,9 +16,7 @@ Before running this skill, verify all of the following:
 1. The `foundry/` directory exists in the project root. If it does not
    exist, stop and tell the user:
 
-   > Foundry is not initialized in this project. Run the
-   > `init-foundry` skill first to create the foundry/ directory
-   > structure.
+   > Restart OpenCode to initialise Foundry, then retry this command.
 
 2. The current git branch is a `config/*` branch. Run
    `git rev-parse --abbrev-ref HEAD` and confirm it matches

package/dist/skills/flow/SKILL.md

@@ -15,7 +15,7 @@ A foundry flow reads a flow definition, creates a work branch, and executes cycl
 
 Before running this skill, verify that the `foundry/` directory exists in the project root. If it does not exist, stop and tell the user:
 
-> Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+> Restart OpenCode to initialise Foundry, then retry this command.
 
 ## Starting a flow
 

package/dist/skills/forge/SKILL.md

@@ -12,7 +12,7 @@ You produce or revise artefacts. You read the work file to understand the goal,
 
 Before running this skill, verify that the `foundry/` directory exists in the project root. If it does not exist, stop and tell the user:
 
-> Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+> Restart OpenCode to initialise Foundry, then retry this command.
 
 ## Stage lifecycle (mandatory)
 

package/dist/skills/human-appraise/SKILL.md

@@ -12,7 +12,7 @@ You are a human quality gate. Sort has routed to you either because the LLM appr
 
 Before running this skill, verify that the `foundry/` directory exists in the project root. If it does not exist, stop and tell the user:
 
-> Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+> Restart OpenCode to initialise Foundry, then retry this command.
 
 ## Stage lifecycle (mandatory)
 

package/dist/skills/init-memory/SKILL.md

@@ -19,9 +19,7 @@ Before running this skill, verify all of the following:
 1. The `foundry/` directory exists in the project root. If it does not
    exist, stop and tell the user:
 
-   > Foundry is not initialized in this project. Run the
-   > `init-foundry` skill first to create the foundry/ directory
-   > structure.
+   > Restart OpenCode to initialise Foundry, then retry this command.
 
 2. The current git branch is a `config/*` branch. Run
    `git rev-parse --abbrev-ref HEAD` and confirm it matches

package/dist/skills/quench/SKILL.md

@@ -12,7 +12,7 @@ You run deterministic checks on an artefact by executing the CLI commands define
 
 Before running this skill, verify that the `foundry/` directory exists in the project root. If it does not exist, stop and tell the user:
 
-> Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+> Restart OpenCode to initialise Foundry, then retry this command.
 
 ## Stage lifecycle (mandatory)
 

package/dist/skills/rename-memory-edge-type/SKILL.md

@@ -13,9 +13,7 @@ Before running this skill, verify all of the following:
 1. The `foundry/` directory exists in the project root. If it does not
    exist, stop and tell the user:
 
-   > Foundry is not initialized in this project. Run the
-   > `init-foundry` skill first to create the foundry/ directory
-   > structure.
+   > Restart OpenCode to initialise Foundry, then retry this command.
 
 2. The current git branch is a `config/*` branch. Run
    `git rev-parse --abbrev-ref HEAD` and confirm it matches

package/dist/skills/rename-memory-entity-type/SKILL.md

@@ -13,9 +13,7 @@ Before running this skill, verify all of the following:
 1. The `foundry/` directory exists in the project root. If it does not
    exist, stop and tell the user:
 
-   > Foundry is not initialized in this project. Run the
-   > `init-foundry` skill first to create the foundry/ directory
-   > structure.
+   > Restart OpenCode to initialise Foundry, then retry this command.
 
 2. The current git branch is a `config/*` branch. Run
    `git rev-parse --abbrev-ref HEAD` and confirm it matches

package/dist/skills/reset-memory/SKILL.md

@@ -16,9 +16,7 @@ Before running this skill, verify all of the following:
 1. The `foundry/` directory exists in the project root. If it does not
    exist, stop and tell the user:
 
-   > Foundry is not initialized in this project. Run the
-   > `init-foundry` skill first to create the foundry/ directory
-   > structure.
+   > Restart OpenCode to initialise Foundry, then retry this command.
 
 2. The current git branch is a `config/*` branch. Run
    `git rev-parse --abbrev-ref HEAD` and confirm it matches

package/dist/skills/upgrade-foundry/SKILL.md

@@ -14,7 +14,7 @@ This is a rebuild-style upgrade. Treat the old `foundry/` directory as source ma
 
 Before running this skill, verify that the project root contains `foundry/`. If it does not, stop and tell the user:
 
-> Foundry is not initialised in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+> Restart OpenCode to initialise Foundry, then retry this command.
 
 Verify a safe base state before making changes:
 
@@ -53,7 +53,7 @@ Do not modify the preserved source directory after moving it. Read from it as so
 
 ### 3. Initialise current-version configuration
 
-Run the current `init-foundry` flow to create a fresh `foundry/` directory for the installed Foundry version.
+On next restart, the plugin's config hook will auto-initialise a fresh `foundry/` directory.
 
 After initialisation, confirm the new config directory exists and contains the expected current top-level structure.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "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",

package/dist/skills/init-foundry/SKILL.md

@@ -1,96 +0,0 @@
----
-name: init-foundry
-type: atomic
-description: Initialise a Foundry project by creating the foundry/ directory structure
----
-
-# Initialise Foundry
-
-Set up the `foundry/` directory structure in the current project.
-
-## Prerequisites
-
-- The project must not already have a `foundry/` directory.
-
-## Steps
-
-1. **Check for existing foundry/ directory**
-   - If `foundry/` already exists, inform the user and stop.
-
-2. **Create the directory structure**
-   Create the following directories, each with a `.gitkeep` file:
-
-   ```
-   foundry/
-     artefacts/.gitkeep
-     flows/.gitkeep
-     cycles/.gitkeep
-     laws/.gitkeep
-     appraisers/.gitkeep
-   ```
-
-3. **Update `.gitignore`**
-
-   Append the following lines to the project's `.gitignore` (creating
-   the file if absent), skipping any that are already present:
-
-   ```
-   .snapshots/
-   node_modules/
-   .DS_Store
-   ```
-
-   - `.snapshots/` keeps dry-run snapshots out of git.
-   - `node_modules/` keeps any npm dependencies (e.g. validator
-     packages) out of git. Without it, foundry's `config/*` tools
-     reject calls with `unexpected_files` as soon as the user runs
-     `npm install`.
-   - `.DS_Store` keeps macOS metadata out of git.
-
-   The plugin will idempotently append `.foundry/` itself on first
-   boot, so you do not need to add that line.
-
-4. **Generate model-routing agent files**
-
-   Call `foundry_refresh_agents()` to generate model-routing `.opencode/agents/foundry-*.md` files.
-
-5. **Install the Foundry guide agent**
-
-   Create `.opencode/agents/foundry.md` from the packaged Foundry guide
-   agent template. Copy whichever template path exists: prefer
-   `dist/agents/foundry.md` when running from the built package, then
-   fall back to `src/agents/foundry.md` when running from a source
-   checkout. This user-facing agent is installed during `init-foundry`;
-   `foundry_refresh_agents()` manages only generated `foundry-*` stage
-   agents.
-
-6. **Commit the structure**
-
-   ```bash
-   git add foundry/ .gitignore .opencode/agents/foundry.md .opencode/agents/foundry-*.md
-   git commit -m "feat: initialise Foundry project structure"
-   ```
-
-7. **Guide next steps**
-
-   Tell the user:
-
-   > Foundry is initialised. **Restart OpenCode** so the new Foundry agents register.
-   >
-   > After the restart, switch to the **Foundry** agent. The Foundry agent is the user-facing guide for setting up artefact types, laws, validators, appraisers, cycles, and flows.
-   >
-   > Then ask the Foundry agent for the outcome you want, for example:
-   >
-   > `set up a flow that writes haikus`
-   >
-   > The first time the plugin boots in this project, it will create the
-   > `.foundry/` runtime directory and idempotently append `.foundry/` to
-   > `.gitignore` so the per-worktree HMAC key stays out of git. The
-   > `.snapshots/` line was added by this skill to keep dry-run snapshots
-   > out of git.
-   >
-   > **Optional: Flow Memory**
-   >
-   > If your flows need persistent knowledge, ask the Foundry agent to add
-   > flow memory. Memory is useful for projects that need to track code
-   > structure, dependencies, or domain knowledge across flow runs.