pi-rolecast 0.2.0

package/examples/rust/README.md

@@ -0,0 +1,22 @@
+# Rust example profile (pi-rolecast v0.2.0)
+
+This directory contains the reference profile for the `coding` group of
+pi-rolecast v0.2.0. It reproduces the routing decisions of the original
+`rust-agent-workflow` skill (pre-2026-10-03), adapted to the new
+grouped-role schema.
+
+## Purpose
+
+Users should:
+
+1. Run `scaffolder init --template rust` in their project.
+2. Diff the generated profile against `examples/rust/profile.yaml`.
+3. If differences exist, decide deliberately which is canonical.
+
+This file is the **ground truth** for "what the coding group does for Rust projects". If your scaffolder-generated profile diverges, file an issue.
+
+## What this is NOT
+
+This is not a one-click migration from `rust-agent-workflow`. See
+`references/migration-from-rust-agent-workflow.md` for the v0.1.x → v0.2.0
+upgrade path.

package/examples/rust/profile.yaml

@@ -0,0 +1,51 @@
+# Reference profile reproducing today's rust-agent-workflow routing,
+# updated for pi-rolecast v0.2.0 (grouped roles, hyphen-prefixed names).
+# Generated manually from the old SKILL.md; this is the ground truth
+# users cross-check their scaffolder-generated profile against.
+
+framework_version: 0.2.0
+name: rust-rolecast-example
+description: |
+  Reference Rust profile preserving the routing decisions of the original
+  rust-agent-workflow skill, updated to the v0.2.0 grouped-role schema.
+  Use scaffolder init --template rust in your project to generate a
+  similar profile; this file is the canonical reference for cross-checking.
+
+workflow:
+  role_groups: [coding]
+
+gates:
+  compile:
+    commands: [cargo check --message-format short --all-targets]
+    timeout: 300
+  lint:
+    commands: [cargo clippy -- -D warnings]
+    timeout: 300
+  test:
+    commands: [cargo test]
+    timeout: 900
+
+bindings:
+  coding-architect:    {alias: opus-thinking-medium, channels: [official]}
+  coding-planner:      {alias: deepseek-verifiable, channels: [official]}
+  coding-implementer:  {alias: deepseek-verifiable, channels: [official]}
+  coding-tester:       {alias: deepseek-verifiable, channels: [official]}
+  coding-reviewer:     {alias: gpt-judgment-high, channels: [official, relay-default]}
+  coding-mapper:       {alias: deepseek-verifiable, channels: [official]}
+  coding-profiler:     {alias: deepseek-verifiable, channels: [official]}
+  coding-auditor:      {alias: opus-thinking-high, channels: [official]}
+  coding-canary:       {alias: minimax-fast, channels: [official]}
+  coding-docs:         {alias: minimax-medium, channels: [official]}
+  coding-orchestrator: {alias: gpt-judgment-medium, channels: [official, relay-default]}
+
+non_negotiables:
+  forbidden_patterns:
+    - pattern: '#\[allow\('
+      message: "never silence a diagnostic with #[allow(...)]"
+    - pattern: '\.unwrap\(\)'
+      message: "no bare .unwrap() — handle the Result"
+
+escalation:
+  max_attempts: 2
+  on_permanent_failure: stop
+  preserve_logs: true

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "pi-rolecast",
+  "version": "0.2.0",
+  "description": "Multi-agent role framework for Pi. Groups of specialist agents (coding, video, etc.) bound to per-role models, dispatched via pi-subagents. Profile-driven, gate-verified, language-agnostic.",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "rootazero",
+    "email": "zouguojunx@gmail.com"
+  },
+  "homepage": "https://github.com/rootazero/pi-rolecast#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rootazero/pi-rolecast.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rootazero/pi-rolecast/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/extension.js",
+  "types": "./dist/extension.d.ts",
+  "files": [
+    "dist/",
+    "scripts/*.py",
+    "scripts/*.sh",
+    "!scripts/__pycache__/",
+    "!scripts/**/__pycache__/",
+    "!scripts/*.pyc",
+    "role-packs/",
+    "registry/",
+    "templates/",
+    "examples/",
+    "references/",
+    "SKILL.md",
+    "README.md",
+    "requirements.txt"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test": "tsx --test tests/unit/test_extension.ts",
+    "prepublishOnly": "npm run typecheck && npm run build && npm test"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "agents",
+    "roles",
+    "rolecast",
+    "multi-agent",
+    "scaffolder",
+    "gate-runner"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.84.0",
+    "@earendil-works/pi-coding-agent": ">=0.84.0",
+    "@earendil-works/pi-tui": ">=0.84.0"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/extension.js"
+    ]
+  },
+  "devDependencies": {
+    "tsx": "^4.23.15"
+  }
+}

package/references/dispatch-model-semantics.md

@@ -0,0 +1,110 @@
+---
+title: Dispatch model semantics
+description: How role model bindings flow through pi-subagents dispatch paths
+---
+
+# Dispatch model semantics
+
+`sync_settings.py` writes project-local agent files at `<cwd>/.pi/agents/<role>.md`
+with a `model: provider/modelId` frontmatter field for every profile binding.
+This doc explains how that field is consumed on each dispatch path.
+
+## The three dispatch paths in pi-subagents
+
+### Path 1: Plain text prompt (no `@` mention)
+
+- User types `design the API` or `/architect design the API` directly
+- pi checks for a registered slash command — `/architect` is **not** registered
+  (only `/agents` is, by pi-subagents itself)
+- Text falls through to the `input` event and reaches the **main LLM**
+- The main LLM may decide to call the `agent` tool with
+  `subagent_type: "architect"`, but that is its choice — not guaranteed
+- The main LLM uses the session's default model
+
+> **Pitfall.** Typing `/architect design the API` does *not* dispatch a
+> subagent. It is just text the main LLM sees. To get a guaranteed
+> subagent dispatch you must use either Path 2 (`@handle` syntax) or Path 3
+> (the `agent` tool).
+
+### Path 2: `@handle` mention syntax (Claude Code style)
+
+- User types `@architect design the API`
+- pi-subagents' `input` handler (`dist/index.js` ≈ line 800) intercepts the
+  text. The mention regex is `/^@([\w-]+)\s+([\s\S]+)$/`
+- pi-subagents dispatches **synchronously** to a subagent with the agent
+  file's `model:` and `thinking:` fields
+- The subagent session is **fresh**; the parent's model does not change
+
+> **Quirk.** This path requires `@` (not `/`) and at least one space before
+> the message. `@architect` with no message is left alone.
+
+### Path 3: `agent` tool / `SubagentWorkflow`
+
+- `Agent({ subagent_type: 'architect' })` or
+  `SubagentWorkflow({ agentType: 'architect' })` — model-driven dispatch
+- The new subagent session uses the agent file's `model:` and `thinking:`
+- `resolveDefaultModel` (`@tintinweb/pi-subagents/dist/agent-runner.js`
+  ≈ line 316) parses `provider/modelId` and resolves via the model registry
+
+```js
+// Agent tool example (subagent_type matches the role name)
+await parallel([
+  () => agent("design the API", { label: 'architect', agentType: 'architect' }),
+  () => agent("implement it",  { label: 'impl',     agentType: 'implementer' }),
+])
+
+// SubagentWorkflow
+await agent('coordinate the build', { agentType: 'orchestrator' })
+```
+
+## Why `provider/modelId` format
+
+`resolveDefaultModel` does:
+
+```js
+if (configModel) {
+  const slashIdx = configModel.indexOf("/");
+  if (slashIdx !== -1) {
+    const provider = configModel.slice(0, slashIdx);
+    const modelId  = configModel.slice(slashIdx + 1);
+    // resolve in registry.find(provider, modelId)
+  }
+}
+return parentModel;  // silent fallback
+```
+
+A plain `model: MiniMax-M3` (no slash) is rejected. The runner silently
+falls back to the parent session's model — which is usually the default
+model set at startup.
+
+`sync_settings.py` therefore rewrites every binding to
+`provider/modelId`. The mapping lives in the script as `VENDOR_TO_PROVIDER`:
+
+| registry `vendor` | pi provider key   | example model binding         |
+| ----------------- | ----------------- | ----------------------------- |
+| `minimax`         | `minimax-cn`      | `minimax-cn/MiniMax-M3`       |
+| `deepseek`        | `deepseek`        | `deepseek/deepseek-flash`     |
+| `openai`          | `openai-codex`    | `openai-codex/gpt-6.1-sol`    |
+| `moonshotai`      | `kimi-coding`     | `kimi-coding/kimi-for-coding` |
+| `typesafe`        | `typesafe`        | `typesafe/jev-latest`         |
+
+If your registry uses a vendor not in the table, add it to the script's
+`VENDOR_TO_PROVIDER` and re-run `sync_settings.py`.
+
+## Summary
+
+| Path                | Dispatch mechanism | Binding honoured? | Caveats                          |
+| ------------------- | ------------------ | ----------------- | -------------------------------- |
+| Plain text          | main LLM           | no                | model is session default         |
+| `@handle` mention   | sync subagent      | **yes**           | needs `@` + space + message      |
+| `agent` tool        | sync subagent      | **yes**           | model-driven, needs no @ syntax  |
+| `SubagentWorkflow`  | subagent pipeline  | **yes**           | orchestrator pattern             |
+
+## Practical usage
+
+For interactive `pi` sessions, the cleanest invocation is the `@handle`
+mention. For automation and subagent pipelines, use `agent` /
+`SubagentWorkflow` with `subagent_type` / `agentType`.
+
+The `sync_settings.py` output is the same for both — `provider/modelId` is
+all that matters.

package/references/gate-runner-usage.md

@@ -0,0 +1,19 @@
+# Gate runner usage (pi-rolecast v0.2.0)
+
+```bash
+python3 $SKILL_ROOT/scripts/gate_runner.py \
+    --profile .pi/rolecast.yaml \
+    [--phase NAME | --phase all] \
+    [--log-dir DIR] \
+    [--framework-root DIR]
+```
+
+The `--profile` flag also accepts the legacy `.pi/agent-workflow.yaml` filename for one release.
+
+Exit codes: `0` (all phases pass), `1` (phase failed after retries), `2` (config error).
+
+Phases run in declared order. Default escalation: `max_attempts=2`, `on_permanent_failure=stop`, `preserve_logs=true`.
+
+Logs written to `<log-dir>/<timestamp>/<phase>-attempt<N>.log` plus `summary.json` on stdout. Default log directory is `.pi/rolecast-logs/` (was `.pi/agent-workflow-logs/` in v0.1.x).
+
+Non-negotiables are NOT enforced by gate-runner; the reviewer agent checks them at diff-review time.

package/references/migration-from-rust-agent-workflow.md

@@ -0,0 +1,107 @@
+# Migration from v0.1.x (pi-agent-workflow) to v0.2.0 (pi-rolecast)
+
+v0.2.0 is a **breaking release**. The package is renamed from `@rootazero/pi-agent-workflow` (scoped) to `pi-rolecast` (unscoped), roles are now grouped, and role names are hyphen-prefixed.
+
+## Summary of changes
+
+| Area | v0.1.x | v0.2.0 |
+|---|---|---|
+| npm package | `@rootazero/pi-agent-workflow` | `pi-rolecast` |
+| Profile filename | `.pi/agent-workflow.yaml` | `.pi/rolecast.yaml` (legacy still recognised) |
+| Role source dir | `agents/<role>.md` | `role-packs/<group>/<role>.md` |
+| Role name format | `architect` | `coding-architect` (full prefixed) |
+| Role scope | All roles are coding | Groups: coding, video, research, ... (future) |
+| Profile field `workflow.role_groups` | (did not exist) | required top-level field |
+| Dispatch mention | `@architect` | `@coding-architect` |
+| Agent tool subagent_type | `architect` | `coding-architect` |
+| Registry user-global dir | `~/.pi/agent-workflow/` | `~/.pi/rolecast/` |
+| Log directory | `.pi/agent-workflow-logs/` | `.pi/rolecast-logs/` |
+
+## Step-by-step migration
+
+```bash
+# 1. Uninstall the old package (keeps your project profile + agent files intact)
+pi uninstall npm:@rootazero/pi-agent-workflow
+
+# 2. Install the new package
+pi install npm:pi-rolecast
+
+# 3. In each project, re-run scaffolder to regenerate the profile
+cd <your-project>
+python3 $SKILL_ROOT/scripts/scaffolder.py init --template <lang> --force
+
+# 4. Rename your profile file (optional — legacy name still works)
+mv .pi/agent-workflow.yaml .pi/rolecast.yaml
+
+# 5. Re-sync project-local agent files
+python3 $SKILL_ROOT/scripts/sync_settings.py
+```
+
+## Profile diff (before / after)
+
+**Before (v0.1.x):**
+
+```yaml
+framework_version: 0.1.0
+name: my-project
+description: ...
+gates:
+  compile: {commands: [cargo check], timeout: 300}
+bindings:
+  architect:      {alias: opus-thinking-medium, channels: [official]}
+  implementer:    {alias: deepseek-verifiable, channels: [official]}
+```
+
+**After (v0.2.0):**
+
+```yaml
+framework_version: 0.2.0
+name: my-project
+description: ...
+workflow:
+  role_groups: [coding]
+gates:
+  compile: {commands: [cargo check], timeout: 300}
+bindings:
+  coding-architect:    {alias: opus-thinking-medium, channels: [official]}
+  coding-implementer:  {alias: deepseek-verifiable, channels: [official]}
+```
+
+## What if I'm coming from the original `rust-agent-workflow`?
+
+If you started on the very first `rust-agent-workflow` skill (pre-pi-agent-workflow), see the role-name translation below. The original skill used unprefixed names; pi-agent-workflow kept them; pi-rolecast prefixes them with the group.
+
+| Original | v0.2.0 |
+|---|---|
+| (main) | coding-orchestrator |
+| rust-architect | coding-architect |
+| contract-planner | coding-planner |
+| codemod | coding-implementer |
+| test-writer | coding-tester |
+| final-reviewer | coding-reviewer |
+| repo-mapper | coding-mapper |
+| perf-profiler | coding-profiler |
+| safety-auditor | coding-auditor |
+| relay-canary | coding-canary |
+| docs-visual | coding-docs |
+
+## Role groups roadmap
+
+v0.2.0 ships with the `coding` group only. Future groups planned for separate releases:
+
+- `video` — scriptwriter, narrator-prompt, thumbnail-designer, video-editor, transcript-cleaner, caption-styler, seo-optimizer, hook-generator
+- `research` — literature-reviewer, data-analyst, fact-checker, summarizer
+- `design` — ux-reviewer, copywriter, asset-curator, brand-checker
+- `music` — composer, lyricist, mix-engineer, mastering-engineer
+
+To enable a group once it's installed, add it to `workflow.role_groups`. Each group ships its own aliases + bindings defaults in its templates.
+
+## Deprecation plan
+
+The v0.2.0 release keeps these compatibility shims for **one** release cycle (until v0.3.0):
+
+- `.pi/agent-workflow.yaml` still loads (with a stderr hint).
+- Legacy unprefixed role names in `bindings:` print a hint pointing to the new prefixed name.
+- The framework symlink path `~/.pi/agent/pi-agent-workflow` is removed on install (warning printed if found).
+
+After v0.3.0 these shims will be removed and v0.2.x profiles will be the only supported format.

package/references/profile-schema.md

@@ -0,0 +1,66 @@
+# Profile schema reference (pi-rolecast v0.2.0)
+
+Full schema lives at `docs/superpowers/specs/2026-10-03-pi-agent-workflow-design.md` (historical) and the live validator at `scripts/profile_loader.py`.
+
+## Top-level fields
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `framework_version` | string | yes | Must match the installed framework version (e.g. `0.2.0`). |
+| `name` | string | yes | Human-readable profile name. |
+| `description` | string | yes | One-paragraph summary. |
+| `workflow` | mapping | yes (v0.2.0+) | Holds `role_groups`. |
+| `workflow.role_groups` | list[string] | yes | Which role groups are enabled. Empty list = no roles enabled. |
+| `gates` | mapping | yes | Phase name → `{commands, timeout}`. May be empty. |
+| `bindings` | mapping | yes | Full role name (`<group>-<role>` or custom name) → `{alias, channels}`. May be empty. |
+| `non_negotiables` | mapping | no | `forbidden_patterns`, `scope_constraints`, `required_gates`. |
+| `escalation` | mapping | no | `max_attempts`, `on_permanent_failure`, `preserve_logs`. |
+| `trigger_overrides` | mapping | no | Phrase → `{role}`. |
+| `custom_roles` | list | no | User-defined roles. |
+
+## Roles and groups
+
+Roles live in `role-packs/<group>/<role>.md` in the framework installation. The v0.2.0 release ships the `coding` group with 11 roles. Each role md file has YAML frontmatter:
+
+```yaml
+---
+name: coding-architect
+category: coding
+description: Design system boundaries, public APIs, error strategies.
+model: deepseek-flash
+thinking: high
+---
+```
+
+The `name:` field is the full role name used in profile bindings and dispatch mentions. It must match `<group>-<role>` so the `<group>-<role>` mention syntax (`@coding-architect`) works through pi-subagents.
+
+Profile bindings reference these full names:
+
+```yaml
+bindings:
+  coding-architect:    {alias: opus-thinking-medium, channels: [official]}
+  coding-implementer:  {alias: deepseek-verifiable, channels: [official]}
+  # ...
+```
+
+## Validation rules
+
+1. `bindings` keys must be one of the role names from enabled `workflow.role_groups`, OR a `custom_roles` entry.
+2. Each `alias` must resolve to a non-`withdrawn` model in the merged registry.
+3. Each `channels` entry must be one the resolved model supports.
+4. `gates` phases run in declared order; `--phase <undeclared>` is a config error.
+5. Trigger phrase collisions across framework defaults + profile overrides + custom role triggers → error.
+6. `forbidden_patterns[*].pattern` must compile as a regex.
+7. `workflow.role_groups` must be a list of strings; group names not present in `role-packs/` cause the loader to skip them silently (an empty group is treated as "no roles available").
+
+## Migration from v0.1.x
+
+The legacy profile filename `.pi/agent-workflow.yaml` is still recognised for one release. Profile schema changes required:
+
+| v0.1.x field | v0.2.0 replacement |
+|---|---|
+| `bindings: { architect: ... }` | `bindings: { coding-architect: ... }` + `workflow.role_groups: [coding]` |
+| Profile file `.pi/agent-workflow.yaml` | `.pi/rolecast.yaml` |
+| (no equivalent) | `workflow.role_groups: [...]` |
+
+The profile loader prints a one-line hint when a legacy role name is detected in a binding.

package/references/registry-resolution.md

@@ -0,0 +1,14 @@
+# Registry resolution reference (pi-rolecast v0.2.0)
+
+Algorithm: spec §6.4 (7 steps).
+
+Three override layers, deep-merged in order (later wins):
+1. Built-in: `<framework>/registry/{built_in,aliases}.yaml`
+2. User-global: `~/.pi/rolecast/{registry,aliases}-overrides.yaml` (renamed from `~/.pi/agent-workflow/` in v0.2.0)
+3. Project-local: `<project>/.pi/rolecast-registry.yaml` (renamed from `agent-workflow-registry.yaml` in v0.2.0)
+
+Status semantics:
+- `stable` — resolves normally.
+- `deprecated` — resolves with a warning.
+- `experimental` — resolves; scaffolder init skips it from defaults.
+- `withdrawn` — does NOT resolve. Profile fails to load.

package/references/scaffolder-usage.md

@@ -0,0 +1,27 @@
+# Scaffolder usage (pi-rolecast v0.2.0)
+
+## init
+
+```bash
+python3 $SKILL_ROOT/scripts/scaffolder.py init [--template LANG] [--blank] [--dry-run] [--force]
+```
+
+Auto-detects language from project files (Cargo.toml → rust, pyproject.toml → python, package.json+tsconfig.json → typescript, go.mod → go). Multi-language projects print a list; pass `--template` to pick.
+
+Templates ship under `<framework>/templates/{rust,typescript,python,go,blank}.yaml`. The generated profile lands at `<project>/.pi/rolecast.yaml` and includes `workflow.role_groups: [coding]` by default.
+
+## validate
+
+```bash
+python3 $SKILL_ROOT/scripts/scaffolder.py validate --profile <path>
+```
+
+Default profile path: `.pi/rolecast.yaml`. Legacy `.pi/agent-workflow.yaml` is also accepted. Delegates to `profile_loader.load_profile`. Exit code 0 = valid, non-zero = error.
+
+## diff
+
+```bash
+python3 $SKILL_ROOT/scripts/scaffolder.py diff --profile <path>
+```
+
+Reads `profile.framework_version` and reports fields added/removed in newer framework schemas. No auto-merge.

package/references/sync-settings-usage.md

@@ -0,0 +1,67 @@
+# Sync settings usage (pi-rolecast v0.2.0)
+
+The framework's profile bindings (alias -> model + channel) need to reach the actual Pi subagent dispatcher. `sync_settings.py` is that bridge.
+
+## What it writes
+
+When you run sync_settings against a project with a profile, two things happen:
+
+1. **settings.json** — `~/.pi/agent/settings.json` -> `subagents.agentOverrides.<full-role-name>.{model,channel}` for each bound role. (Pi core does not currently read this key for dispatch; it is kept for parity with prior skills and debugging.)
+2. **Project-local agent files** — `<project>/.pi/agents/<group>-<role>.md` is written with `model:` and `thinking:` frontmatter set from your binding. The full role name matches the binding key so pi-subagents can find it via `@<full-role-name>` mention syntax or `subagent_type: "<full-role-name>"`.
+
+## Commands
+
+```bash
+python3 $SKILL_ROOT/scripts/sync_settings.py \
+    --profile .pi/rolecast.yaml \       # source of truth (legacy .pi/agent-workflow.yaml also accepted)
+    --framework-root $SKILL_ROOT        # where role-packs/ lives
+```
+
+Useful flags:
+- `--status` — show current sync state vs profile bindings; flags `DRIFT` if a project-local agent file's model field was manually edited away from the binding. Exits 0 regardless (informational only).
+- `--dry-run` — print what would be written without touching disk.
+- `--clear` — remove all `agentOverrides` from settings.json and delete every project-local agent file. User-made files and symlinks in the agents dir are preserved.
+- `--no-settings` / `--no-agents` — skip settings.json / project-local agent files respectively.
+- `--agents-dir <path>` — override the default `.pi/agents/` location.
+- `--settings <path>` — override `~/.pi/agent/settings.json`.
+- `--list-groups` — list available role groups from `role-packs/` and exit.
+
+## When sync runs
+
+- Automatically by `scripts/install.sh` whenever a profile is found in the cwd.
+- Manually by you whenever you edit `.pi/rolecast.yaml` and want the change to take effect.
+
+## pi-subagents dependency
+
+`@tintinweb/pi-subagents` must be installed for role dispatch to actually work. `install.sh` warns when it's missing:
+
+```
+WARNING: pi-subagents not found in ~/.pi/agent/settings.json packages[]
+  Role symlinks are installed but dispatch won't work without pi-subagents.
+  Install with:  pi install npm:@tintinweb/pi-subagents
+```
+
+## `model:` resolution chain
+
+When sync_settings resolves `model:` for a binding:
+
+1. Profile binding specifies an alias (e.g. `opus-thinking-medium`).
+2. Alias resolution uses the 3-layer registry merge (built-in -> user-global `~/.pi/rolecast/registry-overrides.yaml` -> project-local `.pi/rolecast-registry.yaml`). The alias points to a model ID (e.g. `MiniMax-M3`).
+3. That model ID is rewritten to `provider/modelId` (see below) and written into the project-local agent file's `model:` frontmatter.
+
+## `thinking:` resolution
+
+The project-local agent file's `thinking:` field is preserved from the role-packs/<group>/<role>.md default. Each role's default is set by its output category:
+- Judgement roles (orchestrator, architect, auditor, reviewer): `high`
+- Meta roles (mapper, planner, profiler, docs): `medium`
+- Verifiable roles (implementer, tester, canary): `low`
+
+If you want to override `thinking:` per project, edit the project-local file after sync.
+
+## provider/modelId format
+
+`sync_settings.py` rewrites each binding to `provider/modelId` (e.g.
+`minimax-cn/MiniMax-M3`, `openai-codex/gpt-6.1-sol`) before writing it
+into the agent file. `pi-subagents` `resolveDefaultModel` only parses
+strings that contain a `/`; plain `MiniMax-M3` would silently fall back to
+the parent session's model. See [`dispatch-model-semantics.md`](./dispatch-model-semantics.md) for the full explanation.

package/registry/aliases.yaml

@@ -0,0 +1,38 @@
+# Built-in alias set. Profiles reference aliases; framework resolves them.
+# Adding an alias = PR; renaming an alias = breaking change.
+
+aliases:
+  opus-thinking-medium:
+    preferred:       claude-opus-5-5
+    fallback_chain:  [claude-sonnet-5-5]
+    notes: "Frontier reasoning + thinking; judgement work"
+
+  opus-thinking-high:
+    preferred:       claude-opus-5-5
+    fallback_chain:  []
+    notes: "High-effort reasoning"
+
+  gpt-judgment-medium:
+    preferred:       gpt-6.1-sol
+    fallback_chain:  []
+    notes: "Judgement + relay channel; output reviewed"
+
+  gpt-judgment-high:
+    preferred:       gpt-6.1-sol
+    fallback_chain:  []
+    notes: "High-effort judgement"
+
+  deepseek-verifiable:
+    preferred:       deepseek-v4.1-flash
+    fallback_chain:  []
+    notes: "Verifiable-output work; trusted channel only"
+
+  minimax-medium:
+    preferred:       minimax-m3
+    fallback_chain:  []
+    notes: "Generation + general purpose"
+
+  minimax-fast:
+    preferred:       minimax-m3
+    fallback_chain:  []
+    notes: "Cheap, fast"

package/registry/built_in.yaml

@@ -0,0 +1,42 @@
+# Built-in model registry shipped with pi-agent-workflow.
+# Updated via framework version bumps. Add new models here; never mutate a
+# shipped model — change `status: deprecated` or `withdrawn` instead.
+
+models:
+  - id: claude-opus-5-5
+    vendor: anthropic
+    capabilities: {reasoning: high, thinking: true, context_window: 200000}
+    channels:
+      - {id: official,      trust: trusted}
+      - {id: relay-default, trust: unverified}
+    cost_tier: high
+    status: stable
+
+  - id: claude-sonnet-5-5
+    vendor: anthropic
+    capabilities: {reasoning: medium, thinking: false, context_window: 200000}
+    channels:
+      - {id: official, trust: trusted}
+    cost_tier: medium
+    status: stable
+
+  - id: deepseek-v4.1-flash
+    vendor: deepseek
+    capabilities: {reasoning: medium, thinking: false, context_window: 64000}
+    channels: [{id: official, trust: trusted}]
+    cost_tier: low
+    status: stable
+
+  - id: gpt-6.1-sol
+    vendor: openai
+    capabilities: {reasoning: high, thinking: true, context_window: 128000}
+    channels: [{id: relay-default, trust: unverified}]
+    cost_tier: medium
+    status: stable
+
+  - id: minimax-m3
+    vendor: minimax
+    capabilities: {reasoning: medium, thinking: false, context_window: 200000}
+    channels: [{id: official, trust: trusted}]
+    cost_tier: low
+    status: stable

package/requirements.txt

@@ -0,0 +1,2 @@
+PyYAML>=6.0,<7
+pytest>=7.0,<10