@wsxyt/pi-agents-md

A Pi package for nested AGENTS.md context injection and autonomous, managed instruction files.

Install

pi install npm:@wsxyt/pi-agents-md

The package registers one extension entrypoint and two on-demand skills. It supports Pi >=0.84.2 <0.85.0 on Node >=24 <25 and has no runtime dependency beyond Pi's peer packages.

What It Does

• Appends descendant AGENTS.md guidance only after successful textual read results.
• Resolves instruction candidates canonically, rejects symlinks and outside-root paths, and enforces file, read, and session byte budgets.
• Lets the AI explore the repository, summarize its structure, and choose useful root and child scopes.
• Generates and applies package-owned blocks automatically with preimage checks and same-directory atomic renames.
• Adds one persistent maintenance cue after a successful source edit or write, limited to affected scopes.

The package generates only AGENTS.md. AGENTS.override.md is read for precedence but is never generated.

Commands

Command	Purpose
/agents-init	Autonomously explore the repository, generate practical guidance, and write it.
/agents-cancel	Stop a stalled initialization and unblock ordinary writes.
/agents-audit [path]	Check managed scopes for marker, scope, and line-budget problems.
/agents-apply <plan-id>	Apply an already staged fallback plan.
/agents-refresh	Clear the nested instruction read cache.
/agents-status	Show injection decisions, budgets, maintenance, and initialization state.

Normal source edits can add a prompt-mode maintenance cue. The cue activates agents_scan_changed, then the package-owned agents_apply_managed tool after a validated fact pack is available. maxAffectedFiles caps distinct changed source paths in one agent run. Configure the behavior in trusted .pi/agents-md.json or the global agent config:

{
  "maintenance": {
    "mode": "prompt",
    "maxCuesPerAgentRun": 1,
    "maxAffectedFiles": 12,
    "maxGeneratedBytes": 32768,
    "allowHeadlessAuto": false
  }
}

Modes are prompt, settled, review, and off. review records a notification only; it does not generate or apply a draft. Automatic modes are disabled in print and JSON runs unless explicitly enabled.

Safety Model

Pi's startup context remains the authority for ancestor instructions. This extension considers descendants only and appends provenance-labelled text without replacing the original read result. It never fetches prompt sources at runtime. Generated files must still pass scope, path, marker, preimage, per-file, and effective-chain limits.

/agents-init gives the AI an autonomous exploration turn: it can inspect the repository with read, search, code-navigation, project-analysis, and shell inspection tools, then summarize what matters for future work. The extension uses those findings to select scopes, accepts natural Markdown guidance, and automatically writes every successfully staged scope. Existing human text is preserved outside pi-agents-md markers. During initialization, ordinary edit and write calls are blocked; the package-owned apply path performs the final writes.

Development

npm install
npm run check
npm test
npm run pack:smoke

npm run pack:smoke packs the allowlisted artifact, installs it into a temporary clean project with scripts disabled, and checks the installed resource paths. The source manifest at sources/prompt-sources.json records the development-time prompt research and is not fetched by the extension.

License

MIT. See LICENSE. Prompt-source provenance and reuse decisions are recorded in sources/prompt-sources.json.