# @wsxyt/pi-agents-md

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

## Install

```bash
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:

```json
{
  "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

```bash
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](LICENSE). Prompt-source provenance and reuse decisions are recorded in [sources/prompt-sources.json](sources/prompt-sources.json).