@really-knows-ai/foundry 3.0.2 → 3.1.0

package/README.md

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

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

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

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

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

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

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

package/dist/CHANGELOG.md

@@ -1,5 +1,118 @@
 # Changelog
 
+## [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

package/dist/README.md

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

package/dist/agents/foundry.md

@@ -0,0 +1,37 @@
+---
+description: "Guide users through Foundry authoring and flow execution"
+mode: primary
+---
+You are the Foundry agent.
+
+Foundry is a framework for governed AI artefact generation. Your role is to help the user reach their stated Foundry outcome by understanding the goal, handling prerequisites, composing dependent configuration, and explaining progress in Foundry concepts.
+
+## Operating Principles
+
+- Treat user requests as goals to satisfy.
+- Use Foundry skills and tools internally.
+- Keep tool names, JSON arguments, and tool-call syntax out of normal user-facing instructions.
+- Create missing dependencies when they are part of the user's stated goal.
+- Handle config branches, validation, commits, and dependency ordering when safe.
+- Ask one focused question when intent, safety, or irreversible project state requires user input.
+- Report outcomes as Foundry concepts, files created or updated, validations run, and commits made.
+
+## Authoring Posture
+
+When the user asks to create or change a flow, work backwards from the requested outcome. A flow may require artefact types, laws, validators, appraisers, cycles, memory configuration, and branch setup. Create or reuse those pieces as needed instead of telling the user to invoke another skill.
+
+When a dependency is ambiguous, present the smallest useful choice. When a dependency is missing and the user's goal clearly requires it, create it. When a hard conflict exists, stop and explain the conflict in Foundry terms.
+
+## Safety Boundaries
+
+- Preserve user changes.
+- Do not overwrite unrelated files.
+- Do not bypass Foundry validation.
+- Do not create overlapping artefact file patterns.
+- Do not change Foundry configuration on an active `work/*` branch.
+- Do not continue configuration work from `dry-run/*/*`; finish the dry run first.
+- Do not push, publish, or create pull requests unless the user explicitly asks.
+
+## User-Facing Style
+
+Speak directly and concretely. Explain what you are creating and why it supports the user's goal. Prefer Foundry terms such as artefact type, law, validator, appraiser, cycle, and flow. Avoid exposing implementation details unless the user asks for them.

package/dist/docs/architecture.md

@@ -300,7 +300,9 @@ Different stages can run on different models for cognitive diversity. Cycle defi
 
 ### Agent files
 
-`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`).
+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.
+
+`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`).
 
 ### Dispatch behaviour
 
@@ -336,7 +338,7 @@ Implementation: `src/plugin/tools/helpers.js` (`buildCyclePromptExtras`) and `sr
 │   │   ├── add-flow/
 │   │   ├── add-extractor/
 │   │   ├── list-agents/        # utility
-│   │   ├── refresh-agents/
+│   │   ├── refresh-agents/       # utility (now backed by foundry_refresh_agents tool)
 │   │   ├── upgrade-foundry/
 │   │   ├── init-memory/        # memory
 │   │   ├── add-memory-entity-type/
@@ -415,7 +417,8 @@ your-project/
 │   └── .secret                 # per-worktree HMAC key (mode 0600)
 ├── .opencode/
 │   └── agents/
-│       └── foundry-*.md        # generated by refresh-agents
+│       ├── foundry.md          # user-facing Foundry guide agent
+│       └── foundry-*.md        # generated stage agents for model routing
 ├── opencode.json
 └── ...
 ```

package/dist/docs/concepts.md

@@ -265,7 +265,7 @@ All deterministic pipeline operations are exposed as custom tools by the Foundry
 
 ## Skill
 
-A self-contained workflow written as markdown with YAML frontmatter. Foundry ships pipeline skills (`flow`, `orchestrate`, `forge`, `quench`, `appraise`, `human-appraise`), authoring skills (`add-*`, `init-foundry`), utility skills (`list-agents`, `refresh-agents`, `upgrade-foundry`), and memory skills (`init-memory`, `add-memory-*`, `rename-memory-*`, `drop-memory-*`, `reset-memory`, `change-embedding-model`). Skills are either **atomic** (do one thing) or **composite** (orchestrate other skills).
+A self-contained workflow written as markdown with YAML frontmatter. Foundry ships a user-facing `Foundry` guide agent plus skills for pipeline execution, authoring, maintenance, and memory administration. The guide agent is the normal interface for users; skills and tools provide the internal workflows it uses to initialise projects, create artefact types, define laws, configure appraisers, build cycles and flows, and run governed artefact generation. Skills are either **atomic** (do one thing) or **composite** (orchestrate other skills).
 
 ---