@really-knows-ai/foundry 3.0.2 → 3.2.0

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

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

@@ -15,32 +15,23 @@ Before running this skill, verify all of the following:
 1. The `foundry/` directory exists in the project root. If it does not
    exist, stop and tell the user:
 
-   > Foundry is not initialized in this project. Run the
-   > `init-foundry` skill first to create the foundry/ directory
-   > structure.
+   > Restart OpenCode to initialise Foundry, then retry this command.
 
 2. The current git branch is a `config/*` branch. Run
    `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:
+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.
 
-   > 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).
+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 +41,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 +102,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.

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

@@ -8,34 +8,29 @@ description: Creates a new law, checking for conflicts with existing laws.
 
 You help the user create a new law. You ensure it's well-scoped, doesn't conflict with existing laws, and ends up in the right 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
 
@@ -49,7 +44,7 @@ If the user doesn't specify, ask:
 
 > Should this law apply globally to all artefact types, or to a specific type?
 
-If they name a type, verify it exists in `foundry/artefacts/`. If it doesn't, tell them and ask if they want to create the artefact type first.
+If the user names a type-specific law for an artefact type that does not exist, create the artefact type first when that supports the user's stated goal. Use the `add-artefact-type` workflow internally, and ask for the file pattern only when it cannot be inferred safely.
 
 ### 2. Draft the law
 
@@ -154,7 +149,7 @@ Show the user the resulting commit hash from the response.
 
 ### 7. Verify uniqueness
 
-After the file is created, confirm the law id is unique across all law files. If a collision exists, ask the user to rename and edit by hand on this branch.
+After the file is created, confirm the law id is unique across all law files. If a collision exists, read the colliding law, present the conflict to the user, propose a rename or merge, ask one focused question about the user's preference, then write and commit the resolution.
 
 ### 7a. Validator contract
 
@@ -299,4 +294,4 @@ Validate the result. If the tool returns `{ ok: true }`, show the user the commi
 
 - You do not skip the conflict check
 - You do not silently overwrite existing laws
-- You do not create artefact types — that is a separate skill
+- You do not create artefact types unless the user's stated goal clearly requires it; ask one focused question when multiple designs are plausible

package/dist/skills/add-memory-edge-type/SKILL.md

@@ -13,31 +13,23 @@ Before running this skill, verify all of the following:
 1. The `foundry/` directory exists in the project root. If it does not
    exist, stop and tell the user:
 
-   > Foundry is not initialized in this project. Run the
-   > `init-foundry` skill first to create the foundry/ directory
-   > structure.
+   > Restart OpenCode to initialise Foundry, then retry this command.
 
 2. The current git branch is a `config/*` branch. Run
    `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. Memory is initialised (`foundry/memory/` exists; run `init-memory`
-   if not). Entity types referenced in `sources` and `targets` must
-   already exist (or be added first).
+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. Memory is initialised (`foundry/memory/` exists; initialise memory
+   internally first if not). Entity types referenced in `sources` and
+   `targets` must already exist (or be created or composed internally
+   when they are part of the user's stated goal).
 
 ## Steps
 

package/dist/skills/add-memory-entity-type/SKILL.md

@@ -16,30 +16,21 @@ Before running this skill, verify all of the following:
 1. The `foundry/` directory exists in the project root. If it does not
    exist, stop and tell the user:
 
-   > Foundry is not initialized in this project. Run the
-   > `init-foundry` skill first to create the foundry/ directory
-   > structure.
+   > Restart OpenCode to initialise Foundry, then retry this command.
 
 2. The current git branch is a `config/*` branch. Run
    `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:
+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.
 
-   > 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. Memory is initialised (`foundry/memory/` exists; run `init-memory`
-   if not).
+4. Memory is initialised (`foundry/memory/` exists; initialise memory
+   internally first if not).
 
 ## Steps
 
@@ -71,4 +62,4 @@ Before running this skill, verify all of the following:
    git commit -m "feat(memory): add entity type <name>"
    ```
 
-6. **Guidance to the user**: suggest they also add relevant edge types using `add-memory-edge-type`.
+6. **Dependency composition**: if related edge types would serve the user's stated goal, compose them internally with one focused question for ambiguity.