@really-knows-ai/foundry 3.3.0 → 3.3.2

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

@@ -142,7 +142,7 @@ function artefactTypeArgs(s) { return {
 function appraiserArgs(s) { return {
   id: s.string().describe('Slugged identifier matching the filename under foundry/appraisers/'),
   name: s.string().describe('Human-readable display name written to frontmatter.name'),
-  description: s.string().describe('Prose personality description placed after frontmatter'),
+  description: s.string().describe('Personality or perspective (2-4 sentences: how they think, what they care about, how they evaluate). Appraisers read laws to learn what to check — laws define boundaries and constraints, this field defines the evaluator character and lens only. Do not enumerate criteria here; put those in laws.'),
   model: s.string().optional().describe('Optional model override for this appraiser (e.g. openai/gpt-4o)'),
 }; }
 

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

@@ -332,7 +332,7 @@ function makeAddLawTool(tool) {
       }).describe('Where to write the law'),
       validators: tool.schema.array(tool.schema.object({
         id: tool.schema.string().describe('Validator identifier'),
-        command: tool.schema.string().describe('CLI command with optional {pattern} / {files} placeholders'),
+        command: tool.schema.string().describe('CLI command with optional {pattern} / {files} placeholders. Prefer JavaScript (.mjs) scripts as separate files (e.g. "node foundry/artefacts/<type>/check.mjs {files}"). Stdout must be NDJSON: one JSON object per line with required fields "file" (relative path) and "text" (message). Optional: "location" (line:col), "severity" (error|warning). Exit code is ignored.'),
         failureMeans: tool.schema.string().optional().describe('Description of what failure means'),
       })).optional().describe('Optional deterministic validators'),
     },

package/dist/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## [3.3.2] - 2026-05-14
+
+### Changed
+
+- **All 15 creation and edit skills converted to an interactive wizard
+  protocol.** Every skill now follows Understand → Plan → Confirm → Build
+  instead of auto-creating configuration. The AI asks questions, presents a
+  plan, waits for confirmation, then builds — no file is created before the
+  user says yes.
+
+  Skills converted:
+
+  | Phase | Skills |
+  |-------|--------|
+  | Core config | `add-artefact-type`, `add-appraiser`, `add-law` |
+  | Cycle and flow | `add-cycle`, `add-flow` (composite — invokes sub-skills with context) |
+  | Memory creation | `add-extractor`, `add-memory-entity-type`, `add-memory-edge-type`, `init-memory` |
+  | Memory edit/destructive | `rename-memory-entity-type`, `rename-memory-edge-type`, `change-embedding-model`, `reset-memory`, `drop-memory-entity-type`, `drop-memory-edge-type` |
+
+- **Sub-skill composition via context object contract.** Parent skills (e.g.
+  `add-flow`, `add-artefact-type`) pass pre-filled field objects to
+  sub-skills (e.g. `add-law`, `add-cycle`). Sub-skills skip questions for
+  provided fields and only ask for gaps. `add-flow` presents a single
+  combined plan covering all dependencies and confirms once before building.
+- **Destructive skills require typed confirmation.** `reset-memory` requires
+  typing "reset"; `drop-*` skills show previews of affected rows and edges
+  before requiring explicit confirmation.
+
+## [3.3.1] - 2026-05-14
+
+### Fixed
+
+- **Appraiser tool description** now explicitly states that appraisers are
+  personalities only — boundaries and constraints belong in laws. Prevents
+  the AI from embedding criteria in appraiser descriptions that should be
+  encoded as laws.
+- **Validator command description** now mandates `.mjs` scripts and NDJSON
+  stdout format (`file`, `text`, optional `location`/`severity`, exit code
+  ignored). Prevents the AI from using inline bash/Python validators that
+  don't produce machine-parseable output.
+- **add-law skill** gains §2a: a deterministic-vs-subjective split step
+  that walks the user through which law elements can be script-checked and
+  which are left to appraisers. Includes guidance to prefer existing
+  libraries over hand-rolled validation logic.
+- **add-artefact-type skill** no longer carries validator guidance
+  (validators are exclusively law-related, not artefact-type-related).
+
 ## [3.3.0] - 2026-05-14
 
 ### Added

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

@@ -34,30 +34,23 @@ Do not tell the user to call branch tools directly.
 
 ## Protocol
 
-### 1. Gather basics
+### Context object
 
-From the user's prompt, establish:
-- `id` — lowercase, hyphenated identifier
-- `name` — a short character name (e.g., "The Pedant", "The Pragmatist")
-- `model` — (optional) a specific model ID to use for this appraiser (e.g., `openai/gpt-4o`). Overrides the cycle-level model for the appraise stage. If omitted, the appraiser uses whatever model the cycle's appraise stage is configured with.
-- A prose description of the personality: how they think, what they prioritize, how they evaluate
+When invoked with pre-filled fields matching the `foundry_config_create_appraiser` tool args, skip questions for provided fields. Missing fields trigger clarifying questions.
 
-If `id`, `name`, or the personality description are missing, ask. The `model` field is optional — only ask about it if the user mentions wanting a specific model for this appraiser.
+Context fields: `{id, name, description, model?}`
 
-### 2. Check for id conflicts
+When invoked with a context:
+- If all required fields are present, skip the Understand phase and proceed to Plan → Confirm → Build.
+- If only some fields are present, ask only for the missing ones.
 
-Read all existing appraiser definitions in `foundry/appraisers/*.md`.
+### 1. Understand
 
-- Exact id match → hard conflict, must choose a different id
+Ask for `id`, `name`, and `description` one at a time. Ask about `model` (optional) — offer the default model as the recommended choice.
 
-### 3. Check for semantic overlap
+**Id conflict check**: Read all existing appraiser definitions in `foundry/appraisers/*.md`. Exact id match means a hard conflict — choose a different id.
 
-For each existing appraiser, compare the new personality against it:
-- What does this appraiser prioritize?
-- What lens do they evaluate through?
-- Would two artefacts get meaningfully different feedback from these appraisers?
-
-If significant overlap is found, present it to the user:
+**Semantic overlap check**: For each existing appraiser, compare the new personality against it. If significant overlap is found, present it to the user:
 
 > The new appraiser `<new-id>` seems to overlap with existing appraiser `<existing-id>`:
 > - New: <name> — <personality summary>
@@ -74,45 +67,23 @@ If significant overlap is found, present it to the user:
 
 Do not proceed until the user has decided.
 
-### 4. Draft the definition
-
-Present the definition to the user with these structured fields:
-
-- `id` (string) — lowercase, hyphenated identifier
-- `name` (string) — a short character name (e.g., "The Pedant", "The Pragmatist")
-- `description` (string) — 2-4 sentences describing how this appraiser thinks, what they care about, and how they approach evaluation
-- `model` (string, optional) — a specific model ID to use for this appraiser (e.g., `openai/gpt-4o`). Overrides the cycle-level model for the appraise stage. Omit this field to use the cycle's default model.
-
-Ask: does this capture the personality correctly?
-
-### 5. Refine with the user
-
-Iterate until the user is happy with the personality description. Key things to check:
-- Is the personality distinct enough from existing appraisers?
-- Does the description give the LLM enough direction to adopt a consistent voice?
-- Is it clear what this appraiser would flag vs let pass?
-
-### 6. Validate the draft
-
-Call `foundry_config_validate_appraiser({ name: "<id>", body: "<assembled markdown>" })`. Assemble the body from the fields using the frontmatter format the tool produces internally.
+### 2. Plan
 
-If the result is `{ ok: false, errors: [...] }`, address each error (adjust the body) and re-run until you get `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types or flows that don't exist yet.
+Present a quick inline summary: id, name, personality description. Include the model if one was specified. Ask: "Does this capture the personality correctly?" Iterate until the user is satisfied.
 
-### 7. Create the file
+### 3. Confirm
 
-Call `foundry_config_create_appraiser({ id: "<id>", name: "<name>", description: "<description>" })`. The tool:
+Ask: "Proceed with this plan?" — wait for user answer before building. If the user rejects the plan, return to the Understand phase and adjust.
 
-- re-validates the body (TOCTOU);
-- writes `foundry/appraisers/<id>.md`;
-- produces one git commit on the current `config/*` branch.
+### 4. Build
 
-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.
+1. **Validate**: Call `foundry_config_validate_appraiser({ 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.
 
-Show the user the resulting commit hash from the response.
+2. **Create**: Call `foundry_config_create_appraiser({ id: "<id>", name: "<name>", description: "<description>" })`. The tool re-validates the body (TOCTOU), writes `foundry/appraisers/<id>.md`, and produces one git commit on the current `config/*` branch. Show the user the resulting commit hash.
 
-### 8. Mention artefact type configuration
+   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.
 
-After creating the appraiser, offer to connect it to relevant artefact-type configuration when doing so supports the user's stated goal. If the user confirms, update the artefact type's `appraisers.allowed` list on the same config branch.
+3. **Artefact type configuration**: After creating the appraiser, offer to connect it to relevant artefact-type configuration when doing so supports the user's stated goal. If the user confirms, update the artefact type's `appraisers.allowed` list on the same config branch.
 
 ## What you do NOT do
 

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

@@ -34,24 +34,21 @@ Do not tell the user to call branch tools directly.
 
 ## Protocol
 
-### 1. Gather basics
+### Context object
 
-From the user's prompt, establish:
-- `id` — lowercase, hyphenated identifier (e.g. `haiku`). The
-  frontmatter `name:` field must equal this id; any human-readable
-  label goes in the `## Definition` prose, not in frontmatter.
-- `file-patterns` — glob patterns for files this type produces
-  (forge's write scope is exactly these patterns).
-- A prose description of what this artefact type is.
+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.
 
-If any of these are missing, ask.
+Context fields: `{id, name, filePatterns, description, appraisers?}`
 
-### 2. Check for naming conflicts
+When invoked with a context:
+- If all required fields are present, skip the Understand phase and proceed to Plan → Confirm → Build.
+- If only some fields are present, ask only for the missing ones.
 
-Read all existing artefact type definitions in `foundry/artefacts/*/definition.md`.
+### 1. Understand
 
-- Exact id match → hard conflict, must choose a different id
-- Semantically similar name or description → warn the user. Ask:
+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.
+
+**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:
 > - Existing: <name> — <description summary>
@@ -59,16 +56,7 @@ Read all existing artefact type definitions in `foundry/artefacts/*/definition.m
 >
 > Is the new type genuinely distinct, or should you extend the existing one?
 
-### 3. Check for glob intersection
-
-For each existing artefact type, check whether the new type's `file-patterns` could match the same files as any existing type's `file-patterns`.
-
-Examples of intersections:
-- `features/*.feature` vs `features/*.feature` — exact overlap
-- `features/**` vs `features/*.feature` — subset overlap
-- `output/*.md` vs `output/reports/*.md` — potential overlap if nested
-
-If any intersection is found, this is a hard block:
+**File pattern overlap check**: For each existing artefact type, check whether the new type's `filePatterns` could match the same files as any existing type's patterns. Overlapping file patterns are a hard block:
 
 > The file pattern `<new-pattern>` intersects with artefact type `<existing-id>` which uses `<existing-pattern>`.
 >
@@ -78,100 +66,33 @@ If any intersection is found, this is a hard block:
 
 Do not proceed until the patterns are non-overlapping.
 
-### 4. Draft the definition
+### 2. Plan
 
 Present the definition to the user with these structured fields:
 
-- `id` (string) — lowercase, hyphenated identifier (e.g. `haiku`). Must be unique across artefact types.
-- `name` (string) — human-readable label
-- `filePatterns` (string[]) — glob patterns for files this type produces (forge's write scope is exactly these patterns)
-- `description` (string) — prose description of what this artefact type is
-- `appraisers` ({ count?: number, allowed?: string[] }, optional) — appraiser configuration
-
-The `id` value must exactly match the artefact type's identifier
-(lowercase, hyphenated). If you want a human-readable label, put it
-in the `name` field.
-
-Ask: does this capture the artefact type correctly?
-
-When laws or validators are clearly part of the requested artefact type, draft them during artefact-type creation. Use the validator contract from `add-law` and prefer established packages installed with the project package manager.
-
-### 5. Laws (optional)
-
-Ask:
-
-> Do you want to define any type-specific laws for this artefact type? (Global laws in `foundry/laws/` will apply automatically.)
-
-If yes, walk through each law using the same format as `add-law`:
-- Draft each law, adding validators where a deterministic check applies
-- Check for conflicts with global laws and any existing type-specific laws
-- Confirm with the user
-
-Each law may declare an optional `validators:` block; the YAML shape,
-JSONL output contract, `{pattern}` / `{files}` placeholders, skip
-rule, working directory, and a worked example are documented once in
-the `add-law` skill under **§7a. Validator contract**. Authors of
-type-specific laws must follow that contract — do not invent a
-different one here.
-
-**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
-
-### 6. Appraisers (optional)
-
-Ask:
-
-> How should appraisers be configured for this artefact type?
-> - How many appraisers per foundry cycle? (default: 3)
-> - Restrict to specific appraiser personalities? (default: all available)
-
-If the user specifies preferences, include these fields:
-
-- `appraisers.count` (number, optional, default: 3) — how many appraisers per foundry cycle
-- `appraisers.allowed` (string[], optional, default: all available) — whitelist of appraiser personality IDs
-
-If the user is happy with the defaults (3 appraisers, any personality), omit the appraisers configuration entirely.
-
-List the available appraisers from `foundry/appraisers/*.md` so the user can see their options.
-
-### 7. Validate the draft
-
-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 (adjust the body) and re-run until you get `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types or flows that don't exist yet.
+- `id` (string) — lowercase, hyphenated identifier. Must be unique across artefact types.
+- `name` (string) — human-readable label.
+- `filePatterns` (string[]) — glob patterns for files this type produces.
+- `description` (string) — prose description of what this artefact type is.
+- `appraisers` ({ count?: number, allowed?: string[] }, optional) — appraiser configuration.
 
-### 8. Create the file
+Ask: does this capture the artefact type correctly? Iterate until the user is satisfied.
 
-Call `foundry_config_create_artefact_type({ id: "<id>", name: "<name>", filePatterns: ["<pattern>"], description: "<description>" })`. The tool:
+### 3. Confirm
 
-- re-validates the body (TOCTOU);
-- writes `foundry/artefacts/<id>/definition.md`;
-- produces one git commit on the current `config/*` branch.
+Ask: "Proceed with this plan?" — wait for user answer before building. If the user rejects the plan, return to the Understand phase and adjust.
 
-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.
+### 4. Build
 
-Show the user the resulting commit hash from the response.
+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.
 
-### 9. Add laws file (if defined)
+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.
 
-If you drafted any type-specific laws in step 5, add them via
-`foundry_config_add_law` (one call per law) with
-`target: { kind: "type-specific", typeId: "<id>" }`. The first call
-creates `foundry/artefacts/<id>/laws.md`; subsequent calls append to
-that same file. Each call produces its own microcommit. See the
-`add-law` skill for the full protocol.
+   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.
 
-### 10. Confirm
+3. **Type-specific laws**: Ask "Define any type-specific laws for this artefact type?" If yes, invoke the `add-law` protocol with context: `{target: {kind: "type-specific", typeId: "<new-type-id>"}}`. The `add-law` skill asks for the missing law fields (id, name, description, passing, failing) and creates the law at `foundry/artefacts/<typeId>/laws.md`.
 
-Show the user the complete file listing and the commit hashes.
+4. **Appraisers**: Ask "How should appraisers be configured for this artefact type?" Offer the defaults (3 appraisers, any personality) or let the user specify preferences. List the available appraisers from `foundry/appraisers/*.md` so the user can see their options.
 
 ## What you do NOT do
 

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

@@ -34,151 +34,83 @@ Do not tell the user to call branch tools directly.
 
 ## Protocol
 
-### 1. Identify the foundry flow
+### Context object
 
-From the user's prompt, identify which foundry flow this foundry cycle belongs to. If not specified, list available flows from `foundry/flows/` and ask.
+When invoked with pre-filled fields matching the `foundry_config_create_cycle` tool args, skip questions for provided fields. Missing fields trigger clarifying questions.
 
-If the parent flow or required artefact type is missing and the user's goal clearly requires it, create that dependency first. If multiple designs are plausible, ask one focused question before creating it.
-
-### 2. Gather basics
-
-From the user's prompt, establish:
-- `id` — lowercase, hyphenated identifier for the foundry cycle
-- `name` — human-readable name
-- `output-type` — the artefact type this foundry cycle produces (must exist in `foundry/artefacts/`)
-- `inputs` — artefact types this cycle reads, with a contract type:
-  - `type`: `any-of` (at least one must exist) or `all-of` (all must exist)
-  - `artefacts`: list of artefact type IDs
-  - May be empty for starting cycles
-- `targets` — cycle(s) to route to after this cycle completes (may be empty for terminal cycles)
-- A prose description of what this foundry cycle does
+Context fields: `{id, name, outputType, description, inputs?, targets?, humanAppraise?, deadlockAppraise?, deadlockIterations?, maxIterations?, assay?, memory?, models?}`
 
-If any of these are missing, ask.
+When invoked with a context:
+- If all required fields are present, skip the Understand phase and proceed to Plan → Confirm → Build.
+- If only some fields are present, ask only for the missing ones.
 
-### 3. Gather model configuration
+### 1. Understand
 
-For each stage in the cycle (forge, quench, appraise), ask the user if they want to specify a model:
+**Identify the flow**: From the user's prompt, identify which foundry flow this cycle belongs to. If not specified, list available flows from `foundry/flows/` and ask.
 
-> Each stage can optionally run on a specific model for model diversity. Available session models are listed in your session configuration.
->
-> For each stage, specify a model ID (e.g., `openai/gpt-4o`) or leave blank to use the session's default model:
-> - forge: ___
-> - quench: ___
-> - appraise: ___
-
-Only stages with an explicitly specified model are included in the `models` frontmatter map.
+If the parent flow or required artefact type is missing and the user's goal clearly requires it, create that dependency first. If multiple designs are plausible, ask one focused question before creating it.
 
-If the user has no preference, omit the `models` map and use the session defaults.
+**Required fields** — Gather each required field one question at a time:
+- `id` — lowercase, hyphenated identifier for the cycle
+- `name` — human-readable name
+- `outputType` — the artefact type this cycle produces. List existing artefact types from `foundry/artefacts/*/definition.md` as multiple-choice options.
+- `description` — prose description of what this cycle does
 
-### 4. Configure human appraise
+**Id conflict check**: Read all existing cycle definitions in `foundry/cycles/*.md`. An exact id match is a hard conflict — choose a different id.
 
-Ask the user:
+**Output-type conflict check**: Read the flow definition from `foundry/flows/<flow-id>.md`. Check that no cycle in the flow already outputs the same artefact type. Two cycles producing the same type in one flow is a conflict — the file modification enforcement cannot distinguish which cycle owns the files. If a conflict exists, present it:
 
-> Human-appraise has two independent knobs and one dependent setting:
->
-> 1. `human-appraise` — should a human review the artefact every iteration? Default: no.
-> 2. `deadlock-appraise` — should a human be pulled in only when LLM appraisers deadlock? Default: yes.
-> 3. `deadlock-iterations` — the deadlock threshold (default: 5). Only applies when `deadlock-appraise` or `human-appraise` is enabled.
+> A cycle `<existing-id>` already produces `<outputType>` in this flow. Two cycles producing the same artefact type creates a conflict.
 >
-> - human-appraise: yes/no (default no)
-> - deadlock-appraise: yes/no (default yes)
-> - deadlock-iterations: number (default 5)
-
-### 5. Validate artefact types
-
-For `output-type` and each entry in `inputs`, verify the artefact type exists in `foundry/artefacts/<type>/definition.md`.
-
-If a required artefact type is missing and the user's goal clearly requires it, create that dependency first. If the file pattern or type design cannot be inferred safely, ask one focused question before creating it.
-
-### 6. Validate against the foundry flow
-
-Read the flow definition from `foundry/flows/<flow-id>.md`. Check:
+> Options:
+> 1. Choose a different `outputType`
+> 2. Choose a different flow
+> 3. Proceed anyway if the types are intentionally distinct
 
-- No existing foundry cycle in the foundry flow already outputs the same artefact type. Two foundry cycles producing the same type in one foundry flow is a conflict — the file modification enforcement can't distinguish which foundry cycle owns the files.
-- Each `input` artefact type is produced by some cycle that can run before this one according to the flow's `targets` graph (a reachable predecessor). If an input references an artefact type that no reachable predecessor outputs, warn:
+**Input reachability check**: For each input artefact type, verify that a reachable predecessor in the flow's `targets` graph produces it. If an input references a type that no reachable predecessor outputs, warn:
 
-> Input `<type>` is not produced by any reachable predecessor of this foundry cycle in the flow's `targets` graph. The artefact won't exist when this foundry cycle runs.
+> Input `<type>` is not produced by any reachable predecessor of this cycle in the flow's `targets` graph. The artefact will not exist when this cycle runs.
 >
 > Options:
-> 1. Add a foundry cycle that produces `<type>` and route to this cycle via `targets`
-> 2. Remove `<type>` from inputs (this foundry cycle won't have that context)
-> 3. Proceed anyway (the artefact may exist from a previous foundry flow run)
-
-### 7. Check for id conflicts
-
-Read all existing cycle definitions in `foundry/cycles/*.md`.
-
-- Exact id match → hard conflict, must choose a different id
-
-### 8. Check for semantic overlap
-
-For foundry cycles already in this foundry flow, check whether the new foundry cycle overlaps in purpose:
-- Does another foundry cycle already transform the same inputs into a similar output?
-- Would the new foundry cycle's description make sense as a revision of an existing foundry cycle rather than a new one?
-
-If overlap is found, present it and ask the user to confirm the distinction is real.
-
-### 9. Draft the definition
-
-Present the foundry cycle definition to the user with these structured fields:
-
-- `id` (string) — lowercase, hyphenated identifier
-- `name` (string) — human-readable name
-- `outputType` (string) — the artefact type this cycle produces (must exist in `foundry/artefacts/`)
-- `description` (string) — prose description of what this cycle does
-- `inputs` (object, optional) — input contract. Shape: `{ type: "any-of" | "all-of", artefacts: string[] }`. May be omitted for starting cycles.
-- `targets` (string[], optional) — cycle IDs to route to after completion. May be omitted for terminal cycles.
-- `humanAppraise` (boolean, optional, default: false) — whether a human reviews the artefact every iteration
-- `deadlockAppraise` (boolean, optional, default: true) — whether a human is pulled in when LLM appraisers deadlock
-- `deadlockIterations` (number, optional, default: 5) — deadlock threshold
-- `maxIterations` (number, optional) — maximum iterations before forced progression
-- `assay` (object, optional) — assay configuration
-- `memory` (object, optional) — memory configuration
-- `models` (object, optional) — stage-specific model overrides, e.g. `{ appraise: "openai/gpt-4o" }`
-
-Ask: does this capture the foundry cycle correctly?
-
-### 10. Validate target routing
-
-For each target cycle:
-- Verify the target cycle exists in `foundry/cycles/`
-- Verify this cycle's output type satisfies at least one of the target's input artefacts
-- If the target doesn't exist yet, note it as pending
+> 1. Add a cycle that produces `<type>` and route to this cycle via `targets`
+> 2. Remove `<type>` from inputs (this cycle will not have that context)
+> 3. Proceed anyway (the artefact may exist from a previous flow run)
 
-For input validation:
-- Verify that at least one cycle in the flow has the input artefact type(s) as its output
-- If using `all-of`, verify all input types are producible
+**Validate target routing**: For each target cycle, verify the target exists in `foundry/cycles/` and that this cycle's output type satisfies at least one of the target's input artefacts. If a target does not exist yet, note it as pending.
 
-### 11. Validate the draft
+**Optional clusters** — After each cluster, ask whether the user wants to configure it; if not, skip:
 
-Call `foundry_config_validate_cycle({ name: "<id>", body: "<assembled markdown>" })`. Assemble the body from the fields using the frontmatter format the tool produces internally.
+- **Routing**: `inputs` (input contract: `{type: "any-of"|"all-of", artefacts: string[]}`), `targets` (cycle IDs to route to after completion), `maxIterations` (maximum iterations before forced progression)
+- **Human-appraise**: `humanAppraise` (boolean, default false) — human reviews every iteration; `deadlockAppraise` (boolean, default true) — human is pulled in when LLM appraisers deadlock; `deadlockIterations` (number, default 5) — deadlock threshold. Only applies when either appraise is enabled.
+- **Memory and models**: `assay` (assay configuration), `memory` (memory configuration), `models` (stage-specific model overrides, e.g. `{forge: "openai/gpt-4o", appraise: "openai/gpt-4o"}`). For models, offer each stage (forge, quench, appraise) individually. If the user has no preference, omit the `models` map and use the session defaults.
 
-If the result is `{ ok: false, errors: [...] }`, address each error (adjust the body) and re-run until you get `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types or flows that don't exist yet.
+### 2. Plan
 
-### 12. Create the cycle file
+Present a structured summary of the cycle definition: id, name, outputType, description, and any configured optional fields (inputs, targets, humanAppraise, deadlockAppraise, deadlockIterations, maxIterations, assay, memory, models). Include only fields that have values.
 
-Call `foundry_config_create_cycle({ id: "<id>", name: "<name>", outputType: "<type>", description: "<description>", inputs: ..., targets: ..., humanAppraise: ..., deadlockAppraise: ..., deadlockIterations: ..., maxIterations: ..., assay: ..., memory: ..., models: ... })`. The tool:
+Ask: "Does this capture the cycle correctly?" Iterate until the user is satisfied.
 
-- re-validates the body (TOCTOU);
-- writes `foundry/cycles/<id>.md`;
-- produces one git commit on the current `config/*` branch.
+### 3. Confirm
 
-If the tool returns `{ ok: false, errors }` because the target file already exists, read the existing cycle file, apply any necessary updates, write it back, and commit on this `config/*` branch.
+Ask: "Proceed with this plan?" — wait for user answer before building. If the user rejects the plan, return to the Understand phase and adjust.
 
-Show the user the resulting commit hash from the response.
+### 4. Build
 
-### 13. Add the cycle to the flow's cycle list
+1. **Validate**: Call `foundry_config_validate_cycle({ 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.
 
-`foundry_config_create_cycle` writes the cycle file only. The cycle still needs to appear in the parent flow's `## Cycles` list.
+2. **Create**: Call `foundry_config_create_cycle({ id: "<id>", name: "<name>", outputType: "<type>", description: "<description>", inputs: ..., targets: ..., humanAppraise: ..., deadlockAppraise: ..., deadlockIterations: ..., maxIterations: ..., assay: ..., memory: ..., models: ... })`. The tool:
+   - re-validates the body (TOCTOU);
+   - writes `foundry/cycles/<id>.md`;
+   - produces one git commit on the current `config/*` branch.
 
-Read the existing flow file from `foundry/flows/<flow-id>.md`. Add the new cycle id under `## Cycles` if it is not already present. Write the updated file back and commit on this same `config/*` branch.
+   If the tool returns `{ ok: false, errors }` because the target file already exists, read the existing cycle file, apply any necessary updates, write it back, and commit on this `config/*` branch.
 
-### 14. Confirm
+3. **Add to flow cycle list**: `foundry_config_create_cycle` writes the cycle file only. The cycle still needs to appear in the parent flow's `## Cycles` list. Read the existing flow file from `foundry/flows/<flow-id>.md`. Add the new cycle id under `## Cycles` if not already present. Write the updated file back and commit on this same `config/*` branch.
 
-Show the user the cycle file, the updated flow file, and both commit hashes.
+4. Show the user the cycle file, the updated flow file, and both commit hashes.
 
 ## What you do NOT do
 
-- You do not create foundry cycles that output an artefact type already produced by another foundry cycle in the same foundry flow
+- You do not create cycles that output an artefact type already produced by another cycle in the same flow
 - You do not skip artefact type validation
 - You do not create dependencies (artefact types, flows) unless the user's stated goal clearly requires them; ask one focused question when multiple designs are plausible