@really-knows-ai/foundry 2.3.1 → 3.0.0

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

@@ -0,0 +1,186 @@
+import { execSync } from 'child_process';
+import { createHash } from 'node:crypto';
+import { readActiveStage, writeActiveStage, clearActiveStage, writeLastStage, clearLastStage } from '../../../scripts/lib/state.js';
+import { verifyToken } from '../../../scripts/lib/token.js';
+import { readOrCreateSecret } from '../../../scripts/lib/secret.js';
+import { getContext, invalidateStore } from '../../../scripts/lib/memory/singleton.js';
+import { syncStore } from '../../../scripts/lib/memory/store.js';
+import { makeIO, makeMemoryIO, branchIoFactory, asyncIoFactory, flowBranchGuard } from './helpers.js';
+import { markWorkfileFailed, readFailedStatus, clearWorkfileFailed } from '../../../scripts/lib/failed-flow.js';
+import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
+
+const gateNotFailed = notFailedGuard(makeIO);
+
+// -- Helpers for foundry_stage_begin --
+
+function resolveBaseSha(worktree) {
+  try {
+    return execSync('git rev-parse HEAD', { cwd: worktree }).toString().trim();
+  } catch {
+    return null;
+  }
+}
+
+function verifyStageToken(token, secret, stage, cycle) {
+  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 };
+}
+
+async function executeStageBegin(args, context, pending) {
+  const io = makeIO(context.worktree);
+  const secret = readOrCreateSecret(context.worktree);
+
+  const current = readActiveStage(io);
+  if (current) {
+    return JSON.stringify({ error: `foundry_stage_begin requires no active stage; current: ${current.stage}` });
+  }
+
+  const tokenResult = verifyStageToken(args.token, secret, args.stage, args.cycle);
+  if (tokenResult.error) return JSON.stringify({ error: tokenResult.error });
+
+  const baseSha = resolveBaseSha(context.worktree);
+  if (!baseSha) {
+    return JSON.stringify({ error: 'foundry_stage_begin: git rev-parse HEAD failed (no commits?)' });
+  }
+
+  const meta = pending.consume(tokenResult.payload.nonce);
+  if (!meta) return JSON.stringify({ error: 'foundry_stage_begin: nonce not pending or already consumed' });
+
+  const tokenHash = createHash('sha256').update(args.token).digest('hex');
+  const active = {
+    cycle: args.cycle,
+    stage: args.stage,
+    tokenHash,
+    baseSha,
+    startedAt: new Date().toISOString(),
+  };
+  writeActiveStage(io, active);
+  return JSON.stringify({ ok: true, active });
+}
+
+// -- Helpers for foundry_stage_end --
+
+function markWorkfileFailedSilently(io, msg) {
+  try { markWorkfileFailed(io, msg); } catch { /* WORK.md gone */ }
+}
+
+async function syncMemoryAtStageEnd(worktree) {
+  const memIo = makeMemoryIO(worktree);
+  const ctx = getContext(worktree);
+  if (ctx && ctx.store) {
+    await syncStore({ store: ctx.store, io: memIo });
+  }
+}
+
+async function executeStageEnd(args, context) {
+  const io = makeIO(context.worktree);
+  const active = readActiveStage(io);
+  if (!active) {
+    return JSON.stringify({ error: 'foundry_stage_end requires active stage; current: none' });
+  }
+  writeLastStage(io, {
+    cycle: active.cycle,
+    stage: active.stage,
+    baseSha: active.baseSha,
+    summary: args.summary,
+  });
+  clearActiveStage(io);
+
+  try {
+    await syncMemoryAtStageEnd(context.worktree);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    const msg = `memory sync at stage end failed: ${detail}`;
+    markWorkfileFailedSilently(io, msg);
+    return JSON.stringify({ error: msg, flow_failed: true });
+  }
+  return JSON.stringify({ ok: true, summary: args.summary });
+}
+
+// -- Helpers for foundry_stage_retry --
+
+function checkGitWorkingTreeClean(worktree) {
+  try {
+    const statusOut = execSync('git status --porcelain', { cwd: worktree }).toString();
+    return statusOut.trim() === '' ? { ok: true } : { ok: false };
+  } catch {
+    return { ok: false };
+  }
+}
+
+async function executeStageRetry(_args, context) {
+  const io = makeIO(context.worktree);
+
+  const failed = readFailedStatus(io);
+  if (!failed) {
+    return JSON.stringify({
+      ok: false,
+      error: 'foundry_stage_retry requires failed flow; current status is not failed',
+    });
+  }
+
+  const active = readActiveStage(io);
+  if (active) {
+    return JSON.stringify({
+      ok: false,
+      error: 'foundry_stage_retry requires no active stage; call foundry_stage_end first',
+    });
+  }
+
+  const gitCheck = checkGitWorkingTreeClean(context.worktree);
+  if (!gitCheck.ok) {
+    return JSON.stringify({
+      ok: false,
+      error: 'foundry_stage_retry requires clean git working tree; commit or stash changes first',
+    });
+  }
+
+  invalidateStore(context.worktree);
+
+  try { clearLastStage(io); } catch { /* last-stage.json might not exist */ }
+
+  clearWorkfileFailed(io);
+
+  return JSON.stringify({
+    ok: true,
+    message: 'Flow unlocked. Memory state reset to disk. Stage can be re-run.',
+  });
+}
+
+export function createStageTools({ tool, pending }) {
+  return {
+    foundry_stage_begin: tool({
+      description: 'Open a subagent work stage; consumes a dispatch token from foundry_orchestrate.',
+      args: {
+        stage: tool.schema.string().describe('Stage alias, e.g. "forge:create-haiku"'),
+        cycle: tool.schema.string().describe('Cycle name'),
+        token: tool.schema.string().describe('Token received from foundry_orchestrate via the dispatch prompt'),
+      },
+      execute: guarded('foundry_stage_begin', [flowBranchGuard, gateNotFailed],
+        (args, context) => executeStageBegin(args, context, pending),
+        { branchIo: branchIoFactory, io: asyncIoFactory }),
+    }),
+
+    foundry_stage_end: tool({
+      description: 'Close the active subagent work stage; preserves baseSha for finalize.',
+      args: {
+        summary: tool.schema.string().describe('Short summary of the work done'),
+      },
+      execute: guarded('foundry_stage_end', [flowBranchGuard],
+        executeStageEnd,
+        { branchIo: branchIoFactory, io: asyncIoFactory }),
+    }),
+
+    foundry_stage_retry: tool({
+      description: 'Retry a failed stage by discarding uncommitted memory changes and clearing the failed state. Requires clean git working tree.',
+      args: {},
+      execute: guarded('foundry_stage_retry', [flowBranchGuard],
+        executeStageRetry,
+        { branchIo: branchIoFactory, io: asyncIoFactory }),
+    }),
+  };
+}

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

@@ -0,0 +1,263 @@
+import { execSync } from 'child_process';
+import { readdir } from 'fs/promises';
+import { join, relative, sep } from 'path';
+import { minimatch } from 'minimatch';
+import { getLawsForQuench, getArtefactType } from '../../../scripts/lib/config.js';
+import { parseValidatorJsonl } from '../../../scripts/lib/validator-jsonl.js';
+import { makeIO, branchIoFactory, asyncIoFactory, flowBranchGuard } from './helpers.js';
+import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
+
+const gateNotFailed = notFailedGuard(makeIO);
+
+/**
+ * Shell-quote a string for POSIX `/bin/sh` so it is treated as a single literal
+ * argument. Wraps the value in single quotes and escapes any embedded single
+ * quotes via the `'\''` idiom. Safe for arbitrary file paths including ones
+ * containing spaces, semicolons, `$()`, backticks, quotes, and newlines.
+ */
+function shellQuote(value) {
+  return "'" + String(value).replace(/'/g, "'\\''") + "'";
+}
+
+/**
+ * Execute a validator command and parse its output.
+ */
+async function executeValidator(expanded, worktree, patterns) {
+  try {
+    const output = execSync(expanded, {
+      cwd: worktree,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const { Readable } = await import('stream');
+    const stream = Readable.from([output]);
+    return await parseValidatorJsonl(stream, patterns);
+  } catch (err) {
+    // Validator command failed - prefer stdout for JSONL (tools like rg exit 1 with results on stdout)
+    const output = (err.stdout || err.stderr || err.message || '').trim();
+    const { Readable } = await import('stream');
+    const stream = Readable.from([output]);
+    return await parseValidatorJsonl(stream, patterns);
+  }
+}
+
+/**
+ * Run all validators for laws and collect results.
+ *
+ * Aggregates per-validator parse results into a single structured payload:
+ * - `items`: each successfully parsed feedback item, annotated with the
+ *   `lawId` and `validatorId` it came from. The quench skill consumes this
+ *   to call `foundry_feedback_add` with tag `law:<lawId>:<validatorId>`.
+ * - `errors`: validator-level errors split by type. `parse` for malformed
+ *   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) {
+  const results = {
+    validatorsRun: 0,
+    items: [],
+    errors: [],
+  };
+
+  for (const law of laws) {
+    if (!law.validators || law.validators.length === 0) continue;
+    await runLawValidators(law, patterns, patternSubstitution, worktree, results);
+  }
+
+  return results;
+}
+
+/**
+ * Run validators for a single law.
+ */
+async function runLawValidators(law, patterns, patternSubstitution, 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}')) {
+      continue;
+    }
+    results.validatorsRun++;
+    const expanded = expandValidatorCommand(validator.command, patternSubstitution);
+    const parseResult = await executeValidator(expanded, worktree, patterns);
+    collectValidatorResult(parseResult, law.id, validator.id, results);
+  }
+}
+
+/**
+ * Fold a single validator's parse result into the aggregate results.
+ *
+ * Items always flow through annotated with their `lawId` and `validatorId`,
+ * so the caller can construct `law:<lawId>:<validatorId>` feedback tags.
+ * Errors are surfaced with their type so the caller can distinguish parse
+ * failures from file-pattern mismatches.
+ */
+function collectValidatorResult(parseResult, lawId, validatorId, results) {
+  for (const item of parseResult.items) {
+    results.items.push({ lawId, validatorId, ...item });
+  }
+  for (const message of parseResult.parseErrors) {
+    results.errors.push({ lawId, validatorId, type: 'parse', message });
+  }
+  for (const message of parseResult.patternErrors) {
+    results.errors.push({ lawId, validatorId, type: 'pattern-mismatch', message });
+  }
+}
+
+export function createValidateTools({ tool }) {
+  return {
+    foundry_validate_run: tool({
+      description: 'Run validation commands for an artefact type. Returns parsed feedback items per validator with their law and validator IDs so the caller can tag feedback as law:<law-id>:<validator-id>.',
+      args: {
+        typeId: tool.schema.string().describe('Artefact type ID'),
+      },
+      execute: guarded('foundry_validate_run', [flowBranchGuard, gateNotFailed],
+        executeValidateRun,
+        { branchIo: branchIoFactory, io: asyncIoFactory }),
+    }),
+  };
+}
+
+async function executeValidateRun(args, context) {
+  try {
+    return await performValidation(args, context);
+  } catch (err) {
+    return JSON.stringify({ ok: false, error: `foundry_validate_run: ${err.message}` });
+  }
+}
+
+/**
+ * Perform actual validation work.
+ */
+async function getValidationPatterns(foundryDir, typeId, io) {
+  const artType = await getArtefactType(foundryDir, typeId, io);
+  return artType.frontmatter['file-patterns'] || [];
+}
+
+async function performValidation(args, context) {
+  const io = makeIO(context.worktree);
+  const foundryDir = join(context.worktree, 'foundry');
+
+  let patterns;
+  try {
+    patterns = await getValidationPatterns(foundryDir, args.typeId, io);
+  } catch (err) {
+    return JSON.stringify({ ok: false, error: err.message });
+  }
+
+  const validationErr = validatePatterns(patterns, args.typeId);
+  if (validationErr) return JSON.stringify(validationErr);
+
+  const laws = await getLawsForQuench(foundryDir, io, { typeId: args.typeId });
+  if (!laws?.length) {
+    return JSON.stringify({ ok: true, validatorsRun: 0, items: [], errors: [] });
+  }
+  return runValidatorsAndReport(laws, patterns, context.worktree);
+}
+
+/**
+ * Run validators and report results.
+ */
+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);
+
+  return JSON.stringify({
+    ok: results.errors.length === 0,
+    validatorsRun: results.validatorsRun,
+    items: results.items,
+    errors: results.errors,
+  });
+}
+
+/**
+ * Validate file patterns.
+ */
+function validatePatterns(patterns, typeId) {
+  if (!Array.isArray(patterns) || patterns.length === 0) {
+    return { ok: false, error: `Artefact type ${typeId} has no file-patterns` };
+  }
+  return null;
+}
+
+const SKIP_DIRS = new Set(['node_modules', '.git']);
+
+function toPosix(p) {
+  return sep === '/' ? p : p.split(sep).join('/');
+}
+
+async function readdirSafe(dir) {
+  try {
+    return await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Recursively walk `dir` and yield POSIX-style paths relative to `root`.
+ * Skips `node_modules` and `.git` for speed; the artefacts we validate live
+ * elsewhere.
+ */
+async function* walkFiles(root, dir) {
+  for (const entry of await readdirSafe(dir)) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory() && !SKIP_DIRS.has(entry.name)) {
+      yield* walkFiles(root, full);
+    } else if (entry.isFile()) {
+      yield toPosix(relative(root, full));
+    }
+  }
+}
+
+function fileMatchesAnyPattern(rel, patterns) {
+  for (const pattern of patterns) {
+    if (minimatch(rel, pattern)) return true;
+  }
+  return false;
+}
+
+/**
+ * Expand glob patterns to actual files in the worktree.
+ *
+ * Implemented over `readdir` + `minimatch` so we work on Node 20, which lacks
+ * `fs/promises.glob` (added in Node 22).
+ */
+async function expandPatterns(patterns, worktree) {
+  const files = new Set();
+  for await (const rel of walkFiles(worktree, worktree)) {
+    if (fileMatchesAnyPattern(rel, patterns)) {
+      files.add(rel);
+    }
+  }
+  return Array.from(files).sort();
+}
+
+/**
+ * Expand validator command by replacing {pattern} placeholder.
+ *
+ * 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.
+ *
+ * @param {string} command - The validator command
+ * @param {string} patternSubstitution - Shell-quoted file paths, space-separated
+ * @returns {string} The expanded command
+ */
+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
+    .replace(/"\{pattern\}"/g, '{pattern}')
+    .replace(/'\{pattern\}'/g, '{pattern}');
+
+  // 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;
+  });
+}

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

@@ -0,0 +1,102 @@
+import path from 'path';
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
+import { requireNoActiveStage } from '../../../scripts/lib/stage-guard.js';
+import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
+import { parseFrontmatter, createWorkfile, enrichStages, parseModelsValue } from '../../../scripts/lib/workfile.js';
+import { makeIO, branchIoFactory, asyncIoFactory, flowBranchGuard } from './helpers.js';
+
+const gateNotFailed = notFailedGuard(makeIO);
+
+function buildFrontmatter(args) {
+  const fm = { flow: args.flow, cycle: args.cycle };
+  if (args.stages) {
+    fm.stages = enrichStages(args.stages, args.cycle);
+  }
+  if (args.maxIterations !== undefined) {
+    fm['max-iterations'] = args.maxIterations;
+  }
+  if (args.models) {
+    fm.models = parseModelsValue(args.models);
+  }
+  return fm;
+}
+
+function deleteIfExists(...paths) {
+  for (const p of paths) {
+    if (existsSync(p)) {
+      unlinkSync(p);
+    }
+  }
+}
+
+async function executeWorkfileCreate(args, context) {
+  const io = makeIO(context.worktree);
+  const guard = requireNoActiveStage(io);
+  if (!guard.ok) return JSON.stringify({ error: `foundry_workfile_create ${guard.error}` });
+  const workPath = path.join(context.worktree, 'WORK.md');
+  if (existsSync(workPath)) {
+    return JSON.stringify({ error: 'foundry_workfile_create requires no WORK.md; current: exists' });
+  }
+  const fm = buildFrontmatter(args);
+  const content = createWorkfile(fm, args.goal);
+  writeFileSync(workPath, content, 'utf-8');
+  return JSON.stringify({ ok: true });
+}
+
+async function executeWorkfileDelete(args, context) {
+  const io = makeIO(context.worktree);
+  const guard = requireNoActiveStage(io);
+  if (!guard.ok) return JSON.stringify({ error: `foundry_workfile_delete ${guard.error}` });
+  if (args.confirm !== true) {
+    return JSON.stringify({ error: 'foundry_workfile_delete requires {confirm: true}' });
+  }
+  const workPath = path.join(context.worktree, 'WORK.md');
+  const historyPath = path.join(context.worktree, 'WORK.history.yaml');
+  const feedbackPath = path.join(context.worktree, 'WORK.feedback.yaml');
+  deleteIfExists(workPath, historyPath, feedbackPath);
+  return JSON.stringify({ ok: true });
+}
+
+export function createWorkfileTools({ tool }) {
+  return {
+    foundry_workfile_create: tool({
+      description: 'Create WORK.md with frontmatter and goal',
+      args: {
+        flow: tool.schema.string().describe('Flow name'),
+        cycle: tool.schema.string().describe('Cycle name'),
+        stages: tool.schema.array(tool.schema.string()).optional().describe('Ordered stage names'),
+        maxIterations: tool.schema.number().optional().describe('Maximum iterations'),
+        goal: tool.schema.string().describe('Goal text'),
+        models: tool.schema.string().optional().describe('Per-stage model overrides as JSON object, e.g. \'{"forge":"openai/gpt-4o"}\''),
+      },
+      execute: guarded('foundry_workfile_create', [flowBranchGuard, gateNotFailed], executeWorkfileCreate, { branchIo: branchIoFactory, io: asyncIoFactory }),
+    }),
+
+    foundry_workfile_get: tool({
+      description: 'Read WORK.md and return frontmatter + goal',
+      args: {},
+      async execute(_args, context) {
+        const workPath = path.join(context.worktree, 'WORK.md');
+        if (!existsSync(workPath)) {
+          return JSON.stringify({ error: 'WORK.md not found' });
+        }
+        const text = readFileSync(workPath, 'utf-8');
+        const fm = parseFrontmatter(text);
+        const goalMatch = text.match(/# Goal\n\n([\s\S]*?)(?=\n\||\n##|$)/);
+        const goal = goalMatch ? goalMatch[1].trim() : '';
+        return JSON.stringify({ ...fm, goal });
+      },
+    }),
+
+    foundry_workfile_delete: tool({
+      description: 'Delete WORK.md, WORK.history.yaml, and WORK.feedback.yaml (requires confirm:true)',
+      args: {
+        confirm: tool.schema.boolean().describe('Must be true to confirm deletion'),
+      },
+      // Branch guard only: workfile_delete is the failed-flow escape hatch,
+      // so it must remain callable when WORK.md has status: failed under
+      // the branch guard alone.
+      execute: guarded('foundry_workfile_delete', [flowBranchGuard], executeWorkfileDelete, { branchIo: branchIoFactory, io: asyncIoFactory }),
+    }),
+  };
+}

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

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { tool } from '@opencode-ai/plugin';
+import { createPendingStore } from '../../scripts/lib/pending.js';
+import { getBootstrapContent } from './foundry-tools/helpers.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';
+import { createOrchestrateTool } from './foundry-tools/orchestrate-tool.js';
+import { createArtefactTools } from './foundry-tools/artefact-tools.js';
+import { createFeedbackTools } from './foundry-tools/feedback-tools.js';
+import { createGitTools } from './foundry-tools/git-tools.js';
+import { createConfigTools } from './foundry-tools/config-tools.js';
+import { createConfigCreateTools } from './foundry-tools/config-create-tools.js';
+import { createConfigLawTools } from './foundry-tools/config-law-tools.js';
+import { createValidateTools } from './foundry-tools/validate-tools.js';
+import { createAssayTools } from './foundry-tools/assay-tools.js';
+import { createAppraiserTools } from './foundry-tools/appraiser-tools.js';
+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';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '../..');
+const allSkillsDir = path.join(packageRoot, 'skills');
+
+export { buildCyclePromptExtras } from './foundry-tools/helpers.js';
+
+function buildTools(createTool, pending) {
+  return {
+    ...createHistoryTools({ tool: createTool }),
+    ...createStageTools({ tool: createTool, pending }),
+    ...createWorkfileTools({ tool: createTool }),
+    ...createOrchestrateTool({ tool: createTool, pending }),
+    ...createArtefactTools({ tool: createTool }),
+    ...createFeedbackTools({ tool: createTool }),
+    ...createGitTools({ tool: createTool }),
+    ...createConfigTools({ tool: createTool }),
+    ...createConfigCreateTools({ tool: createTool }),
+    ...createConfigLawTools({ tool: createTool }),
+    ...createValidateTools({ tool: createTool }),
+    ...createAssayTools({ tool: createTool }),
+    ...createAppraiserTools({ tool: createTool }),
+    ...createMemoryTools({ tool: createTool }),
+    ...createMemoryAdminTools({ tool: createTool }),
+    ...createSnapshotTools({ tool: createTool }),
+    ...createAttestationTools({ tool: createTool }),
+  };
+}
+
+function hasFoundryContext(parts) {
+  return parts.some(p => p.type === 'text' && p.text.includes('FOUNDRY_CONTEXT'));
+}
+
+function getFirstUserWithParts(output) {
+  if (!output.messages.length) return null;
+  const firstUser = output.messages.find(m => m.info.role === 'user');
+  if (!firstUser || !firstUser.parts.length) return null;
+  return firstUser;
+}
+
+export const FoundryPlugin = async ({ directory }) => {
+  // Pending store is per-plugin-instance (shared across all tool invocations).
+  const pending = createPendingStore();
+
+  const plugin = {
+    config: async (config) => {
+      config.skills = config.skills || {};
+      config.skills.paths = config.skills.paths || [];
+
+      // Always register all skills — individual skills check for foundry/ dir
+      if (!config.skills.paths.includes(allSkillsDir)) {
+        config.skills.paths.push(allSkillsDir);
+      }
+    },
+
+    'experimental.chat.messages.transform': async (_input, output) => {
+      const bootstrap = getBootstrapContent(directory, packageRoot);
+      if (!bootstrap) return;
+
+      const firstUser = getFirstUserWithParts(output);
+      if (!firstUser) return;
+
+      if (hasFoundryContext(firstUser.parts)) return;
+
+      const ref = firstUser.parts[0];
+      firstUser.parts.unshift({ ...ref, type: 'text', text: bootstrap });
+    },
+
+    tool: buildTools(tool, pending),
+  };
+
+  Object.defineProperty(plugin, Symbol.for('foundry.test.pending'), { value: pending });
+  return plugin;
+};