pi-agents-init

A pi extension that adds an /init command for guided AGENTS.md authoring.

It adapts OpenCode's /init prompt for pi's context model: AGENTS.md files stack across the directory tree, and a good init should account for that rather than treating the repo as flat.

Install

pi install npm:pi-agents-init

Usage

/init                          # author/update AGENTS.md for the whole tree
/init focus on the deploy flow # emphasize one area

What it does

The command has the agent read the repo and author (or update) AGENTS.md at the current level, and handle layering when child AGENTS.md files exist. Optional focus text narrows what the agent emphasizes.

No extra dependencies — single command, one prompt template.

How it improves on OpenCode's /init

OpenCode's /init is a single static prompt: it says "create or update," ignores nested AGENTS.md files, and tacks update guidance onto the end whether or not a file exists. This extension adapts the prompt to the actual situation: create vs. update is decided up front, and layering guidance only appears when children exist:

1. Nested AGENTS.md layering

The extension walks the subdirectories for you, skipping node_modules, dist, build, and other generated trees, collects any child AGENTS.md files it finds, then hands their paths to the agent. The prompt tells the agent to author for this level and point to children by path rather than re-enumerating what lives in their subtrees (the child owns its subtree). When there are no children, the layering guidance is omitted entirely; the model doesn't reason about stacking it doesn't need.

2. Create vs. update, decided up front

The extension detects whether an AGENTS.md already exists at this level and picks one mode:

• No existing file: the agent creates a new AGENTS.md.
• Existing file: the agent updates it in place — preserves verified useful guidance, deletes fluff or stale claims, and reconciles it with the current codebase. It does not blindly rewrite or overwrite.

No conditional "create or update" phrasing reaches the model. It gets one direct instruction set for the situation it's actually in, so the model isn't branching on a condition it already knows the answer to.

3. Descendant clause tracks the layering decision

The writing rules' "exclude details that belong in a descendant's own AGENTS.md" bullet appears only when children exist, so the rules stay consistent with the layering section.

4. Opinionated toward the portable AGENTS.md convention

OpenCode's /init reads every instruction file it can find — AGENTS.md, CLAUDE.md, .cursor/rules/, .cursorrules, .github/copilot-instructions.md, opencode.json. This extension narrows to the portable AGENTS.md convention: AGENTS.md, AGENTS.override.md, and repo-local settings.json.

Pi itself loads CLAUDE.md too, so /init could read it. It chooses not to. AGENTS.md is a plain, vendor-neutral file you own — not one named for a product — and standardizing on it keeps guidance portable across any harness that respects the convention. If a repo keeps high-signal guidance in a CLAUDE.md or .cursorrules, fold the relevant bits into a $ARGUMENTS focus note, or fork this extension and widen the investigation list. The default stays opinionated: author for the open convention.

License

AGPL-3.0-or-later.