pi-rolecast 0.2.0

package/README.md

@@ -0,0 +1,260 @@
+# pi-rolecast
+
+Multi-agent role framework for [Pi](https://github.com/earendil-works/pi-coding-agent).
+**Groups of specialist agents** (coding, video, ...) bound to per-role models
+and dispatched via `@<group>-<role>` mention syntax or the `Agent` tool.
+Profile-driven, gate-verified, language-agnostic.
+
+A profile is one YAML file under your project (`<project>/.pi/rolecast.yaml`)
+that decides which alias + channel serves each role and which commands the
+gate-runner must execute. The framework owns the **configuration contract**,
+not execution.
+
+## v0.2.0 breaking changes
+
+If you're coming from `pi-agent-workflow` v0.1.x, see [references/migration-from-rust-agent-workflow.md](references/migration-from-rust-agent-workflow.md). Summary:
+
+- Package renamed: `@rootazero/pi-agent-workflow` → `pi-rolecast` (unscoped).
+- Role names prefixed: `architect` → `coding-architect`, etc.
+- Profile filename: `.pi/agent-workflow.yaml` → `.pi/rolecast.yaml`.
+- Profile gains `workflow.role_groups: [coding]` field.
+- Role source moved: `agents/` → `role-packs/<group>/`.
+
+## Prerequisites
+
+- macOS or Linux
+- Python 3.10+ (3.12 is fine)
+- Node.js 20+ (only needed to build the Pi extension from source; pre-built `dist/` ships in the npm tarball)
+- For the install gate, a marker file for your language: `Cargo.toml`, `pyproject.toml`, `package.json + tsconfig.json`, or `go.mod`
+- A pi-compatible chat client (or `pi` CLI) to dispatch roles
+
+## Install
+
+### Via `pi install` (recommended)
+
+```bash
+# From a local checkout:
+pi install /Volumes/TBU/Workspace/pi-rolecast
+
+# From npm:
+pi install npm:pi-rolecast
+```
+
+This registers the framework as a Pi extension. After installing, run `/reload` in Pi. The extension exposes:
+
+- **Slash commands**: `/workflow-init`, `/workflow-validate`, `/workflow-diff`, `/workflow-run`
+- **Model-callable tools**: `scaffolder_init`, `scaffolder_validate`, `scaffolder_diff`, `gate_run`
+- **A `session_start` hook** that notifies when no `.pi/rolecast.yaml` is present
+
+The extension is a thin TypeScript bridge (`src/extension.ts` → `dist/extension.js`) that shells out to the Python CLI in `scripts/`. Python is the source of truth; the extension adds Pi integration on top.
+
+### Manual install (non-Pi consumers, or fall-back)
+
+From the framework root:
+
+```bash
+bash scripts/install.sh
+```
+
+Default prefix is `$HOME/.pi/agent/`. The installer:
+
+1. Creates `~/.pi/agent/pi-rolecast/` → symlink to this repo.
+2. Creates `~/.pi/agent/agents/<group>-<role>.md` → symlinks to `pi-rolecast/role-packs/<group>/<role>.md` for every role in every group. This is the location read by the **pi-subagents** extension.
+3. Removes the legacy `~/.pi/agent/pi-agent-workflow` symlink if found (v0.1.x).
+4. Removes any deprecated `~/.pi/agent/agent-<role>/SKILL.md` directories left over from earlier installs.
+5. If a profile is found in the current working directory (`.pi/rolecast.yaml` or legacy `.pi/agent-workflow.yaml`), runs `sync_settings.py` which both updates `~/.pi/agent/settings.json` and writes project-local `.pi/agents/<group>-<role>.md` files with `model:` + `thinking:` frontmatter populated from your bindings — these project-local copies override the global symlinks for that project (per pi-subagents precedence).
+6. Runs `python3 -m pip install --user -r requirements.txt` (PyYAML + pytest) unless PyYAML is already importable.
+
+Flags:
+
+- `--prefix DIR` — install under `DIR` instead of `~/.pi/agent/`
+- `--framework-root DIR` — treat `DIR` as the framework root (default: parent of `scripts/`)
+- `--no-pip` — skip the `pip install` step
+- `--dry-run` — print what would be created without writing anything
+- `--keep-old-layout` — skip removal of legacy `agent-<role>/SKILL.md` directories
+
+## Configure (bootstrap a project)
+
+```bash
+cd <your-project>
+python3 ~/.pi/agent/pi-rolecast/scripts/scaffolder.py init
+```
+
+The scaffolder inspects your tree, picks the matching template, and writes `<project>/.pi/rolecast.yaml` with sensible defaults (workflow.role_groups, gates, bindings, escalation). For multi-language projects it lists candidates and asks you to pick one with `--template`.
+
+Templates ship in `templates/{rust,typescript,python,go,blank}.yaml`. Each declares 11 role bindings (the `coding` group) and 2–3 gate phases (compile / lint / test).
+
+Validate and inspect:
+
+```bash
+python3 ~/.pi/agent/pi-rolecast/scripts/scaffolder.py validate \
+    --profile .pi/rolecast.yaml
+
+python3 ~/.pi/agent/pi-rolecast/scripts/scaffolder.py diff \
+    --profile .pi/rolecast.yaml
+```
+
+## Use
+
+### Via the Pi extension (recommended)
+
+After `pi install`, the extension exposes:
+
+**Slash commands:**
+
+```
+/workflow-init                 # scaffold .pi/rolecast.yaml
+/workflow-validate             # validate the project profile
+/workflow-diff                 # check for framework schema drift
+/workflow-run [phase]          # run gate-runner; phase defaults to all
+```
+
+**Model-callable tools** (the LLM can call these directly):
+
+- `scaffolder_init` — wraps `python3 scripts/scaffolder.py init`
+- `scaffolder_validate` — wraps `python3 scripts/scaffolder.py validate`
+- `scaffolder_diff` — wraps `python3 scripts/scaffolder.py diff`
+- `gate_run` — wraps `python3 scripts/gate_runner.py`
+
+**`session_start` hook** — if no `.pi/rolecast.yaml` is found in the project root, you'll see a one-time hint pointing to `/workflow-init`.
+
+### Via the manual install (shell only)
+
+```bash
+python3 ~/.pi/agent/pi-rolecast/scripts/gate_runner.py \
+    --profile .pi/rolecast.yaml
+```
+
+### Dispatching a role
+
+Roles use the **full prefixed name** in dispatch:
+
+```
+@coding-architect design a module boundary for the auth layer
+@coding-implementer add the new endpoint
+@coding-reviewer review this diff
+```
+
+The framework does not register `/role` slash commands. pi-subagents handles dispatch via the `@handle` mention syntax and the `Agent` tool. See [`references/dispatch-model-semantics.md`](references/dispatch-model-semantics.md) for the full mechanism.
+
+## Customise models
+
+Profile bindings reference **aliases** (e.g. `opus-thinking-medium`, `gpt-judgment-high`). Aliases resolve to specific models via `registry/aliases.yaml`.
+
+To override the registry **without editing the framework**, drop a YAML file at one of two layers (deep-merge precedence, lowest first):
+
+1. `<project>/.pi/rolecast-registry.yaml` — project-local (highest priority)
+2. `~/.pi/rolecast/registry-overrides.yaml` — user-global
+
+You can also override aliases at `<project>/.pi/rolecast-aliases-overrides.yaml` and `~/.pi/rolecast/aliases-overrides.yaml`.
+
+See [references/registry-resolution.md](references/registry-resolution.md) for the full algorithm.
+
+### Bridging profile bindings to pi dispatch
+
+Profile bindings (alias -> model + channel) live in `.pi/rolecast.yaml`. Pi subagent dispatch reads `~/.pi/agent/settings.json` -> `subagents.agentOverrides.<group>-<role>.model`. The bridge is `scripts/sync_settings.py`:
+
+```
+python3 ~/.pi/agent/pi-rolecast/scripts/sync_settings.py --dry-run
+python3 ~/.pi/agent/pi-rolecast/scripts/sync_settings.py --clear
+python3 ~/.pi/agent/pi-rolecast/scripts/sync_settings.py --status        # show current state vs profile bindings (no changes)
+python3 ~/.pi/agent/pi-rolecast/scripts/sync_settings.py --list-groups  # show available role groups from role-packs/
+```
+
+`bash scripts/install.sh` runs sync automatically when a profile is found in cwd.
+
+## Directory layout
+
+```
+pi-rolecast/
+├── SKILL.md                          # skill doc for pi
+├── README.md                         # this file
+├── package.json                      # npm + Pi `pi.extensions` declaration
+├── tsconfig.json                     # TypeScript build config
+├── src/
+│   └── extension.ts                  # Pi extension factory
+├── dist/                             # built TS (gitignored; shipped in npm tarball)
+├── scripts/
+│   ├── install.sh                    # framework installer
+│   ├── profile_loader.py             # load + validate a profile (v0.2.0 grouped roles)
+│   ├── gate_runner.py                # execute phases, write logs
+│   ├── scaffolder.py                 # init / diff / validate
+│   └── sync_settings.py              # profile -> pi settings.json bridge
+├── role-packs/
+│   └── coding/                       # 11 coding-specialist roles
+│       ├── coding-architect.md
+│       ├── coding-orchestrator.md
+│       └── …
+├── registry/
+│   ├── built_in.yaml                 # model registry (status, channels)
+│   └── aliases.yaml                  # alias → model
+├── templates/                        # scaffolder pre-fills
+│   ├── rust.yaml
+│   ├── typescript.yaml
+│   ├── python.yaml
+│   ├── go.yaml
+│   └── blank.yaml
+├── examples/
+│   └── rust/                         # reference profile
+├── references/                       # deep docs (one per concept)
+│   ├── profile-schema.md
+│   ├── registry-resolution.md
+│   ├── gate-runner-usage.md
+│   ├── scaffolder-usage.md
+│   ├── sync-settings-usage.md
+│   ├── dispatch-model-semantics.md
+│   └── migration-from-rust-agent-workflow.md
+└── tests/
+    ├── unit/                         # Python unit tests + TS extension smoke test
+    └── integration/                  # install + sample-rust fixtures + dispatch PoC
+```
+
+## How dispatch works
+
+The framework does not run a custom dispatch extension itself. Instead, the **pi-subagents** extension (third-party, by `@tintinweb`, install separately: `pi install npm:@tintinweb/pi-subagents`) reads each role's `model:` + `thinking:` frontmatter and dispatches accordingly.
+
+When `install.sh` or `sync_settings.py` runs against a project with a profile:
+
+- Global symlinks at `~/.pi/agent/agents/<group>-<role>.md` point at the framework defaults (`deepseek-flash` everywhere).
+- `sync_settings.py` then writes **project-local** copies at `<project>/.pi/agents/<group>-<role>.md` with `model:` + `thinking:` set from your profile bindings.
+
+**Project-local copies win** (pi-subagents' load order: project before global), so `@coding-architect` in a project will use whatever you bound `coding-architect` to.
+
+## Adding a new role group
+
+1. Create `role-packs/<group>/<role>.md` for each role in the new group. Frontmatter must include `name: <group>-<role>` (hyphen-namespaced).
+2. Add the group to `workflow.role_groups` in your profile.
+3. Add bindings for the new full role names in `bindings:`.
+4. Run `python3 scripts/sync_settings.py`.
+
+See [references/migration-from-rust-agent-workflow.md](references/migration-from-rust-agent-workflow.md) for the planned future groups (video, research, design, music).
+
+## Building from source
+
+```bash
+cd pi-rolecast
+npm install
+npm run build        # tsc → dist/
+npm test             # extension smoke test
+```
+
+The `dist/` directory is gitignored; the npm tarball includes the prebuilt output.
+
+## Reference docs
+
+- [Profile schema](references/profile-schema.md) — full YAML spec, every field, every validation rule.
+- [Registry resolution](references/registry-resolution.md) — alias → model + channel algorithm, override layers, status semantics.
+- [Dispatch model semantics](references/dispatch-model-semantics.md) — `@handle` mention vs `Agent` tool vs plain text; why `provider/modelId` is required.
+- [Gate runner usage](references/gate-runner-usage.md) — CLI, exit codes, escalation, logs.
+- [Scaffolder usage](references/scaffolder-usage.md) — `init` / `diff` / `validate`, auto-detect, templates.
+- [Sync settings usage](references/sync-settings-usage.md) — how profile bindings reach pi-subagents dispatch.
+- [Migration from rust-agent-workflow](references/migration-from-rust-agent-workflow.md) — v0.1.x → v0.2.0 upgrade path.
+
+## Related projects
+
+- **[@tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents)** — concurrent sub-agent execution with live monitoring. pi-rolecast owns the *profile + gate + scaffolder* layer; pi-subagents owns *concurrent AgentSession dispatch*. They compose.
+- **[Michaelliv/pi-dynamic-workflows](https://github.com/Michaelliv/pi-dynamic-workflows)** — dynamic workflow composition (different concern: workflows-as-data rather than profile-driven role bindings).
+
+## License
+
+MIT.

package/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: pi-rolecast
+description: Multi-agent role framework for Pi. Groups of specialist agents (coding, video, etc.) bound to per-role models, profile-driven, gate-verified. Use when you want a coordinated set of specialised agents with explicit model bindings per role and machine-checkable vs judgement routing.
+---
+
+# pi-rolecast
+
+A language-agnostic multi-agent framework. **Profiles** bind roles to models; **gates** verify the project compiles and tests pass; a **scaffolder** bootstraps a profile in any project. v0.2.0 introduces **role groups** (currently `coding`; future: `video`, `research`, `design`, `music`) so the framework can host non-coding roles without name clashes.
+
+## Install
+
+```bash
+bash $SKILL_ROOT/scripts/install.sh
+```
+
+Default prefix: `~/.pi/agent/`. The installer creates a symlink at `~/.pi/agent/pi-rolecast/` and one per-role symlink at `~/.pi/agent/agents/<group>-<role>.md` for every role under `role-packs/`, so pi-subagents' discovery picks them up.
+
+## Use in a project
+
+```bash
+cd <your-project>
+python3 $SKILL_ROOT/scripts/scaffolder.py init
+# auto-detects language, pre-fills from template, writes .pi/rolecast.yaml
+```
+
+Then run gates:
+
+```bash
+python3 $SKILL_ROOT/scripts/gate_runner.py --profile .pi/rolecast.yaml
+```
+
+## What this framework gives you
+
+- **Role groups** shipped under `role-packs/<group>/`. v0.2.0 ships the `coding` group with 11 specialist roles.
+- **Profile-driven model binding**: `bindings.<group>-<role>: { alias, channels }`. Aliases resolve via the built-in registry.
+- **Registry overrides** at user-global (`~/.pi/rolecast/registry-overrides.yaml`) and project-local (`<project>/.pi/rolecast-registry.yaml`).
+- **Custom roles** declared in profile; agent files live in `<project>/.pi/rolecast-agents/`.
+- **Gate runner** with per-phase escalation (`max_attempts`, `on_permanent_failure: stop | continue`).
+- **Scaffolder**: `init`, `diff`, `validate`.
+- **Rust example profile** under `examples/rust/profile.yaml`.
+
+## Dispatching agents
+
+`sync_settings.py` writes project-local agent files at `<cwd>/.pi/agents/<group>-<role>.md`
+with `model: provider/modelId` frontmatter. pi-subagents picks them up via its
+standard discovery. Two paths actually dispatch a subagent (both honour the
+binding):
+
+- **Mention syntax** in interactive `pi`: `@coding-architect design the API` — pi-subagents
+  intercepts in the `input` event and dispatches synchronously.
+- **Agent tool** from automation / workflows:
+  `Agent({ subagent_type: "coding-architect" })` or `SubagentWorkflow({ agentType: "coding-architect" })`.
+
+Plain text (e.g. `/architect ...`) does NOT dispatch — it is sent to the main LLM.
+See [Dispatch model semantics](references/dispatch-model-semantics.md) for the
+exact mechanism, why `provider/modelId` is required, and the upstream-bug
+caveat.
+
+## Concepts in one paragraph
+
+A profile is project-local. It declares gates (compile / lint / test commands), `workflow.role_groups` (which groups are enabled), bindings (which alias + channel serve each `<group>-<role>` or custom role), non-negotiables (forbidden patterns reviewed by the reviewer role), escalation policy, and optional custom roles. Aliases are framework-level names (`opus-thinking-medium`, `deepseek-verifiable`, `gpt-judgment-high`, etc.) that resolve to a specific model via `registry/aliases.yaml`, with a model having a `status` (`stable | deprecated | experimental | withdrawn`) and a list of channels it can be reached through. The framework does not own execution; it owns the configuration contract.
+
+## Reference docs
+
+- [Profile schema](references/profile-schema.md) — full YAML spec, every field, every validation rule, v0.1.x → v0.2.0 migration table.
+- [Registry resolution](references/registry-resolution.md) — alias → model + channel algorithm, override layers, status semantics.
+- [Dispatch model semantics](references/dispatch-model-semantics.md) — how `provider/modelId` reaches pi-subagents; `@handle` mention vs `Agent` tool vs plain text.
+- [Sync settings](references/sync-settings-usage.md) — how profile bindings reach pi-subagents dispatch (project-local agent files + settings.json bridge).
+- [Gate runner usage](references/gate-runner-usage.md) — CLI, exit codes, escalation, logs.
+- [Scaffolder usage](references/scaffolder-usage.md) — `init` / `diff` / `validate`, auto-detect, templates.
+- [Migration from rust-agent-workflow](references/migration-from-rust-agent-workflow.md) — v0.1.x → v0.2.0 upgrade path (package rename, role prefix, schema change).
+
+## Role catalogue (coding group)
+
+| Role | Output | Trigger |
+|---|---|---|
+| coding-orchestrator | judgement | (always-on) |
+| coding-architect | judgement | "design", "architect" |
+| coding-planner | verifiable | "plan" |
+| coding-implementer | verifiable | "implement", "code" |
+| coding-tester | verifiable | "write tests" |
+| coding-reviewer | judgement | "review this diff" |
+| coding-mapper | verifiable | "map", "repo map" |
+| coding-profiler | verifiable | "profile this" |
+| coding-auditor | judgement | "audit security" |
+| coding-canary | meta | "is the relay real" |
+| coding-docs | generation | "write README" |
+
+See `role-packs/coding/<role>.md` for each role's instructions.

package/dist/extension.d.ts

@@ -0,0 +1,25 @@
+/**
+ * pi-rolecast — Pi extension entrypoint.
+ *
+ * Bridges the framework's Python CLI (scripts/) to Pi as model-callable
+ * tools and slash commands. The Python scripts remain the source of truth;
+ * this module only shells out.
+ *
+ * Provides:
+ *   Tools (model-callable):
+ *     - scaffolder_init     wraps `python3 scripts/scaffolder.py init`
+ *     - scaffolder_validate wraps `python3 scripts/scaffolder.py validate`
+ *     - scaffolder_diff     wraps `python3 scripts/scaffolder.py diff`
+ *     - gate_run            wraps `python3 scripts/gate_runner.py`
+ *
+ *   Slash commands:
+ *     - /workflow-init      scaffold a project profile
+ *     - /workflow-validate  validate the project profile
+ *     - /workflow-diff      check for framework schema drift
+ *     - /workflow-run       run a gate phase
+ *
+ *   Event hooks:
+ *     - session_start: detect missing profile and notify
+ */
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function piRolecastExtension(pi: ExtensionAPI): void;

package/dist/extension.js

@@ -0,0 +1,287 @@
+/**
+ * pi-rolecast — Pi extension entrypoint.
+ *
+ * Bridges the framework's Python CLI (scripts/) to Pi as model-callable
+ * tools and slash commands. The Python scripts remain the source of truth;
+ * this module only shells out.
+ *
+ * Provides:
+ *   Tools (model-callable):
+ *     - scaffolder_init     wraps `python3 scripts/scaffolder.py init`
+ *     - scaffolder_validate wraps `python3 scripts/scaffolder.py validate`
+ *     - scaffolder_diff     wraps `python3 scripts/scaffolder.py diff`
+ *     - gate_run            wraps `python3 scripts/gate_runner.py`
+ *
+ *   Slash commands:
+ *     - /workflow-init      scaffold a project profile
+ *     - /workflow-validate  validate the project profile
+ *     - /workflow-diff      check for framework schema drift
+ *     - /workflow-run       run a gate phase
+ *
+ *   Event hooks:
+ *     - session_start: detect missing profile and notify
+ */
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+const execFileP = promisify(execFile);
+// ---- Resolution ----
+// dist/extension.js → ../ is the framework root.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FRAMEWORK_ROOT = resolve(__dirname, "..");
+const SCRIPTS = join(FRAMEWORK_ROOT, "scripts");
+const PYTHON = process.env.PYTHON ?? "python3";
+// v0.2.0: project profile is .pi/rolecast.yaml. Legacy .pi/agent-workflow.yaml
+// is still recognised for one release as a deprecation aid.
+const PROFILE_FILENAMES = ["rolecast.yaml", "agent-workflow.yaml"];
+const PROFILE_DIR = ".pi";
+function projectProfile(cwd) {
+    return join(cwd, PROFILE_DIR, PROFILE_FILENAMES[0]);
+}
+function findProjectProfile(cwd) {
+    const dir = join(cwd, PROFILE_DIR);
+    for (const name of PROFILE_FILENAMES) {
+        const p = join(dir, name);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+async function runPythonScript(script, args, options = {}) {
+    const cmd = PYTHON;
+    const cmdArgs = [join(SCRIPTS, script), ...args];
+    const cwd = options.cwd ?? process.cwd();
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    try {
+        const { stdout, stderr } = await execFileP(cmd, cmdArgs, {
+            cwd,
+            timeout: timeoutMs,
+            maxBuffer: 4 * 1024 * 1024,
+        });
+        return { exitCode: 0, stdout: String(stdout), stderr: String(stderr) };
+    }
+    catch (err) {
+        const e = err;
+        return {
+            exitCode: typeof e.code === "number" ? e.code : 1,
+            stdout: e.stdout ?? "",
+            stderr: e.stderr ?? e.message ?? String(err),
+        };
+    }
+}
+function summarize(result, maxChars = 6000) {
+    const parts = [];
+    if (result.stdout)
+        parts.push(result.stdout.trim());
+    if (result.stderr)
+        parts.push(`[stderr]\n${result.stderr.trim()}`);
+    const combined = parts.join("\n");
+    if (combined.length <= maxChars)
+        return combined;
+    return `${combined.slice(0, maxChars)}\n... (truncated, full output in script logs)`;
+}
+// ---- Tool: scaffolder_init ----
+const scaffolderInitTool = defineTool({
+    name: "scaffolder_init",
+    label: "Scaffolder Init",
+    description: [
+        "Bootstrap a pi-rolecast profile in the current project.",
+        "Auto-detects the project's language (Cargo.toml → rust, pyproject.toml → python,",
+        "package.json + tsconfig.json → typescript, go.mod → go) and writes",
+        ".pi/rolecast.yaml from the matching template. Idempotent: refuses to overwrite",
+        "an existing profile unless --force is passed.",
+    ].join(" "),
+    promptSnippet: "Bootstrap .pi/rolecast.yaml in the current project by auto-detecting the language and pre-filling from a template.",
+    promptGuidelines: [
+        "Use scaffolder_init when the user asks to set up a workflow profile, scaffold a project, or wants the framework to write its config file.",
+        "Do NOT use this to validate or diff an existing profile — use scaffolder_validate / scaffolder_diff for that.",
+        "If the project has multiple language markers, pass --template to pick one; otherwise the tool errors with the list of candidates.",
+    ],
+    parameters: Type.Object({
+        template: Type.Optional(Type.Union([
+            Type.Literal("rust"),
+            Type.Literal("typescript"),
+            Type.Literal("python"),
+            Type.Literal("go"),
+            Type.Literal("blank"),
+        ], {
+            description: "Template name. Pass this when the project has multiple language markers or to override auto-detect.",
+        })),
+        force: Type.Optional(Type.Boolean({
+            description: "Overwrite an existing .pi/rolecast.yaml if present. Default: refuse.",
+        })),
+        dry_run: Type.Optional(Type.Boolean({ description: "Print what would be created without writing." })),
+    }),
+    async execute(_id, params, _signal, _onUpdate, _ctx) {
+        const args = ["init"];
+        if (params.template)
+            args.push("--template", params.template);
+        if (params.force)
+            args.push("--force");
+        if (params.dry_run)
+            args.push("--dry-run");
+        const result = await runPythonScript("scaffolder.py", args);
+        return {
+            content: [{ type: "text", text: summarize(result) }],
+            details: { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr },
+        };
+    },
+});
+// ---- Tool: scaffolder_validate ----
+const scaffolderValidateTool = defineTool({
+    name: "scaffolder_validate",
+    label: "Scaffolder Validate",
+    description: [
+        "Validate the project's .pi/rolecast.yaml profile against the framework schema.",
+        "Checks every binding resolves to a known alias + model + channel; rejects unknown roles,",
+        "trigger collisions, missing framework_version, etc. Delegates to profile_loader.load_profile.",
+    ].join(" "),
+    promptSnippet: "Validate the project profile against the framework schema.",
+    promptGuidelines: [
+        "Use scaffolder_validate after editing a profile or before running gates to catch typos early.",
+        "If it reports INVALID, do NOT run gates — fix the violations first.",
+    ],
+    parameters: Type.Object({
+        profile_path: Type.Optional(Type.String({
+            description: "Path to the profile YAML. Default: .pi/rolecast.yaml relative to the current working directory.",
+        })),
+    }),
+    async execute(_id, params, _signal, _onUpdate, _ctx) {
+        const args = ["validate"];
+        if (params.profile_path)
+            args.push("--profile", params.profile_path);
+        const result = await runPythonScript("scaffolder.py", args);
+        return {
+            content: [{ type: "text", text: summarize(result) }],
+            details: { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr },
+        };
+    },
+});
+// ---- Tool: scaffolder_diff ----
+const scaffolderDiffTool = defineTool({
+    name: "scaffolder_diff",
+    label: "Scaffolder Diff",
+    description: [
+        "Compare the project profile's framework_version against the current framework version",
+        "and report any fields added or removed in newer framework schemas. No auto-merge —",
+        "you decide what to update.",
+    ].join(" "),
+    promptSnippet: "Check whether the project profile is out of date with the current framework schema.",
+    promptGuidelines: [
+        "Use scaffolder_diff after upgrading pi-rolecast to see what changed in the schema.",
+        "The tool does NOT modify the profile — apply any updates manually.",
+    ],
+    parameters: Type.Object({
+        profile_path: Type.Optional(Type.String({
+            description: "Path to the profile YAML. Default: .pi/rolecast.yaml relative to the current working directory.",
+        })),
+    }),
+    async execute(_id, params, _signal, _onUpdate, _ctx) {
+        const args = ["diff"];
+        if (params.profile_path)
+            args.push("--profile", params.profile_path);
+        const result = await runPythonScript("scaffolder.py", args);
+        return {
+            content: [{ type: "text", text: summarize(result) }],
+            details: { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr },
+        };
+    },
+});
+// ---- Tool: gate_run ----
+const gateRunTool = defineTool({
+    name: "gate_run",
+    label: "Gate Run",
+    description: [
+        "Execute the project's gate-runner. Runs declared gate phases (compile / lint / test etc.)",
+        "in order, with per-phase retry + escalation per the profile.",
+        "Exit code 0 = all phases pass; 1 = a phase failed after retries; 2 = config error.",
+        "Logs land under <project>/.pi/rolecast-logs/<timestamp>/.",
+    ].join(" "),
+    promptSnippet: "Run the project's gate-runner to verify compilation / lint / tests after code changes.",
+    promptGuidelines: [
+        "Use gate_run after implementation changes that should compile or pass tests.",
+        "Pass phase to run a single phase when iterating; omit to run all in order.",
+        "gate_run does NOT enforce non-negotiables — those are checked by the reviewer role at diff-review time.",
+    ],
+    parameters: Type.Object({
+        profile_path: Type.Optional(Type.String({
+            description: "Path to the profile YAML. Default: .pi/rolecast.yaml relative to the current working directory.",
+        })),
+        phase: Type.Optional(Type.String({
+            description: "Phase name to run (e.g. 'compile', 'lint', 'test'). Omit to run all phases in declared order.",
+        })),
+        log_dir: Type.Optional(Type.String({
+            description: "Override the default log directory (.pi/rolecast-logs/).",
+        })),
+    }),
+    async execute(_id, params, _signal, _onUpdate, _ctx) {
+        const args = [];
+        if (params.profile_path)
+            args.push("--profile", params.profile_path);
+        if (params.phase)
+            args.push("--phase", params.phase);
+        if (params.log_dir)
+            args.push("--log-dir", params.log_dir);
+        // 10 minute ceiling so retries don't run forever in interactive sessions.
+        const result = await runPythonScript("gate_runner.py", args, { timeoutMs: 10 * 60_000 });
+        return {
+            content: [{ type: "text", text: summarize(result) }],
+            details: { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr },
+        };
+    },
+});
+function profileStatus(cwd) {
+    return { exists: existsSync(projectProfile(cwd)), path: projectProfile(cwd) };
+}
+// ---- Extension factory ----
+export default function piRolecastExtension(pi) {
+    // Register all four tools so the model can call them.
+    pi.registerTool(scaffolderInitTool);
+    pi.registerTool(scaffolderValidateTool);
+    pi.registerTool(scaffolderDiffTool);
+    pi.registerTool(gateRunTool);
+    // Slash commands mirror the tools for direct user invocation.
+    pi.registerCommand("workflow-init", {
+        description: "Bootstrap .pi/rolecast.yaml in the current project.",
+        handler: async (args, ctx) => {
+            const parts = args.trim().split(/\s+/).filter(Boolean);
+            const pyArgs = ["init", ...parts];
+            const result = await runPythonScript("scaffolder.py", pyArgs);
+            ctx.ui.notify(summarize(result, 2000), result.exitCode === 0 ? "info" : "error");
+        },
+    });
+    pi.registerCommand("workflow-validate", {
+        description: "Validate the current project's profile.",
+        handler: async (_args, ctx) => {
+            const result = await runPythonScript("scaffolder.py", ["validate"]);
+            ctx.ui.notify(summarize(result, 2000), result.exitCode === 0 ? "info" : "error");
+        },
+    });
+    pi.registerCommand("workflow-diff", {
+        description: "Check the project profile for framework schema drift.",
+        handler: async (_args, ctx) => {
+            const result = await runPythonScript("scaffolder.py", ["diff"]);
+            ctx.ui.notify(summarize(result, 2000), result.exitCode === 0 ? "info" : "error");
+        },
+    });
+    pi.registerCommand("workflow-run", {
+        description: "Run the project's gate-runner. Usage: /workflow-run [phase]",
+        handler: async (args, ctx) => {
+            const phase = args.trim();
+            const pyArgs = phase ? ["--phase", phase] : [];
+            const result = await runPythonScript("gate_runner.py", pyArgs, { timeoutMs: 10 * 60_000 });
+            ctx.ui.notify(summarize(result, 2000), result.exitCode === 0 ? "info" : "error");
+        },
+    });
+    // Detect missing profile on session start and surface it as a one-time hint.
+    pi.on("session_start", (_event, ctx) => {
+        const status = profileStatus(ctx.cwd);
+        if (!status.exists) {
+            ctx.ui.notify(`pi-rolecast: no profile found at ${status.path}. Run /workflow-init to bootstrap one.`, "info");
+        }
+    });
+}