pi-fabric 0.1.0

package/skills/fabric-ambient/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: fabric-ambient
+description: Creates an emergent supervisor or advisor as a persistent Pi Fabric actor. Use when the user asks for ambient supervision, ongoing peer review, an advisor, or a goal watcher without installing a separate extension.
+disable-model-invocation: true
+---
+
+# Fabric Ambient Actors
+
+This is the meta-pattern for custom ambient roles. Prefer `/skill:fabric-supervisor` or `/skill:fabric-advisor` when either dedicated pattern matches exactly.
+
+Create the requested behavior with `fabric_exec` and `agents.create()`. Do not install or load pi-supervisor, pi-advisor, or another orchestration extension.
+
+The first skill argument selects the pattern:
+
+- `supervisor <goal>`: watch until the goal is achieved; steer only when work is incomplete or drifting.
+- `advisor [focus]`: peer-review turns and surface only material advice.
+
+If the pattern is omitted, infer it from the request. If a supervisor goal is omitted, derive a concrete goal from the current user request. Do not ask for details that are already in the conversation.
+
+Pass long instructions through the `strings` parameter and reference them as `π.instructions`. Use one Fabric call shaped like this:
+
+```ts
+await workflow.configure({
+  name: `Ambient · ${π.name}`,
+  description: "Persistent event-driven actor setup",
+});
+await phase("Start actor", { total: 1 });
+const current = await agents.actors();
+const duplicate = current.find((actor) => actor.name === π.name && actor.status !== "stopped");
+if (duplicate) return { reused: true, actor: duplicate };
+
+const actor = await agents.create({
+  name: π.name,
+  instructions: π.instructions,
+  events: ["agent_settled", "tool_error"],
+  responseMode: "directive",
+  delivery: "steer",
+  triggerTurn: true,
+  coalesce: true,
+  tools: ["read", "grep", "find", "ls"],
+});
+return {
+  started: true,
+  actor,
+  inspect: `/fabric messages ${actor.id.slice(0, 8)}`,
+  stop: `/fabric stop ${actor.id.slice(0, 8)}`,
+};
+```
+
+For an advisor, change the event list to `["turn_end"]` and set `triggerTurn: false` so advice does not create an interruption loop.
+
+## Supervisor instructions
+
+Build `π.instructions` from the goal and these rules:
+
+```text
+You are an ambient supervisor for this goal:
+
+<goal>
+GOAL
+</goal>
+
+Review the supplied parent-session event and recent transcript. You are an outside observer, not a second implementer.
+
+Return {"action":"silent"} while work is productively advancing and after the goal is verifiably complete. Return {"action":"message","message":"..."} only when the main agent is idle with material work missing, is drifting from the goal, is stuck after a tool error, or needs one concrete next action. Keep messages direct and at most three sentences. Do not repeat a prior steer. Never request credentials or invent user decisions. Once the goal is clearly complete, return {"action":"stop","message":"Goal verified complete."}.
+```
+
+Replace `GOAL` with the actual goal before passing the string.
+
+## Advisor instructions
+
+Build `π.instructions` from the optional focus and these rules:
+
+```text
+You are an ambient peer advisor reviewing the main coding agent one turn at a time. Focus on correctness, missed constraints, risky assumptions, and cheaper paths to the user's outcome. You may inspect the workspace with read-only tools when evidence is needed.
+
+Prefer silence. Return {"action":"silent"} when the agent is on track. Return {"action":"message","message":"..."} only for a concrete, material observation that could prevent wasted work or a defect. State the evidence and recommendation tersely; frame it as advice to weigh, not an order. Do not repeat advice already present in the recent transcript.
+```
+
+Append the user's requested focus when present.
+
+## After creation
+
+Tell the user the actor name, short ID, subscribed events, and the `/fabric messages` and `/fabric stop` commands. Do not wait for the actor: it is session-persistent and event-driven.

package/skills/fabric-council/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: fabric-council
+description: Runs a bounded multi-perspective Pi Fabric council with independent reviewers and an optional synthesis decision. Use for architecture choices, plans, reviews, and adversarial cross-checking.
+disable-model-invocation: true
+---
+
+# Fabric Council
+
+Use one `fabric_exec` call and `council.run()`. Choose roles that disagree usefully rather than duplicating one another.
+
+```ts
+const roles = JSON.parse(π.roles) as string[];
+await workflow.configure({
+  name: "Council review",
+  description: `${roles.length} independent perspectives with synthesis`,
+});
+await phase("Deliberate", { total: roles.length });
+const decision = await council.run({
+  task: π.task,
+  roles,
+  tools: ["read", "grep", "find", "ls"],
+  synthesize: true,
+});
+return decision;
+```
+
+Pass the full task and role array through `strings`. Usually use three to five roles. Examples:
+
+- implementation correctness reviewer
+- security and abuse-case reviewer
+- test and operability reviewer
+- simplicity and maintenance reviewer
+- user-requirements skeptic
+
+Council members must inspect evidence independently. The synthesizer must preserve material disagreement, reject unsupported claims, and make a concrete recommendation. Use `synthesize: false` only when the user asked for raw independent opinions.
+
+Do not use a council for a simple lookup or a decision with no meaningful competing considerations.

package/skills/fabric-exec/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: fabric-exec
+description: >-
+  Reference for writing `fabric_exec` TypeScript programs in the QuickJS
+  sandbox: the mental model (one program, return only the final value), the
+  core `pi` tools (read/bash/edit/write/grep/find/ls) with exact signatures,
+  `tools` discovery and introspection, `π` named strings,
+  and the validate, describe, retry error loop. Load before your first
+  `fabric_exec` call and whenever a call errors on argument shape. For MCP,
+  agents/rlm, and mesh, see `references/mcp.md`, `references/agents.md`, `references/mesh.md`.
+---
+
+# fabric_exec — core reference
+
+One type-checked TS program in a QuickJS sandbox. Only the `return` value reaches the model; `print()`/`console.log` go to the activity panel. `π` is not a tool.
+
+## `pi` core tools (full code mode only)
+`pi.<tool>(arg)` — single arg: bare string (primary field) or options object; `edit`/`write` need an object. No positional args: `pi.grep(p, path)` → `pi.grep({ pattern: p, path })`.
+
+| Tool | Form | Returns |
+|------|------|---------|
+| `read` | `path` \| `{path,offset?,limit?}` | `string` |
+| `bash` | `command` \| `{command,timeout?}` | `{ok,output,details}` |
+| `grep` | `pattern` \| `{pattern,path?,glob?,ignoreCase?,literal?,context?,limit?}` | `string` |
+| `find` | `pattern` \| `{pattern,path?,limit?}` | `string` |
+| `ls` | `path?` \| `{path?,limit?}` | `string` |
+| `edit` | `{path,edits:[{oldText,newText}]}` \| `{path,oldText,newText}` | `{ok,output,details}` |
+| `write` | `{path,content}` | `{ok,output,details}` |
+
+Aliases: `cmd`→`command`, `query`→`pattern`, `file`→`path`, `dir`→`path`.
+
+## `tools` — discovery & generic calls
+Refs namespaced: `pi.grep`, `extensions.<tool>`, `mcp.<server>.<tool>`; bare names rejected. `tools.providers()`→`[{name,description}]` · `tools.search({query,limit?})`→`FabricAction[]`(`ref,name,description,inputSchema,risk`) · `tools.describe({ref})`→full `FabricAction` (read `inputSchema` first) · `tools.call({ref,args?})` · `tools.list({provider?,namespace?,query?,limit?})` · `extensions.<tool>(args)` (full code mode only).
+
+## Error recovery: read, describe, retry
+Read the line-numbered error → `await tools.describe({ref})` for the schema → match `inputSchema`, rerun (don't guess). Common mistakes: two positional args; bare ref (`grep`→`pi.grep`).
+
+## Other surfaces
+`references/mcp.md` (mcp.*) · `references/agents.md` (agents/actors/rlm) · `references/mesh.md` (topics/cas state). Workflow/councils → `/skill:fabric-workflow`, `/skill:fabric-council`.

package/skills/fabric-exec/references/agents.md

@@ -0,0 +1,78 @@
+# Agents and rlm reference
+
+`fabric_exec` can spawn one-shot child agents, create persistent event-driven actors, and run recursive queries. For the sandbox model and `tools` discovery, see the parent `fabric-exec` skill; for actor coordination across sessions, see `mesh.md`.
+
+Every method takes a single options object.
+
+## One-shot child agents
+
+- `agents.run(args)` runs to completion and returns `FabricAgentResult` with `{ id, status, text, value?, error?, usage, turns, toolCalls }`.
+- `agents.spawn(args)` returns a background `FabricAgentHandle` with an `id`. Then use `agents.wait({ id })`, `agents.status({ id })`, `agents.stop({ id })`.
+- `agents.list()` returns all children.
+- `agents.cleanup({ id, deleteBranch? })` returns `{ cleaned }` and removes a worktree branch.
+
+`args` is a `FabricAgentRequest`: `{ task, name?, transport?, model?, thinking?, tools?, timeoutMs?, extensions?, recursive?, worktree?, schema? }`.
+
+- `transport` is one of `auto`, `process`, `tmux`, `screen`, `localterm` (default `process`). `auto` tries LocalTerm, tmux, screen, then process.
+- `tools` defaults to `subagents.defaultTools`. Children inherit the parent model unless `model` is set.
+- `schema` is a JSON Schema; the worker returns validated structured data in `result.value`.
+- `worktree: true` creates a dedicated Git worktree on branch `pi-fabric/<name>-<id>`, retained until `agents.cleanup()`.
+
+```ts
+const result = await agents.run({
+  name: "security-review",
+  task: "Review the current diff for concrete security defects. Do not edit files.",
+  tools: ["read", "grep", "find", "ls"],
+});
+return result;
+```
+
+```ts
+const handle = await agents.spawn({ task: "Map the persistence layer.", transport: "tmux" });
+// independent work here
+return await agents.wait({ id: handle.id });
+```
+
+Use `/fabric agents` to list children and `/fabric attach <id>` for the attach command. Abort signals propagate to the transport and child Pi process.
+
+## Persistent actors
+
+`agents.create(args)` returns `FabricActorInfo`. An actor has its own Pi session, a serial mailbox, and optional subscriptions to parent events or durable mesh topics. It processes messages one at a time, coalesces repeated host events by default, and resumes when the same Pi session reopens in a trusted project.
+
+`args` is a `FabricActorRequest`: `{ name, instructions, events?, topics?, delivery?, responseMode?, triggerTurn?, coalesce?, model?, thinking?, tools?, transport?, timeoutMs? }`.
+
+- `events` is a subset of `input`, `turn_end`, `agent_settled`, `tool_error`, `session_compact` (host events to subscribe to).
+- `topics` lists durable mesh topics to subscribe to (see `mesh.md`).
+- `responseMode` is `text` (every non-empty response becomes an outbox message) or `directive` (validated `{ action, message?, data? }` where `action` is `silent`, `message`, or `stop`; the actor decides whether to intervene).
+- `delivery` is `mailbox`, `steer`, `followUp`, or `nextTurn`; fixed at creation, an actor cannot escalate it.
+- `triggerTurn` fires on the first event of a coalesced burst; `coalesce` is on by default.
+
+```ts
+return agents.create({
+  name: "auth-supervisor",
+  instructions: "Watch the main session until the auth migration is complete and tested. Prefer silence; reply with a directive only for material drift, a blocker, or verified completion.",
+  events: ["agent_settled", "tool_error"],
+  responseMode: "directive",
+  delivery: "steer",
+  triggerTurn: true,
+  tools: ["read", "grep", "find", "ls"],
+});
+```
+
+Mailbox:
+
+- `agents.ask({ id, message, data? })` returns a `FabricActorMessage` (blocking exchange).
+- `agents.tell({ id, message, data? })` returns `{ queued, messageId }` (fire and forget).
+- `agents.actorStatus({ id })` and `agents.actors()` return actor info.
+- `agents.messages({ id, limit? })` returns message history.
+- `agents.remove({ id })` returns `{ removed }`.
+
+## Recursive queries
+
+`rlm.query(args)` is `agents.run({ ...args, recursive: true })` with Fabric enabled in the child. Recursion is rejected at `subagents.maxDepth`. Approving the initial recursive call delegates only the `agent` risk capability to recursive children; network, execution, and write approvals are not inherited. Each Fabric process enforces its own concurrency and timeout limits.
+
+```ts
+return rlm.query({ task: "Decompose this repository and produce a compact architecture map.", transport: "process" });
+```
+
+`council.run({ task, roles, synthesize?, ...agentOptions })` runs several `agents.run` calls concurrently under the subagent semaphore and optionally synthesizes them; load `/skill:fabric-council` for the pattern.

package/skills/fabric-exec/references/mcp.md

@@ -0,0 +1,46 @@
+# MCP surface reference
+
+MCP tools are available inside `fabric_exec` through the `mcp` surface, backed by the public `mcporter` runtime (config discovery, imports, OAuth cache, connection pooling). For the sandbox model and `tools` discovery, see the parent `fabric-exec` skill.
+
+## Call a tool
+
+`mcp.<server>.<tool>(args)` takes a single options object matching the tool input schema. The server and tool names are whatever mcporter loaded.
+
+```ts
+const result = await mcp.context7.resolve_library_id({ libraryName: "react", query: "hooks" });
+return result;
+```
+
+## Server management
+
+- `mcp.servers()` returns server metadata `{ name, description, transport }` (description may be null; transport is "http" or "stdio"). Credentials are never exposed.
+- `mcp.reload()` returns `{ servers }`. Call it after changing mcporter configuration.
+- `mcp.register({ name, description?, command?, args?, cwd?, baseUrl?, headers?, env?, overwrite? })` returns `{ registered }`. Register an ephemeral server in the pooled runtime after host approval. HTTP servers use `baseUrl` instead of `command`. Dynamic definitions live until `mcp.reload()` or session shutdown; they are not written to config.
+
+```ts
+await mcp.register({ name: "project-docs", command: "npx", args: ["-y", "@example/docs-mcp"], cwd: "." });
+return mcp.project_docs.search({ query: "authentication" });
+```
+
+## Generic call
+
+`mcp.call({ server, tool, args? })` is for when a server or tool name cannot be expressed as property access.
+
+```ts
+return mcp.call({ server: "my-server", tool: "weird-tool-name", args: { q: "x" } });
+```
+
+## Introspect an uncertain tool
+
+MCP tools are discoverable through the generic `tools` surface; refs are `mcp.<server>.<tool>`.
+
+```ts
+const schema = await tools.describe({ ref: "mcp.context7.resolve_library_id" });
+// schema.inputSchema is the tool JSON Schema
+```
+
+## Notes
+
+- When `mcp.disableOAuth` is configured, calls may use cached credentials but cannot launch a new interactive OAuth flow.
+- Call timeout is bounded by `mcp.callTimeoutMs`.
+- Set `mcp.enabled: false` to disable the MCP surface.

package/skills/fabric-exec/references/mesh.md

@@ -0,0 +1,42 @@
+# Durable coordination reference
+
+`mesh` is a project-scoped, event-sourced coordination substrate. With persistent actors (see `agents.md`) it is sufficient to express messenger-style swarms without a daemon or fixed planner/worker roles. For the sandbox model, see the parent `fabric-exec` skill.
+
+Every method takes a single options object. Mesh data defaults to `<project>/.pi/fabric/mesh`; relocate it with `mesh.root` in config, and add `.pi/fabric/mesh/` to your ignore file unless you intentionally version the coordination log.
+
+## Identity and presence
+
+- `mesh.self()` returns `{ id, name, kind, sessionId? }` where `kind` is `main`, `actor`, or `agent`.
+- `mesh.members({ limit? })` returns actor presence across live Fabric sessions as entries with `{ key, value, version, updatedAt, updatedBy }` (the `value` is a `FabricActorInfo`).
+
+## Topics (durable channels)
+
+- `mesh.publish({ topic, kind?, to?, text?, data? })` returns a `FabricMeshEvent`. Use `to` for a direct message.
+- `mesh.read({ after?, topic?, to?, limit? })` returns `FabricMeshEvent[]` by cursor, topic, or recipient. Each event has `{ id, sequence, topic, kind, from, to?, text?, data?, createdAt }`.
+
+Topics provide durable channel and direct-message semantics with sequence cursors.
+
+```ts
+await mesh.publish({ topic: "team.auth", kind: "finding", text: "Refresh-token rotation is not atomic", data: { path: "src/auth/refresh.ts" } });
+const events = await mesh.read({ topic: "team.auth", limit: 50 });
+```
+
+## Shared state (compare-and-swap)
+
+- `mesh.get({ key })` returns a `FabricMeshStateEntry` or null.
+- `mesh.put({ key, value, ifVersion? })` creates or updates; `ifVersion` enables optimistic compare-and-swap.
+- `mesh.delete({ key, ifVersion? })` returns `{ deleted, version? }`.
+- `mesh.list({ prefix?, limit? })` returns matching entries.
+
+Each entry is `{ key, value, version, updatedAt, updatedBy }`. Use `ifVersion` for task claims, leases, reservations, and decisions: create with `ifVersion: 0`, claim by passing the current `version`.
+
+```ts
+const task = await mesh.put({ key: "tasks/auth-review", value: { status: "ready", owner: null }, ifVersion: 0 });
+const claimed = await mesh.put({ key: task.key, value: { status: "claimed", owner: "security-reviewer" }, ifVersion: task.version });
+return claimed;
+```
+
+## Notes
+
+- Actors subscribe to topics via `agents.create({ topics: [...] })` (see `agents.md`); published events are delivered as `mesh:<topic>` messages.
+- Set `mesh.enabled: false` in config to disable both mesh actions and ambient actor restoration.

package/skills/fabric-rlm/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: fabric-rlm
+description: Recursively decomposes a large task by delegating bounded subtasks to child Pi agents via rlm.query(), where each child gets a fresh context window and can itself recurse. Use for tasks too big for one context window — whole-repo audits, massive-context analysis, multi-file refactors.
+disable-model-invocation: true
+---
+
+# Fabric Recursive Decomposition (RLM)
+
+Inspired by Recursive Language Models: an LLM with a sub-call function can recursively decompose problems by self-delegation. `rlm.query()` is `agents.run()` with `recursive: true` — it spawns a child Pi agent with a fresh context window that can call `rlm.query()` again, bounded by `subagents.maxDepth`.
+
+Recurse not because a task is hard, but because it is too big for one context window. Each child gets a fresh context budget; you get back only its compact answer instead of all the raw material.
+
+## Core pattern: size up → search → delegate → combine
+
+1. **Size up** — `wc -l`, `wc -c`, file counts, grep scope. If it fits one context window, do it directly; do not delegate.
+2. **Search** — `grep`, `find`, `ls`, `read` to orient before delegating.
+3. **Delegate** — hand clear, bounded subtasks to children. Use `rlm.query()` when the child should be able to recurse again; use `agent()` for a one-shot leaf worker that does not need to recurse.
+4. **Combine** — aggregate, deduplicate, resolve conflicts, produce the final output.
+5. **Do it directly when it's small** — never delegate what you can do in one step.
+
+## One fabric_exec program
+
+Turn the request into a single type-checked `fabric_exec` program. The program holds the decomposition loop and branches. Pass the root task through `strings.task`.
+
+```ts
+await workflow.configure({
+  name: "Recursive decomposition",
+  description: "Size up, delegate bounded subtasks, combine",
+});
+
+// Size up and orient with read-only tools before delegating.
+await phase("Orient", { total: 1 });
+const scope = await agent<{ paths: string[] }>(
+  `Identify the bounded set of files relevant to this task. Return structured output.\n\nTask:\n${π.task}`,
+  {
+    label: "scope",
+    tools: ["read", "grep", "find", "ls"],
+    schema: {
+      type: "object",
+      properties: { paths: { type: "array", items: { type: "string" } } },
+      required: ["paths"],
+      additionalProperties: false,
+    },
+  },
+);
+
+// Delegate each bounded subtask to a recursive child. Each child gets a fresh
+// context window and may call rlm.query() again up to subagents.maxDepth.
+await phase("Decompose", { total: scope.paths.length });
+const findings = await parallel(
+  scope.paths.map((p) => () =>
+    rlm.query({
+      task: `Analyze ${p} for this objective and report concrete, bounded findings.\n\nObjective:\n${π.task}`,
+      name: `analyze ${p}`.slice(0, 50),
+      tools: ["read", "grep", "find", "ls"],
+    }),
+  ),
+  { concurrency: 4 },
+);
+
+await phase("Combine", { total: 1 });
+const summary = await agent(
+  `Synthesize these independent findings into one compact result. Drop unsupported claims and resolve conflicts:\n${JSON.stringify(findings)}`,
+  { label: "combine", tools: ["read", "grep", "find", "ls"] },
+);
+return summary;
+```
+
+Adapt the phases, tools, and fan-out to the request. Use `schema` on a worker when machine-readable output makes aggregation safer.
+
+## When to recurse vs do it directly
+
+- A 30-line file or a single function: read it and act directly. No delegation.
+- A multi-file refactor: delegate per file or per module and combine.
+- A whole-repo audit or massive-context analysis: size up first, fan out bounded subtasks, then synthesize.
+
+## Guardrails
+
+- `subagents.maxDepth` bounds recursion depth; `subagents.budgetUsd` optionally bounds total USD spend across the whole tree (0 disables it).
+- When a budget is active, each recursive result carries a `budget` summary (`limit`, `spent`, `remaining`, `tokens`). Stop spawning children when `remaining` is low and finish the remaining work directly.
+- Approving the initial recursive call delegates only the `agent` risk capability to children; network, execution, and write approvals are not inherited. Give children edit tools only when they must change files.
+- Deeper children should be more conservative: fewer sub-calls, more direct action. Teach the pattern once — size-first → search → chunk → delegate → combine — and let it repeat at every depth.
+- For edits, partition ownership by path or set `worktree: true`; never let concurrent recursive children edit the same files.
+- The pre-spawn budget check is best-effort (concurrent children can overshoot slightly); the race-free ceiling is `subagents.maxPerExecution`.

package/skills/fabric-supervisor/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: fabric-supervisor
+description: Starts a persistent, event-driven Pi Fabric supervisor that watches the main session toward a concrete goal and steers only when needed. Use for long-running goal supervision without another extension.
+disable-model-invocation: true
+---
+
+# Fabric Supervisor
+
+Start an emergent supervisor using `fabric_exec`; never install or invoke an external supervisor extension.
+
+Derive the goal from the skill arguments. If arguments are empty, use the active user request and conversation. Make the goal concrete and measurable without asking for information already present.
+
+Call `fabric_exec` once. Put the completed supervisor prompt in `strings.instructions` and the stable name `supervisor` in `strings.name`, then execute:
+
+```ts
+await workflow.configure({
+  name: `Supervisor · ${π.name}`,
+  description: "Persistent ambient goal supervision",
+});
+await phase("Start actor", { total: 1 });
+const current = await agents.actors();
+const existing = current.find((actor) => actor.name === π.name && actor.status !== "stopped");
+if (existing) return { reused: true, actor: existing };
+
+const actor = await agents.create({
+  name: π.name,
+  instructions: π.instructions,
+  events: ["agent_settled", "tool_error"],
+  responseMode: "directive",
+  delivery: "steer",
+  triggerTurn: true,
+  coalesce: true,
+  tools: ["read", "grep", "find", "ls"],
+});
+return {
+  started: true,
+  actor,
+  inspect: `/fabric messages ${actor.id.slice(0, 8)}`,
+  stop: `/fabric stop ${actor.id.slice(0, 8)}`,
+};
+```
+
+Use this prompt, replacing `GOAL`:
+
+```text
+You are an ambient supervisor for this goal:
+
+<goal>
+GOAL
+</goal>
+
+Review each supplied parent-session event and recent transcript as an outside observer, not a second implementer.
+
+Return {"action":"silent"} while work is productively advancing. Return {"action":"message","message":"..."} only when the main agent is idle with material work missing, is drifting from the goal, is stuck after a tool error, or needs one concrete next action. Keep a steer direct and at most three sentences. Do not repeat prior guidance. Never request credentials or invent a decision only the user can make.
+
+The goal is complete only when the requested result and its relevant validation are evident in the transcript. At that point return {"action":"stop","message":"Goal verified complete."}.
+```
+
+## Heuristic: steer on good signals, not every turn
+
+The supervisor subscribes to `agent_settled` and `tool_error`, not `turn_end` or `input`. It runs at decision points (idle and on failures) and stays silent while work is productively advancing, so it does not invoke a model review on every turn. Intervene only on a concrete, high-confidence signal: material work missing at idle, drift from the goal, a stuck state after a tool error, or verified completion.
+
+After creation, report the goal, actor short ID, and inspect/stop commands. Do not wait for it; host events drive it across later turns.

package/skills/fabric-swarm/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: fabric-swarm
+description: Creates a self-organizing team of persistent Pi Fabric actors with durable topics, direct mailboxes, and compare-and-swap shared tasks. Use for messenger-like multi-agent collaboration and long-lived delegated work.
+disable-model-invocation: true
+---
+
+# Fabric Swarm
+
+Build the team from Pi Fabric primitives; do not install or invoke pi-messenger or another swarm extension.
+
+Use:
+
+- `agents.create()` for persistent identities and mailbox processors.
+- `agents.tell()` for asynchronous direct delegation.
+- `agents.ask()` only when the coordinator truly must block for a response.
+- `mesh.publish()` for durable channel-like events.
+- `mesh.read()` for feed history and cursors.
+- `mesh.members()` for project-wide actor presence.
+- `mesh.put(..., ifVersion)` for atomic task claims, leases, and shared decisions.
+
+Choose a short run key and topic, such as `team.auth-migration`. Seed task records under `runs/<run-key>/tasks/<task-id>` with `ifVersion: 0`. Each value should include `title`, `status`, `owner`, `dependencies`, `progress`, and `result`.
+
+Create role-shaped actors subscribed to the team topic. Their instructions must require:
+
+1. Read the assigned task from mesh state.
+2. Claim it with compare-and-swap using the observed version; do not work after a failed claim.
+3. Publish progress to the team topic.
+4. Update the task with compare-and-swap when blocked or complete.
+5. Address questions with `mesh.publish({ topic, to, ... })`.
+6. Avoid files owned by another task or actor.
+7. Return a directive message only for a blocker or final result; otherwise stay silent.
+
+Example coordinator skeleton:
+
+```ts
+const run = π.run;
+const topic = `team.${run}`;
+await workflow.configure({
+  name: `Swarm · ${run}`,
+  description: "Persistent actors coordinating through durable shared tasks",
+});
+
+const tasks = JSON.parse(π.tasks) as Array<{ id: string; title: string; detail: string }>;
+await phase("Seed tasks", { total: tasks.length });
+for (const task of tasks of JSON.parse(π.tasks) as Array<{ id: string; title: string; detail: string }>) {
+  await mesh.put({
+    key: `runs/${run}/tasks/${task.id}`,
+    value: { ...task, status: "ready", owner: null, progress: [], result: null },
+    ifVersion: 0,
+  });
+}
+
+await phase("Create actors", { total: (JSON.parse(π.roles) as unknown[]).length });
+const actors = await Promise.all(
+  (JSON.parse(π.roles) as Array<{ name: string; instructions: string }>).map((role) =>
+    agents.create({
+      name: role.name,
+      instructions: role.instructions,
+      topics: [topic],
+      responseMode: "directive",
+      delivery: "mailbox",
+      coalesce: false,
+    }),
+  ),
+);
+
+await phase("Dispatch", { total: actors.length });
+for (const actor of actors) {
+  await agents.tell({
+    id: actor.id,
+    message: `Join ${topic}. Inspect ready tasks under runs/${run}/tasks/ and atomically claim one matching your role.`,
+  });
+}
+
+await mesh.publish({
+  topic,
+  kind: "run.started",
+  data: { run, actors: actors.map(({ id, name }) => ({ id, name })) },
+});
+
+await workflow.event({ message: `${actors.length} actors dispatched`, level: "success" });
+return { run, topic, actors, taskPrefix: `runs/${run}/tasks/` };
+```
+
+Pass generated role instructions and tasks through `strings`, not large inline literals. Keep the coordinator pull-based: inspect `mesh.read({ topic })`, task state, and actor mailboxes at decision points rather than continuously polling in one Fabric execution.

package/skills/fabric-workflow/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: fabric-workflow
+description: Runs a Claude Code-style dynamic workflow in Pi Fabric using code-held phases, fan-out, pipelines, structured agents, and synthesis. Use for large audits, migrations, parallel research, or explicit workflow requests.
+disable-model-invocation: true
+---
+
+# Fabric Dynamic Workflow
+
+Turn the request into one type-checked `fabric_exec` program. The program, not the parent context, must hold the loop and branches.
+
+Use these globals:
+
+- `workflow.agent(prompt, options)` or `agent(...)` for one worker. Set `label` on every call.
+- `workflow.parallel(thunks, { concurrency })` or `parallel(...)` for fan-out. Pass functions, not promises.
+- `workflow.pipeline(items, ...stages)` or `pipeline(...)` for per-item sequential stages with cross-item concurrency.
+- `workflow.configure({ name, description })` to name the general-purpose Fabric dashboard.
+- `workflow.phase(name, { id?, description?, total? })` or `phase(...)` for progress groups.
+- `workflow.item(...)` for non-agent work items whose status changes over time.
+- `workflow.event(...)` for notable milestones in the dashboard feed.
+- `workflow.log(...)` for compact progress notes.
+- `workflow.budget` for token-budget observations.
+
+Use `schema` in agent options when machine-readable output will make aggregation safer. It is ordinary JSON Schema.
+
+A good shape is:
+
+```ts
+await workflow.configure({
+  name: "Request analysis",
+  description: "Discover, analyze, and adversarially verify bounded work items",
+});
+
+await phase("Discover", { total: 1 });
+const inventory = await agent<{ items: string[] }>(
+  "Discover the bounded work items for this request. Return structured output.",
+  {
+    label: "inventory",
+    tools: ["read", "grep", "find", "ls"],
+    schema: {
+      type: "object",
+      properties: { items: { type: "array", items: { type: "string" } } },
+      required: ["items"],
+      additionalProperties: false,
+    },
+  },
+);
+
+await phase("Analyze", { total: inventory.items.length });
+const findings = await parallel(
+  inventory.items.map((item) => () =>
+    agent(`Analyze this bounded item and report evidence: ${item}`, {
+      label: `analyze ${item}`.slice(0, 50),
+      tools: ["read", "grep", "find", "ls"],
+    }),
+  ),
+  { concurrency: 8 },
+);
+
+await phase("Verify", { total: 1 });
+const result = await agent(
+  `Adversarially verify and synthesize these findings. Remove unsupported claims:\n${JSON.stringify(findings)}`,
+  { label: "verify synthesis", tools: ["read", "grep", "find", "ls"] },
+);
+
+await workflow.event({ message: "Verification complete", level: "success" });
+return { ok: true, result };
+```
+
+Adapt the phases and worker tools to the request. For edits, partition ownership by path or use `worktree: true`; never have concurrent agents edit the same files. Include a final verifier or synthesizer when conclusions come from multiple workers. Set `agentBudget` and `tokenBudget` on `fabric_exec` when the requested scale is potentially large.