@really-knows-ai/foundry 2.0.0 → 2.1.0

package/.opencode/plugins/foundry.js

@@ -17,13 +17,39 @@ import { parseFrontmatter, createWorkfile, setFrontmatterField, getFrontmatterFi
 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';
+import { slugify } from '../../scripts/lib/slug.js';
 import { runSort } from '../../scripts/sort.js';
-import { execSync } from 'child_process';
+import { execSync, execFileSync } from 'child_process';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(__dirname, '../..');
 const allSkillsDir = path.join(packageRoot, 'skills');
 
+function listFlows(foundryDir) {
+  const flowsDir = path.join(foundryDir, 'flows');
+  if (!fs.existsSync(flowsDir)) return [];
+  const flows = [];
+  for (const entry of readdirSync(flowsDir)) {
+    if (!entry.endsWith('.md') || entry === '.gitkeep') continue;
+    try {
+      const text = readFileSync(path.join(flowsDir, entry), 'utf-8');
+      const fmMatch = text.match(/^---\n([\s\S]*?)\n---/);
+      if (!fmMatch) continue;
+      const fm = fmMatch[1];
+      const idMatch = fm.match(/^id:\s*(.+)$/m);
+      const nameMatch = fm.match(/^name:\s*(.+)$/m);
+      const startingMatch = fm.match(/^starting-cycles:\s*\n((?:\s*-\s*.+\n?)+)/m);
+      const id = idMatch ? idMatch[1].trim() : entry.replace(/\.md$/, '');
+      const name = nameMatch ? nameMatch[1].trim() : id;
+      const startingCycles = startingMatch
+        ? startingMatch[1].split('\n').map(l => l.replace(/^\s*-\s*/, '').trim()).filter(Boolean)
+        : [];
+      flows.push({ id, name, startingCycles });
+    } catch { /* skip bad files */ }
+  }
+  return flows;
+}
+
 function getBootstrapContent(directory) {
   const foundryDir = path.join(directory, 'foundry');
   const foundryExists = fs.existsSync(foundryDir) && fs.statSync(foundryDir).isDirectory();
@@ -37,6 +63,14 @@ and guide you through defining artefact types, laws, appraisers, cycles, and flo
 </FOUNDRY_CONTEXT>`;
   }
 
+  const flows = listFlows(foundryDir);
+  const flowList = flows.length > 0
+    ? flows.map(f => {
+        const sc = f.startingCycles.length > 0 ? ` — starting cycles: ${f.startingCycles.join(', ')}` : '';
+        return `- \`${f.id}\` — ${f.name}${sc}`;
+      }).join('\n')
+    : '- (no flows defined yet — use the `add-flow` skill to create one)';
+
   return `<FOUNDRY_CONTEXT>
 Foundry is active in this project. The foundry/ directory contains the project's artefact definitions,
 laws, appraisers, cycles, and flows.
@@ -44,15 +78,32 @@ laws, appraisers, cycles, and flows.
 Foundry is a skill-driven framework for governed artefact generation and evaluation.
 The pipeline: forge (produce) → quench (deterministic checks) → appraise (subjective evaluation) → iterate.
 
-Available skills:
-- **Pipeline:** forge, quench, appraise, cycle, flow, sort, hitl
-- **Helpers:** add-artefact-type, add-law, add-appraiser, add-cycle, add-flow, init-foundry
+## Defined flows
+
+${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.
 
-Multi-model routing: Foundry uses \`foundry-*\` sub-agents defined as markdown files in \`.opencode/agents/\`.
+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.
+
+## Available skills
+
+- **Pipeline:** forge, quench, appraise, cycle, flow, sort, human-appraise
+- **Authoring:** add-artefact-type, add-law, add-appraiser, add-cycle, add-flow, init-foundry
+- **Maintenance:** upgrade-foundry, refresh-agents, list-agents
+
+## 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/.
+All user content lives under foundry/.
 Scripts are located at: ${path.join(packageRoot, 'scripts')}
 </FOUNDRY_CONTEXT>`;
 }
@@ -129,8 +180,8 @@ export const FoundryPlugin = async ({ directory }) => {
         args: {
           flow: tool.schema.string().describe('Flow name'),
           cycle: tool.schema.string().describe('Cycle name'),
-          stages: tool.schema.array(tool.schema.string()).describe('Ordered stage names'),
-          maxIterations: tool.schema.number().describe('Maximum iterations'),
+          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"}\''),
         },
@@ -139,7 +190,13 @@ export const FoundryPlugin = async ({ directory }) => {
           if (existsSync(workPath)) {
             return JSON.stringify({ error: 'WORK.md already exists' });
           }
-          const fm = { flow: args.flow, cycle: args.cycle, stages: enrichStages(args.stages, args.cycle), maxIterations: args.maxIterations };
+          const fm = { flow: args.flow, cycle: args.cycle };
+          if (args.stages) {
+            fm.stages = enrichStages(args.stages, args.cycle);
+          }
+          if (args.maxIterations !== undefined) {
+            fm.maxIterations = args.maxIterations;
+          }
           if (args.models) {
             fm.models = parseModelsValue(args.models);
           }
@@ -374,8 +431,10 @@ export const FoundryPlugin = async ({ directory }) => {
           description: tool.schema.string().describe('Branch description suffix'),
         },
         async execute(args, context) {
-          const branch = `work/${args.flowId}-${args.description}`;
-          execSync(`git checkout -b ${branch}`, { cwd: context.worktree, encoding: 'utf8' });
+          const flowSlug = slugify(args.flowId);
+          const descSlug = slugify(args.description);
+          const branch = `work/${flowSlug}-${descSlug}`;
+          execFileSync('git', ['checkout', '-b', branch], { cwd: context.worktree, encoding: 'utf8', stdio: 'pipe' });
           return JSON.stringify({ ok: true, branch });
         },
       }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "2.0.0",
+  "version": "2.1.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",
@@ -25,7 +25,7 @@
     "node": ">=18.3.0"
   },
   "scripts": {
-    "test": "node --test tests/**/*.test.js"
+    "test": "node --test"
   },
   "dependencies": {
     "@opencode-ai/plugin": "^1.4.0",

package/scripts/lib/slug.js

@@ -0,0 +1,33 @@
+/**
+ * Slug utilities for generating shell-safe, git-ref-safe identifiers.
+ */
+
+/**
+ * Convert an arbitrary string into a URL/git-branch-friendly slug.
+ *
+ * Rules:
+ * - Strips diacritics (e.g. "café" → "cafe")
+ * - Lowercases
+ * - Replaces any run of non-[a-z0-9] characters with a single dash
+ * - Trims leading/trailing dashes
+ *
+ * Throws if the input is not a string or if the resulting slug is empty.
+ */
+export function slugify(input) {
+  if (typeof input !== 'string') {
+    throw new TypeError(`slugify: expected string, got ${typeof input}`);
+  }
+
+  const slug = input
+    .normalize('NFD')
+    .replace(/\p{Diacritic}/gu, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+  if (slug.length === 0) {
+    throw new Error(`slugify: input produced empty slug (input: ${JSON.stringify(input)})`);
+  }
+
+  return slug;
+}

package/scripts/sort.js

@@ -209,7 +209,7 @@ function checkModifiedFiles(lastBase, foundryDir, cycleDef, cycle, io = defaultI
 // Exported runSort — structured result for programmatic use
 // ---------------------------------------------------------------------------
 
-export function runSort({ workPath = 'WORK.md', historyPath = 'WORK.history.yaml', foundryDir = 'foundry', cycleDef } = {}, io = defaultIO) {
+export function runSort({ workPath = 'WORK.md', historyPath = 'WORK.history.yaml', foundryDir = 'foundry', cycleDef, agentsDir = '.opencode/agents' } = {}, io = defaultIO) {
   if (!io.exists(workPath)) {
     return { route: 'blocked', details: 'WORK.md not found' };
   }
@@ -255,7 +255,16 @@ export function runSort({ workPath = 'WORK.md', historyPath = 'WORK.history.yaml
   const routeBase = baseStage(route);
   if (frontmatter.models && frontmatter.models[routeBase]) {
     const modelId = frontmatter.models[routeBase];
-    model = `foundry-${modelId.replace(/\//g, '-')}`;
+    model = `foundry-${modelId.replace(/[/.]/g, '-')}`;
+
+    // Fail-fast: required subagent file must exist
+    const agentPath = `${agentsDir}/${model}.md`;
+    if (!io.exists(agentPath)) {
+      return {
+        route: 'violation',
+        details: `Missing required subagent: ${model}.md is not present in ${agentsDir}/. Run the refresh-agents skill to regenerate agent files, then restart.`,
+      };
+    }
   }
 
   return { route, ...(model ? { model } : {}) };

package/skills/flow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: flow
 type: composite
-description: Orchestrates foundry cycles as a dependency graph, driven by a flow definition.
+description: Runs a defined foundry flow to produce artefacts. Use this whenever the user references a flow by id, name, or paraphrase (e.g. "use the creative flow", "run creative-flow"). Do not brainstorm — the flow's cycles already define the work. The user's request is the goal to pass in.
 composes: [cycle]
 ---
 
@@ -23,7 +23,7 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
    - If only one starting cycle, use it
    - If multiple starting cycles, check whether the user's request makes the choice obvious (e.g., "write a haiku" clearly maps to `create-haiku`)
    - If ambiguous, prompt the user to choose
-4. Call `foundry_workfile_create` with the flow ID, chosen cycle ID, and goal
+4. Call `foundry_workfile_create` with **only** the flow ID, chosen cycle ID, and goal — do **not** pass `stages` or `maxIterations`. The `cycle` skill will read the cycle definition and populate those via `foundry_workfile_set` in the next step.
 5. Execute the cycle by invoking the cycle skill
 
 ## Between cycles

package/skills/refresh-agents/SKILL.md

@@ -16,11 +16,14 @@ Regenerate `.opencode/agents/foundry-*.md` files from the currently available mo
 
 ### Agent file format
 
-Filename: `.opencode/agents/foundry-<provider>-<model-key>.md`
+Filename: `.opencode/agents/foundry-<slug>.md`
 
-Where `<provider>-<model-key>` is the model ID with `/` replaced by `-`.
+Where `<slug>` is the model ID with **both** `/` and `.` replaced by `-`. This keeps filenames shell-safe and unambiguous.
 
-Example: model `opencode/claude-sonnet-4` produces `.opencode/agents/foundry-opencode-claude-sonnet-4.md`
+Examples:
+- `opencode/claude-sonnet-4` → `.opencode/agents/foundry-opencode-claude-sonnet-4.md`
+- `github-copilot/claude-sonnet-4.6` → `.opencode/agents/foundry-github-copilot-claude-sonnet-4-6.md`
+- `github-copilot/gpt-5.4` → `.opencode/agents/foundry-github-copilot-gpt-5-4.md`
 
 Content:
 

package/skills/sort/SKILL.md

@@ -6,7 +6,7 @@ description: Deterministic routing for a foundry cycle. Runs the foundry_sort to
 
 # Sort
 
-You are the central dispatcher for a foundry cycle. You call the `foundry_sort` tool to determine what stage to execute next, then invoke that stage's skill.
+You are the central dispatcher for a foundry cycle. You call the `foundry_sort` tool to determine what stage to execute next, then dispatch that stage to a fresh subagent.
 
 ## Prerequisites
 
@@ -21,21 +21,59 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 2. Call `foundry_history_append` with the current cycle, stage `"sort"`, and a comment explaining the routing decision in natural language. This is your audit trail — if something goes wrong, this comment is what someone will read to understand what happened.
 
 3. Act on the route:
-   - `forge:*` — dispatch the forge skill as a sub-agent. Use model dispatch (see below).
-   - `quench:*` — dispatch the quench skill as a sub-agent. Use model dispatch.
-   - `appraise:*` — dispatch the appraise skill as a sub-agent. Use model dispatch. Note: the appraise skill handles its own per-appraiser model resolution internally.
-   - `human-appraise:*` — invoke the human-appraise skill (no model dispatch — human stage)
+   - `forge:*` — **dispatch** (see §Dispatch below)
+   - `quench:*` — **dispatch**
+   - `appraise:*` — **dispatch**. Note: the appraise skill handles its own per-appraiser model resolution internally.
+   - `human-appraise:*` — invoke the human-appraise skill inline (human stage, no subagent)
    - `done` — foundry cycle is complete, return to the cycle skill
    - `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
+   - `violation` — a validation, file-modification, or missing-subagent violation was detected (see `details`). The cycle halts — call `foundry_artefacts_set_status` with status `"blocked"` for each affected artefact, and return to the cycle skill. If `details` mentions a missing subagent, tell the user to run the `refresh-agents` skill and restart.
 
 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.
 
 5. After logging the stage history, call `foundry_sort` again. Repeat from step 1 until it returns `done`, `blocked`, or `violation`.
 
+## Dispatch
+
+Every forge, quench, and appraise stage runs in a **fresh subagent**. Never inline the stage work in the orchestrator conversation — even if the chosen model happens to match the orchestrator's model. The orchestrator's job is to route and log, nothing else.
+
+### Choosing the subagent
+
+- If `foundry_sort` returned a `model` field in its response, use that value verbatim as `subagent_type`. It is already in `foundry-<slug>` form (the tool does the slug computation by replacing both `/` and `.` with `-` in the model ID).
+- If `foundry_sort` returned **no** `model` field (the cycle has no `models:` map, or no entry for this stage base), dispatch to the default general-purpose subagent: `general`.
+
+### Dispatch call shape
+
+Use the `task` tool:
+
+```
+task tool:
+  subagent_type: <model-slug-from-foundry_sort-response, or "general">
+  description: "Run <stage-alias> for <cycle-id>"
+  prompt: |
+    You are a Foundry stage agent. Invoke the <stage-base> skill and follow its instructions exactly.
+
+    Current cycle: <cycle-id>
+    Current stage: <stage-alias>
+    Working directory: <worktree>
+
+    When done, report back a brief summary of what you did. Do NOT call foundry_history_append — the orchestrator handles history.
+```
+
+Substitute:
+- `<stage-alias>` — the full route string from `foundry_sort` (e.g., `forge:write-haiku`)
+- `<stage-base>` — the base of the alias (e.g., `forge`, `quench`, `appraise`)
+- `<cycle-id>` — the current cycle ID from WORK.md frontmatter
+- `<worktree>` — the current working directory
+
+### Missing subagent (fail-fast)
+
+The `foundry_sort` tool verifies that the required `.opencode/agents/foundry-<slug>.md` file exists before returning a `model`. If it doesn't, sort returns `{route: 'violation', details: 'Missing required subagent: ...'}`. Handle this as described in step 3 above — halt the cycle, mark artefacts blocked, and instruct the user to run the `refresh-agents` skill.
+
 ## 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 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 gets a `sort` entry, and every completed stage gets a stage entry (e.g., `forge:write-haiku`). You are the sole writer of history.
+- You do **not** inline forge/quench/appraise work — always dispatch to a subagent via the `task` tool, even when the resolved model matches the orchestrator's own model.

package/skills/upgrade-foundry/SKILL.md

@@ -27,12 +27,17 @@ Read all configuration files:
 - `foundry/laws/*.md` — global laws
 - `foundry/appraisers/*.md` — appraiser definitions
 
+Also scan `.opencode/agents/foundry-*.md` for agent-filename migration (see §2).
+
 For each file, parse the frontmatter and body content.
 
 ### 2. Detect what needs migration
 
 Check each file against the current expected format:
 
+**Agent files (v2.1 migration):**
+- Any `.opencode/agents/foundry-*.md` filename containing a `.` character? → needs renaming to all-dashes format. The v2.1 naming convention replaces both `/` and `.` in the model ID with `-`. For example, `foundry-github-copilot-claude-sonnet-4.6.md` must become `foundry-github-copilot-claude-sonnet-4-6.md`. The inner `model:` frontmatter field is **not** changed — only the filename.
+
 **Flows:**
 - Has `starting-cycles` field? If not → needs DAG migration
 - Has ordered numbered list under `## Cycles`? → needs conversion to unordered list
@@ -84,7 +89,16 @@ Present a grouped summary of all issues found:
 
 If nothing needs migration, say so and stop.
 
-### 4. Migrate flows
+### 4. Migrate agent files (v2.1)
+
+For each `.opencode/agents/foundry-*.md` file with a `.` in its filename:
+- Compute the new filename by replacing all `.` with `-` (keep the `.md` extension)
+- `git mv <old> <new>` to preserve history
+- Do **not** modify the file contents — the `model:` field inside retains its original dots
+
+After renaming, remind the user: **Restart OpenCode** for the new agent filenames to register.
+
+### 5. Migrate flows
 
 For each flow needing migration:
 - Show the current ordered cycle list
@@ -93,7 +107,7 @@ For each flow needing migration:
 - Present the proposed `starting-cycles` and confirm
 - Convert numbered `## Cycles` list to unordered
 
-### 5. Migrate cycles
+### 6. Migrate cycles
 
 For each cycle needing migration:
 
@@ -112,20 +126,20 @@ For each cycle needing migration:
 
 Remove `hitl` from stages and add `human-appraise` config if enabled.
 
-### 6. Migrate other config
+### 7. Migrate other config
 
 For artefact types, appraisers, laws, and validation with issues:
 - Present each issue with a suggested fix
 - Ask the user to confirm or adjust
 
-### 7. Present migration plan
+### 8. Present migration plan
 
 Before writing anything, show the complete list of changes:
 - Group by category
 - Show each file and the specific changes
 - Ask for confirmation
 
-### 8. Apply changes
+### 9. Apply changes
 
 - Update all affected files
 - Commit with message: `[foundry] upgrade: migrate to current format`