Skip to content

docs(pi): record SYSTEM.md / APPEND_SYSTEM.md system-prompt surface #2088

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dyoshikawa merged 1 commit into from
Jun 30, 2026
Merged

docs(pi): record SYSTEM.md / APPEND_SYSTEM.md system-prompt surface #2088

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 22 additions & 11 deletions .rulesync/skills/rulesync-feature-research/references/pi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.
2 changes: 2 additions & 0 deletions docs/reference/file-formats.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
2 changes: 2 additions & 0 deletions skills/rulesync/file-formats.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
11 changes: 10 additions & 1 deletion src/features/rules/pi-rule.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ export type PiRuleSettablePaths = Pick<ToolRuleSettablePaths, "root"> & {
/**
* 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
Expand All @@ -39,6 +39,15 @@ export type PiRuleSettablePaths = Pick<ToolRuleSettablePaths, "root"> & {
* 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) {
Expand Down
Loading