@really-knows-ai/foundry 3.3.3 → 3.3.6

package/dist/.opencode/plugins/foundry-tools/agent-refresh.js

@@ -152,29 +152,13 @@ function resolveGuideSource(packageRoot) {
   return path.join(packageRoot, 'src', 'agents', 'foundry.md');
 }
 
-/**
- * Copy the Foundry guide agent (foundry.md) from the installed package
- * to the project's .opencode/agents/ directory.
- *
- * Resolves the source from `packageRoot/dist/agents/foundry.md` and
- * falls back to `packageRoot/src/agents/foundry.md` when the dist
- * path does not exist. Skips writing when the target file already
- * exists (uses existsSync check).
- *
- * @param {string} worktree - Absolute path to the project worktree root.
- * @param {string} packageRoot - Absolute path to the installed package root.
- * @returns {{ ok: true, written: boolean } | { ok: false, error: string }}
- */
 export function writeFoundryGuideAgent(worktree, packageRoot) {
   const targetDir = path.join(worktree, '.opencode', 'agents');
   const targetPath = path.join(targetDir, 'foundry.md');
 
-  if (existsSync(targetPath)) {
-    return { ok: true, written: false };
-  }
+  if (existsSync(targetPath)) return { ok: true, written: false };
 
   const sourcePath = resolveGuideSource(packageRoot);
-
   try {
     const content = readFileSync(sourcePath, 'utf8');
     mkdirSync(targetDir, { recursive: true });
@@ -184,3 +168,4 @@ export function writeFoundryGuideAgent(worktree, packageRoot) {
     return { ok: false, error: `Failed to write guide agent: ${err.message ?? String(err)}` };
   }
 }
+

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

@@ -218,6 +218,9 @@ export const FoundryPlugin = async ({ directory }) => {
         config.skills.paths.push(allSkillsDir);
       }
 
+      // Always ensure guide agent is up to date
+      ensureGuideAgent(directory, packageRoot);
+
       restartNeeded = runPluginBootstrap(directory, packageRoot);
     },
 

package/dist/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [3.3.6] - 2026-05-18
+
+### Fixed
+
+- **Foundry skills reference in agent.** The Foundry agent now lists all 27
+  skills in an "Available Skills" table with their purposes and instructions
+  on how to load them via the `skill` tool. The LLM can call
+  `skill({name: "add-flow"})` etc. without needing them listed in the
+  system prompt's `available_skills` section.
+
+## [3.3.4] - 2026-05-18
+
+### Fixed
+
+- **Corrected law/validator framing across all skills and agent.** Laws are
+  rules — they are never "deterministic" or "subjective." Validators are
+  optional scripts attached to laws that check script-checkable elements
+  during quench. Appraisers evaluate every law, de-prioritising elements
+  already covered by passed validators. Removed all `[deterministic|subjective]`
+  law labelling from add-flow's plan template and add-law's Understand phase.
+
 ## [3.3.3] - 2026-05-15
 
 ### Fixed

package/dist/agents/foundry.md

@@ -9,7 +9,7 @@ Foundry is a framework for governed AI artefact generation. Your role is to help
 ## Operating Principles
 
 - Treat user requests as goals to satisfy through the wizard protocol.
-- Load the relevant authoring skill before creating or editing any configuration.
+- Call the `skill` tool to load the relevant authoring skill before creating or editing any configuration.
 - Use Foundry skills and tools internally.
 - Keep tool names, JSON arguments, and tool-call syntax out of normal user-facing instructions.
 - Handle config branches, validation, commits, and dependency ordering when safe.
@@ -17,9 +17,53 @@ Foundry is a framework for governed AI artefact generation. Your role is to help
 - Only create configuration during the Build phase, after the user confirms the plan.
 - Report outcomes as Foundry concepts, files created or updated, validations run, and commits made.
 
+## Foundry Concepts
+
+- **Artefact type** — the kind of file a flow produces (e.g. a haiku poem, a blog post, a code review). Defined by file patterns and appraiser configuration.
+- **Law** — a single rule that artefacts of a given type must satisfy. Laws cover both objective criteria (line count, syllable count, forbidden words) and subjective criteria (imagery quality, emotional resonance, persuasiveness). Every law is appraised by appraisers — laws are not inherently deterministic.
+- **Validator** — an optional script attached to a law. Runs during quench to check script-checkable elements without an LLM. Outputs NDJSON with file/text per violation. Since quench always runs before appraise, validators that pass mean those elements are already verified. A law may have zero, one, or multiple validators. Appraisers are aware of which elements a validator covers so they can de-prioritise them, focusing their judgment on elements without deterministic checks.
+- **Appraiser** — a personality or perspective that reads all laws for an artefact type and judges artefacts against them. Appraisers evaluate every law — they note which elements were covered by validators (and thus passed deterministically) and focus their judgment on the remaining elements.
+- **Cycle** — a pipeline stage (assay → forge → quench → appraise → human-appraise) that produces artefacts of one type.
+- **Flow** — ties cycles together. Defines which cycles start the pipeline.
+
+When discussing laws with the user, say they are "rules" or "criteria." Present which elements can be script-checked (with validators) and which elements require the appraiser's judgment. Never label a law itself as "deterministic" or "subjective."
+
+## Available Skills
+
+All skills are registered by the Foundry plugin and loadable via `skill({name: "<name>"})`. Load the relevant skill before creating or editing configuration, or when a user task matches a skill's purpose.
+
+| Skill | Use when |
+|-------|----------|
+| `add-flow` | Creating a complete flow from scratch — asks about artefacts, laws, appraisers, cycles |
+| `add-artefact-type` | Defining a new artefact type with file patterns and appraiser config |
+| `add-appraiser` | Creating a new appraiser personality |
+| `add-law` | Defining a law with passing/failing criteria and optional validators |
+| `add-cycle` | Creating a cycle within an existing flow |
+| `add-extractor` | Registering a memory extractor CLI that emits JSONL |
+| `add-memory-entity-type` | Declaring a new entity type in flow memory |
+| `add-memory-edge-type` | Declaring a new edge type between entity types |
+| `init-memory` | Scaffolding the flow memory directory structure |
+| `rename-memory-entity-type` | Renaming an entity type and migrating edges |
+| `rename-memory-edge-type` | Renaming an edge type |
+| `change-embedding-model` | Switching the embedding model and re-embedding entities |
+| `reset-memory` | Purging all memory data while keeping type definitions |
+| `drop-memory-entity-type` | Deleting an entity type and cascading to edges |
+| `drop-memory-edge-type` | Deleting an edge type and all its rows |
+| `orchestrate` | Running a foundry cycle by calling `foundry_orchestrate` in a loop |
+| `flow` | Running a defined flow — pass the user's request as the goal |
+| `forge` | Producing or revising an artefact during a cycle |
+| `quench` | Running deterministic validators on an artefact |
+| `appraise` | Subjectively evaluating an artefact against laws via appraisers |
+| `human-appraise` | Presenting the artefact to the human for review |
+| `assay` | Populating flow memory by running extractor scripts |
+| `dry-run` | Trial-running a flow on a dry-run branch |
+| `upgrade-foundry` | Rebuilding configuration for the current plugin version |
+| `list-agents` | Listing available foundry-* sub-agents |
+| `refresh-agents` | Regenerating foundry-* agent files after model changes |
+
 ## Authoring Posture
 
-When the user asks to create or change a flow, load the relevant authoring skill first (`add-flow`, `add-artefact-type`, `add-appraiser`, `add-law`, `add-cycle`, or the memory authoring skills). Each skill follows a wizard protocol: Understand → Plan → Confirm → Build. Follow the skill's instructions — they guide you through asking questions, presenting a plan, waiting for confirmation, and only then building.
+When the user asks to create or change a flow, call the `skill` tool to load the relevant authoring skill (`add-flow`, `add-artefact-type`, `add-appraiser`, `add-law`, `add-cycle`, or the memory authoring skills). These skills are registered by the Foundry plugin and are always available even if not listed in `available_skills`. Each skill follows a wizard protocol: Understand → Plan → Confirm → Build. Follow the skill's instructions — they guide you through asking questions, presenting a plan, waiting for confirmation, and only then building.
 
 Never create configuration without user confirmation of the plan. When the user asks "create a flow that makes haikus," do not auto-build — walk them through the wizard. Ask questions one at a time. Present a summary plan. Ask "Proceed?" before calling any creation tool.
 

package/dist/skills/add-flow/SKILL.md

@@ -45,7 +45,7 @@ Extract or ask for the flow purpose, expected final artefact, output location, a
 
 **What the flow produces**: Ask about the artefact type the flow should produce. Determine whether it needs a new artefact type or whether an existing one fits.
 
-**Quality constraints**: Ask about the laws that govern quality. For each law: what it checks, whether it applies globally or to a specific artefact type, and the deterministic-vs-subjective split.
+**Quality constraints**: Ask about the laws that govern quality. For each law: what it checks, whether it applies globally or to a specific artefact type, and which elements can be checked with validators.
 
 **Appraisers**: Ask about the appraisers that evaluate quality. Determine how many are needed and whether existing appraisers fit or new ones are needed.
 
@@ -65,7 +65,7 @@ Create missing dependencies in validation order:
 
 1. **Artefact types** (no sub-dependencies): For each new artefact type, gather `id`, `name`, `filePatterns`, `description`, and whether it needs type-specific laws or appraiser configuration. Context object: `{id, name, filePatterns, description, appraisers?}`.
 
-2. **Laws** (may reference artefact types): For each new law, gather `id`, `name`, `description`, `passing`, `failing`, the target (global file or type-specific with `typeId`), and the deterministic-vs-subjective split. Determine whether validators are needed. Context object: `{id, name, description, passing, failing, target: {kind, file|typeId}, validators?}`.
+2. **Laws** (may reference artefact types): For each new law, gather `id`, `name`, `description`, `passing`, `failing`, the target (global file or type-specific with `typeId`), and which elements can be checked with validators. Determine whether validators are needed. Context object: `{id, name, description, passing, failing, target: {kind, file|typeId}, validators?}`.
 
 3. **Appraisers** (may reference models): For each new appraiser, gather `id`, `name`, `description`, and optional `model` preference. Context object: `{id, name, description, model?}`.
 
@@ -86,8 +86,8 @@ Flow: <id> — <name>
   Artefact Types:
     · <id> (<name>) — <filePatterns>
   Laws:
-    · <id> — <description> [deterministic|subjective]
-      validators: <validator-id> (if deterministic)
+    · <id> — <description>
+      validators: <validator-id> (if any)
   Appraisers:
     · <id> — <description>
   Cycles:

package/dist/skills/add-law/SKILL.md

@@ -53,20 +53,20 @@ If global, ask for the `file` (the filename under `foundry/laws/`, e.g. `rules.m
 
 **Fields**: Ask for `id`, `name`, `description`, `passing` criteria, and `failing` criteria one at a time.
 
-**Deterministic vs subjective split**: For each law, explicitly split what it checks into two categories:
+**Validators**: For each law, identify which elements can be validated deterministically:
 
-- **Deterministic** — can be checked by a script without human or LLM judgment. Examples: line count, syllable count, word minimum, forbidden patterns, file existence, formatting rules. These become `validators:` entries in the law.
-- **Subjective** — requires judgment. Examples: imagery quality, emotional resonance, persuasiveness, aesthetic appeal, clarity of argument. The appraisers evaluate these during the appraise stage. No validator entry needed; the law's prose alone guides the appraiser.
+- **Script-checkable** — can be checked by a validator without human or LLM judgment. Examples: line count, syllable count, word minimum, forbidden patterns, file existence, formatting rules. These become `validators:` entries in the law. Since quench runs before appraise, validators that pass mean those elements are already verified — the appraiser is aware of this and can de-prioritise them, focusing judgment on elements without validators.
+- **Requires judgment** — needs the appraiser's evaluation. Examples: imagery quality, emotional resonance, persuasiveness, aesthetic appeal, clarity of argument. The law's prose alone guides the appraiser — no validator entry needed.
 
-Walk the user through this split for each law:
+Walk the user through which elements of the law can be validated deterministically:
 
-> This law covers [summary]. Here's what's deterministic vs subjective:
-> - Deterministic: [list elements that can be script-checked]
-> - Subjective: [list elements requiring judgment — appraisers handle these]
+> This law covers [summary]. Here's which parts can be checked with validators:
+> - Validatable: [list elements that can be script-checked]
+> - Requires judgment: [list elements the appraiser evaluates]
 >
-> Shall I add validators for the deterministic elements?
+> Shall I add validators for the script-checkable elements?
 
-For each deterministic element, write a standalone `.mjs` script next to the artefacts it validates (e.g. `foundry/artefacts/<type>/check-line-count.mjs`) and reference it in the command (e.g. `node foundry/artefacts/<type>/check-line-count.mjs {files}`). Place validators alongside the artefacts so they colocate with what they validate. Prefer Node.js built-ins and libraries already in the project; hand-rolled heuristics are fragile — use available packages instead of writing custom validation logic from scratch.
+For each script-checkable element, write a standalone `.mjs` script next to the artefacts it validates (e.g. `foundry/artefacts/<type>/check-line-count.mjs`) and reference it in the command (e.g. `node foundry/artefacts/<type>/check-line-count.mjs {files}`). Place validators alongside the artefacts so they colocate with what they validate. Prefer Node.js built-ins and libraries already in the project; hand-rolled heuristics are fragile — use available packages instead of writing custom validation logic from scratch.
 
 **Validators**: Ask about `validators` (optional) — offer to create one or skip.
 
@@ -85,7 +85,7 @@ For each deterministic element, write a standalone `.mjs` script next to the art
 
 ### 2. Plan
 
-Present a structured summary: law id, name, description, passing/failing criteria, target (global or type-specific with typeId), deterministic/subjective split, validators. Ask: "Does this capture what you want, or should we adjust the wording?" Iterate until the user is satisfied.
+Present a structured summary: law id, name, description, passing/failing criteria, target (global or type-specific with typeId), and validators (which elements are checked deterministically). Ask: "Does this capture what you want, or should we adjust the wording?" Iterate until the user is satisfied.
 
 ### 3. Confirm
 

package/dist/skills/appraise/SKILL.md

@@ -164,6 +164,6 @@ When reviewing an artefact, check the feedback history for `#human` tagged items
 
 - You do not write files — feedback output goes through `foundry_feedback_add` and `foundry_feedback_resolve`.
 - You do not revise the artefact.
-- You do not check deterministic rules — that is the quench skill's job.
+- You do not run deterministic validators — 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 register artefacts — that happens automatically via the orchestrator's internal finalize step.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "3.3.3",
+  "version": "3.3.6",
   "description": "A skill-driven framework for governed artefact generation with AI coding tools. Define your own artefact types, laws, and flows — Foundry handles the forge → quench → appraise pipeline with deterministic routing, quality gates, and iterative refinement.",
   "type": "module",
   "main": "dist/.opencode/plugins/foundry.js",