Prompt AGENTS.md @piex-dev/init

init — One-Shot Project AGENTS.md

TL;DR

/init invents no new protocol: it turns "scan repo → write rules" into a repeatable prompt so every new project establishes agent conventions on day one.

Overview

An agent's first step in a repo should be reading project rules, but reality is: no rules, stale rules, high migration cost, inconsistent entry points. Without high-signal rules the agent guesses wrong test commands, breaks package boundaries, repeats environment pitfalls. @piex-dev/init fixes it: pi install once, then /init.

How it works

Pi only loads rules, never generates them: the core walks up from ~/.pi/agent and cwd to discover AGENTS.md/CLAUDE.md and inject into the system prompt, but has no built-in /init. Prompt template = zero-code slash command: prompts/init.md's filename is the command name, supports $ARGUMENTS, and Pi expands it into a full user message for the current session model.

The value is the investigation checklist, not template length: a good init prompt specifies three things — what to read first, what to extract, what to write/not write. Executable sources (package.json scripts, CI, lockfile) beat prose README; existing rules are improved in place, not blindly overwritten.

Usage

Install

bash

pi install npm:@piex-dev/init

Source: prompts/init

Usage

bash

/init           # scan the repo and generate/improve AGENTS.md
/init <notes>    # with extra notes

After writing, it prompts /reload to activate in the current session.

Configuration

Pure prompt package: no TypeScript, no peer deps, no runtime code. package.json declares "pi": { "prompts": ["./init.md"] }; prompts/init.md is the command body.

Implementation

A pure prompt package — no extensions/, no peer deps.

tree

prompts/init/
├── package.json          # "pi": { "prompts": ["./init.md"] }
├── README.md
└── init.md

init.md requires: read README/manifest/build-test-CI/existing-instruction/.pi/settings.json first; keep only high-signal facts agents easily get wrong; ask the user only for conventions the repo can't answer; write to project-root AGENTS.md and prompt /reload. Deliberately not done: auto-writing global ~/.pi/agent/AGENTS.md, interactive menus, extension wrapping.

Design notes

Project	Mechanism	piex choice
OpenCode /init	built-in slash, template injected; can ask question; in-place improve `AGENTS.md`	Adopted checklist, writing rules, `$ARGUMENTS`, in-place improvement. Not adopted built-in core, opencode-specific config; instead a pi `prompts/` package
oh-my-pi	multi-provider discover/load rules; no generating `/init`	Not redone the load layer (pi already walks up). Borrowed "rules are first-class context", fills the generation side
pi native	`loadProjectContextFiles` read-only; `prompts/*.md` as slash	Built directly on prompt template, zero runtime, upgrades with pi

Conclusion: generation logic should be a "distributable prompt", not a second agent-core feature.

Changelog

Roadmap

Current	Impact	Plan
Single-file prompt, relies on model honesty	no structured quality check	optional thin extension injecting absolute paths & "exists → prompt update"
—	complex monorepos may miss per-package commands; manual `/reload`	post-gen checklist (test/lint present?); `/init global` for user-level rules
—	rules can't accumulate in session	link with learning extensions (sediment rules in-session, merge into AGENTS.md)

Version history

Version	Date	Changes
0.1.0	2026-07-19	Initial release: pure prompt package (`pi.prompts`); `/init` scans the repo to generate/improve `AGENTS.md`; checklist (README/manifest/CI/lockfile over prose); in-place improvement without blind overwrite; prompts `/reload` after writing

Source Markdown: docs/packages/init.md