@really-knows-ai/foundry 3.8.3 → 3.8.4

package/dist/.opencode/plugins/foundry-tools/config-create-tools.js

@@ -133,6 +133,7 @@ function artefactTypeArgs(s) { return {
   name: s.string().describe('Human-readable display name (accepted at boundary, not persisted — id becomes frontmatter.name)'),
   filePatterns: s.array(s.string()).describe('Glob patterns defining forge write scope (written to frontmatter.file-patterns)'),
   description: s.string().describe('Prose description placed under ## Definition'),
+  example: s.string().optional().describe('Example artefact structure (markdown with code blocks). Written to example.md alongside definition.md. Guides forge agents on the expected output format.'),
   appraisers: s.object({
     count: s.number().optional().describe('Number of appraisers per cycle'),
     allowed: s.array(s.string()).optional().describe('Restrict to specific appraiser IDs'),

package/dist/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [3.8.4] - 2026-05-27
+
+### Added
+
+- `foundry_config_create_artefact_type` now accepts an optional `example` arg. When provided, it writes `foundry/artefacts/<id>/example.md` alongside `definition.md`. The example file is a structure document — markdown with code blocks showing the expected output format, plus documentation for the forge agent.
+
+- The `add-artefact-type` skill now prompts users to provide an example artefact during the Understand phase, includes it in the Plan, and passes it to the create tool in Build.
+
+### Fixed
+
+- Human-appraise stage tokens no longer carry a subagent model scope. Previously, `sort.js` resolved a model for human-appraise routes (falling through to `defaultModel`), which got embedded in the token. `foundry_stage_begin` then rejected the token because the main Foundry agent is not the scoped subagent, causing the human-appraise stage to fail to start and user feedback to be lost. Human-appraise always runs inline by the Foundry agent.
+
 ## [3.8.3] - 2026-05-27
 
 ### Changed

package/dist/scripts/lib/config-creators/artefact-type.js

@@ -50,7 +50,30 @@ const _create = makeCreator({
   validator: validate,
 });
 
+/**
+ * Assemble the markdown body for example.md from structured arguments.
+ *
+ * The example file is a structure document: markdown with code blocks showing
+ * the expected output format, plus documentation for the forge agent.
+ *
+ * @param {string} exampleContent - Raw markdown for example.md
+ * @returns {string} Trimmed content with trailing newline.
+ */
+export function assembleExampleMarkdown(exampleContent) {
+  return `${exampleContent.trim()}\n`;
+}
+
 export async function create(args) {
   const body = assembleArtefactTypeMarkdown(args);
+
+  if (args.example) {
+    const exampleDir = join('foundry', 'artefacts', args.id);
+    await args.io.mkdirp(exampleDir);
+    await args.io.writeFile(
+      join(exampleDir, 'example.md'),
+      assembleExampleMarkdown(args.example),
+    );
+  }
+
   return _create({ ...args, name: args.id, body });
 }

package/dist/scripts/sort.js

@@ -166,6 +166,7 @@ function resolveModelId(routeBase, models, defaultModel) {
 
 function pickModelId(route, frontmatter, defaultModel) {
   const routeBase = baseStage(route);
+  if (routeBase === 'human-appraise') return null;
   const resolved = frontmatter.models ? resolveModelId(routeBase, frontmatter.models, defaultModel) : null;
   return resolved || defaultModel || defaultForStage(routeBase);
 }

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

@@ -38,7 +38,7 @@ Do not tell the user to call branch tools directly.
 
 When invoked with pre-filled fields matching the `foundry_config_create_artefact_type` tool args, skip questions for provided fields. Missing fields trigger clarifying questions.
 
-Context fields: `{id, name, filePatterns, description, appraisers?}`
+Context fields: `{id, name, filePatterns, description, example?, appraisers?}`
 
 When invoked with a context:
 - If all required fields are present, skip the Understand phase and proceed to Plan → Confirm → Build.
@@ -48,6 +48,12 @@ When invoked with a context:
 
 Ask for each field one question at a time. Prefer multiple choice for `filePatterns`, deriving options from the artefact type name and common conventions (e.g. `haikus/*.md`, `haiku.md`, `output/haiku/*.md`). Ask about `appraisers` (optional) — either provide an existing appraiser ID or skip.
 
+After the core fields, ask about the example:
+
+> Would you like to provide an example artefact? An example shows forge agents the expected output structure — markdown with code blocks, plus any conventions, constraints, or required sections. Give a short example file that demonstrates what a valid output looks like.
+
+If the user provides an example, capture it verbatim. If the artefact type has no structured output (e.g. free-form prose with no required format), the user may skip this step.
+
 **Naming conflict check**: Read all existing artefact type definitions in `foundry/artefacts/*/definition.md`. Exact id match means a hard conflict — choose a different id. A semantically similar name or description triggers a warning:
 
 > An artefact type `<existing-id>` already exists that seems similar:
@@ -74,6 +80,7 @@ Present the definition to the user with these structured fields:
 - `name` (string) — human-readable label.
 - `filePatterns` (string[]) — glob patterns for files this type produces.
 - `description` (string) — prose description of what this artefact type is.
+- `example` (string, optional) — example artefact to guide forge agents on the expected output structure.
 - `appraisers` ({ count?: number, allowed?: string[] }, optional) — appraiser configuration.
 
 Ask: does this capture the artefact type correctly? Iterate until the user is satisfied.
@@ -86,7 +93,7 @@ Ask: "Proceed with this plan?" — wait for user answer before building. If the
 
 1. **Validate**: Call `foundry_config_validate_artefact_type({ name: "<id>", body: "<assembled markdown>" })`. Assemble the body from the fields using the frontmatter format the tool produces internally. If the result is `{ ok: false, errors: [...] }`, address each error and re-run until `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types or flows that do not exist yet.
 
-2. **Create**: Call `foundry_config_create_artefact_type({ id: "<id>", name: "<name>", filePatterns: ["<pattern>"], description: "<description>" })`. The tool re-validates the body (TOCTOU), writes `foundry/artefacts/<id>/definition.md`, and produces one git commit on the current `config/*` branch. Show the user the resulting commit hash.
+2. **Create**: Call `foundry_config_create_artefact_type({ id: "<id>", name: "<name>", filePatterns: ["<pattern>"], description: "<description>", example: "<example>" })`. Include `example` only when the user provided one. The tool re-validates the body (TOCTOU), writes `foundry/artefacts/<id>/definition.md` (and `example.md` if provided), and produces one git commit on the current `config/*` branch. Show the user the resulting commit hash.
 
    If the tool returns `{ ok: false, errors }` because the target file already exists, read the existing file, incorporate the user's requested changes into the current body, propose the merged result for review, then write and commit the updated file.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "3.8.3",
+  "version": "3.8.4",
   "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",