@really-knows-ai/foundry 3.0.1 → 3.1.0

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,44 +8,41 @@ 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
 
 ### 1. Gather basics
 
 From the user's prompt, establish:
-- `id` — lowercase, hyphenated identifier
-- `name` — human-readable name
-- `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
+- `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.
 
 If any of these are missing, ask.
 
@@ -87,7 +84,7 @@ Present the definition to the user:
 
 ```markdown
 ---
-name: <name>
+name: <id>
 file-patterns:
   - "<pattern>"
 ---
@@ -97,8 +94,14 @@ file-patterns:
 <description>
 ```
 
+The `name:` value must exactly match the artefact type's `id`
+(lowercase, hyphenated). If you want a human-readable label, put it
+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:
@@ -110,22 +113,18 @@ If yes, walk through each law using the same format as `add-law`:
 - Check for conflicts with global laws and any existing type-specific laws
 - Confirm with the user
 
-Each law may declare an optional `validators:` block. Include validators only when a deterministic check is needed. The format matches `add-law`:
-
-```markdown
-## <law-id>
-
-<What this law checks — one or two sentences.>
-
-validators:
-  - id: validator-id
-    command: ./script.sh
-    failure-means: (optional description)
-```
-
-The `validators` block is optional. When present, `quench` runs each validator for this law. Validator scripts live within the artefact type directory (e.g., `foundry/artefacts/<type>/check-foo.mjs`).
+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.
+**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
@@ -171,13 +170,18 @@ 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.
 
 ### 9. Add laws file (if defined)
 
-The create tool writes only `definition.md`. If you drafted any type-specific laws in step 5, append them to `foundry/artefacts/<id>/laws.md` by hand on this same `config/*` branch (use the `Edit` tool to create the file) and commit that as a separate microcommit.
+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.
 
 ### 10. Confirm
 

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

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

@@ -23,24 +23,17 @@ Before running this skill, verify all of the following:
    `git rev-parse --abbrev-ref HEAD` and confirm it matches
    `config/<description>`.
 
-3. If the branch does not start with `config/`, instruct the user to
-   create one before continuing:
-
-   > 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.
-
-   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/*`.
-
-4. `foundry/memory/config.md` exists and has `enabled: true` (run
-   `init-memory` first if not). Every entity type the extractor will
-   populate must already be declared in `foundry/memory/entities/`
-   (use `add-memory-entity-type` to create any that are missing).
+3. If the branch does not start with `config/`, move to a suitable
+   `config/*` branch internally when the current branch is safe. If
+   the current branch is `work/*` or `dry-run/*/*`, stop and explain
+   the active work must be finished first. When unrelated uncommitted
+   changes could be affected by branching or writing files, ask before
+   proceeding.
+
+4. `foundry/memory/config.md` exists and has `enabled: true` (initialise
+   memory internally first if not). Missing memory entity or edge type
+   dependencies are created or composed internally when they are part of
+   the user's stated goal.
 
 ## Steps
 
@@ -50,7 +43,7 @@ Ask the user for, in this order (one question at a time):
 
 1. **Extractor name.** Lowercase kebab-case (`java-symbols`, `python-classes`, `tree-sitter-rust`). This becomes the filename under `foundry/memory/extractors/<name>.md` and the identifier referenced from cycle frontmatter.
 2. **Command.** The path to the executable (relative to the repo root, e.g. `scripts/extract-java-symbols.sh`) or a short shell command. This is passed to `/bin/sh -c` at runtime.
-3. **Entity types to populate (`memoryWrite`).** A list of entity type names already declared in this project's memory vocabulary. Validate against what exists; if the user names a type that doesn't exist, either offer to create it via `add-memory-entity-type` first or ask them to adjust.
+3. **Entity types to populate (`memoryWrite`).** A list of entity type names already declared in this project's memory vocabulary. Validate against what exists; if the user names a type that doesn't exist, compose or create it internally when it is part of the user's stated goal, or ask one focused question when schema design is ambiguous.
 4. **Timeout** (optional). Duration string like `30s`, `2m`, or a number of milliseconds. Defaults to 60 seconds if omitted.
 5. **Brief description.** 1–3 paragraphs of prose describing what this extractor extracts, what it requires on `PATH`, and any re-run triggers. This body is injected into the forge prompt of every cycle that uses this extractor, so clarity here translates to better downstream generation.
 
@@ -111,23 +104,18 @@ git add foundry/memory/extractors/<name>.md scripts/<command>
 git commit -m "feat(memory): add '<name>' extractor"
 ```
 
-### 6. Guide the user on wiring it in
+### 6. Compose into a cycle when the user's goal requires it
 
-After creation, tell the user how to opt a cycle into this extractor:
+When the user's stated goal is to add memory extraction to a flow or cycle, compose this extractor into the relevant cycle definition. See **Composing cycle definitions** below.
 
-> To use this extractor, add the following to the cycle's frontmatter:
->
-> ```yaml
-> memory:
->   write: [<each type in memoryWrite>]   # must include every type the extractor writes
-> assay:
->   extractors: [<this extractor's name>]
-> ```
->
-> Then run the `flow` or `orchestrate` skill. On the first iteration of the cycle, the assay stage will execute this extractor before forge.
+## Dependency composition
+
+Missing memory entity or edge type dependencies are **composed internally** when they are part of the user's stated goal. Compose into the appropriate memory vocabulary when schema design is ambiguous — ask one focused question rather than stalling.
 
 ## What this skill must not do
 
 - **Must not** run the extractor script itself to verify it works. That is the author's job.
-- **Must not** modify cycle definitions. Opting a cycle into the extractor is an explicit editorial step for the user to take.
-- **Must not** create entity or edge types that don't already exist. Compose into `add-memory-entity-type` / `add-memory-edge-type` for any missing vocabulary.
+
+## Composing cycle definitions
+
+When the user's stated goal includes opting an existing cycle into this extractor, update the cycle definition internally to add the `extractors` and `memoryWrite` fields. Ask for confirmation or one focused question when cycle selection or wiring is ambiguous.

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

@@ -6,119 +6,74 @@ description: Creates a new foundry flow definition.
 
 # Add Flow
 
-You help the user create a new foundry flow. A foundry flow is a set of foundry cycles with declared starting points — cycles own their own routing via targets and input contracts.
+You help the user create a complete Foundry flow for their stated outcome. A flow may require artefact types, laws, validators, appraisers, and cycles before the flow file itself can validate. Work backwards from the requested outcome and create missing dependencies in validation order.
 
-## 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.
 
-## Protocol
-
-### 1. Gather basics
-
-From the user's prompt, establish:
-- `id` — lowercase, hyphenated identifier
-- `name` — human-readable name
-- A prose description of what this foundry flow achieves end-to-end
-
-If any of these are missing, ask.
-
-### 2. Check for id conflicts
-
-Read all existing flow definitions in `foundry/flows/*.md`.
-
-- Exact id match → hard conflict, must choose a different id
-- Semantically similar name or description → warn and ask if the new foundry flow is genuinely distinct
-
-### 3. Determine foundry cycles and starting cycles
-
-Ask the user which foundry cycles this flow includes. List available cycles from `foundry/cycles/*.md` for reference.
+Do not tell the user to call branch tools directly.
 
-Then ask: which of these are **starting cycles** — the cycles that can be entered first when the flow begins?
-
-- Starting cycles typically have no input dependencies
-- Multiple starting cycles are fine — the user (or context) determines which one to run first
-
-### 4. Validate cycle graph
-
-For each non-starting cycle, verify it is reachable:
-- At least one other cycle in the flow has it as a target
-- Its input contract can be satisfied by cycles in the flow
-
-If a cycle is unreachable (no cycle targets it and it's not a starting cycle), warn:
-
-> Cycle `<id>` is not a starting cycle and no other cycle targets it. It will never be reached in this flow.
-
-### 5. Draft the definition
+## Protocol
 
-Present the flow definition to the user:
+### 1. Understand the outcome
 
-```markdown
----
-id: <id>
-name: <name>
-starting-cycles:
-  - <cycle-id>
----
+Extract or ask for the flow purpose, expected final artefact, output location, and any quality constraints. Prefer practical defaults for common requests.
 
-# <Name>
+### 2. Inventory existing configuration
 
-<description>
+Read existing flows in `foundry/flows/*.md`, cycles in `foundry/cycles/*.md`, artefact types in `foundry/artefacts/*/definition.md`, laws in `foundry/laws/*.md`, and appraisers in `foundry/appraisers/*.md`. Identify reusable pieces and conflicts.
 
-## Cycles
+Reject duplicate flow IDs — if a flow with the same ID already exists, choose a different ID. Warn about semantic duplicates (different ID but near-identical purpose) and ask whether the new flow is genuinely distinct.
 
-- <cycle-id>
-- <cycle-id>
-```
+### 3. Design the dependency set
 
-The `starting-cycles` field lists entry points. `## Cycles` lists all cycles in the flow (no ordering implied — routing is owned by individual cycle definitions via their `targets` field).
+Create missing dependencies in validation order:
 
-Ask: does this capture the flow correctly?
+1. Artefact type and file patterns.
+2. Type-specific laws.
+3. Deterministic validators attached to laws.
+4. Appraisers or appraiser selection.
+5. Cycles that produce the artefact types.
+6. Flow tying starting cycles and cycle list together.
 
-### 6. Validate the draft
+For the haiku example, default to a `haiku` artefact type, `haikus/*.md` file pattern, laws for form, imagery, and mood, a deterministic syllable validator where project dependencies allow it, two or three distinct appraisers, one cycle, and one flow.
 
-Call `foundry_config_validate_flow({ name: "<id>", body: "<full markdown>" })`.
+After designing cycles, validate the cycle graph: verify each non-starting cycle is reachable from a starting cycle through the `targets` graph, and verify each cycle's input contracts can be satisfied by other cycles in the flow. Warn about unreachable cycles or unsatisfiable contracts before proceeding.
 
-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.
+### 4. Confirm ambiguous choices
 
-### 7. Create the file
+Ask only for choices that affect the user's goal or safety. Reuse compatible existing configuration when it clearly fits.
 
-Call `foundry_config_create_flow({ name: "<id>", body: "<full markdown>" })`. The tool:
+### 5. Validate and create each piece
 
-- re-validates the body (TOCTOU);
-- writes `foundry/flows/<id>.md`;
-- produces one git commit on the current `config/*` branch.
+For each definition, use the `foundry_config_validate_*` tool family to validate it first. Resolve any validation errors, then use the corresponding `foundry_config_create_*` tool to create it. Summarise each created file and commit hash in Foundry terms.
 
-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_flow` does not support updates.
+### 6. Final summary
 
-Show the user the resulting commit hash from the response.
+Report the flow, starting cycles, artefact type, laws, validators, appraisers, and files created. Tell the user they can now ask the Foundry agent to run the flow.
 
-## What you do NOT do
+## Safety Rules
 
-- You do not create foundry cycles — that is a separate skill
-- You do not skip dependency validation
+- Do not create overlapping artefact file patterns.
+- Do not skip dependency validation.
+- Do not expose internal tool-call syntax to the user.
+- Do not continue when a branch or worktree state could overwrite user changes.