pi-profile-switch 0.7.0 → 0.9.0

package/README.md

@@ -27,72 +27,64 @@ pi-profile ask -- --model openai/gpt-5.4
 
 ## Define your own profiles
 
-Profiles live in two JSON files, both optional:
+Profiles live in two directories, with one JSON file per profile:
 
-| File | Scope |
+| Path | Scope |
 | --- | --- |
-| `~/.pi-profile-switch/profiles.json` | Global, all projects. `PI_PROFILE_SWITCH_DIR` overrides the root; `~/.pi/agent/profiles.json` is read as a legacy fallback for migration. |
-| `<project>/.pi/profiles.json` | Project-level, trusted projects only. |
+| `~/.pi-profile-switch/profiles/<name>.json` | Global, all projects. `PI_PROFILE_SWITCH_DIR` overrides the workspace root. |
+| `<project>/.pi/profiles/<name>.json` | Project-level, trusted projects only. |
 
-Create or change a profile by editing the JSON directly — schema: [`schemas/profiles.schema.json`](schemas/profiles.schema.json).
+Create or change a profile by editing or creating a `<name>.json` file directly — schema: [`schemas/profiles.schema.json`](schemas/profiles.schema.json).
 
-On install, pi-profile-switch seeds the global file with a starter **`ask`** profile — read-only Q&A and code exploration. It assumes nothing about your setup; edit or delete it freely:
+You can also configure profiles conversationally: the package ships a **`profile-config`** skill (distributed to `<agentDir>/skills/profile-config/` on install) that guides the agent to clarify requirements, discover resources, and write or remove profile files. Profiles created with a `skills` list include `"profile-config"` by default (unless explicitly opted out or covered by a wildcard like `"*"`), keeping configuration available after switching. Details: [`skills/profile-config/SKILL.md`](skills/profile-config/SKILL.md).
+
+On install, pi-profile-switch seeds the global `profiles/` directory with a starter **`ask`** profile (`ask.json`) — read-only Q&A and code exploration. It assumes nothing about your setup; edit or delete it freely:
 
 ```json
 {
-  "schemaVersion": 1,
-  "profiles": {
-    "ask": {
-      "label": "Ask & Discuss",
-      "description": "Read-only Q&A and code exploration; no file modifications or command execution",
-      "skills": [],
-      "extensions": [],
-      "tools": ["read", "grep", "find", "ls"],
-      "instructions": "You are in read-only discussion mode. Answer questions and explain code without modifying any files or running shell commands."
-    }
-  }
+  "label": "Ask & Discuss",
+  "description": "Read-only Q&A and code exploration; no file modifications or command execution",
+  "skills": [],
+  "extensions": [],
+  "tools": ["read", "grep", "find", "ls"],
+  "instructions": "You are in read-only discussion mode. Answer questions and explain code without modifying any files or running shell commands."
 }
 ```
 
-One profile can use every field at once. This example `impl` profile loads the TDD skill, the mcp-scripting skill (shipped by pi-mcp-adapter), and your internal skills; wires up two MCP servers; allows the built-in tools plus both servers' MCP tools by glob; and pins the model and standing instructions:
+One profile can use every field at once. This example `impl` profile (`impl.json`) loads the TDD skill, the mcp-scripting skill (shipped by pi-mcp-adapter), and your internal skills; wires up two MCP servers; allows the built-in tools plus both servers' MCP tools by glob; and pins the model and standing instructions:
 
 ```json
 {
-  "schemaVersion": 1,
-  "profiles": {
-    "impl": {
-      "label": "Implementation",
-      "description": "Full-powered implementation profile: every available field, pinned model",
-      "skills": [
-        "tdd",
-        "internal-*",
-        "mcp-scripting"
-      ],
-      "extensions": [
-        "pi-mcp-adapter"
-      ],
-      "mcps": [
-        "github",
-        "linear"
-      ],
-      "tools": [
-        "read",
-        "grep",
-        "find",
-        "ls",
-        "bash",
-        "edit",
-        "write",
-        "mcp__*",
-        "github_*",
-        "linear_*"
-      ],
-      "defaultProvider": "anthropic",
-      "defaultModel": "claude-sonnet-4-5",
-      "defaultThinkingLevel": "high",
-      "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
-    }
-  }
+  "label": "Implementation",
+  "description": "Full-powered implementation profile: every available field, pinned model",
+  "skills": [
+    "tdd",
+    "internal-*",
+    "mcp-scripting"
+  ],
+  "extensions": [
+    "pi-mcp-adapter"
+  ],
+  "mcps": [
+    "github",
+    "linear"
+  ],
+  "tools": [
+    "read",
+    "grep",
+    "find",
+    "ls",
+    "bash",
+    "edit",
+    "write",
+    "mcp__*",
+    "github_*",
+    "linear_*"
+  ],
+  "defaultProvider": "anthropic",
+  "defaultModel": "claude-sonnet-4-5",
+  "defaultThinkingLevel": "high",
+  "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
 }
 ```
 
@@ -103,7 +95,15 @@ How fields resolve:
 - `mcps` references servers from your pi-mcp-adapter configuration; connection details stay in the adapter's own config.
 - Any field you omit keeps plain Pi behavior.
 
-The files in [`examples/`](examples/) mirror the two profiles above: `profiles.json` is the seeded starter, `example.json` the full-field demo.
+The files in [`examples/`](examples/) mirror the two profiles above: `ask.json` is the seeded starter, `example.json` the full-field demo.
+
+### Migrating from earlier versions
+
+If you used an earlier version that stored all profiles in a single `profiles.json` (`schemaVersion: 1`), migrate manually by creating a file for each profile under the `profiles/` directory:
+
+1. Create directory `~/.pi-profile-switch/profiles/` (or `<project>/.pi/profiles/`).
+2. For each key `<name>` in your old `profiles.json`'s `profiles` object, save its value directly as `<name>.json`.
+3. Drop the outer `schemaVersion` and `profiles` envelope.
 
 ## Commands
 

package/README.zh-CN.md

@@ -27,72 +27,64 @@ pi-profile ask -- --model openai/gpt-5.4
 
 ## 自定义 profile
 
-profile 定义在两个 JSON 文件中，均可选：
+profile 保存在两个目录中，每个 profile 对应一个独立 JSON 文件：
 
-| 文件 | 作用域 |
+| 路径 | 作用域 |
 | --- | --- |
-| `~/.pi-profile-switch/profiles.json` | 全局，对所有项目生效。`PI_PROFILE_SWITCH_DIR` 可自定义根目录；`~/.pi/agent/profiles.json` 作为遗留路径向下兼容，用于迁移。 |
-| `<项目>/.pi/profiles.json` | 项目级，仅对已信任项目生效。 |
+| `~/.pi-profile-switch/profiles/<name>.json` | 全局，对所有项目生效。`PI_PROFILE_SWITCH_DIR` 可自定义根目录。 |
+| `<项目>/.pi/profiles/<name>.json` | 项目级，仅对已信任项目生效。 |
 
-直接编辑 JSON 即可创建或修改 profile——schema 见 [`schemas/profiles.schema.json`](schemas/profiles.schema.json)。
+直接编辑或新建 `<name>.json` 即可创建或修改 profile——schema 见 [`schemas/profiles.schema.json`](schemas/profiles.schema.json)。
 
-安装时，pi-profile-switch 会向全局文件播种一个初始 **`ask`** profile——只读的问答与代码走读模式。它不假设你安装过任何插件，可随意修改或删除：
+你也可以通过对话让 agent 帮你配置：随包附带的 **`profile-config`** skill（安装时分发至 `<agentDir>/skills/profile-config/`）会指导 agent 澄清需求、发现资源并读写 profile 文件。按约定，生成声明了 `skills` 的 profile 时默认包含 `"profile-config"`（除非明确排除或已被 `*` 等 glob 覆盖），确保切换到新 profile 后仍可持续对话配置。详情见 [`skills/profile-config/SKILL.md`](skills/profile-config/SKILL.md)。
+
+安装时，pi-profile-switch 会向全局 `profiles/` 目录播种一个初始 **`ask`** profile（`ask.json`）——只读的问答与代码走读模式。它不假设你安装过任何插件，可随意修改或删除：
 
 ```json
 {
-  "schemaVersion": 1,
-  "profiles": {
-    "ask": {
-      "label": "Ask & Discuss",
-      "description": "Read-only Q&A and code exploration; no file modifications or command execution",
-      "skills": [],
-      "extensions": [],
-      "tools": ["read", "grep", "find", "ls"],
-      "instructions": "You are in read-only discussion mode. Answer questions and explain code without modifying any files or running shell commands."
-    }
-  }
+  "label": "Ask & Discuss",
+  "description": "Read-only Q&A and code exploration; no file modifications or command execution",
+  "skills": [],
+  "extensions": [],
+  "tools": ["read", "grep", "find", "ls"],
+  "instructions": "You are in read-only discussion mode. Answer questions and explain code without modifying any files or running shell commands."
 }
 ```
 
-一个 profile 可以同时使用全部字段。下面这个 `impl` profile 示例加载 TDD skill、mcp-scripting skill（pi-mcp-adapter 自带）和你的内部 skills；接入两个 MCP server；tool 白名单用 glob 覆盖内建工具和这两个 server 的 MCP 工具；并钉住模型与常驻 instructions：
+一个 profile 可以同时使用全部字段。下面这个 `impl` profile 示例（`impl.json`）加载 TDD skill、mcp-scripting skill（pi-mcp-adapter 自带）和你的内部 skills；接入两个 MCP server；tool 白名单用 glob 覆盖内建工具和这两个 server 的 MCP 工具；并钉住模型与常驻 instructions：
 
 ```json
 {
-  "schemaVersion": 1,
-  "profiles": {
-    "impl": {
-      "label": "Implementation",
-      "description": "Full-powered implementation profile: every available field, pinned model",
-      "skills": [
-        "tdd",
-        "internal-*",
-        "mcp-scripting"
-      ],
-      "extensions": [
-        "pi-mcp-adapter"
-      ],
-      "mcps": [
-        "github",
-        "linear"
-      ],
-      "tools": [
-        "read",
-        "grep",
-        "find",
-        "ls",
-        "bash",
-        "edit",
-        "write",
-        "mcp__*",
-        "github_*",
-        "linear_*"
-      ],
-      "defaultProvider": "anthropic",
-      "defaultModel": "claude-sonnet-4-5",
-      "defaultThinkingLevel": "high",
-      "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
-    }
-  }
+  "label": "Implementation",
+  "description": "Full-powered implementation profile: every available field, pinned model",
+  "skills": [
+    "tdd",
+    "internal-*",
+    "mcp-scripting"
+  ],
+  "extensions": [
+    "pi-mcp-adapter"
+  ],
+  "mcps": [
+    "github",
+    "linear"
+  ],
+  "tools": [
+    "read",
+    "grep",
+    "find",
+    "ls",
+    "bash",
+    "edit",
+    "write",
+    "mcp__*",
+    "github_*",
+    "linear_*"
+  ],
+  "defaultProvider": "anthropic",
+  "defaultModel": "claude-sonnet-4-5",
+  "defaultThinkingLevel": "high",
+  "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
 }
 ```
 
@@ -103,7 +95,15 @@ profile 定义在两个 JSON 文件中，均可选：
 - `mcps` 引用 pi-mcp-adapter 配置中的 server；连接细节留在 adapter 自己的配置里。
 - 未写的字段保持原生 Pi 行为。
 
-[`examples/`](examples/) 中的两个文件与上面一一对应：`profiles.json` 是播种的初始 profile，`example.json` 是全字段演示。
+[`examples/`](examples/) 中的两个文件与上面一一对应：`ask.json` 是播种的初始 profile，`example.json` 是全字段演示。
+
+### 从旧版本迁移
+
+如果你之前使用了把全部 profile 存在单个 `profiles.json`（含 `schemaVersion: 1`）的旧版本，请手动把每个 profile 拆分到 `profiles/` 目录：
+
+1. 创建 `~/.pi-profile-switch/profiles/`（或 `<项目>/.pi/profiles/`）目录。
+2. 将旧 `profiles.json` 中 `profiles` 下的每个 `<name>` 键值提取为独立的 `<name>.json` 文件。
+3. 去除外层的 `schemaVersion` 与 `profiles` 信封，文件顶层即为裸 profile 定义。
 
 ## 命令
 

package/bin/postinstall.d.ts

@@ -11,3 +11,5 @@ export interface InstallResult {
 }
 
 export function installDefaultProfiles(options?: { env?: NodeJS.ProcessEnv }): Promise<InstallResult>;
+
+export function installProfileConfigSkill(options?: { env?: NodeJS.ProcessEnv }): Promise<InstallResult>;

package/bin/postinstall.js

@@ -1,29 +1,31 @@
 #!/usr/bin/env node
 /**
- * postinstall: seed the global catalog with the default profiles file.
+ * postinstall: seed the global catalog with the default starter profile,
+ * and distribute the profile-config skill to the agent skills directory.
  *
  * Runs at package install time (`npm install pi-profile-switch` / `pi install`).
  * Idempotent and conservative:
- * - Writes the shipped `examples/profiles.json` starter catalog to the
- *   profile-switch dir ONLY when no
- *   catalog exists there yet (COPYFILE_EXCL; an existing file — including
- *   one written concurrently — is never touched).
- * - Skips entirely when a legacy `~/.pi/agent/profiles.json` exists, because
- *   the resolver still falls back to it and a new preferred-path file would
- *   silently shadow it (see src/workspace.ts resolveGlobalProfilesPath).
+ * - Writes the shipped `examples/ask.json` starter profile to the
+ *   profiles dir ONLY when no .json profile exists there yet
+ *   (COPYFILE_EXCL; an existing file — including one written concurrently — is never touched).
+ * - Distributes the shipped `skills/profile-config/SKILL.md` to
+ *   `<agentDir>/skills/profile-config/SKILL.md`, always overwriting with
+ *   the shipped version so the skill stays in sync with the package.
  * - Never fails the install: errors are downgraded to a warning.
  *
  * This module is plain Node ESM (no jiti/TS): npm may run postinstall in a
  * context where only plain JS is safe. The path rules intentionally mirror
- * src/workspace.ts — keep them in sync.
+ * src/workspace.ts and Pi's getAgentDir() (in @earendil-works/pi-coding-agent)
+ * — keep them in sync.
  */
-import { access, copyFile, mkdir } from "node:fs/promises";
+import { copyFile, mkdir, readdir } from "node:fs/promises";
 import { constants } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-const DEFAULT_TEMPLATE = fileURLToPath(new URL("../examples/profiles.json", import.meta.url));
+const DEFAULT_TEMPLATE = fileURLToPath(new URL("../examples/ask.json", import.meta.url));
+const SKILL_TEMPLATE = fileURLToPath(new URL("../skills/profile-config/SKILL.md", import.meta.url));
 
 /** Mirrors getProfileSwitchDir() in src/workspace.ts.
  *  @param {NodeJS.ProcessEnv} env */
@@ -33,38 +35,58 @@ function profileSwitchDir(env) {
 	return path.join(homedir(), ".pi-profile-switch");
 }
 
-/** The legacy migration fallback the resolver still reads (~/.pi/agent).
+/** Mirrors getGlobalProfilesDir() in src/workspace.ts.
  *  @param {NodeJS.ProcessEnv} env */
-function legacyCatalogPath(env) {
-	const agentDir = env.PI_CODING_AGENT_DIR ?? path.join(homedir(), ".pi", "agent");
-	return path.join(agentDir, "profiles.json");
+function globalProfilesDir(env) {
+	return path.join(profileSwitchDir(env), "profiles");
 }
 
-/** @param {string} filePath */
-async function exists(filePath) {
+/** Mirrors Pi's getAgentDir() in @earendil-works/pi-coding-agent.
+ *  Keep in sync with Pi's config resolution.
+ *  Deliberate divergence from Pi: trims whitespace and resolves relative
+ *  paths via path.resolve() for safety during postinstall.
+ *  @param {NodeJS.ProcessEnv} env */
+function agentDir(env) {
+	const override = env.PI_CODING_AGENT_DIR;
+	if (override && override.trim()) {
+		const trimmed = override.trim();
+		if (trimmed === "~") return homedir();
+		if (trimmed.startsWith("~/") || (process.platform === "win32" && trimmed.startsWith("~\\"))) {
+			return path.join(homedir(), trimmed.slice(2));
+		}
+		return path.resolve(trimmed);
+	}
+	return path.join(homedir(), ".pi", "agent");
+}
+
+/** Checks whether the directory exists and contains any .json files.
+ *  @param {string} dir */
+async function hasAnyJsonProfiles(dir) {
 	try {
-		await access(filePath);
-		return true;
+		const entries = await readdir(dir);
+		return entries.some((name) => name.endsWith(".json"));
 	} catch {
 		return false;
 	}
 }
 
-/** @typedef {{ path: string, written: boolean, skipped?: string }} InstallResult */
+/** @typedef {{ path: string, written: boolean }} InstallResult */
 
 /**
- * Seeds the default catalog. Safe to call repeatedly; only the first call
- * writes.
+ * Seeds the default starter profile. Safe to call repeatedly; only writes
+ * if no .json files exist in the global profiles directory.
  * @param {{ env?: NodeJS.ProcessEnv }} [options]
  * @returns {Promise<InstallResult>}
  */
 export async function installDefaultProfiles({ env = process.env } = {}) {
-	const target = path.join(profileSwitchDir(env), "profiles.json");
-	if (await exists(target)) return { path: target, written: false };
-	if (await exists(legacyCatalogPath(env))) {
-		return { path: target, written: false, skipped: "legacy-catalog-present" };
+	const dir = globalProfilesDir(env);
+	const target = path.join(dir, "ask.json");
+
+	if (await hasAnyJsonProfiles(dir)) {
+		return { path: target, written: false };
 	}
-	await mkdir(path.dirname(target), { recursive: true });
+
+	await mkdir(dir, { recursive: true });
 	try {
 		await copyFile(DEFAULT_TEMPLATE, target, constants.COPYFILE_EXCL);
 	} catch (error) {
@@ -76,14 +98,44 @@ export async function installDefaultProfiles({ env = process.env } = {}) {
 	return { path: target, written: true };
 }
 
+/**
+ * Distributes the shipped profile-config skill to the agent skills directory.
+ * Always overwrites with the shipped version. Downgrades failures to a warning.
+ * @param {{ env?: NodeJS.ProcessEnv }} [options]
+ * @returns {Promise<InstallResult>}
+ */
+export async function installProfileConfigSkill({ env = process.env } = {}) {
+	const dir = path.join(agentDir(env), "skills", "profile-config");
+	const target = path.join(dir, "SKILL.md");
+
+	try {
+		await mkdir(dir, { recursive: true });
+		await copyFile(SKILL_TEMPLATE, target);
+		return { path: target, written: true };
+	} catch (error) {
+		console.warn(
+			`pi-profile: could not distribute profile-config skill: ${error instanceof Error ? error.message : error}`,
+		);
+		return { path: target, written: false };
+	}
+}
+
 const invokedDirectly = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (invokedDirectly) {
 	installDefaultProfiles().then(
 		(result) => {
-			if (result.written) console.log(`pi-profile: seeded default profiles at ${result.path}`);
+			if (result.written) console.log(`pi-profile: seeded starter profile at ${result.path}`);
+		},
+		(error) => {
+			console.warn(`pi-profile: could not seed starter profile: ${error instanceof Error ? error.message : error}`);
+		},
+	);
+	installProfileConfigSkill().then(
+		(result) => {
+			if (result.written) console.log(`pi-profile: distributed profile-config skill at ${result.path}`);
 		},
 		(error) => {
-			console.warn(`pi-profile: could not seed default profiles: ${error instanceof Error ? error.message : error}`);
+			console.warn(`pi-profile: could not distribute profile-config skill: ${error instanceof Error ? error.message : error}`);
 		},
 	);
 }

package/examples/ask.json

@@ -0,0 +1,13 @@
+{
+  "label": "Ask & Discuss",
+  "description": "Read-only Q&A and code exploration; no file modifications or command execution",
+  "skills": [],
+  "extensions": [],
+  "tools": [
+    "read",
+    "grep",
+    "find",
+    "ls"
+  ],
+  "instructions": "You are in read-only discussion mode. Answer questions and explain code without modifying any files or running shell commands."
+}

package/examples/example.json

@@ -1,37 +1,32 @@
 {
-  "schemaVersion": 1,
-  "profiles": {
-    "impl": {
-      "label": "Implementation",
-      "description": "Full-powered implementation profile: every available field, pinned model",
-      "skills": [
-        "tdd",
-        "internal-*",
-        "mcp-scripting"
-      ],
-      "extensions": [
-        "pi-mcp-adapter"
-      ],
-      "mcps": [
-        "github",
-        "linear"
-      ],
-      "tools": [
-        "read",
-        "grep",
-        "find",
-        "ls",
-        "bash",
-        "edit",
-        "write",
-        "mcp__*",
-        "github_*",
-        "linear_*"
-      ],
-      "defaultProvider": "anthropic",
-      "defaultModel": "claude-sonnet-4-5",
-      "defaultThinkingLevel": "high",
-      "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
-    }
-  }
+  "label": "Implementation",
+  "description": "Full-powered implementation profile: every available field, pinned model",
+  "skills": [
+    "tdd",
+    "internal-*",
+    "mcp-scripting"
+  ],
+  "extensions": [
+    "pi-mcp-adapter"
+  ],
+  "mcps": [
+    "github",
+    "linear"
+  ],
+  "tools": [
+    "read",
+    "grep",
+    "find",
+    "ls",
+    "bash",
+    "edit",
+    "write",
+    "mcp__*",
+    "github_*",
+    "linear_*"
+  ],
+  "defaultProvider": "anthropic",
+  "defaultModel": "claude-sonnet-4-5",
+  "defaultThinkingLevel": "high",
+  "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-profile-switch",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Named profiles for Pi: reference skills, extensions, MCP servers, and tools per workflow, switched without restarting. Install: npm install -g pi-profile-switch (not pi install).",
   "type": "module",
   "keywords": [
@@ -46,6 +46,7 @@
   "files": [
     "bin",
     "extensions",
+    "skills",
     "src",
     "schemas",
     "examples",