@schovest/pi-coding-agent 0.7.3

package/docs/packages.md

@@ -0,0 +1,228 @@
+> pi can help you create pi packages. Ask it to bundle your extensions, skills, prompt templates, or themes.
+
+# Pi Packages
+
+Pi packages bundle extensions, skills, prompt templates, and themes so you can share them through npm or git. A package can declare resources in `package.json` under the `pi` key, or use conventional directories.
+
+Claude-compatible marketplace plugins are managed separately. Use [`pi plugins`](plugins.md) for Claude plugin catalogs and `.claude-plugin/plugin.json` manifests.
+
+## Table of Contents
+
+- [Install and Manage](#install-and-manage)
+- [Package Sources](#package-sources)
+- [Creating a Pi Package](#creating-a-pi-package)
+- [Package Structure](#package-structure)
+- [Dependencies](#dependencies)
+- [Package Filtering](#package-filtering)
+- [Enable and Disable Resources](#enable-and-disable-resources)
+- [Scope and Deduplication](#scope-and-deduplication)
+
+## Install and Manage
+
+> **Security:** Pi packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages.
+
+```bash
+pi install npm:@foo/bar@1.0.0
+pi install git:github.com/user/repo@v1
+pi install https://github.com/user/repo  # raw URLs work too
+pi install /absolute/path/to/package
+pi install ./relative/path/to/package
+
+pi remove npm:@foo/bar
+pi list                     # show installed packages from settings
+pi update                   # update pi, update packages, and reconcile pinned git refs
+pi update --extensions      # update packages and reconcile pinned git refs only
+pi update --self            # update pi only
+pi update --self --force    # reinstall pi even if current
+pi update npm:@foo/bar      # update one package
+pi update --extension npm:@foo/bar
+```
+
+These commands manage pi packages, not Claude-compatible plugins or the pi CLI installation. To install Claude-compatible plugins, use [`pi plugins`](plugins.md). To uninstall pi itself, see [Quickstart](quickstart.md#uninstall).
+
+By default, `install` and `remove` write to user settings (`~/.pi/agent/settings.json`). Use `-l` to write to project settings (`.pi/settings.json`) instead. Project settings can be shared with your team, and pi installs any missing packages automatically on startup after the project is trusted.
+
+To try a package without installing it, use `--extension` or `-e`. This installs to a temporary directory for the current run only:
+
+```bash
+pi -e npm:@foo/bar
+pi -e git:github.com/user/repo
+```
+
+## Package Sources
+
+Pi accepts three source types in settings and `pi install`.
+
+### npm
+
+```
+npm:@scope/pkg@1.2.3
+npm:pkg
+```
+
+- Versioned specs are pinned and skipped by package updates (`pi update`, `pi update --extensions`).
+- User installs go under `~/.pi/agent/npm/`.
+- Project installs go under `.pi/npm/`.
+- Set `npmCommand` in `settings.json` to pin npm package lookup and install operations to a specific wrapper command such as `mise` or `asdf`.
+
+Example:
+
+```json
+{
+  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
+}
+```
+
+### git
+
+```
+git:github.com/user/repo@v1
+git:git@github.com:user/repo@v1
+https://github.com/user/repo@v1
+ssh://git@github.com/user/repo@v1
+```
+
+- Without `git:` prefix, only protocol URLs are accepted (`https://`, `http://`, `ssh://`, `git://`).
+- With `git:` prefix, shorthand formats are accepted, including `github.com/user/repo` and `git@github.com:user/repo`.
+- HTTPS and SSH URLs are both supported.
+- SSH URLs use your configured SSH keys automatically (respects `~/.ssh/config`).
+- For non-interactive runs (for example CI), you can set `GIT_TERMINAL_PROMPT=0` to disable credential prompts and set `GIT_SSH_COMMAND` (for example `ssh -o BatchMode=yes -o ConnectTimeout=5`) to fail fast.
+- Refs are pinned tags or commits. `pi update` and `pi update --extensions` do not move them to newer refs, but they do reconcile an existing clone to the configured ref.
+- Use `pi install git:host/user/repo@new-ref` to update settings and move an existing package to a new pinned ref.
+- Cloned to `~/.pi/agent/git/<host>/<path>` (global) or `.pi/git/<host>/<path>` (project).
+- When reconciliation changes the checkout, pi resets and cleans the clone, then runs `npm install` if `package.json` exists.
+
+**SSH examples:**
+```bash
+# git@host:path shorthand (requires git: prefix)
+pi install git:git@github.com:user/repo
+
+# ssh:// protocol format
+pi install ssh://git@github.com/user/repo
+
+# With version ref
+pi install git:git@github.com:user/repo@v1.0.0
+```
+
+### Local Paths
+
+```
+/absolute/path/to/package
+./relative/path/to/package
+```
+
+Local paths point to files or directories on disk and are added to settings without copying. Relative paths are resolved against the settings file they appear in. If the path is a file, it loads as a single extension. If it is a directory, pi loads resources using package rules.
+
+## Creating a Pi Package
+
+Add a `pi` manifest to `package.json` or use conventional directories. Include the `pi-package` keyword for discoverability.
+
+```json
+{
+  "name": "my-package",
+  "keywords": ["pi-package"],
+  "pi": {
+    "extensions": ["./extensions"],
+    "skills": ["./skills"],
+    "prompts": ["./prompts"],
+    "themes": ["./themes"]
+  }
+}
+```
+
+Paths are relative to the package root. Arrays support glob patterns and `!exclusions`.
+
+### Gallery Metadata
+
+The [package gallery](https://pi.dev/packages) displays packages tagged with `pi-package`. Add `video` or `image` fields to show a preview:
+
+```json
+{
+  "name": "my-package",
+  "keywords": ["pi-package"],
+  "pi": {
+    "extensions": ["./extensions"],
+    "video": "https://example.com/demo.mp4",
+    "image": "https://example.com/screenshot.png"
+  }
+}
+```
+
+- **video**: MP4 only. On desktop, autoplays on hover. Clicking opens a fullscreen player.
+- **image**: PNG, JPEG, GIF, or WebP. Displayed as a static preview.
+
+If both are set, video takes precedence.
+
+## Package Structure
+
+### Convention Directories
+
+If no `pi` manifest is present, pi auto-discovers resources from these directories:
+
+- `extensions/` loads `.ts` and `.js` files
+- `skills/` recursively finds `SKILL.md` folders and loads top-level `.md` files as skills
+- `prompts/` loads `.md` files
+- `themes/` loads `.json` files
+
+## Dependencies
+
+Third party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, or themes also belong in `dependencies`. When pi installs a package from npm or git, it runs `npm install`, so those dependencies are installed automatically.
+
+Pi bundles core packages for extensions and skills. If you import any of these, list them in `peerDependencies` with a `"*"` range and do not bundle them: `@schovest/pi-ai`, `@schovest/pi-agent-core`, `@schovest/pi-coding-agent`, `@schovest/pi-tui`, `typebox`.
+
+Other pi packages must be bundled in your tarball. Add them to `dependencies` and `bundledDependencies`, then reference their resources through `node_modules/` paths. Pi loads packages with separate module roots, so separate installs do not collide or share modules.
+
+Example:
+
+```json
+{
+  "dependencies": {
+    "shitty-extensions": "^1.0.1"
+  },
+  "bundledDependencies": ["shitty-extensions"],
+  "pi": {
+    "extensions": ["extensions", "node_modules/shitty-extensions/extensions"],
+    "skills": ["skills", "node_modules/shitty-extensions/skills"]
+  }
+}
+```
+
+## Package Filtering
+
+Filter what a package loads using the object form in settings:
+
+```json
+{
+  "packages": [
+    "npm:simple-pkg",
+    {
+      "source": "npm:my-package",
+      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
+      "skills": [],
+      "prompts": ["prompts/review.md"],
+      "themes": ["+themes/legacy.json"]
+    }
+  ]
+}
+```
+
+`+path` and `-path` are exact paths relative to the package root.
+
+- Omit a key to load all of that type.
+- Use `[]` to load none of that type.
+- `!pattern` excludes matches.
+- `+path` force-includes an exact path.
+- `-path` force-excludes an exact path.
+- Filters layer on top of the manifest. They narrow down what is already allowed.
+
+## Enable and Disable Resources
+
+Use `pi config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. Works for both global (`~/.pi/agent`) and project (`.pi/`) scopes.
+
+## Scope and Deduplication
+
+Packages can appear in both global and project settings. If the same package appears in both, the project entry wins. Identity is determined by:
+
+- npm: package name
+- git: repository URL without ref
+- local: resolved absolute path

package/docs/plugins.md

@@ -0,0 +1,48 @@
+# Claude-Compatible Plugins
+
+Pi can install a subset of Claude marketplace plugins through the `pi plugins` command family. These plugins are separate from Pi packages.
+
+Use `pi install`, `pi remove`, `pi list`, and `pi update --extensions` for native Pi packages. Use `pi plugins ...` for Claude-compatible marketplace plugins.
+
+## Commands
+
+```bash
+pi plugins marketplace add claude https://github.com/example/marketplace
+pi plugins marketplace list
+pi plugins marketplace remove claude
+
+pi plugins search
+pi plugins search super
+pi plugins search super --marketplace claude
+
+pi plugins install superpowers@claude
+pi plugins install https://github.com/user/claude-plugin
+pi plugins install ./local/plugin -l
+
+pi plugins list
+pi plugins remove superpowers
+pi plugins update
+pi plugins update superpowers
+```
+
+By default, plugin settings are written to `~/.pi/agent/settings.json` and plugin clones are stored in `~/.pi/agent/plugins/`. Use `-l` with `install` or `remove` to use project scope: `.pi/settings.json` and `.pi/plugins/`.
+
+`pi plugins search [query]` searches the catalogs from configured `pluginMarketplaces`. With no query it lists all catalog entries. Use `--marketplace <name>` or `-m <name>` to search one configured marketplace.
+
+In interactive mode, `/plugins` opens the plugin manager. It can search marketplace catalogs, install a selected plugin to user or project scope, list installed user/project plugins, update or remove installed plugins, and list/add/remove configured marketplaces. Marketplace add/remove writes user settings by default, matching the CLI behavior.
+
+## Supported Claude Fields
+
+Pi reads `.claude-plugin/plugin.json` and supports:
+
+- `skills`: loaded into Pi's existing skills system.
+- `commands`: loaded as Pi prompt templates.
+- `mcpServers`: written to Pi-owned MCP config, `~/.pi/agent/mcp.json` for user scope or `.pi/mcp.json` for project scope.
+
+If `skills` or `commands` are omitted, Pi also checks conventional `skills/`, `commands/`, and `.claude/commands/` directories.
+
+MCP server names are prefixed with the plugin name to avoid collisions. For example, plugin `superpowers-chrome` server `chrome` becomes `superpowers-chrome-chrome`. `${CLAUDE_PLUGIN_ROOT}` is replaced with the installed plugin root. Other variables are left unchanged.
+
+## Unsupported Claude Fields
+
+Pi reports diagnostics for Claude runtime fields that it does not execute, including `hooks`, `agents`, and session hooks. Pi does not emulate Claude runtime behavior for those fields.

package/docs/primary-agents.md

@@ -0,0 +1,272 @@
+# Primary Agents
+
+Primary agent 是控制 agent 角色、工具集和系统提示词的顶层配置机制。每个会话激活一个 primary agent，决定 agent 的行为模式。
+
+## 概述
+
+Primary agent 通过以下方式影响 agent 行为：
+
+- **系统提示词**：agent 定义文件的 body 内容作为角色 prompt，始终 prepend 在系统提示词最前面
+- **工具集**：通过 `includedTools` / `excludedTools` 控制可用工具范围
+- **模型和思考级别**（可选）：可指定默认模型和思考级别
+
+切换 primary agent 后：
+- agent 角色 prompt 立即更新
+- 工具集立即重解析
+- 系统提示词自动重建
+- 选择持久化到项目 settings（`defaultPrimaryAgent`），下次启动自动恢复
+
+## 内置 Agent
+
+| Agent | 描述 | 工具 | 角色 Prompt |
+|-------|------|------|-------------|
+| `build` | 默认 agent，拥有全部工具，用于实现和执行 | 全部内置工具（read, bash, edit, write, grep, find, ls）+ `subagent` + 扩展注册的工具 | 无（使用默认系统提示词） |
+| `plan` | 规划 agent，只读工具，用于分析和设计 | 排除 `bash` 和 `subagent`；剩余工具（read, edit, write, grep, find, ls）均在列表中，但 prompt 约束为只读行为 | "You are a planning agent..." |
+
+`build` 是初始默认值，每次启动时如果未恢复其他 agent 则使用 `build`。`build` 的 `systemPrompt` 为空，意味着使用 Pi 的默认系统提示词（无额外角色 prompt）。
+
+`plan` 的实现是 `excludedTools: ["bash", "subagent"]`，未设置 `includedTools`，因此除 bash 和 subagent 外的所有工具都在可用列表中。plan 的 systemPrompt 要求不修改文件、不执行命令，实际效果为只读。
+
+## 加载和优先级
+
+Primary agent 从三个来源加载，按优先级覆盖：
+
+| 优先级 | 来源 | 路径 | Scope |
+|--------|------|------|-------|
+| 1（最低） | 内置 | 硬编码 | `builtin` |
+| 2 | 用户级 | `~/.pi/agent/primary-agents/*.md` | `user` |
+| 3（最高） | 项目级 | `.pi/primary-agents/*.md`（从 cwd 向上查找） | `project` |
+
+同名 agent 按优先级覆盖：项目 > 用户 > 内置。
+
+## 创建自定义 Primary Agent
+
+### 文件结构
+
+```
+~/.pi/agent/primary-agents/
+└── my-agent.md
+```
+
+或项目级：
+
+```
+.pi/primary-agents/
+└── my-agent.md
+```
+
+文件名（不含 `.md`）即为 agent 名称。
+
+### 格式
+
+```markdown
+---
+description: 简短描述 agent 的用途和行为
+model: anthropic/claude-sonnet-4-5
+thinking: high
+includedTools: [read, grep, find, ls]
+excludedTools: [subagent]
+---
+
+你是一个专注代码审查的 agent。分析代码变更，找出：
+1. 逻辑错误和边界情况
+2. 安全漏洞
+3. 性能问题
+4. 测试覆盖缺口
+
+始终提供具体的文件路径和行号。不要修改文件——只报告发现的问题。
+```
+
+### Frontmatter 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `description` | string | Agent 描述，显示在 agent 选择器中 |
+| `model` | string | 默认模型 ID，如 `anthropic/claude-sonnet-4-5`。切换到此 agent 时自动切换模型 |
+| `thinking` | string | 默认思考级别：`off`、`minimal`、`low`、`medium`、`high`、`xhigh` |
+| `includedTools` | string[] | 允许的工具列表，支持 glob 模式（详见下文） |
+| `excludedTools` | string[] | 排除的工具列表，支持 glob 模式（详见下文） |
+
+#### 工具匹配（glob 模式）
+
+`includedTools` / `excludedTools` 使用 [minimatch](https://github.com/isaacs/minimatch) glob 模式匹配工具名（大小写不敏感）：
+
+- `"read"` — 精确匹配 `read` 工具
+- `"read*"` — 匹配 `read`、`readFile` 等所有以 read 开头的工具
+- `"!*"` — 匹配所有工具的否定模式
+- 未设置 `includedTools` 且未设置 `excludedTools` — 使用全部已注册工具
+- `includedTools: []`（空数组）— 无工具
+- 若同时设置 `includedTools` 和 `excludedTools`，`includedTools` 生效，`excludedTools` 被忽略（included 优先）
+
+内置工具名：`read`、`bash`、`edit`、`write`、`grep`、`find`、`ls`。此外 `subagent` 工具由 coding-agent 扩展注册，扩展也可注册自定义工具名。
+
+> **注意**：Primary agent 不支持 `skills` 字段。Skills 继承是 subagent 独有的能力，primary agent 始终使用主会话加载的全部 skills。
+
+兼容性：`tools`（旧字段名）仍然可读，自动映射到 `includedTools`，优先使用 `includedTools`。
+
+### Body（系统提示词）
+
+Frontmatter 之后的 Markdown body 是 agent 的角色 prompt。它 **始终 prepend** 在完整系统提示词的最前面。这意味着即使存在 `SYSTEM.md` 或 `--system-prompt`，primary agent 的角色 prompt 依然在它们之前生效。
+
+**`build` agent 的特殊情况**：`build` 的 systemPrompt 为空字符串，因此不注入额外的角色 prompt，直接使用默认系统提示词（或 `SYSTEM.md` 自定义 prompt）。
+
+## 系统提示词构成
+
+完整系统提示词按以下优先级构成：
+
+| 顺序 | 组成部分 | 来源 | 是否可替换 |
+|------|----------|------|------------|
+| 1 | **Primary Agent Prompt** | Agent 定义文件的 body | 始终在最前 |
+| 2 | **Custom Prompt** | `.pi/SYSTEM.md` 或 `--system-prompt` | 存在时替换默认 prompt |
+| 3 | **Default Prompt** | 内置默认系统提示词 | 当 custom prompt 不存在时使用 |
+| 4 | **Append** | `APPEND_SYSTEM.md` 或 `--append-system-prompt` | 追加 |
+| 5 | **Context Files** | `AGENTS.md` / `CLAUDE.md` | 追加 |
+| 6 | **Skills** | Skills 元数据 | 追加 |
+| 7 | **Date & CWD** | 自动生成 | 末尾 |
+
+### 示例
+
+**使用默认 build agent**（systemPrompt 为空）：
+```
+[默认系统提示词]
+→ You are an expert coding assistant...
+→ Tools: ...
+→ Guidelines: ...
+
+→ AGENTS.md 内容
+→ Skills
+→ Current date and CWD
+```
+
+**使用 plan agent**（有 systemPrompt）：
+```
+[primaryAgentPrompt prepend]
+→ You are a planning agent. Analyze requirements...
+
+[默认系统提示词]
+→ You are an expert coding assistant...
+→ Tools: read, grep, find, ls
+→ Guidelines: ...
+
+→ AGENTS.md 内容
+→ Skills
+→ Current date and CWD
+```
+
+**使用自定义 agent + SYSTEM.md**（custom prompt 替换默认）：
+```
+[primaryAgentPrompt prepend]
+→ 你是一个专注代码审查的 agent...
+
+[SYSTEM.md 内容]
+→ 项目的自定义 prompt...
+
+→ AGENTS.md 内容
+→ Skills
+→ Current date and CWD
+```
+
+## 切换 Agent
+
+### 交互模式
+
+- 使用 `/agent` 打开 agent 选择器（TUI overlay）
+- 使用 `/agent <name>` 直接切换，如 `/agent plan`
+- Footer 始终显示当前 agent 名称（accent 颜色），格式：`{agent} • {model} • {thinking}`
+
+### SDK
+
+```typescript
+// 列出可用 agent
+const agents = await session.listPrimaryAgents();
+
+// 切换 agent
+await session.switchPrimaryAgent("plan");
+
+// 获取当前 agent
+const currentAgent = session.currentPrimaryAgent;  // "build" | "plan" | ...
+```
+
+### RPC
+
+```json
+// 获取可用 agent（通过 get_commands 获取 extension 注册的 agent 命令）
+{"type": "prompt", "message": "/agent"}
+```
+
+## 持久化
+
+切换 primary agent 时，选择自动保存到项目 settings（`.pi/settings.json`）：
+
+```json
+{
+  "defaultPrimaryAgent": "plan"
+}
+```
+
+下次在相同项目启动会话时，自动恢复上次使用的 agent（除非恢复的是 `build`，则不写入 settings）。恢复逻辑在 `restorePrimaryAgent()` 中实现，仅在 `savedAgent !== "build"` 且 agent 仍然存在时才切换。
+
+## Agent 选择器
+
+交互模式中的 agent 选择器（TUI overlay）显示：
+
+- 所有已发现的 agent（按字母顺序排列）
+- 每个 agent 的 scope（`builtin` / `user` / `project`）和描述
+- 当前激活的 agent 标记 `(active)`
+- 详细信息：描述、prompt 摘要（截断至 120 字符）、工具约束、模型、思考级别
+
+键盘控制：`↑/↓` 或 `j/k` 导航，`Enter` 选择，`Escape` 关闭。
+
+## 与 Subagent 的区别
+
+| 维度 | Primary Agent | Subagent |
+|------|---------------|----------|
+| 作用范围 | 整个会话 | 单次任务委托 |
+| 系统提示词 | 修改主 agent 的系统提示词 | 有自己的独立系统提示词 |
+| 工具控制 | `includedTools` / `excludedTools` | `includedTools` / `excludedTools` |
+| Skills 继承 | 不支持 `skills` 字段，始终使用主会话的全部 skills | 支持 `skills` 字段（glob 模式匹配，默认不继承） |
+| 持久化 | 自动保存到项目 settings | 不持久化 |
+| 数量 | 一个会话同时只有一个 | 可并行运行多个 |
+| 定义位置 | `primary-agents/*.md` | `subagents/*.md` |
+
+## 示例：创建代码审查 Agent
+
+```bash
+mkdir -p ~/.pi/agent/primary-agents
+cat > ~/.pi/agent/primary-agents/reviewer.md << 'EOF'
+---
+description: 代码审查专家，只读模式，分析代码质量和安全性
+model: anthropic/claude-sonnet-4-5
+thinking: high
+includedTools: [read, grep, find, ls]
+excludedTools: [bash, edit, write, subagent]
+---
+
+你是代码审查专家。对代码变更进行严格审查：
+
+检查清单：
+1. **逻辑正确性**：边界情况、空值处理、并发安全
+2. **安全性**：注入风险、权限问题、敏感数据泄漏
+3. **性能**：不必要的分配、N+1 查询、阻塞调用
+4. **可维护性**：命名清晰度、函数复杂度、代码重复
+
+输出格式：
+- 每个问题标注严重程度：🔴严重 / 🟡中等 / 🟢建议
+- 提供具体的文件路径和行号
+- 给出具体的修改建议
+
+不要修改任何文件，只报告发现的问题。
+EOF
+```
+
+然后在交互模式中使用：
+```
+/agent reviewer
+```
+
+## 相关文档
+
+- [Subagents](subagents.md) - 子 agent 任务委托
+- [Settings](settings.md) - `defaultPrimaryAgent` 设置
+- [Extensions](extensions.md) - 扩展 API 与系统提示词交互
+- [Usage](usage.md) - 系统提示词文件（SYSTEM.md / APPEND_SYSTEM.md）

package/docs/prompt-templates.md

@@ -0,0 +1,95 @@
+> pi can create prompt templates. Ask it to build one for your workflow.
+
+# Prompt Templates
+
+Prompt templates are Markdown snippets that expand into full prompts. Type `/name` in the editor to invoke a template, where `name` is the filename without `.md`.
+
+## Locations
+
+Pi loads prompt templates from:
+
+- Global: `~/.pi/agent/prompts/*.md`
+- Project: `.pi/prompts/*.md` (only after the project is trusted)
+- Packages: `prompts/` directories or `pi.prompts` entries in `package.json`
+- Settings: `prompts` array with files or directories
+- CLI: `--prompt-template <path>` (repeatable)
+
+Disable discovery with `--no-prompt-templates`.
+
+## Format
+
+```markdown
+---
+description: Review staged git changes
+---
+Review the staged changes (`git diff --cached`). Focus on:
+- Bugs and logic errors
+- Security issues
+- Error handling gaps
+```
+
+- The filename becomes the command name. `review.md` becomes `/review`.
+- `description` is optional. If missing, the first non-empty line is used.
+- `argument-hint` is optional. When set, the hint is displayed before the description in the autocomplete dropdown.
+
+### Argument Hints
+
+Use `argument-hint` in frontmatter to show expected arguments in autocomplete. Use `<angle brackets>` for required arguments and `[square brackets]` for optional ones:
+
+```markdown
+---
+description: Review PRs from URLs with structured issue and code analysis
+argument-hint: "<PR-URL>"
+---
+```
+
+This renders in the autocomplete dropdown as:
+
+```
+→ pr   <PR-URL>       — Review PRs from URLs with structured issue and code analysis
+  is   <issue>        — Analyze GitHub issues (bugs or feature requests)
+  wr   [instructions] — Finish the current task end-to-end
+  cl   — Audit changelog entries before release
+```
+
+## Usage
+
+Type `/` followed by the template name in the editor. Autocomplete shows available templates with descriptions.
+
+```
+/review                           # Expands review.md
+/component Button                 # Expands with argument
+/component Button "click handler" # Multiple arguments
+```
+
+## Arguments
+
+Templates support positional arguments, defaults, and simple slicing:
+
+- `$1`, `$2`, ... positional args
+- `$@` or `$ARGUMENTS` for all args joined
+- `${1:-default}` uses arg 1 when present/non-empty, otherwise `default`
+- `${@:N}` for args from the Nth position (1-indexed)
+- `${@:N:L}` for `L` args starting at N
+
+Example:
+
+```markdown
+---
+description: Create a component
+---
+Create a React component named $1 with features: $@
+```
+
+Default values are useful for optional arguments:
+
+```markdown
+Summarize the current state in ${1:-7} bullet points.
+```
+
+Usage: `/component Button "onClick handler" "disabled support"`
+
+## Loading Rules
+
+- Template discovery in `prompts/` is non-recursive.
+- If you want templates in subdirectories, add them explicitly via `prompts` settings or a package manifest.