@really-knows-ai/foundry 3.0.2 → 3.1.0

package/dist/docs/getting-started.md

@@ -26,24 +26,16 @@ OpenCode resolves the package itself — `npm install` is **not** required. Rest
 Optionally, if you want the package available to your project's local node_modules (for editor tooling or scripts), run:
 
 ```sh
-npm install --save-dev @really-knows-ai/foundry
+pnpm add -D @really-knows-ai/foundry
 ```
 
 ## Initialise
 
-In your project, invoke the `init-foundry` skill. It:
+Run the `init-foundry` skill.
 
-1. Creates the `foundry/` directory structure:
-   ```
-   foundry/
-     artefacts/.gitkeep
-     flows/.gitkeep
-     cycles/.gitkeep
-     laws/.gitkeep
-     appraisers/.gitkeep
-   ```
-2. Runs `refresh-agents` to generate `.opencode/agents/foundry-*.md` — one per available model — so cycles can dispatch to specific models later.
-3. Commits the scaffolding.
+Initialisation installs the user-facing `Foundry` agent at `.opencode/agents/foundry.md` and generates model-routing `foundry-*` stage agents for any models available in your OpenCode session.
+
+Restart OpenCode after initialisation. Then switch to the **Foundry** agent before authoring flows. The Foundry agent understands Foundry's authoring workflow and handles dependent setup such as artefact types, laws, validators, appraisers, cycles, and config branches.
 
 The `.foundry/` runtime directory (holding `.secret` for stage tokens) is created automatically on first plugin boot and added to `.gitignore`.
 
@@ -51,134 +43,67 @@ The `.foundry/` runtime directory (holding `.secret` for stage tokens) is create
 
 ## Author the configuration
 
-Foundry's configuration is five things: artefact types, laws, appraisers, cycles, and flows. You can write the files by hand, but the authoring skills do conflict checking, scaffolding, and validation — use them.
-
-Before using any schema-writing skill, open a config branch. All schema-mutation tools (`foundry_config_create_*`, `foundry_memory_create_*`, `foundry_extractor_create`, the memory admin family) refuse off `main` and off flow branches:
-
-```text
-foundry_git_branch({ kind: "config", description: "<short-name>" })
-```
-
-This typically puts you on `config/<short-name>` from `main`. Make all the
-edits below on this branch, then `foundry_git_finish({ message: "...",
-baseBranch: "main", confirm: true })` squashes the work back to
-`main` in one commit. To trial the in-progress edits against a real
-flow before merging, see "Trial config edits with dry-run" below.
-
-### 1. Define an artefact type
-
-Run `add-artefact-type`. It walks you through:
-
-- `id` (lowercase, hyphenated), `name`, prose description.
-- `file-patterns` — glob patterns describing which files this type owns. Forge's write scope is exactly these patterns; anything written outside them violates the cycle. The skill refuses patterns that overlap with existing types.
-- Appraiser config — how many appraisers evaluate this type and which personalities are allowed.
-- Optional `laws.md` — type-specific criteria, with optional validators for deterministic checks.
-
-Produces `foundry/artefacts/<id>/definition.md` (+ optional `laws.md`).
-
-### 2. Write laws
-
-Laws are subjective pass/fail criteria evaluated by appraisers. Two scopes:
-
-- **Global** — `foundry/laws/*.md`. All files are concatenated and apply to every artefact.
-- **Type-specific** — `foundry/artefacts/<type>/laws.md`.
-
-Run `add-law` to create one with conflict detection. Each law is a `## heading` (its identifier, referenced as `law:<id>` in feedback) with a description, passing criteria, and failing criteria.
-
-### 3. Create appraisers
-
-Appraisers are independent evaluators with named personalities. Run `add-appraiser`. Each appraiser may override the cycle-level appraise model via a `model` field. Artefact types pick which appraisers may evaluate them (`appraisers.allowed`).
+Foundry's configuration is five things: artefact types, laws, appraisers, cycles, and flows. The Foundry agent handles branch setup, conflict checking, scaffolding, and validation for normal authoring.
 
-### 4. Define a cycle
+### Author through the Foundry agent
 
-Run `add-cycle`. A cycle produces one artefact type and declares:
+Ask the Foundry agent to author or modify any part of the configuration. For example:
 
-- `output-type` — the artefact type (must already exist).
-- `inputs` — a contract (`any-of` or `all-of`) over other types. Empty for starting cycles.
-- `targets` — the cycle(s) that may run after this one. Empty for terminal cycles.
-- `human-appraise` / `deadlock-appraise` / `deadlock-iterations` — human-gate config.
-- `models` — optional per-stage model overrides.
+> Add a `haiku` artefact type with a `poetic-form` appraiser.
 
-Example:
+> Add a law that requires at least one sensory metaphor in every haiku.
 
-```markdown
----
-id: haiku-creation
-name: Haiku Creation
-output-type: haiku
-inputs:
-  type: any-of
-  artefacts:
-    - petition
-targets: []
-human-appraise: false
-deadlock-appraise: true
-deadlock-iterations: 5
-models:
-  appraise: openai/gpt-5
----
+> Create a cycle that produces haikus from petitions.
 
-# Haiku Creation
+> Set up a `make-haiku` flow starting from `haiku-ideation`.
 
-Writes a haiku satisfying the petition produced by haiku-ideation.
-```
+The agent opens a config branch, creates the files, validates them, and commits the result. To trial in-progress edits against a real flow before merging, see "Trial config edits with dry-run" below.
 
-The skill validates that every input type can be produced by some cycle in the flow and that targets are reachable.
+### Configuration reference
 
-### 5. Define a flow
+These are the five pieces of a Foundry configuration, in dependency order:
 
-Run `add-flow`. A flow groups cycles and declares starting points:
+1. **Artefact types** — define the output of each cycle. Each type has an `id`, `name`, prose description, `file-patterns` (forge's write scope), appraiser config, and optional type-specific `laws.md`. Produces `foundry/artefacts/<id>/definition.md`.
 
-```markdown
----
-id: make-haiku
-name: Make a Haiku
-starting-cycles:
-  - haiku-ideation
----
+2. **Laws** — subjective pass/fail criteria evaluated by appraisers. Two scopes: global (`foundry/laws/*.md`, concatenated for every artefact) and type-specific (`foundry/artefacts/<type>/laws.md`). Each law is a `## heading` (its identifier, referenced as `law:<id>` in feedback) with a description, passing criteria, and failing criteria.
 
-# Make a Haiku
-
-End-to-end flow: petition → haiku, with a human quality gate.
-
-## Cycles
-
-- haiku-ideation
-- haiku-creation
-```
+3. **Appraisers** — independent evaluators with named personalities. Each may override the cycle-level appraise model via a `model` field. Artefact types pick which appraisers may evaluate them (`appraisers.allowed`).
 
-Routing between cycles is owned by individual cycles via their `targets`, not by the flow.
+4. **Cycles** — produce one artefact type and declare `output-type`, `inputs` (a contract over other types), `targets` (reachable downstream cycles), human-gate config, and optional per-stage model overrides. Example:
 
-### 6. Validate before writing (optional)
+   ```markdown
+   ---
+   id: haiku-creation
+   name: Haiku Creation
+   output-type: haiku
+   inputs:
+     type: any-of
+     artefacts:
+       - petition
+   targets: []
+   human-appraise: false
+   deadlock-appraise: true
+   deadlock-iterations: 5
+   models:
+     appraise: openai/gpt-5
+   ---
+   ```
 
-Each `add-*` skill writes and commits in one step. When you want to validate a draft body without committing it, call the matching validator first:
+5. **Flows** — group cycles and declare starting points. Routing between cycles is owned by individual cycles via their `targets`.
 
-```text
-foundry_config_validate_artefact_type({ name, body })
-foundry_config_validate_law({ name, body })
-foundry_config_validate_appraiser({ name, body })
-foundry_config_validate_cycle({ name, body })
-foundry_config_validate_flow({ name, body })
-```
+### Hand-authoring configuration files
 
-Validators return `{ok: true}` on success or
-`{ok: false, errors: [...]}` on a parse / schema / overlap problem; nothing
-is written either way. Once the validator is happy, call the
-matching `_create_*` tool to commit it.
+Users who prefer to write configuration files by hand open a config branch first. The Foundry agent handles this automatically; hand-authoring is for users who choose to work outside the agent. See [`docs/tools.md`](./tools.md) for the full list of schema-mutation and validation tools.
 
 ---
 
 ## Run the flow
 
-Tell OpenCode something like:
-
-> Run the `make-haiku` flow to write a haiku about autumn rain.
-
-The `flow` skill will:
+To run a flow, ask the Foundry agent with your goal as the input (e.g. "Run the make-haiku flow to write a haiku about autumn rain"). The Foundry agent dispatches the `flow` skill, which:
 
-1. Check prerequisites and pick a starting cycle — matching your prose to a cycle's output type. If the request is ambiguous, it prompts (defaulting to `starting-cycles`). If a cycle's input contract can't be satisfied from files on disk, it won't be chosen.
-2. Create a work branch and scaffold `WORK.md` with the goal.
-3. Hand off to `orchestrate`, which drives the cycle:
+1. Checks prerequisites and picks a starting cycle — matching your prose to a cycle's output type. If the request is ambiguous, it prompts (defaulting to `starting-cycles`). If a cycle's input contract can't be satisfied from files on disk, it won't be chosen.
+2. Creates a work branch and scaffolds `WORK.md` with the goal.
+3. Hands off to `orchestrate`, which drives the cycle:
    - **forge** writes the artefact.
    - **quench** runs CLI validators (if configured).
    - **appraise** dispatches parallel appraiser sub-agents and consolidates their `law:<id>` feedback.
@@ -197,19 +122,14 @@ When you've changed a law, an appraiser, or a cycle on a `config/*`
 branch and want to see how the change behaves end-to-end before
 merging, use dry-run mode.
 
-```text
-# starting on a config/* branch with the in-progress edit
-foundry_git_branch({ kind: "dry-run", flowId: "make-haiku",
-                     description: "stricter-imagery-law" })
-# now on dry-run/<parent>/make-haiku-stricter-imagery-law
-
-# run the flow as you normally would
-# every foundry_* call is traced to .foundry/trace/<branch>.jsonl
-
-foundry_git_finish({ message: "trial: stricter imagery law", confirm: true })
-# writes .snapshots/<run-id>/{README.md, work/WORK*, diff.patch, trace.jsonl}
-# on the parent config/* working tree and force-deletes the dry-run branch
-```
+Starting on the `config/*` branch with the in-progress edit, ask the
+Foundry agent to trial the change with dry-run mode for the target flow
+and a short purpose such as `stricter-imagery-law`. The agent creates a
+`dry-run/<parent>/<flow>-<purpose>` branch, runs the flow, records every
+Foundry tool call in `.foundry/trace/<branch>.jsonl`, then finishes the
+dry-run with a findings summary. Finishing writes
+`.snapshots/<run-id>/{README.md, work/WORK*, diff.patch, trace.jsonl}`
+on the parent `config/*` working tree and deletes the dry-run branch.
 
 Inspect the snapshot at `.snapshots/<run-id>/`, decide whether to keep
 the config edit, and either commit/merge from the parent `config/*`
@@ -263,11 +183,11 @@ Foundry ships a typed, graph-shaped memory store that persists across cycles. Us
 
 ### Initialise
 
-Memory init and vocabulary edits are schema mutations, so they run
-on a config branch — open one first if you are not already on it
-(`foundry_git_branch({ kind: "config", description: "memory-setup" })`).
+Memory init and vocabulary edits are schema mutations, so they run on a
+config branch. The Foundry agent opens a suitable config branch when it
+is safe; if you are working by hand, open one first.
 
-Run the `init-memory` skill. It asks whether to enable embeddings (default: yes, targeting local Ollama `nomic-embed-text` on `http://localhost:11434/v1`) and then invokes `foundry_memory_init`, which deterministically:
+To enable memory, ask the Foundry agent to add flow memory. It asks whether to enable embeddings (default: yes, targeting local Ollama `nomic-embed-text` on `http://localhost:11434/v1`) and then initialises memory, which deterministically:
 
 - creates `foundry/memory/entities/` and `edges/` (each with `.gitkeep`) plus the top-level sibling `foundry-memory/relations/` for committed row data,
 - writes `foundry/memory/config.md` (frontmatter driven by your embeddings choice) and `foundry/memory/schema.json`,
@@ -278,6 +198,8 @@ Run the `init-memory` skill. It asks whether to enable embeddings (default: yes,
 
 Two concepts: **entity types** (things memory knows about, e.g. `class`, `method`) and **edge types** (directed relationships, e.g. `calls`, `references`).
 
+The Foundry agent handles vocabulary setup as part of the normal authoring path — declare what you need in prose and it creates the types. For reference or hand-authoring, the underlying skills are:
+
 - `add-memory-entity-type` — name + prose body (naming convention, what `value` should contain, likely related edges). The body is injected into the prompt of every cycle that reads/writes this type, so write it for an LLM reader.
 - `add-memory-edge-type` — name, `sources` (list of entity types or `any`), `targets` (list or `any`), and a prose body that describes **when** the edge holds and **what it does not cover**.
 

package/dist/docs/tools.md

@@ -2,7 +2,7 @@
 
 Generated from the v3.0.x public plugin API. The authoritative tool set is
 enforced by `tests/plugin/tool-registration.test.js` — if that snapshot
-drifts, this doc must be updated. Total: **65 tools**.
+drifts, this doc must be updated. Total: **66 tools**.
 
 All tools accept arguments as a JSON object and return JSON-stringified
 results. Errors are returned as a stringified `{error: "..."}` object (not
@@ -118,6 +118,9 @@ state machine, see [`docs/concepts.md`](./concepts.md) and
 - [`foundry_attestation_verify`](#foundry_attestation_verify)
 - [`foundry_attest`](#foundry_attest)
 
+**Maintenance**
+- [`foundry_refresh_agents`](#foundry_refresh_agents)
+
 **Memory — Data**
 - [`foundry_memory_put`](#foundry_memory_put)
 - [`foundry_memory_relate`](#foundry_memory_relate)
@@ -782,6 +785,23 @@ success. `{ error: ... }` when verification fails.
 
 ---
 
+## Maintenance
+
+### `foundry_refresh_agents`
+
+> Regenerate `.opencode/agents/foundry-*.md` stage-agent files from the currently available models.
+
+**Args:** none.
+
+**Returns:** `{ ok: true, count: <n> }` on success. `{ ok: false, error: "..." }` on failure.
+
+**Failure modes:**
+- `opencode models` exits non-zero or produces no output → returns an error describing the issue.
+
+**Side effects:** creates `.opencode/agents/` if absent; deletes stale generated `.opencode/agents/foundry-*.md` stage agents; writes one fresh stage-agent file per model returned by `opencode models`.
+
+---
+
 ## Config — Schema mutation
 
 These tools each write one named config artefact and produce a single

package/dist/scripts/sort.js

@@ -156,7 +156,7 @@ function resolveModel(route, frontmatter, agentsDir, io) {
   if (!io.exists(agentPath)) {
     return {
       error: `Missing required subagent: ${model}.md is not present in ${agentsDir}/. `
-        + `Run the refresh-agents skill to regenerate agent files, then restart.`,
+        + `Call foundry_refresh_agents() to regenerate agent files, then restart.`,
     };
   }
   return model;

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

@@ -8,34 +8,29 @@ description: Creates a new appraiser personality, checking for semantic overlap
 
 You help the user create a new appraiser personality. You ensure it's genuinely distinct from existing appraisers and scaffold the definition file.
 
-## Prerequisites
+## Foundry Agent Preflight
 
-Before running this skill, verify all three of the following:
+If you are clearly operating as the Foundry agent, continue.
 
-1. The `foundry/` directory exists in the project root. If it does not
-   exist, stop and tell the user:
+If you are not clearly operating as the Foundry agent, pause and tell the user:
 
-   > Foundry is not initialized in this project. Run the
-   > `init-foundry` skill first to create the foundry/ directory
-   > structure.
+> This work is best handled by the Foundry agent. Restart OpenCode if you have just initialised Foundry, switch to the **Foundry** agent, and continue this request there.
 
-2. The current git branch is a `config/*` branch. Run
-   `git rev-parse --abbrev-ref HEAD` and confirm it matches
-   `config/<description>`.
+This is an advisory guard. Continue only when the active instructions make it clear you are the Foundry agent or the user explicitly asks to proceed here.
 
-3. If the branch does not start with `config/`, instruct the user to
-   create one before continuing:
+## Config Branch Handling
 
-   > Foundry configuration changes must be made on a config/* branch.
-   > From a clean main branch, call:
-   >
-   > `foundry_git_branch({ kind: "config", description: "<short-name>" })`
-   >
-   > Then re-run this skill.
+Before writing Foundry configuration:
 
-   If the user is on a `dry-run/*/*` branch, they must finish
-   that dry-run first (`foundry_git_finish({ message, confirm: true })`)
-   before re-running this skill on the parent `config/*`.
+- Confirm `foundry/` exists. If it is missing, initialise Foundry first when that serves the user's goal.
+- Check the current branch.
+- On `main` or another clean non-work branch, create a `config/<short-description>` branch internally.
+- On `config/*`, continue on the current branch.
+- On `work/*`, stop and explain that active flow work must be finished before configuration changes.
+- On `dry-run/*/*`, stop and explain that the dry run must be finished before configuration changes.
+- If unrelated uncommitted changes could be affected by branching or writing files, ask before proceeding.
+
+Do not tell the user to call branch tools directly.
 
 ## Protocol
 
@@ -118,26 +113,16 @@ Call `foundry_config_create_appraiser({ name: "<id>", body: "<full markdown>" })
 - writes `foundry/appraisers/<id>.md`;
 - produces one git commit on the current `config/*` branch.
 
-If the tool returns `{ ok: false, errors }` because the target file already exists, the user should edit the file by hand on this `config/*` branch — `foundry_config_create_appraiser` does not support updates.
+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.
 
 Show the user the resulting commit hash from the response.
 
 ### 8. Mention artefact type configuration
 
-After creating the appraiser, remind the user:
-
-> Appraiser `<id>` is now available. To use it for a specific artefact type, add it to the `appraisers.allowed` list in that type's `definition.md` frontmatter:
->
-> ```yaml
-> appraisers:
->   count: 3
->   allowed: [<id>, ...]
-> ```
->
-> If no `allowed` list is specified, all available appraisers (including this new one) are eligible.
+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
 
 - You do not skip the semantic overlap check
-- You do not modify artefact type definitions — that is the user's choice
+- You do not modify artefact type definitions without the user's confirmation
 - You do not create appraisers with duplicate ids

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

@@ -8,34 +8,29 @@ description: Creates a new artefact type, checking for conflicts with existing t
 
 You help the user create a new artefact type. You ensure it avoids conflicts with existing types, scaffold the directory structure, and walk the user through defining laws and their optional validators.
 
-## Prerequisites
+## Foundry Agent Preflight
 
-Before running this skill, verify all three of the following:
+If you are clearly operating as the Foundry agent, continue.
 
-1. The `foundry/` directory exists in the project root. If it does not
-   exist, stop and tell the user:
+If you are not clearly operating as the Foundry agent, pause and tell the user:
 
-   > Foundry is not initialized in this project. Run the
-   > `init-foundry` skill first to create the foundry/ directory
-   > structure.
+> This work is best handled by the Foundry agent. Restart OpenCode if you have just initialised Foundry, switch to the **Foundry** agent, and continue this request there.
 
-2. The current git branch is a `config/*` branch. Run
-   `git rev-parse --abbrev-ref HEAD` and confirm it matches
-   `config/<description>`.
+This is an advisory guard. Continue only when the active instructions make it clear you are the Foundry agent or the user explicitly asks to proceed here.
 
-3. If the branch does not start with `config/`, instruct the user to
-   create one before continuing:
+## Config Branch Handling
 
-   > Foundry configuration changes must be made on a config/* branch.
-   > From a clean main branch, call:
-   >
-   > `foundry_git_branch({ kind: "config", description: "<short-name>" })`
-   >
-   > Then re-run this skill.
+Before writing Foundry configuration:
 
-   If the user is on a `dry-run/*/*` branch, they must finish
-   that dry-run first (`foundry_git_finish({ message, confirm: true })`)
-   before re-running this skill on the parent `config/*`.
+- Confirm `foundry/` exists. If it is missing, initialise Foundry first when that serves the user's goal.
+- Check the current branch.
+- On `main` or another clean non-work branch, create a `config/<short-description>` branch internally.
+- On `config/*`, continue on the current branch.
+- On `work/*`, stop and explain that active flow work must be finished before configuration changes.
+- On `dry-run/*/*`, stop and explain that the dry run must be finished before configuration changes.
+- If unrelated uncommitted changes could be affected by branching or writing files, ask before proceeding.
+
+Do not tell the user to call branch tools directly.
 
 ## Protocol
 
@@ -105,6 +100,8 @@ in the `## Definition` prose.
 
 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:
@@ -173,7 +170,7 @@ Call `foundry_config_create_artefact_type({ name: "<id>", body: "<full markdown>
 - writes `foundry/artefacts/<id>/definition.md`;
 - produces one git commit on the current `config/*` branch.
 
-If the tool returns `{ ok: false, errors }` because the target file already exists, the user should edit the file by hand on this `config/*` branch — `foundry_config_create_artefact_type` does not support updates.
+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.
 
 Show the user the resulting commit hash from the response.
 

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

@@ -8,34 +8,29 @@ description: Creates a new foundry cycle within a foundry flow, specifying the o
 
 You help the user create a new foundry cycle and add it to an existing foundry flow. A foundry cycle produces one artefact type (read-write), declares its input contract, targets the next cycle(s), and optionally enables human-appraise as a quality gate.
 
-## Prerequisites
+## Foundry Agent Preflight
 
-Before running this skill, verify all three of the following:
+If you are clearly operating as the Foundry agent, continue.
 
-1. The `foundry/` directory exists in the project root. If it does not
-   exist, stop and tell the user:
+If you are not clearly operating as the Foundry agent, pause and tell the user:
 
-   > Foundry is not initialized in this project. Run the
-   > `init-foundry` skill first to create the foundry/ directory
-   > structure.
+> This work is best handled by the Foundry agent. Restart OpenCode if you have just initialised Foundry, switch to the **Foundry** agent, and continue this request there.
 
-2. The current git branch is a `config/*` branch. Run
-   `git rev-parse --abbrev-ref HEAD` and confirm it matches
-   `config/<description>`.
+This is an advisory guard. Continue only when the active instructions make it clear you are the Foundry agent or the user explicitly asks to proceed here.
 
-3. If the branch does not start with `config/`, instruct the user to
-   create one before continuing:
+## Config Branch Handling
 
-   > Foundry configuration changes must be made on a config/* branch.
-   > From a clean main branch, call:
-   >
-   > `foundry_git_branch({ kind: "config", description: "<short-name>" })`
-   >
-   > Then re-run this skill.
+Before writing Foundry configuration:
 
-   If the user is on a `dry-run/*/*` branch, they must finish
-   that dry-run first (`foundry_git_finish({ message, confirm: true })`)
-   before re-running this skill on the parent `config/*`.
+- Confirm `foundry/` exists. If it is missing, initialise Foundry first when that serves the user's goal.
+- Check the current branch.
+- On `main` or another clean non-work branch, create a `config/<short-description>` branch internally.
+- On `config/*`, continue on the current branch.
+- On `work/*`, stop and explain that active flow work must be finished before configuration changes.
+- On `dry-run/*/*`, stop and explain that the dry run must be finished before configuration changes.
+- If unrelated uncommitted changes could be affected by branching or writing files, ask before proceeding.
+
+Do not tell the user to call branch tools directly.
 
 ## Protocol
 
@@ -43,7 +38,7 @@ Before running this skill, verify all three of the following:
 
 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.
 
-Verify the flow exists. If it doesn't, tell the user and ask if they want to create the foundry flow first (separate skill).
+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
 
@@ -64,7 +59,7 @@ If any of these are missing, ask.
 
 For each stage in the cycle (forge, quench, appraise), ask the user if they want to specify a model:
 
-> Each stage can optionally run on a specific model for model diversity. Available models are listed as `foundry-*` agent files in `.opencode/agents/`. Run the `list-agents` skill to see them.
+> 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: ___
@@ -73,15 +68,17 @@ For each stage in the cycle (forge, quench, appraise), ask the user if they want
 
 Only stages with an explicitly specified model are included in the `models` frontmatter map.
 
+If the user has no preference, omit the `models` map and use the session defaults.
+
 ### 4. Configure human appraise
 
 Ask the user:
 
-> Human-appraise has two independent knobs:
+> 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. If either is enabled, `deadlock-iterations` sets the deadlock threshold (default: 5).
+> 3. `deadlock-iterations` — the deadlock threshold (default: 5). Only applies when `deadlock-appraise` or `human-appraise` is enabled.
 >
 > - human-appraise: yes/no (default no)
 > - deadlock-appraise: yes/no (default yes)
@@ -89,9 +86,9 @@ Ask the user:
 
 ### 5. Validate artefact types
 
-For `output-type` and each entry in `inputs`:
-- Verify the artefact type exists in `foundry/artefacts/<type>/definition.md`
-- If it doesn't, tell the user and ask if they want to create it first (separate skill)
+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
 
@@ -175,7 +172,7 @@ Call `foundry_config_create_cycle({ name: "<id>", body: "<full markdown>" })`. T
 - writes `foundry/cycles/<id>.md`;
 - produces one git commit on the current `config/*` branch.
 
-If the tool returns `{ ok: false, errors }` because the target file already exists, the user should edit the file by hand on this `config/*` branch — `foundry_config_create_cycle` does not support updates.
+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.
 
 Show the user the resulting commit hash from the response.
 
@@ -183,12 +180,7 @@ Show the user the resulting commit hash from the response.
 
 `foundry_config_create_cycle` writes the cycle file only. The cycle still needs to appear in the parent flow's `## Cycles` list.
 
-Edit `foundry/flows/<flow-id>.md` by hand on this same `config/*` branch using the `Edit` tool. Add the new cycle id under `## Cycles` (if not already present). Commit that edit by hand as a separate microcommit, e.g.:
-
-```
-git add foundry/flows/<flow-id>.md
-git commit -m "config(flow): add <cycle-id> to <flow-id>"
-```
+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.
 
 ### 14. Confirm
 
@@ -198,5 +190,4 @@ Show the user the cycle file, the updated flow file, and both commit hashes.
 
 - 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 skip artefact type validation
-- You do not create artefact types — that is a separate skill
-- You do not create foundry flows — that is a separate skill
+- 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