@really-knows-ai/foundry 1.0.0 → 1.2.0

package/.opencode/plugins/foundry.js

@@ -1,9 +1,10 @@
 /**
  * Foundry plugin for OpenCode.ai
  *
- * Conditional bootstrap:
- * - If foundry/ exists in project: full skill registration + pipeline context
- * - If foundry/ does not exist: only init-foundry skill + minimal prompt
+ * 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';
@@ -13,7 +14,6 @@ import { fileURLToPath } from 'url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(__dirname, '../..');
 const allSkillsDir = path.join(packageRoot, 'skills');
-const initSkillDir = path.join(allSkillsDir, 'init-foundry');
 
 function getBootstrapContent(directory) {
   const foundryDir = path.join(directory, 'foundry');
@@ -39,7 +39,8 @@ Available skills:
 - **Pipeline:** forge, quench, appraise, cycle, flow, sort, hitl
 - **Helpers:** add-artefact-type, add-law, add-appraiser, add-cycle, add-flow, init-foundry
 
-Multi-model routing: The Foundry plugin has auto-registered \`foundry-*\` sub-agents for each available model.
+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.
 
 To start a flow, use the \`flow\` skill. All user content lives under foundry/.
@@ -47,46 +48,15 @@ Scripts are located at: ${path.join(packageRoot, 'scripts')}
 </FOUNDRY_CONTEXT>`;
 }
 
-export const FoundryPlugin = async ({ client, directory }) => {
-  const foundryDir = path.join(directory, 'foundry');
-  const foundryExists = fs.existsSync(foundryDir) && fs.statSync(foundryDir).isDirectory();
-
+export const FoundryPlugin = async ({ directory }) => {
   return {
     config: async (config) => {
       config.skills = config.skills || {};
       config.skills.paths = config.skills.paths || [];
 
-      if (foundryExists) {
-        if (!config.skills.paths.includes(allSkillsDir)) {
-          config.skills.paths.push(allSkillsDir);
-        }
-
-        // Register per-model subagents for multi-model stage routing
-        try {
-          const providers = await client.provider.list();
-          config.agent = config.agent || {};
-          for (const provider of providers) {
-            if (!provider.models) continue;
-            const modelKeys = Array.isArray(provider.models)
-              ? provider.models
-              : Object.keys(provider.models);
-            for (const modelKey of modelKeys) {
-              const agentName = `foundry-${provider.id}-${modelKey}`;
-              config.agent[agentName] = {
-                model: `${provider.id}/${modelKey}`,
-                mode: 'subagent',
-                hidden: true,
-                description: `Foundry stage agent using ${provider.id}/${modelKey}`,
-              };
-            }
-          }
-        } catch (err) {
-          console.warn('[foundry] Failed to discover models for agent registration:', err.message);
-        }
-      } else {
-        if (!config.skills.paths.includes(initSkillDir)) {
-          config.skills.paths.push(initSkillDir);
-        }
+      // Always register all skills — individual skills check for foundry/ dir
+      if (!config.skills.paths.includes(allSkillsDir)) {
+        config.skills.paths.push(allSkillsDir);
       }
     },
 

package/README.md

@@ -4,9 +4,9 @@ A skill-driven framework for governed artefact generation and evaluation using A
 
 ## Compatibility
 
-- **OpenCode** — full support, multi-model routing via plugin-registered agents
+- **OpenCode** — full support, multi-model routing via file-based agents
 
-Multi-model support enables model diversity across pipeline stages. The Foundry plugin auto-discovers available models at startup and registers them as hidden sub-agents. Cycle definitions specify which model each stage uses. Tools limited to a single model lose model-diversity but still get personality-based diversity.
+Multi-model support enables model diversity across pipeline stages. Foundry agents are defined as `.opencode/agents/foundry-*.md` files, generated by the `refresh-agents` skill (also run during `init-foundry`). Cycle definitions specify which model each stage uses. Tools limited to a single model lose model-diversity but still get personality-based diversity.
 
 ## Installation
 
@@ -235,7 +235,7 @@ The generator can decline subjective feedback with a justification, but an appra
 
 ### Multi-model stage routing
 
-Cycle definitions specify which model each stage uses via a `models` map. The Foundry plugin auto-discovers available models and registers them as `foundry-*` sub-agents. Individual appraisers can override the cycle-level model. Resolution order: appraiser `model` → cycle `models.<stage>` → session default. Multiple personalities catch different issues. Consolidation is union with dedup — one appraiser flagging an issue is enough.
+Cycle definitions specify which model each stage uses via a `models` map. The `refresh-agents` skill generates `foundry-*` agent files in `.opencode/agents/` from available models. Individual appraisers can override the cycle-level model. Resolution order: appraiser `model` → cycle `models.<stage>` → session default. Multiple personalities catch different issues. Consolidation is union with dedup — one appraiser flagging an issue is enough.
 
 ### Input artefacts are read-only
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "A structured framework for AI-driven artefact creation with deterministic routing, quality gates, and iterative refinement cycles.",
   "type": "module",
   "main": ".opencode/plugins/foundry.js",

package/scripts/sort.js

@@ -76,24 +76,32 @@ function parseFeedback(text, cycle, artefacts) {
   const items = [];
   let currentFile = null;
   let inFeedback = false;
+  let feedbackLevel = 0; // 1 for '# Feedback', 2 for '## Feedback'
 
   for (const line of text.split('\n')) {
     const stripped = line.trim();
 
-    if (stripped === '# Feedback') {
+    if (stripped === '# Feedback' || stripped === '## Feedback') {
       inFeedback = true;
+      feedbackLevel = stripped.startsWith('## ') ? 2 : 1;
       continue;
     }
 
-    if (inFeedback && stripped.startsWith('# ') && stripped !== '# Feedback') {
-      inFeedback = false;
-      continue;
+    // Exit feedback on a heading at the same or higher level
+    if (inFeedback && /^#{1,2} /.test(stripped)) {
+      const level = stripped.startsWith('## ') ? 2 : 1;
+      if (level <= feedbackLevel && stripped !== '# Feedback' && stripped !== '## Feedback') {
+        inFeedback = false;
+        continue;
+      }
     }
 
     if (!inFeedback) continue;
 
-    if (stripped.startsWith('## ')) {
-      currentFile = stripped.slice(3).trim();
+    // File sub-headings are one level below the Feedback heading
+    const fileHeadingPrefix = feedbackLevel === 1 ? '## ' : '### ';
+    if (stripped.startsWith(fileHeadingPrefix)) {
+      currentFile = stripped.slice(fileHeadingPrefix.length).trim();
       continue;
     }
 

package/skills/add-appraiser/SKILL.md

@@ -8,6 +8,12 @@ description: Creates a new appraiser personality, checking for semantic overlap
 
 You help the user create a new appraiser personality. You ensure it's genuinely distinct from existing appraisers and scaffold the definition file.
 
+## Prerequisites
+
+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.
+
 ## Protocol
 
 ### 1. Gather basics

package/skills/add-artefact-type/SKILL.md

@@ -8,6 +8,12 @@ description: Creates a new artefact type, checking for conflicts with existing t
 
 You help the user create a new artefact type. You ensure it doesn't conflict with existing types, scaffold the directory structure, and walk the user through defining laws and validation.
 
+## Prerequisites
+
+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.
+
 ## Protocol
 
 ### 1. Gather basics

package/skills/add-cycle/SKILL.md

@@ -8,6 +8,12 @@ description: Creates a new foundry cycle within a foundry flow, specifying the o
 
 You help the user create a new foundry cycle and add it to an existing foundry flow. A foundry cycle produces one artefact type (read-write) and optionally reads from artefact types produced by earlier foundry cycles (read-only).
 
+## Prerequisites
+
+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.
+
 ## Protocol
 
 ### 1. Identify the foundry flow
@@ -31,7 +37,7 @@ If any of these are missing, ask.
 
 For each stage in the cycle (forge, quench, appraise), ask the user if they want to specify a model:
 
-> Each stage can optionally run on a specific model for model diversity. Available models are registered as `foundry-*` agents by the Foundry plugin.
+> Each stage can optionally run on a specific model for model diversity. Available models are listed as `foundry-*` agent files in `.opencode/agents/`. Run the `list-agents` skill to see them.
 >
 > For each stage, specify a model ID (e.g., `openai/gpt-4o`) or leave blank to use the session's default model:
 > - forge: ___

package/skills/add-flow/SKILL.md

@@ -8,6 +8,12 @@ description: Creates a new foundry flow definition.
 
 You help the user create a new foundry flow. A foundry flow is an ordered list of foundry cycles that transforms a request into finished artefacts.
 
+## Prerequisites
+
+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.
+
 ## Protocol
 
 ### 1. Gather basics

package/skills/add-law/SKILL.md

@@ -8,6 +8,12 @@ description: Creates a new law, checking for conflicts with existing laws.
 
 You help the user create a new law. You ensure it's well-scoped, doesn't conflict with existing laws, and ends up in the right file.
 
+## Prerequisites
+
+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.
+
 ## Protocol
 
 ### 1. Determine scope

package/skills/appraise/SKILL.md

@@ -8,6 +8,12 @@ description: Subjective evaluation of an artefact against laws via multiple inde
 
 You orchestrate subjective appraisal of an artefact by dispatching independent sub-agent appraisers, then consolidating their feedback into WORK.md.
 
+## Prerequisites
+
+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.
+
 ## Appraiser configuration
 
 Appraiser personalities are defined in `foundry/appraisers/` (the appraiser directory). Each markdown file defines:

package/skills/cycle/SKILL.md

@@ -9,6 +9,12 @@ composes: [sort, forge, quench, appraise, hitl]
 
 A foundry cycle reads its definition from `foundry/cycles/<cycle-id>.md`, sets up WORK.md for routing, then hands control to the sort skill which drives the forge → quench → appraise loop.
 
+## Prerequisites
+
+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.
+
 ## Cycle definition
 
 The cycle definition (`foundry/cycles/<cycle-id>.md`) specifies:

package/skills/flow/SKILL.md

@@ -9,6 +9,12 @@ composes: [cycle]
 
 A foundry flow reads a flow definition from `foundry/flows/`, creates a work branch, initialises WORK.md, and executes each foundry cycle in sequence.
 
+## Prerequisites
+
+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.
+
 ## Starting a foundry flow
 
 1. Read the flow definition from `foundry/flows/<flow-id>.md`
@@ -16,7 +22,7 @@ A foundry flow reads a flow definition from `foundry/flows/`, creates a work bra
 3. Create `WORK.md` in the root following the spec in `docs/work-spec.md`:
    - Set frontmatter: flow id, first cycle id, first stage
    - Write the goal (from flow definition + human context)
-   - Empty artefacts table
+   - Empty artefacts table with all four columns: `| File | Type | Cycle | Status |`
    - Empty feedback section
 4. Execute each foundry cycle in order by reading its definition from `foundry/cycles/<cycle-id>.md`
 5. Update the frontmatter cursor as each foundry cycle starts (set `cycle` to the new cycle id)

package/skills/forge/SKILL.md

@@ -8,6 +8,12 @@ description: Produces or revises an artefact, guided by WORK.md and the foundry
 
 You produce or revise artefacts. You read WORK.md to understand the goal and feedback, and the foundry cycle definition to understand what you're producing and what inputs you can read.
 
+## Prerequisites
+
+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.
+
 ## Protocol
 
 ### First generation (no artefact registered in WORK.md yet)
@@ -20,7 +26,7 @@ You produce or revise artefacts. You read WORK.md to understand the goal and fee
 6. If the foundry cycle has inputs, read the input artefacts (read-only context)
 7. Produce the artefact, respecting all applicable laws from the start
 8. Write the artefact to the location specified in the artefact type definition
-9. Register the artefact in the WORK.md artefacts table (file, type, cycle, status: draft)
+9. Register the artefact in the WORK.md artefacts table. The table MUST have all four columns — File, Type, Cycle, Status. Set cycle to the current cycle id from WORK.md frontmatter. Set status to `draft`.
 
 ### Revision (feedback exists in WORK.md)
 

package/skills/hitl/SKILL.md

@@ -8,6 +8,12 @@ description: Human-in-the-loop checkpoint. Pauses the cycle for human input befo
 
 You are a human-in-the-loop checkpoint. Sort has routed to you because the cycle definition includes a pause point here. Your job is to present context, ask the human whatever needs asking, record their response, and return control to sort.
 
+## Prerequisites
+
+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.
+
 ## Protocol
 
 1. Read `WORK.md` — understand the current state: goal, artefacts, feedback

package/skills/init-foundry/SKILL.md

@@ -29,18 +29,24 @@ Set up the `foundry/` directory structure in the current project.
      appraisers/.gitkeep
    ```
 
-3. **Commit the structure**
+3. **Generate foundry agent files**
+
+   Run the `refresh-agents` skill to generate `.opencode/agents/foundry-*.md` files for multi-model routing.
+
+4. **Commit the structure**
 
    ```bash
-   git add foundry/
+   git add foundry/ .opencode/agents/foundry-*.md
    git commit -m "feat: initialize Foundry project structure"
    ```
 
-4. **Guide next steps**
+5. **Guide next steps**
 
    Tell the user:
 
-   > Foundry is initialized. Here's how to set up your first pipeline:
+   > Foundry is initialized. **Restart OpenCode** for the new foundry agents to take effect.
+   >
+   > Here's how to set up your first pipeline:
    >
    > 1. **Define an artefact type** — use the `add-artefact-type` skill
    > 2. **Add laws** — use the `add-law` skill to define quality criteria

package/skills/list-agents/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: list-agents
+description: Use when you need to see which foundry-* sub-agents are available for multi-model routing.
+---
+
+# List Agents
+
+Output all available `foundry-*` sub-agents.
+
+## Protocol
+
+1. List all files matching `.opencode/agents/foundry-*.md`
+2. For each file, read the `model` field from its YAML frontmatter
+3. Output each agent name and its model, one per line
+
+## Output format
+
+```
+foundry-<provider>-<model>  →  <provider>/<model>
+```
+
+If no `foundry-*.md` files are found, output:
+
+> No foundry agent files found. Run the `refresh-agents` skill to generate them.

package/skills/quench/SKILL.md

@@ -8,6 +8,12 @@ description: Deterministic validation of an artefact by running CLI commands. Wr
 
 You run deterministic checks on an artefact by executing the CLI commands defined in the artefact type's validation file. No judgment — commands pass or fail.
 
+## Prerequisites
+
+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.
+
 ## When this skill applies
 
 This skill only runs if `foundry/artefacts/<type>/validation.md` exists. If there is no validation file for the artefact type, this skill is skipped.

package/skills/refresh-agents/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: refresh-agents
+description: Use when initializing Foundry or after adding/removing providers to regenerate foundry-* agent files for multi-model routing.
+---
+
+# Refresh Agents
+
+Regenerate `.opencode/agents/foundry-*.md` files from the currently available models.
+
+## Protocol
+
+1. Run `opencode models` to get all available `provider/model` IDs
+2. Create `.opencode/agents/` directory if it does not exist
+3. Delete all existing `.opencode/agents/foundry-*.md` files (stale agents from removed providers)
+4. For each model line in the output, generate a markdown agent file
+
+### Agent file format
+
+Filename: `.opencode/agents/foundry-<provider>-<model-key>.md`
+
+Where `<provider>-<model-key>` is the model ID with `/` replaced by `-`.
+
+Example: model `opencode/claude-sonnet-4` produces `.opencode/agents/foundry-opencode-claude-sonnet-4.md`
+
+Content:
+
+```markdown
+---
+description: "Foundry stage agent using <provider>/<model-key>"
+mode: subagent
+model: "<provider>/<model-key>"
+hidden: true
+---
+You are a Foundry stage agent. Follow the skill instructions provided in your task prompt exactly.
+```
+
+5. After writing all files, output:
+
+> Generated `<count>` foundry agent files in `.opencode/agents/`.
+> **Restart OpenCode** for the new agents to take effect.

package/skills/sort/SKILL.md

@@ -8,6 +8,12 @@ description: Deterministic routing for a foundry cycle. Runs scripts/sort.js and
 
 You are the central dispatcher for a foundry cycle. You run the sort script to determine what stage to execute next, then invoke that stage's skill.
 
+## Prerequisites
+
+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.
+
 ## Protocol
 
 1. Run the sort script: