@really-knows-ai/foundry 3.3.1 → 3.3.2

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

@@ -8,64 +8,75 @@ description: Create a new extractor definition under foundry/memory/extractors/.
 
 Use this skill to register a new extractor — a script that reads the codebase (via `tree-sitter`, `javap`, language servers, or whatever suits the project) and emits line-delimited JSON describing entities and edges to upsert into flow memory during an `assay` stage.
 
-## Prerequisites
+## Foundry Agent Preflight
 
-Before running this skill, verify all 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:
 
-   > Restart OpenCode to initialise Foundry, then retry this command.
+> 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/`, 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.
+## Config Branch Handling
 
-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.
+Before writing Foundry configuration:
 
-## Steps
+- 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.
 
-### 1. Gather inputs
+Do not tell the user to call branch tools directly.
 
-Ask the user for, in this order (one question at a time):
+`foundry/memory/config.md` must exist with `enabled: true`. Initialise memory internally first if not. Missing memory entity or edge type dependencies are composed internally when they are part of the user's stated goal.
+
+## Protocol
+
+### 1. Understand
+
+Ask the user for each field one question at a time, in this order:
 
 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, 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.
+4. **Timeout** (optional). Present as a choice:
+
+   > Set a timeout for this extractor?
+   > 1. 60 seconds (Recommended)
+   > 2. Custom duration (specify as `30s`, `2m`, or milliseconds)
 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.
 
 **Security note:** Remind the user that extractors inherit the agent's full environment, including any API tokens or credentials. Extractors should keep environment variable handling internal to extraction logic.
 
-### 2. Propose and confirm
+### 2. Plan
 
-Summarise the proposed extractor back to the user and ask for confirmation before writing. Example:
+Summarise the proposed extractor back to the user and invite refinement. Include the extractor name, command, memory write path, description, and timeout. Ask: "Does this capture the extractor correctly?" Example:
 
 > I'll create `foundry/memory/extractors/java-symbols.md` with:
 > - command: `scripts/extract-java-symbols.sh`
 > - memoryWrite: [class, method]
-> - timeout: 60s (default)
+> - timeout: 60s
 > - brief: "Walks the Java source tree with tree-sitter-java…"
 >
-> OK to proceed?
+> Does this capture the extractor correctly?
 
-### 3. Create the extractor file
+### 3. Confirm
 
-Call `foundry_extractor_create({ name, command, memoryWrite, body, timeout? })`. On error, surface the error to the user and stop — do not attempt to recover silently.
+Ask: "Proceed with this plan?" — wait for the user to answer. Do not proceed to Build unless the user says yes. If the user rejects the plan, return to the Understand phase and adjust.
 
-### 4. Offer to scaffold the command script
+### 4. Build
 
-If the user confirms, create the script file at the `command` path with an executable permission. Provide a starter stub that documents the JSONL contract and a minimal example. For example, for `scripts/extract-java-symbols.sh`:
+1. **Create**: Call `foundry_extractor_create({ name: "<name>", command: "<command>", memoryWrite: ["<type>", ...], body: "<description>", timeout: "<optional>" })`. On error, surface the error to the user and stop — do not attempt to recover silently.
+
+2. **Commit**: Run `git add foundry/memory/extractors/<name>.md` plus the command script path if one was created. Run `git commit -m "feat(memory): add '<name>' extractor"`. Report the commit hash.
+
+#### Post-Build — scaffold the command script
+
+When the user has confirmed, create the script file at the `command` path with executable permission. Provide a starter stub that documents the JSONL contract and a minimal example:
 
 ```bash
 #!/bin/sh
@@ -93,27 +104,12 @@ echo '{"kind":"entity","type":"class","name":"example.Foo","value":"Example clas
 
 Make the script executable (`chmod +x <path>`). Do **not** run the script — validation is the author's responsibility.
 
-### 5. Commit
+#### Post-Build — compose into a cycle
 
-Commit both the definition and (if created) the stub script:
+When the user's stated goal is to add memory extraction to a flow or cycle, compose this extractor into the relevant cycle definition. 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.
 
-```bash
-git add foundry/memory/extractors/<name>.md scripts/<command>
-git commit -m "feat(memory): add '<name>' extractor"
-```
-
-### 6. Compose into a cycle when the user's goal requires it
-
-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.
-
-## 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.
+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.
-
-## 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

@@ -38,47 +38,114 @@ Do not tell the user to call branch tools directly.
 
 Extract or ask for the flow purpose, expected final artefact, output location, and any quality constraints. Prefer practical defaults for common requests.
 
-### 2. Inventory existing configuration
+**Flow basics**: Gather the flow's own required fields:
+- `id` — lowercase, hyphenated identifier. Reject duplicate 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.
+- `name` — human-readable name
+- `description` — prose description of the flow purpose
 
-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.
+**What the flow produces**: Ask about the artefact type the flow should produce. Determine whether it needs a new artefact type or whether an existing one fits.
 
-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.
+**Quality constraints**: Ask about the laws that govern quality. For each law: what it checks, whether it applies globally or to a specific artefact type, and the deterministic-vs-subjective split.
 
-### 3. Design the dependency set
+**Appraisers**: Ask about the appraisers that evaluate quality. Determine how many are needed and whether existing appraisers fit or new ones are needed.
+
+**Cycles**: Ask about the cycles that process the artefact. Determine how many cycles there are and what each produces.
+
+**Starting cycles**: Identify which cycle IDs begin the flow.
+
+**Cycle graph validation**: After designing the 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.
+
+**Inventory**: 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.
+
+### 2. Gather requirements for each dependency
+
+For each dependency type in dependency order, ask questions to build a context object. This is the Understand phase for each sub-skill — the answers are captured and passed along when building.
 
 Create missing dependencies in validation order:
 
-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.
+1. **Artefact types** (no sub-dependencies): For each new artefact type, gather `id`, `name`, `filePatterns`, `description`, and whether it needs type-specific laws or appraiser configuration. Context object: `{id, name, filePatterns, description, appraisers?}`.
+
+2. **Laws** (may reference artefact types): For each new law, gather `id`, `name`, `description`, `passing`, `failing`, the target (global file or type-specific with `typeId`), and the deterministic-vs-subjective split. Determine whether validators are needed. Context object: `{id, name, description, passing, failing, target: {kind, file|typeId}, validators?}`.
+
+3. **Appraisers** (may reference models): For each new appraiser, gather `id`, `name`, `description`, and optional `model` preference. Context object: `{id, name, description, model?}`.
+
+4. **Cycles** (reference artefact types, laws, appraisers): For each new cycle, gather `id`, `name`, `outputType`, `description`, and any optional settings (inputs, targets, appraise, assay, memory, models). Context object: `{id, name, outputType, description, inputs?, targets?, humanAppraise?, deadlockAppraise?, deadlockIterations?, maxIterations?, assay?, memory?, models?}`.
 
 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.
 
-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.
+For each dependency, determine whether it already exists (user says "use the existing haiku artefact type") or needs to be created. If it already exists, capture its id for reference. If it needs creating, capture the context object fields.
+
+### 3. Present the combined plan
+
+Show the full dependency tree as a structured summary:
+
+```text
+Flow: <id> — <name>
+  Starting cycles: <cycle-id>, ...
+  Description: <description>
+  Artefact Types:
+    · <id> (<name>) — <filePatterns>
+  Laws:
+    · <id> — <description> [deterministic|subjective]
+      validators: <validator-id> (if deterministic)
+  Appraisers:
+    · <id> — <description>
+  Cycles:
+    · <id> → <outputType> — <description>
+```
+
+Ask "Proceed with this plan?" — do not build anything until the user confirms.
+
+If the user rejects the plan, return to the Understand phase and adjust.
+
+### 4. Build dependencies in order
+
+For each dependency, invoke the sub-skill's protocol with the captured context object. The context object for each sub-skill matches the args of the corresponding `foundry_config_create_*` tool, with fields populated from the Understand and Gather phases.
+
+Build order (dependency order):
+
+1. **Artefact types**: For each new artefact type, invoke the `add-artefact-type` protocol with the captured context. Example:
+
+   > Invoke the add-artefact-type protocol with context: `{id: "haiku", name: "Haiku", filePatterns: ["haikus/*.md"], description: "A traditional Japanese poem"}`.
+   > The add-artefact-type skill checks its Context object section. If all required fields are present, it proceeds directly to Build, skipping Understand, Plan, and Confirm. If only some fields are present, it asks only for the missing ones and proceeds to Build — it skips Plan and Confirm since the parent's combined plan already handled confirmation.
+
+2. **Laws**: For each new law, invoke the `add-law` protocol with the captured context. Example:
+
+   > Invoke the add-law protocol with context: `{id: "three-lines", name: "Three Lines", description: "must have exactly three lines", passing: "...", failing: "...", target: {kind: "type-specific", typeId: "haiku"}}`.
+   > If all required fields are present, the sub-skill proceeds directly to Build. Otherwise it asks only for the missing required fields, then proceeds to Build.
+
+3. **Appraisers**: For each new appraiser, invoke the `add-appraiser` protocol with the captured context.
+
+   > Invoke the add-appraiser protocol with context: `{id: "haiku-critic", name: "Haiku Critic", description: "Evaluates haiku structure and imagery"}`.
+   > If all required fields are present, proceed directly to Build. Otherwise ask for missing required fields only.
+
+4. **Cycles**: For each new cycle, invoke the `add-cycle` protocol with the captured context.
+
+   > Invoke the add-cycle protocol with context: `{id: "haiku-cycle", name: "Haiku Cycle", outputType: "haiku", description: "Generates haiku poems"}`.
+   > If all required fields are present, proceed directly to Build. Otherwise ask for missing required fields only.
+
+**Build-only mode**: When all required fields for a sub-skill are present in the context, the sub-skill skips Understand, Plan, and Confirm — proceeding directly to validate → create → commit. When only some required fields are present, the sub-skill enters its Understand phase to ask only for those missing required fields, then proceeds to Build (still skipping Plan and Confirm since the parent's combined plan already handled confirmation). Optional fields that are missing are silently skipped.
 
-### 4. Confirm ambiguous choices
+**Error handling during build**: If a sub-skill's Build phase fails (validation error or tool error), surface the error to the user:
 
-Ask only for choices that affect the user's goal or safety. Reuse compatible existing configuration when it clearly fits.
+> Build of `<piece>` failed: `<error>`. Retry, skip this piece, or abort?
 
-### 5. Validate and create each piece
+Do not silently skip or auto-resolve.
 
-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.
+### 5. Build the flow
 
-For the flow definition itself, use these structured fields:
+After all dependencies are built, create the flow itself:
 
-- `id` (string) — lowercase, hyphenated identifier
-- `name` (string) — human-readable name
-- `description` (string) — prose description of the flow purpose
-- `startingCycles` (string[]) — cycle IDs that begin the flow
+1. **Validate**: Call `foundry_config_validate_flow({ name: "<id>", body: "<assembled markdown>" })`. Assemble the body from the fields using the frontmatter format the tool produces internally. If the result is `{ ok: false, errors: [...] }`, address each error and re-run until `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types or cycles that do not exist yet.
 
-Call `foundry_config_create_flow({ id: "<id>", name: "<name>", startingCycles: ["<id>"], description: "<description>" })` to create the flow file.
+2. **Create**: Call `foundry_config_create_flow({ id: "<id>", name: "<name>", startingCycles: ["<cycle-id>", ...], description: "<description>" })`. The tool:
+   - re-validates the body (TOCTOU);
+   - writes `foundry/flows/<id>.md`;
+   - produces one git commit on the current `config/*` branch.
 
-### 6. Final summary
+   If the tool returns `{ ok: false, errors }` because the target file already exists, read the existing flow file, incorporate the user's requested changes into the current body, propose the merged result for review, then write and commit the updated file.
 
-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.
+3. **Report**: Show the user the flow file and the commit hash. Also summarise each dependency that was created, with its commit hash. Tell the user they can now ask the Foundry agent to run the flow.
 
 ## Safety Rules
 

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

@@ -34,32 +34,26 @@ Do not tell the user to call branch tools directly.
 
 ## Protocol
 
-### 1. Determine scope
+### Context object
 
-If the user specifies where the law applies:
-- "global law" → goes in `foundry/laws/` (ask which file, or create a new one)
-- "law for X artefacts" → goes in `foundry/artefacts/<type>/laws.md`
+When invoked with pre-filled fields matching the `foundry_config_add_law` tool args, skip questions for provided fields. Missing fields trigger clarifying questions.
 
-If the user doesn't specify, ask:
+Context fields (global): `{id, name, description, passing, failing, target: {kind: "global", file}, validators?}`
+Context fields (type-specific): `{id, name, description, passing, failing, target: {kind: "type-specific", typeId}, validators?}`
 
-> Should this law apply globally to all artefact types, or to a specific type?
+When invoked with a context:
+- If all required fields are present, skip the Understand phase and proceed to Plan → Confirm → Build.
+- If only some fields are present, ask only for the missing ones.
 
-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.
+### 1. Understand
 
-### 2. Draft the law
+**Scope**: Ask "Should this law apply globally to all artefact types, or to a specific type?" 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 using the `add-artefact-type` workflow internally.
 
-Write the law using these structured fields:
+If global, ask for the `file` (the filename under `foundry/laws/`, e.g. `rules.md`). If type-specific, ask for the `typeId`.
 
-- `id` (string) — lowercase, hyphenated law identifier, unique across all laws
-- `name` (string) — human-readable name
-- `description` (string) — one or two sentences describing what this law checks
-- `passing` (string) — description of what passing looks like
-- `failing` (string) — description of what failing looks like
-- `validators` (array, optional) — validator entries. Include only when a deterministic check can decide pass/fail. See **Validator contract** below for the exact shape a validator command must satisfy.
+**Fields**: Ask for `id`, `name`, `description`, `passing` criteria, and `failing` criteria one at a time.
 
-#### 2a. Identify deterministic vs subjective elements
-
-For each law, explicitly split what it checks into two categories:
+**Deterministic vs subjective split**: For each law, explicitly split what it checks into two categories:
 
 - **Deterministic** — can be checked by a script without human or LLM judgment. Examples: line count, syllable count, word minimum, forbidden patterns, file existence, formatting rules. These become `validators:` entries in the law.
 - **Subjective** — requires judgment. Examples: imagery quality, emotional resonance, persuasiveness, aesthetic appeal, clarity of argument. The appraisers evaluate these during the appraise stage. No validator entry needed; the law's prose alone guides the appraiser.
@@ -74,24 +68,9 @@ Walk the user through this split for each law:
 
 For each deterministic element, write a standalone `.mjs` script next to the artefacts it validates (e.g. `foundry/artefacts/<type>/check-line-count.mjs`) and reference it in the command (e.g. `node foundry/artefacts/<type>/check-line-count.mjs {files}`). Place validators alongside the artefacts so they colocate with what they validate. Prefer Node.js built-ins and libraries already in the project; hand-rolled heuristics are fragile — use available packages instead of writing custom validation logic from scratch.
 
-The `id` value should be:
-- Lowercase, hyphenated
-- Short but descriptive
-- Unique across all laws (global and type-specific)
-
-### 3. Check for conflicts
-
-Read all existing laws that would apply to the same artefact types:
-- All files in `foundry/laws/` (global)
-- `foundry/artefacts/<type>/laws.md` if the law is type-specific
-- If the law is global, also read all `foundry/artefacts/*/laws.md` since a global law applies everywhere
-
-For each existing law, check:
-- Does the new law contradict an existing law? (e.g., "must be formal" vs "must be conversational")
-- Does the new law duplicate an existing law? (same criterion, different wording)
-- Does the new law overlap with an existing law? (partially covers the same ground)
+**Validators**: Ask about `validators` (optional) — offer to create one or skip.
 
-If any conflict is found, present it to the user:
+**Conflict check**: Read all existing laws that would apply to the same artefact types. Check for contradiction, duplication, or overlap. If any conflict is found, present it to the user:
 
 > The new law `<new-id>` may conflict with existing law `<existing-id>`:
 > - New: <summary of new law>
@@ -104,66 +83,77 @@ If any conflict is found, present it to the user:
 > 3. Rephrase the new law to avoid the conflict
 > 4. Cancel
 
-### 4. Refine with the user
+### 2. Plan
 
-Present the drafted law to the user before writing it. Ask:
+Present a structured summary: law id, name, description, passing/failing criteria, target (global or type-specific with typeId), deterministic/subjective split, validators. Ask: "Does this capture what you want, or should we adjust the wording?" Iterate until the user is satisfied.
 
-> Here's the draft law:
->
-> ## <law-id>
->
-> <law content>
->
-> Does this capture what you want, or should we adjust the wording?
+### 3. Confirm
 
-Iterate until the user is happy.
+Ask: "Proceed with this plan?" — wait for user answer before building. If the user rejects the plan, return to the Understand phase and adjust.
 
-### 5. Validate the draft
+### 4. Build
 
-Call `foundry_config_validate_law({ name: "<id>", body: "<assembled markdown>" })`. Assemble the body from the fields using the `## <id>` heading format the tool produces internally.
+1. **Validate**: Call `foundry_config_validate_law({ name: "<id>", body: "<assembled markdown>" })`. Assemble the body from the fields using the `## <id>` heading format the tool produces internally. If the result is `{ ok: false, errors: [...] }`, address each error and re-run until `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types that do not exist yet.
 
-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 that don't exist yet.
+2. **Create**: Translate the scope into the `target` argument:
+   - Global → `target: { kind: "global", file: "<file-name>.md" }`
+   - Type-specific → `target: { kind: "type-specific", typeId: "<artefact-type>" }`
 
-### 6. Create the file
+   Call:
 
-Pick the target. The user has already chosen scope in step 1 — translate that into the `target` argument:
+   ```
+   foundry_config_add_law({
+     id: "<id>",
+     name: "<name>",
+     description: "<description>",
+     passing: "<passing>",
+     failing: "<failing>",
+     target: { kind: "global", file: "<file-name>.md" }
+              // or { kind: "type-specific", typeId: "<artefact-type>" }
+   })
+   ```
 
-- Global → `target: { kind: "global", file: "<file-name>.md" }` (lives at `foundry/laws/<file-name>.md`).
-- Type-specific → `target: { kind: "type-specific", typeId: "<artefact-type>" }` (lives at `foundry/artefacts/<typeId>/laws.md`).
+   The tool re-validates the body (TOCTOU), writes the law file at the path determined by `target`, and produces one git commit on the current `config/*` branch. Show the user the resulting commit hash.
 
-Then call:
+   The tool appends to an existing `laws.md` automatically when the new law id is not already present. It only errors when a law with the same id is already in the file — in that case use `foundry_config_edit_law({ id: "<law-id>", description: "<updated>", passing: "<updated>", failing: "<updated>" })` to modify the existing law in place.
 
-```
-foundry_config_add_law({
-  id: "<id>",
-  name: "<name>",
-  description: "<description>",
-  passing: "<passing>",
-  failing: "<failing>",
-  target: { kind: "global", file: "<file-name>.md" }   // OR
-           { kind: "type-specific", typeId: "<artefact-type>" }
-})
-```
+3. **Verify uniqueness**: 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.
 
-The tool:
+### 5. Editing existing laws (prose or validators)
 
-- re-validates the body (TOCTOU);
-- writes the law file at the path determined by `target`;
-- produces one git commit on the current `config/*` branch.
+When the user wants to modify an existing law — whether updating the prose description or adding/changing validators — use this flow:
 
-The tool appends to an existing `laws.md` automatically when the
-new law id is not already present. It only errors when
-a law with the same id is already in the file — in that case use
-`foundry_config_edit_law({ id: "<law-id>", description: "<updated>", passing: "<updated>", failing: "<updated>" })`
-to modify the existing law in place.
+#### 5a. Read the existing law
 
-Show the user the resulting commit hash from the response.
+Call `foundry_config_read_law({ id: "<law-id>" })` to fetch the full markdown content.
+
+#### 5b. Refine with the user
+
+Show the current content and ask what should change. Iterate on the updated markdown until the user is satisfied.
 
-### 7. Verify uniqueness
+#### 5c. Drift mitigation: Prose changes
 
-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.
+**If the user is modifying the law's prose description**, insert this prompt before updating:
+
+> 🔍 **Drift check:** Verify that all existing validators on this law still accurately enforce the updated intent. Open each validator's command and confirm it catches the same class of failure the prose now describes.
+
+Then proceed with the update.
+
+#### 5d. Drift mitigation: Validator changes
+
+**If the user is adding or modifying a validator**, insert this prompt before updating:
+
+> 🔍 **Drift check:** Verify that the changed validator still aligns with the law's prose. If the validator has narrowed or broadened, the prose may need a corresponding update.
+
+Then proceed with the update.
+
+#### 5e. Apply the update
+
+Call `foundry_config_edit_law({ id: "<law-id>", description: "<updated>", passing: "<updated>", failing: "<updated>", validators: [...] })` with the full updated fields.
+
+Validate the result. If the tool returns `{ ok: true }`, show the user the commit hash. If it returns `{ ok: false, errors }`, address each error and retry.
 
-### 7a. Validator contract
+### 6. Validator contract
 
 A law's `validators:` entries declare CLI commands that `quench` runs
 during a cycle. The plugin parses each command's stdout as **JSONL**
@@ -268,40 +258,6 @@ validators:
     failure-means: The artefact file does not contain exactly three non-empty lines.
 ~~~
 
-### 8. Editing existing laws (prose or validators)
-
-When the user wants to modify an existing law — whether updating the prose description or adding/changing validators — use this flow:
-
-#### 8a. Read the existing law
-
-Call `foundry_config_read_law({ id: "<law-id>" })` to fetch the full markdown content.
-
-#### 8b. Refine with the user
-
-Show the current content and ask what should change. Iterate on the updated markdown until the user is satisfied.
-
-#### 8c. Drift mitigation: Prose changes
-
-**If the user is modifying the law's prose description**, insert this prompt before updating:
-
-> 🔍 **Drift check:** Verify that all existing validators on this law still accurately enforce the updated intent. Open each validator's command and confirm it catches the same class of failure the prose now describes.
-
-Then proceed with the update.
-
-#### 8d. Drift mitigation: Validator changes
-
-**If the user is adding or modifying a validator**, insert this prompt before updating:
-
-> 🔍 **Drift check:** Verify that the changed validator still aligns with the law's prose. If the validator has narrowed or broadened, the prose may need a corresponding update.
-
-Then proceed with the update.
-
-#### 8e. Apply the update
-
-Call `foundry_config_edit_law({ id: "<law-id>", description: "<updated>", passing: "<updated>", failing: "<updated>", validators: [...] })` with the full updated fields.
-
-Validate the result. If the tool returns `{ ok: true }`, show the user the commit hash. If it returns `{ ok: false, errors }`, address each error and retry.
-
 ## What you do NOT do
 
 - You do not skip the conflict check

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

@@ -6,39 +6,68 @@ description: Create a new edge type between entity types in flow memory
 
 # Add Memory Edge Type
 
-## Prerequisites
+## Foundry Agent Preflight
 
-Before running this skill, verify all 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:
 
-   > Restart OpenCode to initialise Foundry, then retry this command.
+> 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/`, 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.
+## Config Branch Handling
 
-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).
+Before writing Foundry configuration:
 
-## Steps
+- 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.
 
-1. **Ask the user for**: edge name (snake_case), `sources` (list of entity types or `any`), `targets` (list of entity types or `any`), and a prose body describing what the edge represents.
-2. **Push back on narrow wording**. A good edge description describes WHEN the edge holds and what it does NOT cover (boundary with related edges).
-3. **Invoke `foundry_memory_create_edge_type`** with `{ name, sources, targets, body }`.
-4. **Commit**:
+Do not tell the user to call branch tools directly.
 
-   ```bash
-   git add foundry/memory/edges/<name>.md foundry/memory/schema.json
-   git commit -m "feat(memory): add edge type <name>"
-   ```
+Memory must be initialised (`foundry/memory/` must exist). Initialise memory internally first if not. Entity types referenced in `sources` and `targets` must already exist — create or compose them internally when they are part of the user's stated goal, or ask one focused question when schema design is ambiguous.
+
+## Protocol
+
+### Context object
+
+When invoked with pre-filled fields matching the `foundry_memory_create_edge_type` tool args, skip questions for provided fields. Missing fields trigger clarifying questions.
+
+Context fields: `{name, sources, targets, body}`
+
+When invoked with a context:
+- If all required fields are present, skip the Understand phase and proceed to Plan → Confirm → Build.
+- If only some fields are present, ask only for the missing ones.
+
+### 1. Understand
+
+Ask for each field one question at a time:
+
+1. **Edge name.** Lowercase snake_case.
+2. **Sources.** The entity types this edge originates from. List existing entity types from `foundry/memory/entities/` as multiple-choice options. Allow `any`.
+3. **Targets.** The entity types this edge points to. List existing entity types as multiple-choice options. Allow `any`.
+4. **Prose body.** A description of what this edge represents. Push back on narrow wording — a good edge description describes when the edge holds and what it does not cover (boundary with related edges). Suggest a clearer alternative when the user provides vague wording and ask before proceeding.
+
+### 2. Plan
+
+Present the edge type definition: name, sources, targets, body. Ask: "Does this capture the edge type correctly?" Iterate until the user is satisfied.
+
+### 3. Confirm
+
+Ask: "Proceed with this plan?" — wait for user answer before building. If the user rejects the plan, return to the Understand phase and adjust.
+
+### 4. Build
+
+1. **Validate**: Call `foundry_memory_validate`. If the result is `{ ok: false, errors: [...] }`, address each error and re-run until `{ ok: true }`.
+2. **Create**: Call `foundry_memory_create_edge_type({ name: "<name>", sources: ["<type>", ...], targets: ["<type>", ...], body: "<body>" })`.
+3. **Commit**: Run `git add foundry/memory/edges/<name>.md foundry/memory/schema.json`. Run `git commit -m "feat(memory): add edge type <name>"`. Report the commit hash.
+
+## What you do NOT do
+
+- You do not delegate memory initialisation to the user — initialise internally when needed
+- You do not create edge types with sources or targets that don't exist — compose them internally when they serve the user's stated goal