@really-knows-ai/foundry 1.1.0 → 1.2.1

package/.opencode/plugins/foundry.js

@@ -2,8 +2,9 @@
  * Foundry plugin for OpenCode.ai
  *
  * All skills are always registered. Individual skills check for foundry/ dir.
- * - If foundry/ exists: pipeline context + multi-model agent registration
+ * - 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,10 +48,7 @@ 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 || {};
@@ -60,31 +58,6 @@ export const FoundryPlugin = async ({ client, directory }) => {
       if (!config.skills.paths.includes(allSkillsDir)) {
         config.skills.paths.push(allSkillsDir);
       }
-
-      if (foundryExists) {
-        // 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);
-        }
-      }
     },
 
     'experimental.chat.messages.transform': async (_input, output) => {

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.1.0",
+  "version": "1.2.1",
   "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-cycle/SKILL.md

@@ -37,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/appraise/SKILL.md

@@ -54,8 +54,18 @@ Model diversity is configured at two levels: the cycle definition sets a default
    - Union of all issues — if any one appraiser flags it, it's feedback
    - De-duplicate: merge overlapping observations into a single feedback item
    - Preserve which appraiser(s) raised each issue (for traceability)
-9. Write consolidated feedback to WORK.md:
-   - `- [ ] <description of the issue> #law:<law-id>`
+9. Write consolidated feedback to WORK.md under the artefact's file heading:
+
+   Feedback MUST be scoped to the artefact file. Under `## Feedback`, create a `### <file-path>` sub-heading matching the artefact's File column from the artefacts table, then write feedback items beneath it:
+
+   ```markdown
+   ## Feedback
+
+   ### foundry/output/haiku/pissed-off-spaghetti.md
+   - [ ] The imagery lacks originality #law:vivid-imagery
+   ```
+
+   If the `## Feedback` section or the file sub-heading already exists (e.g., quench already wrote validation feedback there), append items under the existing heading. Never write feedback items without a file sub-heading — the sort script cannot parse them.
 10. If no appraiser found any issues, the artefact clears appraisal
 
 ## Dispatch
@@ -120,7 +130,7 @@ If there are no issues, return an empty list.
 
 ## Reviewing actioned and wont-fix feedback
 
-On subsequent passes, appraisers also evaluate previously actioned and wont-fix items:
+On subsequent passes, appraisers also evaluate previously actioned and wont-fix items under the artefact's `### <file-path>` heading:
 
 - `[x]` actioned items: appraiser checks whether the change actually addresses the issue
   - If yes: mark `| approved`
@@ -146,3 +156,4 @@ After completing the appraisal consolidation, append an entry to `WORK.history.y
 - You do not revise the artefact
 - You do not check deterministic rules — that is the quench skill's job
 - You do not filter out feedback because only one appraiser raised it — one is enough
+- You do not write feedback items without a file sub-heading under `## Feedback`

package/skills/flow/SKILL.md

@@ -22,7 +22,7 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 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

@@ -26,11 +26,11 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 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)
 
-1. Read `WORK.md` — find unresolved feedback items for the artefact
+1. Read `WORK.md` — find unresolved feedback items for the artefact. Feedback is scoped by file: look under `## Feedback` for the `### <file-path>` sub-heading that matches the artefact's File column in the artefacts table. Only items under that heading belong to this artefact.
 2. Read the artefact
 3. If the foundry cycle has inputs, read the input artefacts (read-only context)
 4. For each unresolved feedback item, either:

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

@@ -26,10 +26,23 @@ This skill only runs if `foundry/artefacts/<type>/validation.md` exists. If ther
 4. For each validation entry:
    - Substitute `{file}` in the command with the artefact path
    - Run the command
-   - If exit code is non-zero: add feedback to WORK.md:
-     - `- [ ] <failure description from validation.md> #validation`
+   - If exit code is non-zero: add feedback to WORK.md under the artefact's file heading
 5. If all commands exit zero, add no new feedback
 
+## Feedback format
+
+Feedback MUST be scoped to the artefact file it applies to. Under `## Feedback`, create a `### <file-path>` sub-heading matching the artefact's File column from the artefacts table, then write feedback items beneath it:
+
+```markdown
+## Feedback
+
+### foundry/output/haiku/pissed-off-spaghetti.md
+- [ ] The haiku does not have exactly 3 lines. #validation
+- [ ] One or more lines do not match the 5-7-5 syllable pattern. #validation
+```
+
+If the `## Feedback` section or the file sub-heading already exists, append items under the existing heading. Never write feedback items without a file sub-heading — the sort script cannot parse them.
+
 ## Reviewing actioned feedback
 
 On subsequent passes, the quench skill re-runs the relevant command for previously actioned items:
@@ -59,3 +72,4 @@ After completing validation (whether issues were found or not), append an entry
 - You do not evaluate laws — that is the appraise skill's job
 - You do not invent validation rules — you only run commands from the validation file
 - You do not duplicate feedback that already exists in WORK.md
+- You do not write feedback items without a file sub-heading under `## Feedback`

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.