@gkzhb/pi-roles 0.2.4-beta.1

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to `pi-roles` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-05-05
+
+### Changed
+
+- **System prompt full replacement**: Role body now completely replaces Pi's
+default system prompt instead of composing on top of it. Non-coding roles
+(e.g., marketing, research) no longer inherit Pi's default "expert coding
+assistant" framing.
+- **Packaging**: Built output via `tsup`; entry point changed from
+`src/index.ts` to `dist/index.js`; `main`/`exports`/`types` fields added;
+`.npmignore` added.
+- **`/role list` format**: Source scope displayed as `[name]` instead of
+`(name)`; shadowed roles (lower-precedence duplicates) listed separately.
+- **`/role <name>` re-reads from disk**: Every `/role` invocation now
+refreshes role discovery and settings before resolving — edits to role
+files are picked up without an explicit `/role reload`.
+- **`composeSystemPrompt` extracted**: Moved from inline in
+`before_agent_start` to a testable exported function with explicit
+replacement contract.
+
+### Added
+
+- **Session naming (Phase 5)**: Session name composed as
+`<role> — <intent>` with intent (~5–10 word summary) generated
+asynchronously from the first user message. Agent loop starts immediately
+while title generation runs out-of-band. Configurable via `titleModel`
+setting.
+- **`titleInFlight` guard**: Prevents concurrent title generation when
+`before_agent_start` fires repeatedly before the first generation resolves.
+- **Shadowed role tracking**: `/role list` shows roles shadowed at
+lower-precedence scopes.
+- **`tsup.config.ts`**: Build configuration for ESM output with type
+declarations.
+- **Tests**: 37 tests for session-naming module (`test/title.test.ts`);
+6 tests for `composeSystemPrompt` replacement contract
+(`test/index.test.ts`).
+
+## [0.1.0] - TBD
+
+### Added
+
+- Initial release.
+- `--role <name>` CLI flag and `PI_ROLE` env var for launching pi as a named role.
+- `/role` slash command with `list`, `current`, `reload`, and `<name>` subcommands.
+- `--reset` flag on `/role <name>` to clear history before applying the new role (equivalent to `/new` + apply).
+- Tab autocompletion for role names.
+- Role frontmatter spec: `name`, `description`, `model`, `thinking`, `tools`, `intercom`, `extends`. Markdown body becomes the system prompt.
+- Discovery from project (`<repo>/.pi/roles/`), user (`~/.pi/agent/roles/`), and built-in scopes, with project-first precedence.
+- `defaultRole` setting, falling back to a built-in `role-assistant` that lists available roles and walks you through building new ones.
+- Role inheritance via `extends`, with chained resolution, cycle detection, and tri-state `tools` semantics (set / explicit-empty / inherit).
+- Markdown body inheritance: parent body prepended to child body.
+- Hot reload via `/role reload` (re-reads currently active role file from disk).
+- Session naming as `<role> — <intent>`, with intent generated asynchronously from the first user message.
+- Role indicator in Pi's footer via `ctx.ui.setStatus`, composing with `pi-powerline-footer`.
+- Optional `pi-intercom` integration: per-role and global `intercomMode` (`off` / `receive` / `send` / `both`), prompt addendum, tool list opt-in. No-op when `pi-intercom` is not installed.
+- Optional `pi-mcp-adapter` integration: `mcp:server-name` entries inside the `tools` field, mirroring `pi-subagents` convention. No-op when `pi-mcp-adapter` is not installed.
+- Two example role files (`examples/architect.md`, `examples/orchestrator.md`).
+
+[Unreleased]: https://github.com/lojacobs/pi-roles/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/lojacobs/pi-roles/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/lojacobs/pi-roles/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Laurent (pi-roles authors)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,367 @@
+# pi-roles
+
+> Role-based session configuration for [pi coding agent](https://github.com/badlogic/pi-mono). Launch a session as a named role (architect, planner, marketing-strategist, …) and hot-swap roles mid-session — without restarting Pi.
+
+`pi-roles` is to **top-level pi sessions** what [`pi-subagents`](https://github.com/nicobailon/pi-subagents) is to **sub-agents**: same `.md` + YAML frontmatter convention, same project/user scope rules, drop-in flow. The extension is **agnostic of which roles exist** — roles are just markdown files you create.
+
+```bash
+pi --role architect              # launch as architect
+PI_ROLE=planner pi               # or via env
+
+/role list                       # inside the session
+/role planner                    # swap role mid-session, keep history
+/role planner --reset            # swap role and clear history
+/role current
+/role reload                     # re-read the active role file from disk
+```
+
+When you swap roles, the session's **system prompt, model, thinking level, and active tool set** are replaced according to the new role's definition. Conversation history is preserved by default.
+
+---
+
+## Install
+
+```bash
+pi install npm:pi-roles
+```
+
+Then restart pi. The extension is auto-discovered; the `--role` flag and `/role` command become available.
+
+To try without installing:
+
+```bash
+pi -e git:github.com/lojacobs/pi-roles
+```
+
+---
+
+## Why this exists
+
+When you build a multi-agent dev workflow with specialized roles — architect (design), planner (decompose), orchestrator (dispatch), or any equivalent for marketing, research, ops — the *top-level* role is a property of the whole session, not of an individual sub-agent dispatch. You want different system prompts, different models, different tool restrictions per role, and you want to switch between them without restarting.
+
+`pi-roles` is the cleanest way to do that. No shell aliases, no separate workspace directories, no forking pi-subagents into something it isn't.
+
+---
+
+## Role files
+
+Roles are markdown files with YAML frontmatter, identical in shape to `pi-subagents` agent files:
+
+```markdown
+---
+name: architect
+description: Defines the WHAT. Owns architecture and specs. Never codes.
+model: anthropic/claude-opus-4-7
+thinking: high
+tools: read, grep, find, ls, write, edit
+intercom: send             # optional, per-role override
+extends: base-reviewer     # optional, role inheritance
+---
+
+# Role
+
+You are the Architect. Your job is to define WHAT the system should
+do, never HOW to build it...
+
+(everything below the frontmatter is the system prompt body)
+```
+
+### Frontmatter reference
+
+| Field | Required | Behavior when omitted |
+|---|---|---|
+| `name` | yes | — must match the filename without `.md` |
+| `description` | yes | — shown in `/role list` and selectors |
+| `model` | no | keeps the session's current model |
+| `thinking` | no | keeps the session's current thinking level (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`) |
+| `tools` | no — see below | inherits from parent (if `extends`) or keeps current active set |
+| `intercom` | no | falls back to the global `intercomMode` setting |
+| `extends` | no | role inherits from another role |
+
+#### `tools` — the tri-state
+
+Three explicit states with three different meanings:
+
+| YAML | Meaning |
+|---|---|
+| `tools: read, bash` | **set** — exactly these tools, nothing else |
+| `tools:` (present, empty) | **disable all tools** — read-only conversation, no actions |
+| field absent | **inherit** — from parent role (`extends`), else keep session default |
+
+You can also include MCP tool refs in the same field, mirroring `pi-subagents`:
+
+```yaml
+tools: read, grep, mcp:chrome-devtools, mcp:github
+```
+
+`mcp:server-name` entries require [`pi-mcp-adapter`](https://github.com/nicobailon/pi-mcp-adapter) to be installed. If it's not, the entry is logged and skipped — the role still loads.
+
+#### `model` — provider/id format
+
+Matches Pi's CLI `--model` syntax:
+
+```yaml
+model: anthropic/claude-opus-4-7
+model: openai/gpt-5
+model: deepseek/deepseek-v4-pro
+```
+
+If the model isn't available (no API key, unknown provider), the role load surfaces a warning and the session keeps its current model.
+
+#### `intercom` — per-role override
+
+Values: `off`, `receive`, `send`, `both`. Defaults to the global `intercomMode` setting (which itself defaults to `off`). See [pi-intercom integration](#pi-intercom-integration) below.
+
+#### `extends` — role inheritance
+
+```yaml
+extends: architect
+```
+
+A child role inherits everything from its parent and overrides selectively. Chains are supported (`A extends B extends C`); cycles are detected at load time and produce a hard error.
+
+**Merge rules:**
+
+- `model`, `thinking`, `description`, `intercom`: child wins if set, else parent value.
+- `tools`: see the tri-state above. **Set overrides; empty disables; absent inherits.**
+- Markdown body: parent's body is **prepended** to child's body with a separator. Useful for "stricter variant" patterns (`architect-strict extends architect`).
+- `name`: never inherited — always the child's own filename.
+
+---
+
+## Discovery
+
+Roles are looked up in this order, **first match wins** for any given name:
+
+| Scope | Path | Marker in `/role list` |
+|---|---|---|
+| project | `<repo>/.pi/roles/<name>.md` (or any ancestor) | `[project]` |
+| user | `~/.pi/agent/roles/<name>.md` | `[user]` |
+| built-in | bundled with the package | `[built-in]` |
+
+When a project-scope role shadows a user-scope role of the same name, the user-scope entry is listed under a separate "Shadowed" heading in `/role list` output so you know it exists but won't load.
+
+The default `roleScope` is `both` (project + user + built-in). Override via settings:
+
+```json
+// ~/.pi/agent/settings.json
+{
+  "pi-roles": {
+    "roleScope": "both",        // "user" | "project" | "both"
+    "defaultRole": "architect", // optional; falls back to role-assistant
+    "preserveRoleOnNewSession": false, // optional; keep the active role for /new
+    "intercomMode": "off",      // "off" | "receive" | "send" | "both"
+    "titleModel": "openai/gpt-4o-mini"
+  }
+}
+```
+
+---
+
+## Built-in `role-assistant`
+
+`pi-roles` ships **one** built-in role: `role-assistant`. It's the default fallback when no `defaultRole` is configured and you don't pass `--role` or `PI_ROLE`.
+
+The role-assistant:
+
+1. Lists the roles available on your machine (project + user + built-in) on its first turn.
+2. Shows the exact command to switch to one (e.g. `/role architect`).
+3. Offers to help you build a **new** role: it asks the questions, drafts the markdown, shows it for your approval, writes it to project or user scope (your choice), and then prints the command for you to launch it (`/role <new-name> --reset`).
+
+You can override the built-in by dropping a `role-assistant.md` into your project or user roles directory — the same priority rules apply.
+
+You can also set any other role as your default:
+
+```json
+{ "pi-roles": { "defaultRole": "architect" } }
+```
+
+If `defaultRole` points to a missing role, the built-in `role-assistant` is used and a warning is shown.
+
+### Retain the role in new conversations
+
+By default, a normal new conversation resolves its role again from `--role`, `PI_ROLE`, `defaultRole`, and finally `role-assistant`. To keep the role selected in the current Pi process when creating a new conversation, enable:
+
+```json
+{ "pi-roles": { "preserveRoleOnNewSession": true } }
+```
+
+This applies only to ordinary new conversations. `/role <name> --reset` still uses its explicitly requested role; reload and resume restore their session role as before. The setting does not persist a role across a Pi restart—on startup, the normal initial-role resolution still applies.
+
+---
+
+## Slash command
+
+`/role <subcommand>` — Tab-completes role names against the current scope.
+
+| Form | Behavior |
+|---|---|
+| `/role <name>` | Switch to `<name>`. **Preserves history.** Re-reads the file from disk (no caching). |
+| `/role <name> --reset` | Switch to `<name>` **and** clear history (equivalent to `/new` + apply role). |
+| `/role list` | List discovered roles with scope markers and shadowing info. |
+| `/role current` | Show the currently active role's name, extends chain, description, and source path. |
+| `/role reload` | Re-read the **currently active** role's file from disk and re-apply. Useful while you're iterating on a prompt. |
+
+---
+
+## CLI flag and env var
+
+```bash
+pi --role architect "Help me design the auth schema"
+PI_ROLE=architect pi
+```
+
+Resolution order: `--role` > `PI_ROLE` > `defaultRole` setting > built-in `role-assistant`.
+
+---
+
+## Session name and footbar
+
+Each session is named `<role-name>` (and, once the title-generation phase ships, `<role-name> — <intent>`, where `<intent>` is a short summary of your first user message). The role-name prefix updates when you `/role` to a different role.
+
+The session name is set via Pi's native `pi.setSessionName()` API, so:
+
+- It shows in Pi's session selector and `/resume` listings.
+- [`pi-intercom`](https://github.com/nicobailon/pi-intercom) automatically uses it as the session target — making cross-session messaging work out of the box.
+
+The role indicator also appears in Pi's footer (via `ctx.ui.setStatus`), composing cleanly with [`pi-powerline-footer`](https://github.com/nicobailon/pi-powerline-footer) if you have it installed. No extra dependency required.
+
+**Title generation model.** `titleModel` selects the model used to summarize the first user message into the session intent. The extension resolves its credentials through Pi's model registry, so provider API keys, headers, and environment-variable references configured in Pi's `models.json` are forwarded to the title request. The setting falls back to the session's current model when omitted or unavailable.
+
+---
+
+## pi-intercom integration
+
+[`pi-intercom`](https://github.com/nicobailon/pi-intercom) is an **optional peer dependency**. `pi-roles` works without it; intercom features are no-ops when it's not installed.
+
+When it **is** installed, the global `intercomMode` setting controls whether roles get the `intercom` tool added to their active tool set, plus a small system-prompt addendum telling the LLM how and when to use it:
+
+| Mode | Behavior |
+|---|---|
+| `off` | Default. No intercom tools, no prompt mentions. |
+| `receive` | Role can be targeted by other sessions but won't proactively send. |
+| `send` | Role can send to other sessions but doesn't expect inbound coordination. |
+| `both` | Full bidirectional coordination — `intercom` tool active, prompt encourages use. |
+
+Per-role override via the `intercom:` frontmatter field. Common pattern: `architect` and `planner` set `intercom: both`, `orchestrator` sets `intercom: off` (you don't want the orchestrator distracted by chatter while it dispatches).
+
+**Inter-session messaging is always between named sessions on the same machine** — `pi-roles` only opts roles in or out, it doesn't manage the broker, the protocol, or the message store. That's all `pi-intercom`.
+
+---
+
+## pi-mcp-adapter integration
+
+When [`pi-mcp-adapter`](https://github.com/nicobailon/pi-mcp-adapter) is installed, you can list MCP tools alongside built-ins in the `tools` field with the `mcp:server-name` syntax:
+
+```yaml
+tools: read, grep, write, mcp:chrome-devtools, mcp:github
+```
+
+This mirrors `pi-subagents`'s convention exactly, so muscle memory transfers. If `pi-mcp-adapter` isn't installed, the `mcp:*` entries are logged and skipped — the role still loads with its built-in tools.
+
+The first time you use a new MCP server, its tool metadata is cold-cached; you may need to restart Pi once for direct MCP tools to become available. This is a `pi-mcp-adapter` behavior, not something `pi-roles` controls.
+
+---
+
+## Hot reload
+
+`/role reload` re-reads the **currently active** role's file from disk and re-applies it. This is for iterating on a prompt without restarting your session.
+
+`/role <name>` (without `--reset`) also always re-reads from disk — there's no hidden cache between switches.
+
+For roles with `extends`, the entire chain is re-resolved on every load.
+
+If you have Pi's [auto-reload](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/extensions.md#ctxreload) feature wired up via `/reload`, that triggers a full extension reload as well — your role re-applies from scratch.
+
+---
+
+## Settings reference
+
+```json
+// ~/.pi/agent/settings.json (global) or .pi/settings.json (project)
+{
+  "pi-roles": {
+    "roleScope": "both",
+    "defaultRole": "role-assistant",
+    "preserveRoleOnNewSession": false,
+    "intercomMode": "off",
+    "titleModel": "openai/gpt-4o-mini",
+    "warnOnMissingMcp": true
+  }
+}
+```
+
+| Key | Default | Description |
+|---|---|---|
+| `roleScope` | `"both"` | Discovery scope. `"user"`, `"project"`, or `"both"`. |
+| `defaultRole` | `"role-assistant"` | Role applied at session start when no `--role` or `PI_ROLE`. |
+| `preserveRoleOnNewSession` | `false` | Keep the current process's active role when creating a normal new conversation. Does not apply across restarts or to explicit `/role <name> --reset`. |
+| `intercomMode` | `"off"` | Default intercom behavior for roles that don't set it explicitly. |
+| `titleModel` | `null` (auto) | Model used for session-intent summarization. Its API key and request headers are resolved from Pi's model registry, including `models.json` environment-variable configuration. Falls back to the session's current model. |
+| `warnOnMissingMcp` | `true` | Whether to surface a warning when a role's `mcp:*` entry can't be resolved. |
+
+Project settings beat global settings, per Pi's standard precedence.
+
+---
+
+## What this extension does **not** do
+
+- **Spawn sub-agents.** That's [`pi-subagents`](https://github.com/nicobailon/pi-subagents). The two compose: use `pi-roles` for top-level session roles, `pi-subagents` for delegated workers within a role.
+- **Define any built-in roles other than `role-assistant`.** Roles are user content; the extension stays small.
+- **Manage parallel sessions.** Use multiple terminals or `tmux`. Coordination between parallel sessions is what `pi-intercom` handles, optionally.
+- **Persist which role was active across pi restarts** — except via `--role` / `PI_ROLE` / `defaultRole`. By design.
+- **Restrict which tools a role can request.** If a role lists `bash`, it gets `bash`. Permission boundaries are your call — pair with [`permission-gate.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/examples/extensions/permission-gate.ts) or a similar guard if you need them.
+
+---
+
+## Design choices worth knowing
+
+These are decided, not configurable, so the extension behaves predictably:
+
+- **Markdown body fully replaces Pi's default system prompt.** No silent merging — most non-coding roles are polluted by the default "expert coding assistant" framing, so by design the role body is authoritative. The handler returns `{ systemPrompt: <role body> }` from `before_agent_start` and ignores the upstream chain value. If you want to keep Pi's default content (or compose with another extension), include the relevant text in your role body explicitly.
+- **Role inheritance**: `model`/`thinking` override; `tools` is tri-state (set/empty/absent); markdown body is **prepended**.
+- **Cycle detection in `extends`** is a hard error at load time, not a warning. A circular role is broken; refusing to load it is the only sane behavior.
+- **`/role <name>` always re-reads from disk.** No staleness between switches, ever.
+- **`--reset` is explicit.** The role-assistant prints the exact `--reset` command for you to run manually rather than auto-resetting; resetting is destructive enough to deserve a deliberate keystroke.
+- **Title generation** (planned, not yet implemented). The current release sets the session name to the bare role name; intent-summarization on first user message lands in a follow-up. `--reset` already clears the cached intent so the future implementation drops in cleanly.
+- **Built-in `role-assistant` lives at the lowest discovery priority.** Drop a same-named file in user or project scope to override it.
+- **`/role list` shows shadowed entries** with a `(shadowed)` marker — you can see what *would* load if the higher-priority file didn't exist.
+
+---
+
+## Layout on disk
+
+After install, your roles live wherever you like — typical setup:
+
+```
+~/.pi/agent/roles/
+  architect.md
+  planner.md
+  orchestrator.md
+  marketing-strategist.md
+  campaign-manager.md
+
+<repo>/.pi/roles/
+  architect.md          # overrides the user one for this project
+```
+
+The extension itself ships only `role-assistant.md` (built-in scope) and the runtime code.
+
+---
+
+## Examples
+
+See [`examples/`](./examples) for two reference role files:
+
+- [`architect.md`](./examples/architect.md) — minimal: just system prompt + model + thinking.
+- [`orchestrator.md`](./examples/orchestrator.md) — fully loaded: every frontmatter field, including `extends`, `intercom`, MCP tools.
+
+---
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+## Credits
+
+Inspired by and structurally indebted to [`pi-subagents`](https://github.com/nicobailon/pi-subagents) (frontmatter convention, scope discovery), [`pi-prompt-template-model`](https://github.com/nicobailon/pi-prompt-template-model) (per-trigger model/skill/thinking switching), and the [`preset.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/examples/extensions/preset.ts) example in pi-mono. Thanks to those authors for both the patterns and the working code to learn from.