@really-knows-ai/foundry 3.3.0 → 3.3.2

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

@@ -6,60 +6,79 @@ description: Create a new entity type in flow memory, with a prose brief for the
 
 # Add Memory Entity Type
 
-Declare a new entity type. The prose body becomes part of every cycle's prompt and
-decides what the LLM writes into memory.
+Declare a new entity type. The prose body becomes part of every cycle's prompt and decides what the LLM writes into memory.
 
-## 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).
+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 the type name** (lowercase snake_case, e.g. `class`, `stored_proc`).
-2. **Propose a prose body template** for the user to edit. Sections required: Name (naming convention for this type), Value (what goes in the value field, must state that relationships belong in edges), Relationships (informational list of likely edges). Example:
+Do not tell the user to call branch tools directly.
 
-   ```markdown
-   # <type>
+Memory must be initialised (`foundry/memory/` must exist). Initialise memory internally first if not.
 
-   Short description of what this entity represents in the subject system.
+## Protocol
 
-   ## Name
-   Convention for how `name` is formed. Be specific enough to guarantee uniqueness.
+### Context object
 
-   ## Value
-   Describe what the `value` string should contain: intrinsic characteristics of
-   the entity only. Relationships to other entities belong in edges, not here.
+When invoked with pre-filled fields matching the `foundry_memory_create_entity_type` tool args, skip questions for provided fields. Missing fields trigger clarifying questions.
 
-   ## Relationships
-   - `<edge>` to `<type>`: brief semantic note
-   ```
+Context fields: `{name, body}`
 
-3. **Confirm the body with the user.** Short bodies (≤100 chars) are a red flag; push back.
-4. **Create the type** by invoking `foundry_memory_create_entity_type` with `{ name, body }`. The tool rejects duplicate names (entity or edge) — surface the error to the user if it fires and stop.
-5. **Commit**:
+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.
 
-   ```bash
-   git add foundry/memory/entities/<name>.md foundry/memory/schema.json
-   git commit -m "feat(memory): add entity type <name>"
-   ```
+### 1. Understand
 
-6. **Dependency composition**: if related edge types would serve the user's stated goal, compose them internally with one focused question for ambiguity.
+Ask for each field one question at a time:
+
+1. **Type name.** Lowercase snake_case (e.g. `class`, `stored_proc`).
+2. **Prose body.** Propose a body template based on the type name. The body template includes:
+   - `# <type>` heading
+   - Short description of what this entity represents in the subject system
+   - `## Name` — convention for how `name` is formed, specific enough to guarantee uniqueness
+   - `## Value` — what the `value` string should contain: intrinsic characteristics of the entity only. Relationships to other entities belong in edges, not here.
+   - `## Relationships` — informational list of likely edges
+
+   After presenting the template, ask the user to confirm or refine the body. Short bodies (≤100 chars) are a red flag; push back.
+
+### 2. Plan
+
+Present the entity type definition: name and body. Ask: "Does this capture the entity 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_entity_type({ name: "<name>", body: "<body>" })`. The tool rejects duplicate names (entity or edge) — surface the error to the user if it fires and stop.
+3. **Commit**: Run `git add foundry/memory/entities/<name>.md foundry/memory/schema.json`. Run `git commit -m "feat(memory): add entity type <name>"`. Report the commit hash.
+
+#### Post-Build — compose related edge types
+
+If related edge types would serve the user's stated goal, compose them internally with one focused question when schema design is ambiguous.
+
+## What you do NOT do
+
+- You do not delegate memory initialisation to the user — initialise internally when needed
+- You do not delegate edge type creation to the user — compose internally when edge types serve the user's stated goal

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

@@ -38,17 +38,27 @@ Before running this skill, verify all of the following:
    from this machine. Allow enough time and bandwidth to re-embed
    (O(#entities) requests in batches).
 
-## Steps
-
-1. **Ask the user for**: `model`, `dimensions`, optionally new `baseURL`, `apiKey`.
-2. **Invoke `foundry_memory_change_embedding_model`** with `{ model, dimensions, baseURL?, apiKey? }`.
-   The tool probes the new provider, re-embeds every entity, rewrites
-   `schema.json`, and then updates `foundry/memory/config.md` frontmatter to
-   match. On probe or re-embed failure, nothing is written.
-3. **Verify** by invoking `foundry_memory_search` with a sample query.
-4. **Commit**:
-
-   ```bash
-   git add foundry/memory/config.md foundry/memory/schema.json foundry-memory/relations/
-   git commit -m "chore(memory): change embedding model to <model>"
-   ```
+## Protocol
+
+### 1. Understand
+
+Ask for each field one question at a time:
+
+1. **Model**: Offer multiple choice from available models (e.g. `text-embedding-3-small`, `text-embedding-3-large`, `nomic-embed-text`).
+2. **Dimensions**: Recommend the default for the chosen model.
+3. **Custom endpoint and API key**: Ask: "Do you need a custom endpoint or API key? (No is the default — uses the current provider.)" Only ask for `baseURL` and `apiKey` if the user says yes.
+
+### 2. Plan
+
+Present a summary: "Change embedding model to `<model>` with `<dimensions>` dimensions. Base URL: `<baseURL or 'default'>`. API key: `<'custom' or 'default'>`."
+
+### 3. Confirm
+
+Ask: "Proceed?" — wait for the user's 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. Build
+
+1. **Check connectivity**: Verify the new provider is reachable from this machine and the model name is valid.
+2. **Execute**: Call `foundry_memory_change_embedding_model({ model: "<model>", dimensions: <dimensions>, baseURL: "<baseURL>", apiKey: "<apiKey>" })`. The tool probes the new provider, re-embeds every entity, rewrites `schema.json`, and then updates `foundry/memory/config.md` frontmatter to match. On probe or re-embed failure, nothing is written.
+3. **Verify**: Invoke `foundry_memory_search` with a sample query.
+4. **Commit**: Run `git add foundry/memory/config.md foundry/memory/schema.json foundry-memory/relations/`. Run `git commit -m "chore(memory): change embedding model to <model>"`. Report the commit hash.

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

@@ -36,15 +36,23 @@ Before running this skill, verify all of the following:
 4. Memory is initialised (`foundry/memory/` exists; run `init-memory`
    if not).
 
-## Steps
-
-1. Ask the user for the edge type name.
-2. Invoke `foundry_memory_drop_edge_type` with `{ name, confirm: false }` (or omit `confirm`). This returns `{ requiresConfirm: true, preview: { rows } }` — show the user the row count that will be deleted.
-3. Require explicit "yes, delete it" confirmation.
-4. Invoke `foundry_memory_drop_edge_type` again with `{ name, confirm: true }`.
-5. Commit:
-
-   ```bash
-   git add -A foundry/memory/ foundry-memory/relations/
-   git commit -m "refactor(memory): drop edge type <name>"
-   ```
+## Protocol
+
+### 1. Understand
+
+Ask for `name`. List existing edge types as multiple choice options. Warn about the destructive nature: this deletes all edges of this type.
+
+### 2. Plan
+
+Present a preview: call `foundry_memory_drop_edge_type({ name: "<name>", confirm: false })`. This returns `{ requiresConfirm: true, preview: { rows } }` — show the user the row count that will be deleted.
+
+Summarise: "Drop edge type `<name>` — this will delete the edge type and all its edges. This action cannot be undone."
+
+### 3. Confirm
+
+Ask: "Proceed?" with explicit confirmation required. Wait for the user's 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. Build
+
+1. **Execute**: Call `foundry_memory_drop_edge_type({ name: "<name>", confirm: true })`.
+2. **Commit**: Run `git add -A foundry/memory/ foundry-memory/relations/`. Run `git commit -m "refactor(memory): drop edge type <name>"`. Report the commit hash.

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

@@ -37,17 +37,25 @@ Before running this skill, verify all of the following:
 4. Memory is initialised (`foundry/memory/` exists; run `init-memory`
    if not).
 
-## Steps
-
-1. Ask the user for the type name.
-2. Invoke `foundry_memory_drop_entity_type` with `{ name, confirm: false }` (or omit `confirm`). This returns `{ requiresConfirm: true, preview: { entityRows, affectedEdges: [...] } }`. Show the user:
-   - `entityRows` — number of entities of this type that will be deleted.
-   - For each `affectedEdges` entry: `cascadeDrop` means the whole edge type disappears; `prune` means `rowsAffected` rows will be removed but the edge type survives.
-3. Require explicit "yes, delete it" confirmation.
-4. Invoke `foundry_memory_drop_entity_type` again with `{ name, confirm: true }`.
-5. Commit:
-
-   ```bash
-   git add -A foundry/memory/ foundry-memory/relations/
-   git commit -m "refactor(memory): drop entity type <name>"
-   ```
+## Protocol
+
+### 1. Understand
+
+Ask for `name`. List existing entity types as multiple choice options. Warn about the destructive nature: this deletes all rows of this type and strips or removes any edges that reference it.
+
+### 2. Plan
+
+Present a preview: call `foundry_memory_drop_entity_type({ name: "<name>", confirm: false })`. This returns `{ requiresConfirm: true, preview: { entityRows, affectedEdges: [...] } }`. Show the user:
+- `entityRows` — number of entities of this type that will be deleted.
+- For each `affectedEdges` entry: `cascadeDrop` means the whole edge type disappears; `prune` means `rowsAffected` rows will be removed but the edge type survives.
+
+Summarise: "Drop entity type `<name>` — this will delete the type and all its edges. This action cannot be undone."
+
+### 3. Confirm
+
+Ask: "Proceed?" with explicit confirmation required. Wait for the user's 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. Build
+
+1. **Execute**: Call `foundry_memory_drop_entity_type({ name: "<name>", confirm: true })`.
+2. **Commit**: Run `git add -A foundry/memory/ foundry-memory/relations/`. Run `git commit -m "refactor(memory): drop entity type <name>"`. Report the commit hash.

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

@@ -12,68 +12,72 @@ definitions, the schema, the config, and the gitignored Cozo database.
 `foundry-memory/relations/` is a top-level sibling of `foundry/` that holds
 the committed NDJSON relations.
 
-## 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
 
-Neither `foundry/memory/` nor `foundry-memory/` may already exist.
+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** whether to enable embeddings (semantic search).
-   - Default: **yes**, targeting a local Ollama instance
-     (`http://localhost:11434/v1`, `nomic-embed-text`, 768 dims).
-   - If the user declines, note it and pass `embeddings_enabled: false` in
-     step 2.
+Do not tell the user to call branch tools directly.
 
-2. **Invoke `foundry_memory_init`** with `{ embeddings_enabled, probe: true }`.
+Neither `foundry/memory/` nor `foundry-memory/` may already exist. If they do, stop and tell the user that memory is already initialised.
 
-   The tool deterministically:
+## Protocol
+
+### 1. Understand
+
+Ask about `embeddings_enabled`. Offer multiple choice:
+
+> Enable embeddings?
+> 1. **Yes (Recommended)** — semantic search with local Ollama instance (`http://localhost:11434/v1`, `nomic-embed-text`, 768 dimensions).
+> 2. **No** — keyword-only search.
+
+### 2. Plan
+
+Present the init plan and invite refinement: whether embeddings are enabled and what that means (semantic search vs keyword-only). Ask: "Does this look right?"
+
+### 3. Confirm
+
+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. Build
+
+1. **Initialise**: Call `foundry_memory_init({ embeddings_enabled: <bool>, probe: true })`. The tool deterministically:
    - creates `foundry/memory/entities/` and `foundry/memory/edges/` with `.gitkeep`,
    - creates `foundry-memory/relations/` (top-level sibling of `foundry/`) with `.gitkeep`,
    - writes `foundry/memory/config.md` (frontmatter set from the embeddings choice),
    - writes `foundry/memory/schema.json` (`embeddings: {...}` when enabled, `null` when not),
-   - appends the three `foundry/memory/memory.db*` entries to `.gitignore`
-     idempotently,
+   - appends the three `foundry/memory/memory.db*` entries to `.gitignore` idempotently,
    - probes the embedding provider (only when enabled) and returns the result.
 
    It fails if either `foundry/memory/` or `foundry-memory/` already exists.
 
-3. **Handle the probe result** (field `probe` in the return value).
+2. **Handle the probe result** (field `probe` in the return value):
    - `probe == null`: embeddings disabled, skip.
-   - `probe.ok == true`: display `✓ Embedding provider responded (dimensions: N)` 
-     where N is `probe.dimensions`, then continue.
+   - `probe.ok == true`: display `✓ Embedding provider responded (dimensions: N)` where N is `probe.dimensions`, then continue.
    - `probe.ok == false`: present the user with these options:
-     1. Install/start Ollama and `ollama pull nomic-embed-text`, then invoke
-        `foundry_memory_validate` to re-check.
-     2. Edit `foundry/memory/config.md` frontmatter to point at a different
-        OpenAI-compatible endpoint, then invoke `foundry_memory_validate`.
+     1. Install/start Ollama and `ollama pull nomic-embed-text`, then invoke `foundry_memory_validate` to re-check.
+     2. Edit `foundry/memory/config.md` frontmatter to point at a different OpenAI-compatible endpoint, then invoke `foundry_memory_validate`.
      3. Set `embeddings.enabled: false` in `foundry/memory/config.md`.
 
-4. **Commit the scaffold**:
-
-   ```bash
-   git add foundry/memory/ foundry-memory/ .gitignore
-   git commit -m "feat: initialise flow memory"
-   ```
+3. **Commit**: Run `git add foundry/memory/ foundry-memory/ .gitignore`. Run `git commit -m "feat: initialise flow memory"`. Report the commit hash.
 
-5. **Continue the user's original request**:
+4. **Continue the user's original request**:
 
-   > Flow memory is scaffolded. The Foundry agent will continue to define
-   > memory entity and edge types as needed to support your goal.
+   > 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/rename-memory-edge-type/SKILL.md

@@ -34,13 +34,22 @@ Before running this skill, verify all of the following:
 4. Memory is initialised. The `from` edge type must exist; the `to`
    name must be free.
 
-## Steps
+## Protocol
 
-1. Ask the user for `from` and `to`.
-2. Invoke `foundry_memory_rename_edge_type` with `{ from, to }`.
-3. Commit:
+### 1. Understand
 
-   ```bash
-   git add -A foundry/memory/ foundry-memory/relations/
-   git commit -m "refactor(memory): rename edge type <from> -> <to>"
-   ```
+Ask for `from` and `to` one question at a time. List existing edge types as multiple choice options for `from`. Warn that this does not touch row data.
+
+### 2. Plan
+
+Present a summary: "Rename edge type `<from>` → `<to>`."
+
+### 3. Confirm
+
+Ask: "Proceed?" — wait for the user's 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. Build
+
+1. **Validate**: Check that `<to>` does not conflict with existing entity or edge types.
+2. **Execute**: Call `foundry_memory_rename_edge_type({ from: "<from>", to: "<to>" })`.
+3. **Commit**: Run `git add -A foundry/memory/ foundry-memory/relations/`. Run `git commit -m "refactor(memory): rename edge type <from> -> <to>"`. Report the commit hash.

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

@@ -34,14 +34,22 @@ Before running this skill, verify all of the following:
 4. Memory is initialised. The `from` entity type must exist; the `to`
    name must be free (no existing entity or edge).
 
-## Steps
+## Protocol
 
-1. Ask the user for `from` and `to`.
-2. Warn the user: this rewrites committed NDJSON rows in every edge that references the entity. Preview the change with `foundry_memory_validate` if desired.
-3. Invoke `foundry_memory_rename_entity_type` with `{ from, to }`.
-4. Commit:
+### 1. Understand
 
-   ```bash
-   git add -A foundry/memory/ foundry-memory/relations/
-   git commit -m "refactor(memory): rename entity type <from> -> <to>"
-   ```
+Ask for `from` and `to` one question at a time. List existing entity types as multiple choice options for `from`. Warn about the destructive nature: this rewrites committed NDJSON rows in every edge that references the entity.
+
+### 2. Plan
+
+Present a summary: "Rename entity type `<from>` → `<to>`."
+
+### 3. Confirm
+
+Ask: "Proceed?" — wait for the user's 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. Build
+
+1. **Validate**: Check that `<to>` does not conflict with existing entity or edge types. Call `foundry_memory_validate` if desired.
+2. **Execute**: Call `foundry_memory_rename_entity_type({ from: "<from>", to: "<to>" })`.
+3. **Commit**: Run `git add -A foundry/memory/ foundry-memory/relations/`. Run `git commit -m "refactor(memory): rename entity type <from> -> <to>"`. Report the commit hash.

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

@@ -33,14 +33,23 @@ Before running this skill, verify all of the following:
    internally if not). After the reset completes, continue the user's
    original request from context.
 
-## Steps
+## Protocol
 
-1. Warn the user of the scope.
-2. Require explicit confirmation.
-3. Invoke `foundry_memory_reset` with `{ confirm: true }`.
-4. Commit:
+### 1. Understand
 
-   ```bash
-   git add foundry-memory/relations/ foundry/memory/schema.json
-   git commit -m "chore(memory): reset memory data"
-   ```
+Warn about the destructive nature: this permanently deletes all memory data including entity types, edge types, and embeddings. This action cannot be undone.
+
+Ask the user to type "reset" to confirm intent. The user must type "reset" to proceed past the Understand phase.
+
+### 2. Plan
+
+Present a destructive-action summary: "This will permanently delete all memory data including entity types, edge types, and embeddings. This action cannot be undone."
+
+### 3. Confirm
+
+Ask: "Proceed?" — this is the final gate. Wait for the user's answer. Do not proceed to Build unless the user says yes. If the user rejects the plan, return to the Understand phase.
+
+### 4. Build
+
+1. **Execute**: Call `foundry_memory_reset({ confirm: true })`.
+2. **Commit**: Run `git add foundry-memory/relations/ foundry/memory/schema.json`. Run `git commit -m "chore(memory): reset memory data"`. Report the commit hash.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "3.3.0",
+  "version": "3.3.2",
   "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",