diff --git a/.rulesync/skills/rulesync-feature-research/references/pi.md b/.rulesync/skills/rulesync-feature-research/references/pi.md index 594c06c13..4fecdc29d 100644 --- a/.rulesync/skills/rulesync-feature-research/references/pi.md +++ b/.rulesync/skills/rulesync-feature-research/references/pi.md @@ -2,17 +2,17 @@ ## Official Docs -| Feature | Official docs | Upstream surface | -| ------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------ | -| index | `https://pi.dev/docs/latest` | Pi Coding Agent documentation index | -| `rules` | `https://pi.dev/docs/latest/usage` | `AGENTS.md`, `CLAUDE.md`, global `~/.pi/agent/AGENTS.md`, context-file discovery | -| `ignore` | No dedicated upstream ignore surface in map | No Rulesync-supported Pi ignore target in map | -| `mcp` | No dedicated upstream MCP surface in map | No Rulesync-supported Pi MCP target in map | -| `commands` | `https://pi.dev/docs/latest/prompt-templates` | `.pi/prompts/*.md`, `~/.pi/agent/prompts/*.md`, prompt template frontmatter and `/name` commands | -| `subagents` | No dedicated upstream subagents surface in map | No Rulesync-supported Pi subagents target in map | -| `skills` | `https://pi.dev/docs/latest/skills` | `.pi/skills`, `~/.pi/agent/skills`, `.agents/skills`, packages, settings, `--skill` | -| `hooks` | No dedicated upstream hooks surface in map | No Rulesync-supported Pi hooks target in map | -| `permissions` | No dedicated upstream permissions surface in map | Tool selection and settings exist upstream | +| Feature | Official docs | Upstream surface | +| ------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | +| index | `https://pi.dev/docs/latest` | Pi Coding Agent documentation index | +| `rules` | `https://pi.dev/docs/latest/usage` | `AGENTS.md`, `CLAUDE.md`, global `~/.pi/agent/AGENTS.md`, context-file discovery, `SYSTEM.md` / `APPEND_SYSTEM.md` system-prompt files | +| `ignore` | No dedicated upstream ignore surface in map | No Rulesync-supported Pi ignore target in map | +| `mcp` | No dedicated upstream MCP surface in map | No Rulesync-supported Pi MCP target in map | +| `commands` | `https://pi.dev/docs/latest/prompt-templates` | `.pi/prompts/*.md`, `~/.pi/agent/prompts/*.md`, prompt template frontmatter and `/name` commands | +| `subagents` | No dedicated upstream subagents surface in map | No Rulesync-supported Pi subagents target in map | +| `skills` | `https://pi.dev/docs/latest/skills` | `.pi/skills`, `~/.pi/agent/skills`, `.agents/skills`, packages, settings, `--skill` | +| `hooks` | No dedicated upstream hooks surface in map | No Rulesync-supported Pi hooks target in map | +| `permissions` | No dedicated upstream permissions surface in map | Tool selection and settings exist upstream | ## Client Anchors @@ -23,3 +23,14 @@ Common adapter paths: `rulesync-source-map.md`. | `rules` | Project and global context-file conversion in `pi-rule.ts` | | `commands` | `.pi/prompts`, `~/.pi/agent/prompts`, `argument-hint`, and prompt template conversion in `pi-command.ts` | | `skills` | `.pi/skills`, global `.pi/agent/skills`, and Agent Skills conversion in `pi-skill.ts` | + +## System-prompt instruction files (not yet mapped) + +Beyond `AGENTS.md`, Pi loads two system-prompt instruction files (docs: `https://pi.dev/docs/latest/usage`): + +| File | Project scope | Global scope | Effect | +| ------------------ | ---------------------- | ------------------------------ | ---------------------------------------- | +| `SYSTEM.md` | `.pi/SYSTEM.md` | `~/.pi/agent/SYSTEM.md` | **Replaces** the default system prompt | +| `APPEND_SYSTEM.md` | `.pi/APPEND_SYSTEM.md` | `~/.pi/agent/APPEND_SYSTEM.md` | **Appends** to the default system prompt | + +Rulesync does not currently emit these files. Rulesync's rules model only routes a designated `root` rule to a single context file (`AGENTS.md`) and folds non-root rules into it; it has no convention for marking a rule as "replace the system prompt" vs "append to the system prompt". Wiring `SYSTEM.md` / `APPEND_SYSTEM.md` would require a new frontmatter routing convention, so this surface is documented here rather than implemented. diff --git a/docs/reference/file-formats.md b/docs/reference/file-formats.md index 8bc059d1d..1fbb502b8 100644 --- a/docs/reference/file-formats.md +++ b/docs/reference/file-formats.md @@ -64,6 +64,8 @@ This is Rulesync, a Node.js CLI tool that automatically generates configuration > **Cline note:** Cline writes the root rule to the auto-loaded `AGENTS.md` (project) as plain Markdown, and non-root rules to its flat `.clinerules/` directory. Each non-root rule is a Markdown file with optional YAML frontmatter for conditional activation: Rulesync maps `globs` ⇄ Cline's `paths` (a glob array; the rule loads only when a matching file is in context) and `description` ⇄ `description`. A rule with **specific** `globs` emits `paths`; a rule with **universal** globs (`**/*` or `*`) emits `alwaysApply: true` (always load); a rule **without** globs is written as plain Markdown with no frontmatter block (always active). In global mode (via `--global`), Cline rules are written to the cross-tool `~/.agents/AGENTS.md` (Cline CLI v3.0.15+) as plain Markdown. See the [Cline rules docs](https://docs.cline.bot/customization/cline-rules). +> **Pi note:** Pi writes the root rule to the auto-loaded `AGENTS.md` (project) / `~/.pi/agent/AGENTS.md` (global, via `--global`) as plain Markdown, and folds non-root rules into that single file (Pi has no modular rules directory). Pi additionally supports two system-prompt instruction files that Rulesync does **not** currently emit: `.pi/SYSTEM.md` (project) / `~/.pi/agent/SYSTEM.md` (global) **replaces** the default system prompt entirely, and `.pi/APPEND_SYSTEM.md` (project) / `~/.pi/agent/APPEND_SYSTEM.md` (global) **appends** to it. Rulesync's rules model only routes a designated `root` rule to a single context file and has no frontmatter convention for marking a rule as "replace the system prompt" versus "append to the system prompt", so these files are left to be authored by hand. See the [Pi usage docs](https://pi.dev/docs/latest/usage). + ## `.rulesync/hooks.json` Hooks run scripts at lifecycle events (e.g. session start, before tool use). Events use **canonical camelCase** in this file, and Rulesync translates them per tool: Cursor uses them as-is; Claude Code, Factory Droid, Codex CLI, Gemini CLI, and Goose get PascalCase (with a few tool-specific name mappings) in their settings files; OpenCode and Kilo hooks are emitted as JavaScript plugins (`.opencode/plugins/rulesync-hooks.js`, `.kilo/plugins/rulesync-hooks.js`); Copilot and Copilot CLI map event names to their own camelCase (e.g. `beforeSubmitPrompt` → `userPromptSubmitted`, `stop` → `agentStop`, `afterError` → `errorOccurred`) and use `powershell`/`bash` command fields — Copilot CLI additionally covers a wider event set and supports `prompt` and `http` hook types beyond `command`; deepagents-cli uses a dot-notation (e.g. `session.start`, `tool.error`); Kiro emits hooks into `.kiro/agents/default.json` using Kiro's CLI event names (`agentSpawn`, `userPromptSubmit`, `preToolUse`, `postToolUse`, `stop`); Qwen Code emits PascalCase events into the `hooks` key of `.qwen/settings.json` (its supported event set differs from Gemini CLI's). diff --git a/skills/rulesync/file-formats.md b/skills/rulesync/file-formats.md index 8bc059d1d..1fbb502b8 100644 --- a/skills/rulesync/file-formats.md +++ b/skills/rulesync/file-formats.md @@ -64,6 +64,8 @@ This is Rulesync, a Node.js CLI tool that automatically generates configuration > **Cline note:** Cline writes the root rule to the auto-loaded `AGENTS.md` (project) as plain Markdown, and non-root rules to its flat `.clinerules/` directory. Each non-root rule is a Markdown file with optional YAML frontmatter for conditional activation: Rulesync maps `globs` ⇄ Cline's `paths` (a glob array; the rule loads only when a matching file is in context) and `description` ⇄ `description`. A rule with **specific** `globs` emits `paths`; a rule with **universal** globs (`**/*` or `*`) emits `alwaysApply: true` (always load); a rule **without** globs is written as plain Markdown with no frontmatter block (always active). In global mode (via `--global`), Cline rules are written to the cross-tool `~/.agents/AGENTS.md` (Cline CLI v3.0.15+) as plain Markdown. See the [Cline rules docs](https://docs.cline.bot/customization/cline-rules). +> **Pi note:** Pi writes the root rule to the auto-loaded `AGENTS.md` (project) / `~/.pi/agent/AGENTS.md` (global, via `--global`) as plain Markdown, and folds non-root rules into that single file (Pi has no modular rules directory). Pi additionally supports two system-prompt instruction files that Rulesync does **not** currently emit: `.pi/SYSTEM.md` (project) / `~/.pi/agent/SYSTEM.md` (global) **replaces** the default system prompt entirely, and `.pi/APPEND_SYSTEM.md` (project) / `~/.pi/agent/APPEND_SYSTEM.md` (global) **appends** to it. Rulesync's rules model only routes a designated `root` rule to a single context file and has no frontmatter convention for marking a rule as "replace the system prompt" versus "append to the system prompt", so these files are left to be authored by hand. See the [Pi usage docs](https://pi.dev/docs/latest/usage). + ## `.rulesync/hooks.json` Hooks run scripts at lifecycle events (e.g. session start, before tool use). Events use **canonical camelCase** in this file, and Rulesync translates them per tool: Cursor uses them as-is; Claude Code, Factory Droid, Codex CLI, Gemini CLI, and Goose get PascalCase (with a few tool-specific name mappings) in their settings files; OpenCode and Kilo hooks are emitted as JavaScript plugins (`.opencode/plugins/rulesync-hooks.js`, `.kilo/plugins/rulesync-hooks.js`); Copilot and Copilot CLI map event names to their own camelCase (e.g. `beforeSubmitPrompt` → `userPromptSubmitted`, `stop` → `agentStop`, `afterError` → `errorOccurred`) and use `powershell`/`bash` command fields — Copilot CLI additionally covers a wider event set and supports `prompt` and `http` hook types beyond `command`; deepagents-cli uses a dot-notation (e.g. `session.start`, `tool.error`); Kiro emits hooks into `.kiro/agents/default.json` using Kiro's CLI event names (`agentSpawn`, `userPromptSubmit`, `preToolUse`, `postToolUse`, `stop`); Qwen Code emits PascalCase events into the `hooks` key of `.qwen/settings.json` (its supported event set differs from Gemini CLI's). diff --git a/src/features/rules/pi-rule.ts b/src/features/rules/pi-rule.ts index fbd87886f..64a4bad4e 100644 --- a/src/features/rules/pi-rule.ts +++ b/src/features/rules/pi-rule.ts @@ -28,7 +28,7 @@ export type PiRuleSettablePaths = Pick & { /** * Rule generator for Pi Coding Agent. * - * Pi loads instruction context only from the `AGENTS.md` / `CLAUDE.md` family — + * Pi loads instruction context from the `AGENTS.md` / `CLAUDE.md` family — * the global `~/.pi/agent/AGENTS.md` plus files discovered by walking up the * directory tree from the current working directory. It does NOT resolve * `@`-imports or a TOON file list, and has no `.agents/memories/` concept, so @@ -39,6 +39,15 @@ export type PiRuleSettablePaths = Pick & { * to map onto; their bodies are folded into the single root `AGENTS.md` by the * RulesProcessor (there is no separate non-root output location — `nonRoot` is * `undefined`). This mirrors the codexcli, grokcli, warp, and deepagents targets. + * + * Pi also loads two system-prompt instruction files that rulesync does NOT emit: + * `.pi/SYSTEM.md` (global `~/.pi/agent/SYSTEM.md`) *replaces* the default system + * prompt entirely, and `.pi/APPEND_SYSTEM.md` (global + * `~/.pi/agent/APPEND_SYSTEM.md`) *appends* to it. rulesync's rules model only + * routes a designated `root` rule to a single context file and has no convention + * for marking a rule as "replace" vs "append" the system prompt, so these + * surfaces are documented in docs/reference/file-formats.md and left to be + * authored by hand rather than mapped to a speculative new frontmatter flag. */ export class PiRule extends ToolRule { constructor({ fileContent, root, ...rest }: PiRuleParams) {