@really-knows-ai/foundry 3.0.2 → 3.2.0

package/dist/skills/appraise/SKILL.md

@@ -12,7 +12,7 @@ You orchestrate subjective appraisal of an artefact by dispatching independent s
 
 Before running this skill, verify that 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.
 
 ## Stage lifecycle (mandatory)
 

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

@@ -16,9 +16,7 @@ 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
@@ -28,15 +26,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

@@ -15,9 +15,7 @@ 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
@@ -27,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 (`foundry/memory/` exists; run `init-memory`
    if not).

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

@@ -16,9 +16,7 @@ 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
@@ -28,15 +26,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

@@ -15,12 +15,12 @@ A foundry flow reads a flow definition, creates a work branch, and executes cycl
 
 Before running this skill, verify that 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.
 
 ## 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/forge/SKILL.md

@@ -12,7 +12,7 @@ You produce or revise artefacts. You read the work file to understand the goal,
 
 Before running this skill, verify that 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.
 
 ## Stage lifecycle (mandatory)
 

package/dist/skills/human-appraise/SKILL.md

@@ -12,7 +12,7 @@ You are a human quality gate. Sort has routed to you either because the LLM appr
 
 Before running this skill, verify that 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.
 
 ## Stage lifecycle (mandatory)
 

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
@@ -19,27 +19,18 @@ 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/*`.
+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 +73,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/quench/SKILL.md

@@ -12,7 +12,7 @@ You run deterministic checks on an artefact by executing the CLI commands define
 
 Before running this skill, verify that 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.
 
 ## Stage lifecycle (mandatory)
 

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

@@ -13,9 +13,7 @@ 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
@@ -25,15 +23,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.

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

@@ -13,9 +13,7 @@ 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
@@ -25,15 +23,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` entity type must exist; the `to`
    name must be free (no existing entity or edge).

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

@@ -16,30 +16,22 @@ 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 it
+   internally if not). After the reset completes, continue the user's
+   original request from context.
 
 ## Steps
 

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

@@ -14,13 +14,13 @@ This is a rebuild-style upgrade. Treat the old `foundry/` directory as source ma
 
 Before running this skill, verify that the project root contains `foundry/`. If it does not, stop and tell the user:
 
-> Foundry is not initialised in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+> Restart OpenCode to initialise Foundry, then retry this command.
 
 Verify a safe base state before making changes:
 
 - The worktree is clean, or the user explicitly chooses how to handle dirty files.
 - `WORK.md` is absent from the repository root.
-- The upgrade runs from a config branch such as `config/upgrade-foundry`, or you create one with `foundry_git_branch({ kind: 'config', description: 'upgrade-foundry' })` before making config changes.
+- The upgrade runs from a config branch such as `config/upgrade-foundry`. 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.
 - Use an isolated worktree where practical, matching the normal config-edit workflow.
 
 If `WORK.md` exists, stop and tell the user:
@@ -53,7 +53,7 @@ Do not modify the preserved source directory after moving it. Read from it as so
 
 ### 3. Initialise current-version configuration
 
-Run the current `init-foundry` flow to create a fresh `foundry/` directory for the installed Foundry version.
+On next restart, the plugin's config hook will auto-initialise a fresh `foundry/` directory.
 
 After initialisation, confirm the new config directory exists and contains the expected current top-level structure.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "3.0.2",
+  "version": "3.2.0",
   "description": "A skill-driven framework for governed artefact generation with AI coding tools. Define your own artefact types, laws, and flows — Foundry handles the forge → quench → appraise pipeline with deterministic routing, quality gates, and iterative refinement.",
   "type": "module",
   "main": "dist/.opencode/plugins/foundry.js",
@@ -34,6 +34,7 @@
   },
   "files": [
     "dist/.opencode/",
+    "dist/agents/",
     "dist/skills/",
     "dist/scripts/",
     "dist/docs/",

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

@@ -1,91 +0,0 @@
----
-name: init-foundry
-type: atomic
-description: Initialize a Foundry project by creating the foundry/ directory structure
----
-
-# Initialize Foundry
-
-Set up the `foundry/` directory structure in the current project.
-
-## Prerequisites
-
-- The project must not already have a `foundry/` directory.
-
-## Steps
-
-1. **Check for existing foundry/ directory**
-   - If `foundry/` already exists, inform the user and stop.
-
-2. **Create the directory structure**
-   Create the following directories, each with a `.gitkeep` file:
-
-   ```
-   foundry/
-     artefacts/.gitkeep
-     flows/.gitkeep
-     cycles/.gitkeep
-     laws/.gitkeep
-     appraisers/.gitkeep
-   ```
-
-3. **Update `.gitignore`**
-
-   Append the following lines to the project's `.gitignore` (creating
-   the file if absent), skipping any that are already present:
-
-   ```
-   .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**
-
-   Run the `refresh-agents` skill to generate `.opencode/agents/foundry-*.md` files for multi-model routing.
-
-5. **Commit the structure**
-
-   ```bash
-   git add foundry/ .gitignore .opencode/agents/foundry-*.md
-   git commit -m "feat: initialize Foundry project structure"
-   ```
-
-6. **Guide next steps**
-
-   Tell the user:
-
-   > Foundry is initialized. **Restart OpenCode** for the new foundry agents to take effect.
-   >
-   > 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.
-   >
-   > Here's how to set up your first pipeline:
-   >
-   > 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
-   >
-   > Then run your flow with the `flow` skill.
-   >
-   > **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.