@really-knows-ai/foundry 1.4.0 → 1.5.1

package/.opencode/plugins/foundry.js

@@ -13,7 +13,7 @@ import { readFileSync, writeFileSync, existsSync, readdirSync, unlinkSync } from
 import { fileURLToPath } from 'url';
 import { tool } from '@opencode-ai/plugin';
 import { loadHistory, appendEntry, getIteration } from '../../scripts/lib/history.js';
-import { parseFrontmatter, createWorkfile, setFrontmatterField, getFrontmatterField, enrichStages } from '../../scripts/lib/workfile.js';
+import { parseFrontmatter, createWorkfile, setFrontmatterField, getFrontmatterField, enrichStages, parseStagesValue, parseModelsValue } from '../../scripts/lib/workfile.js';
 import { parseArtefactsTable, addArtefactRow, setArtefactStatus } from '../../scripts/lib/artefacts.js';
 import { addFeedbackItem, actionFeedbackItem, wontfixFeedbackItem, resolveFeedbackItem, listFeedback } from '../../scripts/lib/feedback.js';
 import { getCycleDefinition, getArtefactType, getLaws, getValidation, getAppraisers, getFlow, selectAppraisers } from '../../scripts/lib/config.js';
@@ -141,7 +141,7 @@ export const FoundryPlugin = async ({ directory }) => {
           }
           const fm = { flow: args.flow, cycle: args.cycle, stages: enrichStages(args.stages, args.cycle), maxIterations: args.maxIterations };
           if (args.models) {
-            try { fm.models = JSON.parse(args.models); } catch { fm.models = {}; }
+            fm.models = parseModelsValue(args.models);
           }
           const content = createWorkfile(fm, args.goal);
           writeFileSync(workPath, content, 'utf-8');
@@ -179,13 +179,21 @@ export const FoundryPlugin = async ({ directory }) => {
           const text = readFileSync(workPath, 'utf-8');
           // Parse JSON values for arrays/objects, keep strings as-is
           let value = args.value;
-          try {
-            const parsed = JSON.parse(args.value);
-            if (typeof parsed === 'object' || Array.isArray(parsed) || typeof parsed === 'number') {
-              value = parsed;
+          if (args.key === 'stages') {
+            // Always parse stages into an array (handles JSON arrays and comma-separated strings)
+            value = parseStagesValue(args.value);
+          } else if (args.key === 'models') {
+            // Always parse models into an object (handles JSON objects and "key: value" strings)
+            value = parseModelsValue(args.value);
+          } else {
+            try {
+              const parsed = JSON.parse(args.value);
+              if (typeof parsed === 'object' || Array.isArray(parsed) || typeof parsed === 'number') {
+                value = parsed;
+              }
+            } catch {
+              // Not JSON, use as plain string
             }
-          } catch {
-            // Not JSON, use as plain string
           }
           // Auto-enrich bare stage names with cycle ID alias
           if (args.key === 'stages' && Array.isArray(value)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "1.4.0",
+  "version": "1.5.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/lib/config.js

@@ -114,7 +114,7 @@ export async function getValidation(foundryDir, typeId, io) {
     } else if (currentId) {
       const cmdMatch = line.match(/^Command:\s*(.+)/);
       const failMatch = line.match(/^Failure means:\s*(.+)/);
-      if (cmdMatch) currentCommand = cmdMatch[1].trim();
+      if (cmdMatch) currentCommand = cmdMatch[1].trim().replace(/^`|`$/g, '');
       if (failMatch) currentFailure = failMatch[1].trim();
     }
   }

package/scripts/lib/workfile.js

@@ -47,6 +47,45 @@ export function enrichStages(stages, cycleId) {
   return stages.map(s => s.includes(':') ? s : `${s}:${cycleId}`);
 }
 
+/**
+ * Parse a stages value from tool input.
+ * Accepts JSON array string or comma-separated string.
+ * Always returns an array of trimmed, non-empty strings.
+ */
+export function parseStagesValue(raw) {
+  // Try JSON first
+  try {
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) return parsed;
+  } catch { /* not JSON */ }
+  // Fall back to comma-separated
+  return raw.split(',').map(s => s.trim()).filter(Boolean);
+}
+
+/**
+ * Parse a models value from tool input.
+ * Accepts JSON object string or "key: value, key: value" string.
+ * Always returns an object mapping stage base names to model IDs.
+ */
+export function parseModelsValue(raw) {
+  if (!raw || !raw.trim()) return {};
+  // Try JSON first
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
+  } catch { /* not JSON */ }
+  // Fall back to "key: value, key: value" format
+  const result = {};
+  for (const part of raw.split(',')) {
+    const colonIdx = part.indexOf(':');
+    if (colonIdx === -1) continue;
+    const key = part.slice(0, colonIdx).trim();
+    const val = part.slice(colonIdx + 1).trim();
+    if (key && val) result[key] = val;
+  }
+  return result;
+}
+
 // ---------------------------------------------------------------------------
 // Workfile creation
 // ---------------------------------------------------------------------------

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

@@ -128,7 +128,11 @@ If yes, walk through each validation entry:
 - A `Command:` line with `{file}` placeholder
 - A `Failure means:` line explaining what a non-zero exit indicates
 
-If the user wants validation scripts (not just inline commands), create them as separate files in the artefact type directory. Check the project's `package.json` for `"type": "module"`:
+If the user wants validation scripts (not just inline commands), create them as separate files in the artefact type directory.
+
+**Use existing libraries:** Before writing custom validation logic, search npm for well-tested libraries that solve the problem (e.g., `syllable` for syllable counting, `natural` for NLP tasks). Hand-rolled heuristics are fragile — prefer battle-tested packages. Install them as project dependencies.
+
+Check the project's `package.json` for `"type": "module"`:
 - If ESM (`"type": "module"`): use `import` syntax, or name scripts with `.mjs` extension
 - If CommonJS (no `"type"` field or `"type": "commonjs"`): `require()` is fine, or use `.cjs` extension
 - When in doubt, use `.mjs` or `.cjs` extensions to be explicit regardless of project settings

package/skills/appraise/SKILL.md

@@ -91,7 +91,7 @@ If there are no issues, return an empty list.
 
 ## History
 
-After completing the appraisal consolidation, call `foundry_history_append` with the current cycle, stage alias, and a brief summary (e.g., "3 issues found across 2 appraisers" or "No issues found").
+Do NOT call `foundry_history_append` — the sort skill (your caller) is responsible for writing history. Instead, return a clear summary of what you found (e.g., "3 issues found across 2 appraisers" or "No issues found") so sort can log it.
 
 ## What you do NOT do
 

package/skills/forge/SKILL.md

@@ -40,7 +40,7 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 
 ### After (both paths)
 
-Call `foundry_history_append` with the current cycle, the full stage alias (e.g., `forge:write-haiku`), and a brief description of what you did.
+Do NOT call `foundry_history_append` — the sort skill (your caller) is responsible for writing history. Instead, return a clear summary of what you did so sort can log it.
 
 ## Unresolved feedback
 

package/skills/hitl/SKILL.md

@@ -36,7 +36,7 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
    - **Provide context** — note in the history comment for future stages to reference
    - **Abort** — call `foundry_artefacts_set_status` with status `"blocked"`, cycle ends
 
-5. Call `foundry_history_append` with the current cycle, stage alias, and a comment capturing the substance of what the human said or decided.
+5. Do NOT call `foundry_history_append` — the sort skill (your caller) is responsible for writing history. Instead, return a clear summary of what the human said or decided so sort can log it.
 
 6. Return control to the sort skill.
 

package/skills/quench/SKILL.md

@@ -35,7 +35,7 @@ There is no wont-fix for validation feedback. Deterministic rules are not negoti
 
 ## History
 
-After completing validation, call `foundry_history_append` with the current cycle, stage alias, and a brief summary (e.g., "2 validation issues found" or "Validation passed").
+Do NOT call `foundry_history_append` — the sort skill (your caller) is responsible for writing history. Instead, return a clear summary of what you found (e.g., "2 validation issues found" or "Validation passed") so sort can log it.
 
 ## What you do NOT do
 

package/skills/sort/SKILL.md

@@ -29,22 +29,13 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
    - `blocked` — foundry cycle is blocked (iteration limit hit with unresolved feedback), return to the cycle skill
    - `violation` — file modification or tag validation violation detected (see `details`). The cycle halts — call `foundry_artefacts_set_status` with status `"blocked"`, and return to the cycle skill
 
-### Model dispatch
+4. After the subagent completes, call `foundry_history_append` with the current cycle, the **dispatched stage alias** (e.g., `forge:write-haiku`), and a comment summarizing what the subagent reported doing. This is critical — sort is the only reliable writer of stage history. Subagents must NOT write their own history entries.
 
-Use the `model` field from the `foundry_sort` result to determine sub-agent routing:
-
-- If `model` is set (e.g., `openai/gpt-4o`):
-  - Convert to agent name: `foundry-openai-gpt-4o`
-  - Dispatch with `subagent_type: "foundry-openai-gpt-4o"`
-  - If no agent with that name exists, **hard fail**: "Cycle specifies model `<model>` for stage `<base>` but no matching agent `foundry-<name>` is registered. Check your OpenCode provider config."
-- If `model` is null:
-  - Dispatch with `subagent_type: "general"` (inherits session model)
-
-4. After the invoked skill completes, call `foundry_sort` again. Repeat until it returns `done`, `blocked`, or `violation`.
+5. After logging the stage history, call `foundry_sort` again. Repeat from step 1 until it returns `done`, `blocked`, or `violation`.
 
 ## What you do NOT do
 
 - You do not make routing decisions yourself — the tool decides
 - You do not skip calling `foundry_sort`
 - You do not override the tool's output
-- You do not skip the history entry — every sort invocation must be logged via `foundry_history_append`
+- You do not skip the history entry — every sort invocation gets a `sort` entry, and every completed stage gets a stage entry (e.g., `forge:write-haiku`). You are the sole writer of history.