[中文](./README.md) | English

# pi-init

An extension for the pi coding agent: adds an `/init [extra instructions]` command that has the agent explore the current project and generate (or update) `AGENTS.md` in the project root, for any coding agent working there later.

## Usage

```text
/init                          # Explore the project, generate/update AGENTS.md
/init <extra instructions>     # Same, plus your extra instructions (the agent weighs them carefully)
```

Examples:

```text
/init
/init Focus on the Rust crate layout, write AGENTS.md in Chinese
```

The command sends a curated prompt to the session's agent, which then explores the project on its own (package manifests, lockfiles, CI configs, directory layout, existing conventions, ...) and writes `AGENTS.md`. If `AGENTS.md` already exists, it is updated in place, preserving still-valid content. If the agent is busy, `/init` queues itself as a follow-up.

## Where prompts live (never in code)

Templates are resolved in this order; the first non-empty file wins:

| Priority | Location | Purpose |
|----------|----------|---------|
| 1 | `<project>/.pi/init/prompt.md` | Per-project override |
| 2 | `~/.pi/agent/init/prompt.md` | Global override |
| 3 | Bundled `prompts/init.md` | Default template |

Templates support:

- `---` frontmatter (stripped at load time; documentation only);
- The `{{cwd}}` placeholder — absolute path of the current project;
- The `{{userInstructions}}` placeholder — the text typed after `/init`, or `(none)` when empty;
- If the template has no `{{userInstructions}}` placeholder and the user did pass extra instructions, the handler appends an "Additional user instructions" section automatically.

## Install

Option 1 (recommended, npm package, upgradable via `pi update`):

```bash
pi install npm:@wxk6b1203/pi-init
```

Option 2 (global extensions directory): copy or symlink this directory into pi's global extensions directory:

```bash
cp -r . ~/.pi/agent/extensions/pi-init
```

Option 3 (project-local): copy into a project's `.pi/extensions/pi-init/`.

Uninstall: `pi remove npm:@wxk6b1203/pi-init`; upgrade: `pi update npm:@wxk6b1203/pi-init` or `pi update --all`.

Quick trial:

```bash
pi -e ./index.ts
```

Then type `/init`.

## Development

```bash
npm --prefix .tooling install   # First time: install typescript + @types/node (for typechecking)
npm run check                   # tsc --noEmit, validates API usage against pi's real type definitions
npm test                        # Smoke tests: jiti loads index.ts + mock-verified behavior (no model calls)
```

Notes:

- The extension has zero runtime npm dependencies (Node built-ins only). Imports from `@earendil-works/pi-coding-agent` resolve through pi's built-in jiti aliases.
- `node_modules/` contains junctions into the local pnpm store (jiti/typebox/@earendil-works), used by `npm test` and `npm run check`; gitignored.
- `test/smoke.mjs` uses a mock `ExtensionAPI` to verify: command registration, template resolution priority, frontmatter stripping, placeholder substitution, appended sections, etc.

## Publishing (maintainers)

Package name: `@wxk6b1203/pi-init`. Before the first publish:

1. Create the organization `wxk6b1203` on [npmjs.com](https://www.npmjs.com) (free plan; unlimited public packages) — when a scope differs from your npm username, npm treats it as an org scope;
2. Make sure `~/.npmrc` contains `//registry.npmjs.org/:_authToken=...` (`npm whoami --registry=https://registry.npmjs.org/` should print your username).

```bash
git commit ...        # pnpm publish requires a clean working tree (npm publish does not)
pnpm publish          # runs check + test first; registry & access are pinned by publishConfig
```

- The publish target is pinned to the official npmjs registry + public access via `publishConfig` in `package.json`, regardless of the machine's default registry (company mirror / npmmirror);
- The `@wxk6b1203:registry` mapping in the project `.npmrc` (and/or user `~/.npmrc`) keeps scope routing correct;
- If pnpm blocks on branch/worktree checks, add `--no-git-checks`;
- Version bumps: `npm version patch|minor|major`, then publish; users upgrade with `pi update npm:@wxk6b1203/pi-init`.

## License

MIT