feat: ship a global AGENTS.md via the global-agents extension #10

Merged

alex merged 1 commit from pi/issue9-1782836087 into master

2026-06-30 16:31:34 +00:00

forgejo-actions commented

2026-06-30 16:15:09 +00:00

Summary

Removes the need to manually drop ~/.pi/agent/AGENTS.md by shipping the global agent rules with this package. After pi install git:forge.l3x.in/alex/pi-shared, the rules are active in every session automatically.

Fixes #9

How it works (the extensibility analysis)

Pi packages can declare extensions, skills, prompts, and themes in their manifest, but cannot ship a global context file. Global AGENTS.md files are loaded only from the global agent dir (~/.pi/agent/AGENTS.md, via loadProjectContextFiles) or from project ancestors — there is no package manifest key or resources_discover return value for context files.

The cleanest native way to close that gap is an extension that injects the rules into the system prompt through the before_agent_start hook (returning { systemPrompt }, the exact mechanism pi's own examples/extensions/claude-rules.ts uses).

Changes

agents/AGENTS.md — the global rules content (sandbox Git env, "don't commit/push without permission", Markdown no-wrap policy).
extensions/global-agents.ts — a new extension that:
- resolves agents/AGENTS.md relative to itself via import.meta.url,
- re-reads it on every session_start (so /new and /reload pick up edits without a restart),
- appends it to the fully-assembled system prompt in a <global_context> block, mirroring pi's own <project_context> context-file format.
It is auto-discovered because the existing manifest already declares "extensions": ["./extensions"] — no package.json change needed.
README.md — documents the feature and how to disable it (pi config → disable global-agents, or filter in settings.json).

Verification

tsc --strict typecheck against the installed @earendil-works/pi-coding-agent types passes.
Loaded the extension through pi's actual loader (jiti) and exercised both handlers:
- session_start → refreshes the cached rules without error
- before_agent_start → correctly appends the <global_context> block (860 chars) containing the rules to the base system prompt.

To disable the rules: pi config → disable global-agents, or filter it out in settings.json (see docs/packages.md "Package Filtering").

## Summary Removes the need to manually drop `~/.pi/agent/AGENTS.md` by shipping the global agent rules with this package. After `pi install git:forge.l3x.in/alex/pi-shared`, the rules are active in every session automatically. Fixes #9 ## How it works (the extensibility analysis) Pi packages can declare `extensions`, `skills`, `prompts`, and `themes` in their manifest, but **cannot** ship a global context file. Global `AGENTS.md` files are loaded _only_ from the global agent dir (`~/.pi/agent/AGENTS.md`, via `loadProjectContextFiles`) or from project ancestors — there is no package manifest key or `resources_discover` return value for context files. The cleanest native way to close that gap is an **extension** that injects the rules into the system prompt through the `before_agent_start` hook (returning `{ systemPrompt }`, the exact mechanism pi's own `examples/extensions/claude-rules.ts` uses). ## Changes - **`agents/AGENTS.md`** — the global rules content (sandbox Git env, "don't commit/push without permission", Markdown no-wrap policy). - **`extensions/global-agents.ts`** — a new extension that: - resolves `agents/AGENTS.md` relative to itself via `import.meta.url`, - re-reads it on every `session_start` (so `/new` and `/reload` pick up edits without a restart), - appends it to the fully-assembled system prompt in a `<global_context>` block, mirroring pi's own `<project_context>` context-file format. - It is auto-discovered because the existing manifest already declares `"extensions": ["./extensions"]` — **no `package.json` change needed**. - **`README.md`** — documents the feature and how to disable it (`pi config` → disable `global-agents`, or filter in `settings.json`). ## Verification - `tsc --strict` typecheck against the installed `@earendil-works/pi-coding-agent` types passes. - Loaded the extension through pi's actual loader (**jiti**) and exercised both handlers: - `session_start` → refreshes the cached rules without error - `before_agent_start` → correctly appends the `<global_context>` block (860 chars) containing the rules to the base system prompt. To disable the rules: `pi config` → disable `global-agents`, or filter it out in `settings.json` (see `docs/packages.md` "Package Filtering").

forgejo-actions added 1 commit

2026-06-30 16:15:09 +00:00

feat: ship a global AGENTS.md via the global-agents extension f99a0aeef0

Add a global-agents extension that injects agents/AGENTS.md into every
session's system prompt through the before_agent_start hook, so the
package itself ships the global coding-agent rules and the manual
~/.pi/agent/AGENTS.md file is no longer needed.

Pi packages cannot declare a global context file (only extensions,
skills, prompts, themes), so an extension is the native way to provide
always-on global instructions. The extension auto-loads via the existing
"extensions": ["./extensions"] manifest entry.

Fixes #9

forgejo-actions referenced this pull request

2026-06-30 16:15:21 +00:00

Share a global AGENTS.md #9