@really-knows-ai/foundry 3.0.1 → 3.1.0

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
 
@@ -71,7 +66,9 @@ The `law-id` (heading) should be:
 - Short but descriptive
 - Unique across all laws (global and type-specific)
 
-The `validators:` block is optional. Include it only if you want to add validation commands for this law.
+The `validators:` block is optional. Include it only when a
+deterministic check can decide pass/fail. See **Validator contract**
+below for the exact shape a validator command must satisfy.
 
 ### 3. Check for conflicts
 
@@ -142,13 +139,122 @@ The tool:
 - writes the law file at the path determined by `target`;
 - produces one git commit on the current `config/*` branch.
 
-If the tool returns `{ ok: false, errors }` because the target file already exists, use `foundry_config_edit_law({ id: "<law-id>", body: "<updated-body>" })` to modify the law.
+The tool appends to an existing `laws.md` automatically when the
+new `## <law-id>` heading 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>", body: "<updated-body>" })`
+to modify the existing law in place.
 
 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
+
+A law's `validators:` entries declare CLI commands that `quench` runs
+during a cycle. The plugin parses each command's stdout as **JSONL**
+(one JSON object per line). Authors must follow this contract exactly;
+nothing in plugin source needs to be read.
+
+#### Output format (stdout, parsed as JSONL)
+
+One JSON object per line. Empty lines are ignored. Required fields:
+
+- `file` *(string)* — path of the offending file, relative to the
+  worktree root. Must match at least one of the artefact type's
+  `file-patterns:`; otherwise the line becomes a validator-level
+  error, not feedback.
+- `text` *(string)* — the feedback message.
+
+Optional fields:
+
+- `location` *(string, e.g. `"3:1"`)* — line:column reference,
+  prepended to `text` as `file:location — text`.
+- `severity` *(string, e.g. `"error"` or `"warning"`)* — prepended to
+  `text` as `[severity] file:location — text` (or `[severity] file —
+  text` when no `location`).
+
+Anything else on the line is preserved verbatim on the parsed item.
+The validator's exit code is **ignored** — the parser reads stdout
+either way, and falls back to stderr when stdout is empty (so tools
+like `rg` that exit non-zero on hits still work).
+
+#### Command placeholders
+
+Inside `command:`, two placeholders may appear, alone, together, or
+not at all. They are recognised only as standalone tokens (bounded by
+whitespace or string start/end). Authors may wrap a placeholder in
+single or double quotes for readability — surrounding quotes are
+stripped before substitution.
+
+- `{pattern}` → the artefact type's `file-patterns:` rendered as
+  space-separated, shell-quoted globs (e.g.
+  `'haikus/*.md' 'drafts/*.md'`). Use this when the validator does
+  its own globbing or accepts globs directly (e.g. `rg --glob`).
+- `{files}` → the matching files in the worktree, rendered as
+  space-separated, shell-quoted paths (e.g.
+  `'haikus/one.md' 'haikus/two.md'`). Use this when the validator
+  takes an explicit list of file paths.
+
+A command with neither placeholder runs verbatim — useful for
+self-resolving validators such as `npm test`, `tsc --noEmit`, or
+`pnpm run lint`.
+
+#### Skip rule
+
+A validator is skipped iff its command contains `{files}` and there
+are no matching files in the worktree. Commands using `{pattern}` only,
+or no placeholders at all, always run.
+
+#### Working directory
+
+Validators run with `cwd` set to the worktree root, so root-level
+`node_modules/`, `package.json`, and project tooling all resolve
+normally. Do not assume the validator runs from inside the artefact
+type's directory.
+
+#### Worked example
+
+A validator that checks each `.md` file in `haikus/` has exactly three
+non-empty lines, attached to a haiku artefact type
+(`file-patterns: ["haikus/*.md"]`):
+
+`foundry/artefacts/haiku/check-line-count.mjs`:
+
+~~~js
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+
+for (const file of process.argv.slice(2)) {
+  const content = await readFile(file, 'utf8');
+  const lines = content
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+  if (lines.length !== 3) {
+    process.stdout.write(JSON.stringify({
+      file,
+      text: `Expected 3 non-empty lines, got ${lines.length}.`,
+      severity: 'error',
+    }) + '\n');
+  }
+}
+~~~
+
+Declared in the law:
+
+~~~markdown
+## three-lines
+
+A haiku must consist of exactly three non-empty lines.
+
+validators:
+  - id: line-count
+    command: node foundry/artefacts/haiku/check-line-count.mjs {files}
+    failure-means: The artefact file does not contain exactly three non-empty lines.
+~~~
 
 ### 8. Editing existing laws (prose or validators)
 
@@ -188,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

@@ -21,23 +21,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. 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

@@ -24,22 +24,15 @@ 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:
+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 +64,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.

package/dist/skills/change-embedding-model/SKILL.md

@@ -28,15 +28,13 @@ Before running this skill, verify all of the following:
    create one before continuing:
 
    > Foundry configuration changes must be made on a config/* branch.
-   > From a clean main branch, call:
+   > If configuration changes are needed, 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.
    >
-   > `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/*`.
+   > After the prerequisite is handled, continue the user's original
+   > request from the current context.
 
 4. Memory is initialised and enabled. The new provider is reachable
    from this machine. Allow enough time and bandwidth to re-embed

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

@@ -27,15 +27,13 @@ Before running this skill, verify all of the following:
    create one before continuing:
 
    > Foundry configuration changes must be made on a config/* branch.
-   > From a clean main branch, call:
+   > If configuration changes are needed, 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.
    >
-   > `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/*`.
+   > After the prerequisite is handled, continue the user's original
+   > request from the current context.
 
 4. Memory is initialised (`foundry/memory/` exists; run `init-memory`
    if not).

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

@@ -28,15 +28,13 @@ Before running this skill, verify all of the following:
    create one before continuing:
 
    > Foundry configuration changes must be made on a config/* branch.
-   > From a clean main branch, call:
+   > If configuration changes are needed, 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.
    >
-   > `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/*`.
+   > After the prerequisite is handled, continue the user's original
+   > request from the current context.
 
 4. Memory is initialised (`foundry/memory/` exists; run `init-memory`
    if not).

package/dist/skills/dry-run/SKILL.md

@@ -22,24 +22,18 @@ files or memory rows behind on `config/<x>`.
 2. Working tree is clean.
 3. The flow id and a one-line description of the goal are known.
 
-If on `main`, edit on a `config/<x>` branch first:
-`foundry_git_branch({ kind: "config", description: "<short-name>" })`.
+If on `main`, edit on a `config/<x>` branch first. If configuration
+changes are needed, 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.
 
 ## Protocol
 
 ### 1. Branch into dry-run mode
 
-```text
-foundry_git_branch({
-  kind: "dry-run",
-  flowId: "<flow-id>",
-  description: "<dry-run-purpose-slug>"
-})
-```
-
-This creates `dry-run/<x>/<flow>-<purpose>` and truncates the trace
-file. From here every `foundry_*` tool call is logged to
-`.foundry/trace/<branch-slug>.jsonl`.
+The assistant creates a `dry-run/<x>/<flow>-<purpose>` branch and
+truncates the trace file. From here every internal tool call is logged
+to `.foundry/trace/<branch-slug>.jsonl`.
 
 ### 2. Run the flow
 
@@ -57,12 +51,8 @@ they appear in the trace.
 
 ### 4. Finish: snapshot + discard
 
-```text
-foundry_git_finish({
-  message: "<one-paragraph findings>",
-  confirm: true
-})
-```
+Finish the dry-run with a one-paragraph findings message and explicit
+confirmation.
 
 The tool:
 
@@ -92,15 +82,8 @@ dry-run mode for another run. Snapshots accumulate; prune them with
 
 ### 6. Finish the config
 
-When ready, finish `config/<x>` to `main`:
-
-```text
-foundry_git_finish({
-  message: "<config description>",
-  baseBranch: "main",
-  confirm: true
-})
-```
+When ready, finish `config/<x>` to `main` with a config description and
+explicit confirmation.
 
 Snapshots are gitignored and stay in the local working tree; they do
 not merge with the config.

package/dist/skills/flow/SKILL.md

@@ -20,7 +20,7 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 ## Starting a flow
 
 1. Call `foundry_config_flow` with the flow ID — get the flow definition
-2. Call `foundry_git_branch` with `kind: "work"`, the flow ID, and a short description — create the work branch (e.g. `foundry_git_branch({ kind: "work", flowId, description })`)
+2. Create a work branch for the flow using the flow ID and a short description
 3. Determine the starting cycle:
    - Any cycle listed in the flow can be the starting cycle. The flow's `starting-cycles` list is a hint for when the user's request is ambiguous.
    - Map the user's goal to a cycle by matching the requested output (e.g. "write a short story from the tennis haiku" → `create-short-story`; "write a haiku" → `create-haiku`).

package/dist/skills/init-foundry/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: init-foundry
 type: atomic
-description: Initialize a Foundry project by creating the foundry/ directory structure
+description: Initialise a Foundry project by creating the foundry/ directory structure
 ---
 
-# Initialize Foundry
+# Initialise Foundry
 
 Set up the `foundry/` directory structure in the current project.
 
@@ -31,46 +31,66 @@ Set up the `foundry/` directory structure in the current project.
 
 3. **Update `.gitignore`**
 
-   Append `.snapshots/` to the project's `.gitignore` (creating the file if absent). This directory is where dry-run snapshots are written and must never be committed.
+   Append the following lines to the project's `.gitignore` (creating
+   the file if absent), skipping any that are already present:
 
-   The plugin will idempotently append `.foundry/` itself on first boot, so you do not need to add that line.
+   ```
+   .snapshots/
+   node_modules/
+   .DS_Store
+   ```
+
+   - `.snapshots/` keeps dry-run snapshots out of git.
+   - `node_modules/` keeps any npm dependencies (e.g. validator
+     packages) out of git. Without it, foundry's `config/*` tools
+     reject calls with `unexpected_files` as soon as the user runs
+     `npm install`.
+   - `.DS_Store` keeps macOS metadata out of git.
+
+   The plugin will idempotently append `.foundry/` itself on first
+   boot, so you do not need to add that line.
 
-4. **Generate foundry agent files**
+4. **Generate model-routing agent files**
 
-   Run the `refresh-agents` skill to generate `.opencode/agents/foundry-*.md` files for multi-model routing.
+   Call `foundry_refresh_agents()` to generate model-routing `.opencode/agents/foundry-*.md` files.
 
-5. **Commit the structure**
+5. **Install the Foundry guide agent**
+
+   Create `.opencode/agents/foundry.md` from the packaged Foundry guide
+   agent template. Copy whichever template path exists: prefer
+   `dist/agents/foundry.md` when running from the built package, then
+   fall back to `src/agents/foundry.md` when running from a source
+   checkout. This user-facing agent is installed during `init-foundry`;
+   `foundry_refresh_agents()` manages only generated `foundry-*` stage
+   agents.
+
+6. **Commit the structure**
 
    ```bash
-   git add foundry/ .gitignore .opencode/agents/foundry-*.md
-   git commit -m "feat: initialize Foundry project structure"
+   git add foundry/ .gitignore .opencode/agents/foundry.md .opencode/agents/foundry-*.md
+   git commit -m "feat: initialise Foundry project structure"
    ```
 
-6. **Guide next steps**
+7. **Guide next steps**
 
    Tell the user:
 
-   > Foundry is initialized. **Restart OpenCode** for the new foundry agents to take effect.
+   > Foundry is initialised. **Restart OpenCode** so the new Foundry agents register.
    >
-   > The first time the plugin boots in this project, it will create the
-   > `.foundry/` runtime directory (which holds the per-worktree HMAC key) and
-   > idempotently append `.foundry/` to your `.gitignore` so the secret never
-   > gets committed. The `.snapshots/` line was added by this skill to keep
-   > dry-run snapshots out of git.
+   > After the restart, switch to the **Foundry** agent. The Foundry agent is the user-facing guide for setting up artefact types, laws, validators, appraisers, cycles, and flows.
    >
-   > Here's how to set up your first pipeline:
+   > Then ask the Foundry agent for the outcome you want, for example:
    >
-   > 1. **Define an artefact type** — use the `add-artefact-type` skill
-   > 2. **Add laws** — use the `add-law` skill to define quality criteria
-   > 3. **Create appraiser personalities** — use the `add-appraiser` skill
-   > 4. **Define a cycle** — use the `add-cycle` skill
-   > 5. **Create a flow** — use the `add-flow` skill
+   > `set up a flow that writes haikus`
    >
-   > Then run your flow with the `flow` skill.
+   > The first time the plugin boots in this project, it will create the
+   > `.foundry/` runtime directory and idempotently append `.foundry/` to
+   > `.gitignore` so the per-worktree HMAC key stays out of git. The
+   > `.snapshots/` line was added by this skill to keep dry-run snapshots
+   > out of git.
    >
    > **Optional: Flow Memory**
    >
-   > If your flows need persistent knowledge (entities, relationships, semantic
-   > search), use the `init-memory` skill to scaffold flow memory. Memory is
-   > useful for projects that need to track code structure, dependencies, or
-   > domain knowledge across flow runs.
+   > If your flows need persistent knowledge, ask the Foundry agent to add
+   > flow memory. Memory is useful for projects that need to track code
+   > structure, dependencies, or domain knowledge across flow runs.

package/dist/skills/init-memory/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: init-memory
 type: atomic
-description: Initialize flow memory by creating the foundry/memory/ and foundry-memory/ directory structures
+description: Initialise flow memory by creating the foundry/memory/ and foundry-memory/ directory structures
 ---
 
-# Initialize Flow Memory
+# Initialise Flow Memory
 
 Scaffold `foundry/memory/` (config) and `foundry-memory/relations/` (row data)
 in the current project. `foundry/memory/` holds entity-type and edge-type
@@ -27,19 +27,12 @@ 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/*`.
+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.
 
 Neither `foundry/memory/` nor `foundry-memory/` may already exist.
 
@@ -82,11 +75,7 @@ Neither `foundry/memory/` nor `foundry-memory/` may already exist.
    git commit -m "feat: initialise flow memory"
    ```
 
-5. **Tell the user what is next**:
+5. **Continue the user's original request**:
 
-   > Flow memory is scaffolded. Next steps:
-   >
-   > - Use `add-memory-entity-type` to declare entity types (e.g. `class`,
-   >   `method`, `table`).
-   > - Use `add-memory-edge-type` to declare edge types (e.g. `calls`,
-   >   `writes`, `references`).
+   > Flow memory is scaffolded. The Foundry agent will continue to define
+   > memory entity and edge types as needed to support your goal.

package/dist/skills/list-agents/SKILL.md

@@ -21,4 +21,4 @@ foundry-<provider>-<model>  →  <provider>/<model>
 
 If no `foundry-*.md` files are found, output:
 
-> No foundry agent files found. Run the `refresh-agents` skill to generate them.
+> No foundry agent files found. Call `foundry_refresh_agents()` to generate them.

package/dist/skills/refresh-agents/SKILL.md

@@ -9,35 +9,13 @@ Regenerate `.opencode/agents/foundry-*.md` files from the currently available mo
 
 ## Protocol
 
-1. Run `opencode models` to get all available `provider/model` IDs
-2. Create `.opencode/agents/` directory if it does not exist
-3. Delete all existing `.opencode/agents/foundry-*.md` files (stale agents from removed providers)
-4. For each model line in the output, generate a markdown agent file
+Call the `foundry_refresh_agents` tool. It runs `opencode models`, deletes stale agent files, and generates fresh ones.
 
-### Agent file format
+## Output
 
-Filename: `.opencode/agents/foundry-<slug>.md`
+The tool returns `{ ok: true, count: <n> }` on success.
 
-Where `<slug>` is the model ID with **both** `/` and `.` replaced by `-`. This keeps filenames shell-safe and unambiguous.
-
-Examples:
-- `opencode/claude-sonnet-4` → `.opencode/agents/foundry-opencode-claude-sonnet-4.md`
-- `github-copilot/claude-sonnet-4.6` → `.opencode/agents/foundry-github-copilot-claude-sonnet-4-6.md`
-- `github-copilot/gpt-5.4` → `.opencode/agents/foundry-github-copilot-gpt-5-4.md`
-
-Content:
-
-```markdown
----
-description: "Foundry stage agent using <provider>/<model-key>"
-mode: subagent
-model: "<provider>/<model-key>"
-hidden: true
----
-You are a Foundry stage agent. Follow the skill instructions provided in your task prompt exactly.
-```
-
-5. After writing all files, output:
+After the tool completes, tell the user:
 
 > Generated `<count>` foundry agent files in `.opencode/agents/`.
 > **Restart OpenCode** for the new agents to take effect.

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

@@ -25,15 +25,13 @@ Before running this skill, verify all of the following:
    create one before continuing:
 
    > Foundry configuration changes must be made on a config/* branch.
-   > From a clean main branch, call:
+   > If configuration changes are needed, 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.
    >
-   > `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/*`.
+   > After the prerequisite is handled, continue the user's original
+   > request from the current context.
 
 4. Memory is initialised. The `from` edge type must exist; the `to`
    name must be free.