pi-profile-switch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VincentFF
+
+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,106 @@
+# pi-profile-switch
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+Named profiles for [Pi](https://github.com/badlogic/pi-mono). A profile selects what the model sees and which capabilities the session uses — skills, MCP servers, tools, a model preset, and extra instructions — switchable in the same Pi process.
+
+Use a lean read-only profile for code review, a full-powered one for implementation, a minimal one for a quick question.
+
+`pi-profile-switch` is a plain Pi package (ADR-0007). It installs like any other extension, leaves Pi's configuration directory untouched, and keeps sessions, packages, project trust, and every other installed extension native.
+
+## Install
+
+```bash
+pi install npm:pi-profile-switch
+```
+
+Requires [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) (installed automatically as a peer dependency).
+
+## Quick start
+
+```bash
+# Use the saved profile (or the built-in default)
+pi
+
+# Use a profile for this run only (not saved)
+pi --profile review
+
+# The explicit native baseline
+pi --profile default
+```
+
+Define profiles in `~/.pi/agent/profiles.json` (global) or `<project>/.pi/profiles.json` (project, trusted projects only):
+
+```json
+{
+  "schemaVersion": 2,
+  "profiles": {
+    "review": {
+      "label": "Code review",
+      "skills": ["code-review"],
+      "mcp": ["github"],
+      "tools": ["read", "grep", "find", "bash"],
+      "instructions": "Review only; do not modify files."
+    }
+  }
+}
+```
+
+Profiles **reference** resources by name — they never copy them. Full schema with more examples: [`examples/profiles.json`](examples/profiles.json).
+
+Existing `schemaVersion: 1` catalogs keep working: the `extensions` field is reported once and ignored, because extensions now load natively in every profile.
+
+## What a profile controls
+
+| Field | Effect |
+| --- | --- |
+| `instructions` | Text appended to the system prompt every turn |
+| `model` | Session-start model preset; an explicit `--model`/`--thinking` or a model recorded in the session wins |
+| `skills` | What the model sees in the prompt's skills list. Every installed skill stays loaded and callable by the user through `/skill:name` |
+| `mcp` | Runtime server allowlist published to `pi-mcp-adapter`; connection details stay in the adapter's own config |
+| `tools` | Active tool set: declared names/globs become the active set; names that register later (MCP, extensions) are applied when they appear |
+
+Anything a profile does not declare keeps Pi's native behavior, and `default` declares nothing.
+
+## Commands
+
+In the TUI, the `/profile` command family manages everything in-session:
+
+| Command | What it does |
+| --- | --- |
+| `/profile` | Interactive profile picker |
+| `/profile list` / `/profile status` | Show profiles / active profile details |
+| `/profile use <name>` | Switch instantly — same session, no reload |
+| `/profile create\|edit\|delete\|duplicate` | Guided profile CRUD (TUI only) |
+| `/profile customize` / `/profile reset` | Narrow the active profile for this session only |
+| `/mcp enable\|disable <server>` | Toggle MCP servers in the active profile |
+
+All commands work in non-interactive modes (`--mode rpc|print|json`); CRUD wizards are TUI-only.
+
+## Guarantees
+
+- **Reference, never copy** — profiles point at resources you already own and maintain.
+- **Pi-native** — the configuration directory is Pi's own, so sessions, extension config, packages, context files, and trust behave exactly as they do in plain Pi.
+- **Fail safe** — untrusted project directories are never read; a failed activation applies nothing and reports the cause.
+- **No reload** — switching re-applies runtime state in place; the next turn's prompt carries the new selection.
+
+## Migrating from the launcher
+
+```bash
+pi-profile review          # before
+pi --profile review        # after
+
+pi-profile review -- --mode rpc   # before
+pi --profile review --mode rpc    # after
+```
+
+`/profile reload` and the `/profile resource` commands are gone: skills are read on demand and catalogs are re-read on every use, so there is nothing to reload. Remove leftover `~/.pi/agent/pi-profile/runtime/` directories; the extension no longer creates them.
+
+## Docs
+
+- [Architecture](docs/architecture/overview.md) · [ADRs](docs/adr/) · [Glossary](CONTEXT.md) (Chinese)
+- JSON Schema: [`schemas/profiles.schema.json`](schemas/profiles.schema.json)
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,106 @@
+# pi-profile-switch
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+[Pi](https://github.com/badlogic/pi-mono) 的命名 profile 扩展。一个 profile 选择模型看到什么、会话使用哪些能力——skills、MCP server、tools、预制模型和附加指令——并在同一 Pi 进程内即时切换。
+
+代码评审用精简的只读 profile，实现需求用全量 profile，临时提问用最小 profile。
+
+`pi-profile-switch` 是普通 Pi package（ADR-0007）：像其他扩展一样安装，不改动 Pi 的配置目录，session、packages、项目信任和其他扩展全部保持原生。
+
+## 安装
+
+```bash
+pi install npm:pi-profile-switch
+```
+
+依赖 [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)（作为 peer dependency 自动安装）。
+
+## 快速上手
+
+```bash
+# 使用已保存的 profile（不存在时用内建 default）
+pi
+
+# 仅本次启动使用指定 profile（不保存）
+pi --profile review
+
+# 显式的原生基线
+pi --profile default
+```
+
+在 `~/.pi/agent/profiles.json`（全局）或 `<项目>/.pi/profiles.json`（项目级，仅限已信任项目）中定义 profile：
+
+```json
+{
+  "schemaVersion": 2,
+  "profiles": {
+    "review": {
+      "label": "Code review",
+      "skills": ["code-review"],
+      "mcp": ["github"],
+      "tools": ["read", "grep", "find", "bash"],
+      "instructions": "Review only; do not modify files."
+    }
+  }
+}
+```
+
+Profile 只**引用**资源，从不复制资源。完整示例见 [`examples/profiles.json`](examples/profiles.json)。
+
+已有的 `schemaVersion: 1` catalog 继续可用：`extensions` 字段会被警告一次并忽略——extensions 现在在所有 profile 中原生加载。
+
+## Profile 控制的范围
+
+| 字段 | 效果 |
+| --- | --- |
+| `instructions` | 每个 turn 追加到 system prompt 末尾 |
+| `model` | 会话启动的模型预设；显式 `--model`/`--thinking` 或 session 历史中记录的模型优先 |
+| `skills` | 模型在 prompt skills 列表中看到的内容；所有已安装 skill 仍保持加载，用户可用 `/skill:name` 手动调用 |
+| `mcp` | 发布给 `pi-mcp-adapter` 的运行时 server allowlist；连接参数仍由 adapter 自己管理 |
+| `tools` | 活动工具集：声明的名字/glob 成为活动集合；之后才注册的工具（MCP、扩展）在出现时补上 |
+
+未声明的字段保持 Pi 原生行为，`default` 什么都不声明。
+
+## 命令
+
+在 TUI 中，`/profile` 命令族完成所有会话内操作：
+
+| 命令 | 作用 |
+| --- | --- |
+| `/profile` | 交互式选择 profile |
+| `/profile list` / `/profile status` | 列出 profile / 查看活动 profile 详情 |
+| `/profile use <name>` | 即时切换——同一 session，无 reload |
+| `/profile create\|edit\|delete\|duplicate` | 向导式 profile 增删改（仅 TUI） |
+| `/profile customize` / `/profile reset` | 仅本次会话收窄活动 profile |
+| `/mcp enable\|disable <server>` | 在活动 profile 中开关 MCP server |
+
+非交互模式（`--mode rpc|print|json`）下命令同样生效；CRUD 向导仅 TUI 可用。
+
+## 保证
+
+- **引用而非复制**——profile 指向你自己拥有和维护的资源。
+- **Pi 原生**——配置目录就是 Pi 自己的目录，session、扩展配置、packages、context 文件和信任行为与原生 Pi 完全一致。
+- **失败安全**——未信任的项目目录从不读取；激活失败时不应用任何设置并报出原因。
+- **无 reload**——切换在原位重新应用运行时状态；下一个 turn 的 prompt 直接带上新选择。
+
+## 从 launcher 迁移
+
+```bash
+pi-profile review          # 旧
+pi --profile review        # 新
+
+pi-profile review -- --mode rpc   # 旧
+pi --profile review --mode rpc    # 新
+```
+
+`/profile reload` 与 `/profile resource` 命令已移除：skill 内容按需读取、catalog 每次使用重新读取，没有需要 reload 的缓存。删除遗留的 `~/.pi/agent/pi-profile/runtime/` 目录；新版本不再创建它们。
+
+## 文档
+
+- [架构设计](docs/architecture/overview.md) · [ADR](docs/adr/) · [术语表](CONTEXT.md)
+- JSON Schema：[`schemas/profiles.schema.json`](schemas/profiles.schema.json)
+
+## 许可证
+
+MIT

package/examples/profiles.json

@@ -0,0 +1,38 @@
+{
+  "schemaVersion": 2,
+  "profiles": {
+    "review": {
+      "label": "Code review",
+      "description": "Read-heavy review workflow",
+      "skills": [
+        "code-review",
+        "diagnosing-bugs"
+      ],
+      "mcp": [
+        "github"
+      ],
+      "tools": [
+        "read",
+        "grep",
+        "find",
+        "bash"
+      ],
+      "instructions": "Review only; do not modify files."
+    },
+    "impl": {
+      "label": "Implementation",
+      "skills": [
+        "tdd"
+      ],
+      "mcp": [
+        "github",
+        "linear"
+      ],
+      "model": {
+        "provider": "deepseek",
+        "id": "deepseek-v4-pro",
+        "thinkingLevel": "high"
+      }
+    }
+  }
+}