docs(pi): record SYSTEM.md / APPEND_SYSTEM.md system-prompt surface - #2088
Merged
Conversation
Pi Coding Agent loads two system-prompt instruction files beyond AGENTS.md: .pi/SYSTEM.md (global ~/.pi/agent/SYSTEM.md) replaces the default system prompt, 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 wiring these files would require inventing a new frontmatter routing convention. Document the surface in the Pi reference map, docs/reference/file-formats.md, and the PiRule class comment instead of implementing a speculative convention. Refs #2073 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This was referenced Jun 30, 2026
Closed
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up for Pi upstream updates (#2073). Pi loads two system-prompt instruction files beyond
AGENTS.md—.pi/SYSTEM.md(replaces the default system prompt) and.pi/APPEND_SYSTEM.md(extends it), at both project (.pi/) and global (~/.pi/agent/) scope.Approach: documentation-only (emission deferred)
rulesync's rules model only supports root-vs-nonRoot routing (Pi folds all rules into a single
AGENTS.md). There is no existing precedent for replace-vs-append system-prompt routing, and emittingSYSTEM.md/APPEND_SYSTEM.mdwould require inventing a speculative new frontmatter convention — which the issue explicitly scopes out. So this PR lands the issue's stated minimum: record the surface.Changes
references/pi.md): documents theSYSTEM.md/APPEND_SYSTEM.mdpaths, replace/append semantics, and why they are currently unmapped.docs/reference/file-formats.md(+ synced skill copy): adds a Pi note.src/features/rules/pi-rule.ts: corrects an inaccurate class comment.Full emission remains an open maintainer design decision, so this PR references rather than closes the issue.
Verification
pnpm cicheckfully green (292 test files, 6570 tests).Refs #2073