@preapexis/pi-kit 1.2.1 → 1.3.0

package/AGENTS.md

@@ -1,20 +1,111 @@
-# AGENTS.md
+# Agent Guidelines: preapexis-pi-kit
+
+## Project Summary
+
+`preapexis-pi-kit` is a personal Pi coding-agent package that bundles TypeScript extensions, prompt templates, reusable skills, and UI themes for the [Pi Agent Harness](https://github.com/earendil-works/pi). It adds safety guards, status displays, prompt workflows, and custom branding to AI-assisted coding sessions.
+
+Published to npm as `@preapexis/pi-kit`.
+
+## Tech Stack
+
+- **Language:** TypeScript (ES2022, NodeNext module resolution)
+- **Runtime:** Node.js
+- **Test runner:** Vitest
+- **Package manager:** npm
+- **Peer dependency:** `@earendil-works/pi-coding-agent`
+
+## Project Map
+
+| Path               | Purpose                                                                                                   |
+| ------------------ | --------------------------------------------------------------------------------------------------------- |
+| `AGENTS.md`        | Core rules and guidance for agents working in this repository. Read this first before any edit.           |
+| `README.md`        | Public documentation, installation instructions, and usage guide.                                         |
+| `package.json`     | Pi package manifest. Declares `pi.extensions`, `pi.prompts`, `pi.skills`, and `pi.themes`.                |
+| `CHANGELOG.md`     | Version history and release notes.                                                                        |
+| `LICENSE`          | ISC license.                                                                                              |
+| `settings.json`    | Local Pi settings (`theme`, `defaultProjectTrust`). Not published as part of the package manifest.        |
+| `tsconfig.json`    | TypeScript configuration covering `extensions/**/*.ts`, `tests/**/*.ts`, and `vitest.config.ts`.          |
+| `vitest.config.ts` | Vitest test runner configuration (Node environment, globals enabled).                                     |
+| `extensions/`      | TypeScript Pi extensions. Each file exports a default function receiving `ExtensionAPI`.                  |
+| `prompts/`         | Markdown prompt templates. The filename (without `.md`) becomes a slash command.                          |
+| `skills/`          | Reusable skills. Each skill lives in its own subfolder containing a `SKILL.md` with frontmatter.          |
+| `themes/`          | JSON theme files for Pi UI. Each file must have `name`, `vars`, `colors`, and `$schema`.                  |
+| `tests/`           | Vitest test suite validating package structure, extension syntax, prompt conventions, skills, and themes. |
+| `scripts/`         | Development helper scripts. Currently contains `git-release.mjs`.                                         |
+| `docs/`            | Project documentation. `docs/plans/` is the target directory for `/save-plan`.                            |
+
+## Common Task Map
+
+| Task                        | Read These Files First                                                                        |
+| --------------------------- | --------------------------------------------------------------------------------------------- |
+| Change branding/UI          | `extensions/brand-ui.ts`, `themes/`                                                           |
+| Change update behavior      | `extensions/update.ts`                                                                        |
+| Change safety behavior      | `extensions/safety.ts`, `extensions/git-guard.ts`, `extensions/workspace-guard.ts`            |
+| Change footer/status        | `extensions/status.ts`, `extensions/usage-tracker.ts`                                         |
+| Change prompt workflows     | `extensions/prompts.ts`, `prompts/`                                                           |
+| Change sound cues           | `extensions/sound-cues.ts`                                                                    |
+| Change workspace boundaries | `extensions/workspace-guard.ts`                                                               |
+| Add a new extension         | `AGENTS.md` (Extension Rules), `tests/extensions.test.ts`, then create `extensions/<name>.ts` |
+| Add a new prompt            | `AGENTS.md` (Prompt Rules), `tests/prompts.test.ts`, then create `prompts/<name>.md`          |
+| Add a new skill             | `AGENTS.md` (Skill Rules), `tests/skills.test.ts`, then create `skills/<name>/SKILL.md`       |
+| Add a new theme             | `tests/themes.test.ts`, then create `themes/<name>.json`                                      |
+| Release a new version       | `scripts/git-release.mjs`, `package.json`, `CHANGELOG.md`, `.github/workflows/publish.yml`    |
+
+## Development Commands
+
+| Command              | Purpose                                                                        |
+| -------------------- | ------------------------------------------------------------------------------ |
+| `npm test`           | Run the full Vitest test suite (structure, syntax, and validation tests).      |
+| `npm run test:watch` | Run Vitest in watch mode.                                                      |
+| `npm run git`        | Run the interactive git-release script (bumps version, commits, tags, pushes). |
+| `pi install -l .`    | Install this package locally into Pi for development testing.                  |
+| `/reload`            | Reload Pi after installing, updating, or changing extensions.                  |
+
+## Coding Conventions
+
+- **Language:** TypeScript with strict mode enabled.
+- **Module system:** ES modules (`"type": "module"`), NodeNext resolution.
+- **Extension pattern:** Each extension exports a default function receiving `ExtensionAPI`.
+- **Naming:** Use clear, explicit names. Prefer `kebab-case` for filenames.
+- **Error handling:** Extensions use `ctx.hasUI` checks before UI operations; fall back to `console.log` or blocking when UI is unavailable.
+- **Testing:** Tests are in `tests/` using Vitest. Tests validate structural constraints (default exports, frontmatter, valid JSON) rather than deep behavioral logic.
+- **Dependencies:** Do not add dependencies unless explicitly approved. The package has no runtime dependencies; only `typescript` and `vitest` as devDependencies.
+- **Comments:** Avoid comments that only repeat the code. Use JSDoc for extension-level documentation.
 
-Guidance for AI agents working in this repository.
+## Safety Rules
+
+Agents must avoid:
+
+- reading or editing `.env` files
+- editing `.git`
+- editing `node_modules`
+- editing build output such as `dist`, `build`, `out`, or `coverage`
+- changing lockfiles unless the user approves
+- running package install/remove commands unless the user approves
+- running destructive Git commands (`git push --force`, `git reset --hard`, `git clean -fd`)
+- running destructive shell commands
+- running commands that leave the workspace without approval
 
-## Project
+Before risky edits, check whether the repo is dirty. Avoid overwriting user work.
 
-This repository is `preapexis-pi-kit`, a personal Pi coding-agent package.
+The `scripts/git-release.mjs` script performs `git push` and may create tags; review its behavior before running in a dirty worktree.
 
-It contains:
+## Architecture Notes
 
-- `extensions/` — TypeScript Pi extensions.
-- `prompts/` — prompt templates that become slash commands.
-- `skills/` — reusable skills, each in its own folder with a `SKILL.md`.
-- `themes/` — Pi UI themes.
-- `package.json` — declares this repository as a Pi package.
+- **Extension API:** All extensions consume `@earendil-works/pi-coding-agent`'s `ExtensionAPI`. They hook into lifecycle events (`session_start`, `before_agent_start`, `tool_call`, `agent_end`) and register slash commands.
+- **System prompt injection:** `safety.ts`, `workspace-guard.ts`, and potentially other extensions append rules to the agent system prompt via `before_agent_start`.
+- **UI availability:** Extensions must check `ctx.hasUI` before calling `ctx.ui.notify`, `ctx.ui.confirm`, `ctx.ui.select`, or `ctx.ui.setStatus`.
+- **Workspace boundary:** `workspace-guard.ts` locks the workspace root at `session_start` and blocks tool calls targeting outside paths.
+- **Git checkpointing:** `git-guard.ts` creates `pi-checkpoint-<branch>-<timestamp>` branches before risky edits when the working tree is dirty.
+- **Separation of concerns:**
+  - Git branch display belongs in `git-guard.ts`.
+  - Model, mode, repo trust, and test status belong in `status.ts`.
+  - Risky non-Git shell command protection belongs in `safety.ts`.
+  - Prompt menu belongs in `prompts.ts`.
 
-## Core Rules
+## Agent Rules
+
+### Core Rules
 
 - Keep changes small, focused, and reviewable.
 - Read existing files before editing them.
@@ -25,7 +116,7 @@ It contains:
 - Do not rewrite Git history.
 - Do not edit secrets, `.env` files, `.git`, build output, or generated files.
 
-## Package Structure Rules
+### Package Structure Rules
 
 The Pi package should continue to use this structure:
 
@@ -57,9 +148,7 @@ skills/
 
 Do not place skill files directly inside `skills/` unless Pi explicitly supports that format.
 
-## Extension Rules
-
-Extensions are TypeScript files in `extensions/`.
+### Extension Rules
 
 Current expected extensions:
 
@@ -69,20 +158,13 @@ Current expected extensions:
 - `prompts.ts` — `/prompts` menu.
 - `brand-ui.ts` — custom UI branding.
 
-Avoid duplicate responsibilities:
-
-- Git branch display belongs in `git-guard.ts`.
-- Model, mode, repo trust, and test status belong in `status.ts`.
-- Risky non-Git shell command protection belongs in `safety.ts`.
-- Prompt menu belongs in `prompts.ts`.
+Avoid duplicate responsibilities (see Architecture Notes).
 
 Do not reintroduce duplicate `/plan`, `/commit`, `/security`, or similar commands in extensions if matching prompt files already exist.
 
-## Prompt Rules
+### Prompt Rules
 
-Prompt files live in `prompts/`.
-
-The filename becomes the slash command.
+Prompt files live in `prompts/`. The filename becomes the slash command.
 
 Examples:
 
@@ -112,7 +194,7 @@ Prompt behavior rules:
 - Save-plan prompt should save plans under `docs/plans/`.
 - Do not edit `AGENTS.md` from a prompt unless the user approves.
 
-## Skill Rules
+### Skill Rules
 
 Skill files must start with valid frontmatter:
 
@@ -127,31 +209,7 @@ Do not add an extra `---` after the frontmatter.
 
 Keep skills focused and reusable.
 
-Good skill categories for this repo:
-
-- safe coding
-- frontend onboarding
-- frontend quality review
-- component implementation
-
-## Safety Rules
-
-Agents must avoid:
-
-- reading or editing `.env` files
-- editing `.git`
-- editing `node_modules`
-- editing build output such as `dist`, `build`, `out`, or `coverage`
-- changing lockfiles unless the user approves
-- running package install/remove commands unless the user approves
-- running destructive Git commands
-- running destructive shell commands
-
-If a task is unclear, ask questions before editing.
-
-Ask only important questions. If the task is clear, continue.
-
-## Verification
+### Verification
 
 When code changes are made, run the narrowest relevant check if available:
 
@@ -164,25 +222,7 @@ If checks cannot be run, explain why.
 
 Do not claim tests passed unless they were actually run.
 
-## Git Rules
-
-Before risky edits, check whether the repo is dirty.
-
-Dirty means there are uncommitted changes.
-
-Avoid overwriting user work.
-
-Do not run:
-
-```bash
-git push --force
-git reset --hard
-git clean -fd
-```
-
-unless the user explicitly approves and the safety extension allows it.
-
-## README Rules
+### README Rules
 
 Keep `README.md` aligned with the actual files.
 
@@ -190,10 +230,38 @@ If an extension, prompt, skill, or theme is renamed, update the README.
 
 Avoid mentioning removed files such as `team.ts` or old names such as `workflow.ts` if they no longer exist.
 
-## Style
+### Style
 
 - Use clear, simple language.
 - Prefer plain Markdown.
 - Avoid unnecessary complexity.
 - Avoid adding comments that only repeat the code.
 - Prefer explicit names over clever names.
+
+### Clarification
+
+If a task is unclear, ask questions before editing.
+
+Ask only important questions. If the task is clear, continue.
+
+Do not edit files until the user answers clarification questions.
+
+## Open Questions
+
+None.
+
+## Inspection Notes
+
+All important files were inspected:
+
+- Root files: `package.json`, `README.md`, `CHANGELOG.md`, `LICENSE`, `settings.json`, `tsconfig.json`, `vitest.config.ts`, `.gitignore`
+- Extensions: all 9 files in `extensions/`
+- Prompts: all 8 files in `prompts/`
+- Skills: all 4 `SKILL.md` files
+- Themes: all 4 JSON files
+- Tests: all 6 test files plus `tests/helpers.ts`
+- Scripts: `scripts/git-release.mjs`
+- CI/CD: `.github/workflows/publish.yml`
+- Editor configs: `.vscode/settings.json`, `.pi/settings.json`
+
+Not inspected in detail: individual theme JSON internals (only structure was validated via tests), and the full `node_modules/` tree (not relevant).

package/docs/PROJECT_MAP.md

@@ -0,0 +1,228 @@
+# Project Map
+
+## Purpose
+
+`preapexis-pi-kit` is a personal Pi coding-agent package that bundles TypeScript extensions, prompt templates, reusable skills, and UI themes for the [Pi Agent Harness](https://github.com/earendil-works/pi). It adds safety guards, status displays, prompt workflows, and custom branding to AI-assisted coding sessions.
+
+## Important Files
+
+| File | Purpose |
+|------|---------|
+| `AGENTS.md` | Core rules and guidance for agents working in this repository. Read this first before any edit. |
+| `README.md` | Public documentation, installation instructions, and usage guide. |
+| `package.json` | Pi package manifest. Declares `pi.extensions`, `pi.prompts`, `pi.skills`, and `pi.themes`. Also defines npm scripts and dev dependencies. |
+| `CHANGELOG.md` | Version history and release notes. |
+| `LICENSE` | ISC license. |
+| `settings.json` | Local Pi settings (`theme`, `defaultProjectTrust`). Not published as part of the package manifest. |
+| `tsconfig.json` | TypeScript configuration covering `extensions/**/*.ts`, `tests/**/*.ts`, and `vitest.config.ts`. |
+| `vitest.config.ts` | Vitest test runner configuration (Node environment, globals enabled). |
+| `.gitignore` | Git ignore rules. |
+
+## Directory Map
+
+| Directory | Purpose |
+|-----------|---------|
+| `extensions/` | TypeScript Pi extensions. Each file exports a default function receiving `ExtensionAPI`. |
+| `prompts/` | Markdown prompt templates. The filename (without `.md`) becomes a slash command. |
+| `skills/` | Reusable skills. Each skill lives in its own subfolder containing a `SKILL.md` with frontmatter. |
+| `themes/` | JSON theme files for Pi UI. Each file must have `name`, `vars`, `colors`, and `$schema`. |
+| `tests/` | Vitest test suite validating package structure, extension syntax, prompt conventions, skills, and themes. |
+| `scripts/` | Development helper scripts. |
+| `docs/` | Project documentation. Currently contains this map. `docs/plans/` is the target directory for `/save-plan`. |
+
+## Extension Map
+
+### `extensions/brand-ui.ts`
+- **Slash commands:** none
+- **UI/status changes:** Custom PreApeXis terminal branding and visual UI customization.
+- **Safety behavior:** none
+- **When to edit:** Changing branding, colors, or terminal UI styling.
+
+### `extensions/git-guard.ts`
+- **Slash commands:** none
+- **UI/status changes:** May show dirty-worktree warnings and checkpoint-branch notifications.
+- **Safety behavior:** Warns on dirty Git worktrees; blocks `git push --force`; confirms `git reset --hard`; creates checkpoint branches before risky edits.
+- **When to edit:** Changing Git-specific safety behavior or checkpoint logic.
+
+### `extensions/prompts.ts`
+- **Slash commands:** `/prompts`
+- **UI/status changes:** Displays a menu listing available prompt workflows.
+- **Safety behavior:** none
+- **When to edit:** Adding or removing prompt workflows, or changing how the menu is rendered.
+
+### `extensions/safety.ts`
+- **Slash commands:** none
+- **UI/status changes:** none
+- **Safety behavior:** Blocks risky shell commands; prevents reading/editing `.env` files; blocks edits to `node_modules`, build output, `.git` internals, and generated files; requires confirmation for package install/remove commands; injects safety and clarification rules into the agent system prompt.
+- **When to edit:** Changing general (non-Git) safety rules or protected path lists.
+
+### `extensions/sound-cues.ts`
+- **Slash commands:** `/sound-on`, `/sound-off`, `/sound-test`
+- **UI/status changes:** none
+- **Safety behavior:** none
+- **When to edit:** Changing sound cue triggers or audio behavior.
+
+### `extensions/status.ts`
+- **Slash commands:** `/test-pass`, `/test-fail`, `/test-none`
+- **UI/status changes:** Shows compact kit status in the footer (e.g., `kit: safe · trusted · tests:none`).
+- **Safety behavior:** none
+- **When to edit:** Changing footer display format or status indicators.
+
+### `extensions/update.ts`
+- **Slash commands:** `/update`
+- **UI/status changes:** Displays an update menu for Pi, this kit, or project packages.
+- **Safety behavior:** none
+- **When to edit:** Changing update behavior or menu options.
+
+### `extensions/usage-tracker.ts`
+- **Slash commands:** `/usage`, `/usage-reset`
+- **UI/status changes:** May display session token usage and estimated cost.
+- **Safety behavior:** none
+- **When to edit:** Changing usage tracking logic or cost estimation.
+
+### `extensions/workspace-guard.ts`
+- **Slash commands:** `/workspace-root`
+- **UI/status changes:** Sets status indicator `workspace: locked` on session start.
+- **Safety behavior:** Blocks file operations (`read`, `write`, `edit`, `ls`, `grep`, `find`) and `bash` commands that target paths outside the workspace root; injects workspace-boundary rules into the agent system prompt.
+- **When to edit:** Changing workspace boundary behavior or outside-access confirmation logic.
+
+## Prompt Map
+
+| Slash command | File path | Purpose | When to use it |
+|---------------|-----------|---------|----------------|
+| `/commit` | `prompts/commit.md` | Suggests a conventional commit message from current Git changes. Does not commit automatically. | After making changes and before committing. |
+| `/implement` | `prompts/implement.md` | Implements a saved or pasted plan. May edit files. Should follow the plan closely and ask if unclear. | After `/plan` and `/save-plan` (or when a plan is provided). |
+| `/init` | `prompts/init.md` | Inspects a repository and creates an onboarding report. Read-only. | When opening a new repo or unfamiliar feature area. |
+| `/plan` | `prompts/plan.md` | Creates a read-only implementation plan with batches, model choice, effort guidance, and risk level. | Before starting implementation work. |
+| `/repo-map` | `prompts/repo-map.md` | Creates or updates `docs/PROJECT_MAP.md`. Read-only for source files. | When the project structure has changed or a map is missing. |
+| `/review-safe` | `prompts/review-safe.md` | Runs a read-only project review. | When wanting a general code or project review. |
+| `/save-plan` | `prompts/save-plan.md` | Saves a generated plan as a markdown file under `docs/plans/`. | After `/plan` to persist the plan. |
+| `/security` | `prompts/security.md` | Runs a read-only security review. | When reviewing for security issues. |
+
+## Skill Map
+
+| Skill name | File path | Purpose | When it should activate |
+|------------|-----------|---------|------------------------|
+| `component-implementation` | `skills/component-implementation/SKILL.md` | Builds or modifies frontend components using existing patterns, styling, accessibility rules, and test conventions. | When creating or modifying frontend UI components. |
+| `frontend-onboarding` | `skills/frontend-onboarding/SKILL.md` | Understands frontend app structure, framework, routing, build tools, styling system, and test setup. Read-only unless asked. | When starting work in an unfamiliar frontend repo or feature area. |
+| `frontend-quality` | `skills/frontend-quality/SKILL.md` | Reviews frontend code for accessibility, responsiveness, performance, UX states, browser behavior, and maintainability. Read-only unless asked. | When reviewing or improving frontend quality. |
+| `safe-coding` | `skills/safe-coding/SKILL.md` | Applies safe, reviewable coding practices: small diffs, pre-read, no secrets, no lockfiles, post-edit verification. | When modifying any file in a codebase. |
+
+## Theme Map
+
+| Theme | File path |
+|-------|-----------|
+| Latte Review | `themes/latte-review.json` |
+| Neon Guardian | `themes/neon-guardian.json` |
+| Safe Dark | `themes/safe-dark.json` |
+| Tokyo Midnight | `themes/tokyo-midnight.json` |
+
+## Common Tasks
+
+### Change branding/UI
+Read:
+- `extensions/brand-ui.ts`
+- `themes/`
+
+### Change update behavior
+Read:
+- `extensions/update.ts`
+
+### Change safety behavior
+Read:
+- `extensions/safety.ts`
+- `extensions/git-guard.ts`
+- `extensions/workspace-guard.ts`
+
+### Change footer/status
+Read:
+- `extensions/status.ts`
+- `extensions/usage-tracker.ts`
+
+### Change prompt workflows
+Read:
+- `extensions/prompts.ts`
+- `prompts/`
+
+### Change sound cues
+Read:
+- `extensions/sound-cues.ts`
+
+### Change workspace boundaries
+Read:
+- `extensions/workspace-guard.ts`
+
+### Add a new extension
+Read first:
+- `AGENTS.md` (Extension Rules)
+- `tests/extensions.test.ts`
+Then create:
+- `extensions/<name>.ts`
+
+### Add a new prompt
+Read first:
+- `AGENTS.md` (Prompt Rules)
+- `tests/prompts.test.ts`
+Then create:
+- `prompts/<name>.md`
+Update:
+- `extensions/prompts.ts` (if the prompt should appear in the `/prompts` menu)
+
+### Add a new skill
+Read first:
+- `AGENTS.md` (Skill Rules)
+- `tests/skills.test.ts`
+Then create:
+- `skills/<name>/SKILL.md`
+
+### Add a new theme
+Read first:
+- `tests/themes.test.ts`
+Then create:
+- `themes/<name>.json`
+
+### Release a new version
+Read:
+- `scripts/git-release.mjs`
+- `package.json`
+- `CHANGELOG.md`
+
+## Common Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npm test` | Run the full Vitest test suite (structure, syntax, and validation tests). |
+| `npm run test:watch` | Run Vitest in watch mode. |
+| `npm run git` | Run the interactive git-release script (bumps version, commits, tags, pushes). |
+| `pi install -l .` | Install this package locally into Pi for development testing. |
+| `/reload` | Reload Pi after installing, updating, or changing extensions. |
+
+## Safety Notes
+
+- **Do not edit `.env` files** — blocked by `extensions/safety.ts`.
+- **Do not edit `.git` internals** — blocked by `extensions/safety.ts`.
+- **Do not edit `node_modules`** — blocked by `extensions/safety.ts`.
+- **Do not edit build output** (`dist`, `build`, `out`, `coverage`) — blocked by `extensions/safety.ts`.
+- **Do not change lockfiles** unless the user explicitly approves.
+- **Do not run destructive Git commands** (`git push --force`, `git reset --hard`, `git clean -fd`) without explicit user approval — guarded by `extensions/git-guard.ts`.
+- **Do not run commands leaving the workspace** without approval — guarded by `extensions/workspace-guard.ts`.
+- **`scripts/git-release.mjs`** performs `git push` and may create tags; review its behavior before running in a dirty worktree.
+
+## Agent Rules
+
+- Read `AGENTS.md` before making any edits.
+- Keep changes small, focused, and reviewable.
+- Read existing files before editing them.
+- Preserve existing behavior unless explicitly asked to change it.
+- Match the style already used in the repo.
+- Do not add dependencies unless explicitly approved.
+- Do not delete files unless explicitly approved.
+- Do not rewrite Git history.
+- Each skill must live in its own folder under `skills/`.
+- Prompt filenames become slash commands; do not create `prompts/prompts.md` because `/prompts` is provided by `extensions/prompts.ts`.
+- Extensions must export a default function receiving `ExtensionAPI`.
+- Run `npm test` after structural changes to extensions, prompts, skills, or themes.
+- Update `README.md` and `CHANGELOG.md` when adding or renaming public features.
+- Planning and review prompts should remain read-only.
+- The `/commit` prompt must suggest a message only; it must not commit automatically.
+- The `/save-plan` prompt should save plans under `docs/plans/`.

package/extensions/agent-rules.ts

@@ -0,0 +1,60 @@
+// cSpell:words preapexis
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI): void {
+  pi.on("before_agent_start", async (event) => {
+    return {
+      systemPrompt:
+        event.systemPrompt +
+        `
+
+PreApeXis Agent Behavior Rules:
+
+Safety rules:
+- Make small, reviewable changes.
+- Do not read or edit secret files such as .env files.
+- Do not expose secrets, API keys, tokens, passwords, or private credentials.
+- Ask before installing, removing, or upgrading packages.
+- Explain risky commands before running them.
+- Prefer safe, additive changes.
+- Run tests or type checks after code changes when available.
+- Ask before destructive Git operations such as reset, clean, force-push, or deleting branches.
+
+Clarification rules:
+- If the task is clear, continue without asking unnecessary questions.
+- If clarification is required before editing files, use the ask_user tool.
+- Ask one question at a time.
+- Provide 2 to 5 short, useful options.
+- Do not manually add "Write something else"; the ask_user tool adds the custom-answer option.
+- After the user answers, continue the same task using that answer.
+- Do not edit files that depend on unanswered clarification.
+- If a reasonable safe default exists, proceed with the default and clearly mention the assumption instead of asking.
+- Do not ask broad open-ended questions when a multiple-choice question would work better.
+
+Workspace boundary rules:
+- Treat the current working directory as the workspace root.
+- By default, only read, search, edit, write, delete, or inspect files inside the current workspace.
+- Do not look outside the current workspace just because it might be useful.
+- Do not read parent folders, sibling folders, home directories, global config folders, or unrelated repositories unless the user explicitly asks.
+- Even when the user explicitly asks to access something outside the workspace, ask for confirmation before each outside read, search, write, edit, delete, or command.
+- Prefer relative paths inside the current repository.
+- Do not run commands that cd, pushd, Set-Location, sl, git -C, npm --prefix, pnpm -C, or otherwise move outside the workspace unless explicitly requested and confirmed.
+- If outside-workspace context seems useful, ask first instead of checking it silently.
+- If no UI is available to ask permission, block outside-workspace access.
+
+Repository behavior:
+- Follow AGENTS.md when present.
+- Keep AGENTS.md concise.
+- Put detailed repository mapping in docs/PROJECT_MAP.md.
+- Do not duplicate docs/PROJECT_MAP.md inside AGENTS.md.
+- Prefer editing existing files over creating duplicate files.
+- Prefer npm install instructions for this package unless the user explicitly asks for GitHub install instructions.
+
+Pi kit behavior:
+- Do not duplicate Pi's built-in model, branch, context, or token footer information.
+- Keep workspace guard behavior strict by default.
+- Keep provider setup commands safe and avoid printing API keys.
+`
+    };
+  });
+}

package/extensions/ask-options.ts

@@ -0,0 +1,158 @@
+// cSpell:words preapexis
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+type AskUserParams = {
+  question: string;
+  options: string[];
+  allowCustom?: boolean;
+};
+
+const CUSTOM_OPTION = "✍ Write something else";
+
+export default function (pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "ask_user",
+    label: "Ask User",
+    description:
+      "Ask the user a multiple-choice question and wait for their answer before continuing.",
+    promptSnippet:
+      "Ask the user a multiple-choice question when clarification is required.",
+    promptGuidelines: [
+      "Use ask_user when you need clarification before continuing.",
+      "Use ask_user instead of guessing when multiple reasonable choices exist.",
+      "Use ask_user with short, clear options.",
+      "Do not ask open-ended clarification questions directly in chat when ask_user can be used.",
+      "Always include useful default options. The ask_user tool automatically adds a custom-answer option."
+    ],
+    parameters: {
+      type: "object",
+      properties: {
+        question: {
+          type: "string",
+          description: "The question to ask the user."
+        },
+        options: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Short answer choices. Do not include 'Write something else'; it is added automatically."
+        },
+        allowCustom: {
+          type: "boolean",
+          description:
+            "Whether the user can write a custom answer. Defaults to true."
+        }
+      },
+      required: ["question", "options"]
+    } as any,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const input = params as AskUserParams;
+
+      if (!ctx.hasUI) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: [
+                "Cannot ask the user with options because Pi UI is not available.",
+                "",
+                `Question: ${input.question}`,
+                "",
+                "Options:",
+                ...input.options.map(
+                  (option, index) => `${index + 1}. ${option}`
+                )
+              ].join("\n")
+            }
+          ],
+          details: {
+            answered: false,
+            reason: "missing_ui"
+          }
+        };
+      }
+
+      const cleanOptions = input.options
+        .map((option) => option.trim())
+        .filter(Boolean);
+
+      const allowCustom = input.allowCustom !== false;
+
+      const choices = allowCustom
+        ? [...cleanOptions, CUSTOM_OPTION]
+        : cleanOptions;
+
+      if (choices.length === 0) {
+        const answer = await ctx.ui.input("Question", input.question);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `User answered: ${answer}`
+            }
+          ],
+          details: {
+            answered: true,
+            answer,
+            custom: true
+          }
+        };
+      }
+
+      const choice = await ctx.ui.select(input.question, choices);
+
+      if (!choice) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "User cancelled the question. Stop and ask again only if the answer is required."
+            }
+          ],
+          details: {
+            answered: false,
+            cancelled: true
+          }
+        };
+      }
+
+      if (choice === CUSTOM_OPTION) {
+        const answer = await ctx.ui.input(
+          "Write something else",
+          input.question
+        );
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `User answered: ${answer}`
+            }
+          ],
+          details: {
+            answered: true,
+            answer,
+            custom: true
+          }
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `User selected: ${choice}`
+          }
+        ],
+        details: {
+          answered: true,
+          answer: choice,
+          custom: false
+        }
+      };
+    }
+  });
+
+
+}

package/extensions/safety.ts

@@ -110,29 +110,6 @@ export default function (pi: ExtensionAPI): void {
     return riskyCommands.some((pattern) => pattern.test(command));
   }
 
-  pi.on("before_agent_start", async (event) => {
-    return {
-      systemPrompt:
-        event.systemPrompt +
-        `
-    Safety rules:
-      - Make small, reviewable changes.
-      - Do not read or edit secret files such as .env files.
-      - Ask before installing or removing packages.
-      - Explain risky commands before running them.
-      - Prefer safe, additive changes.
-      - Run tests or type checks after code changes when available.
-
-    Clarification rules:
-      - If the request is unclear, ask questions before editing files.
-      - Ask only important questions.
-      - Do not ask more than 5 questions.
-      - If the task is clear, continue without asking.
-      - Do not edit files until the user answers clarification questions.
-`
-    };
-  });
-
   pi.on("tool_call", async (event, ctx) => {
     if (event.toolName === "bash") {
       const command = String(event.input.command ?? "");

package/extensions/workspace-guard.ts

@@ -134,23 +134,6 @@ export default function (pi: ExtensionAPI): void {
     }
   });
 
-  pi.on("before_agent_start", async (event) => {
-    return {
-      systemPrompt:
-        event.systemPrompt +
-        `
-
-Workspace boundary rules:
-- Treat the current working directory as the workspace root.
-- Do not read, search, edit, write, delete, or inspect files outside the current workspace unless the user explicitly asks.
-- Before using any path outside the workspace, ask the user for permission.
-- Prefer relative paths inside the current repository.
-- Do not run commands that cd, pushd, Set-Location, or otherwise move outside the workspace unless explicitly requested.
-- If outside-workspace context seems useful, ask first instead of checking it silently.
-`
-    };
-  });
-
   pi.on("tool_call", async (event, ctx) => {
     if (!workspaceRoot) {
       workspaceRoot = normalize(ctx.cwd);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preapexis/pi-kit",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Personal Pi coding-agent kit with safety extensions, status UI, prompt workflows, skills, and themes.",
   "keywords": [
     "pi-package",

package/prompts/init.md

@@ -1,194 +1,253 @@
 # Initialize Repository Understanding
 
-Your job is to deeply inspect this repository and create or update an `AGENTS.md` file that captures everything Pi needs to know to work effectively in this codebase.
-
-If the repository is large, inspect the most important files first and clearly mention what was not inspected.
+> This prompt initializes or updates the repository-level `AGENTS.md` file for Pi.
+> It should rely on `docs/PROJECT_MAP.md` when available and avoid doing full repository mapping itself.
 
 ## Goal
 
-Create a useful `AGENTS.md` file so future Pi sessions can quickly understand:
+Create or update an `AGENTS.md` file that gives future Pi sessions clear, durable instructions for working in this repository.
+
+The `AGENTS.md` file should help future agents quickly understand:
 
 - what this project does
 - where important files live
 - which commands to run
 - which files are risky
 - which files to inspect for common tasks
-- what rules agents should follow
-
-## Steps
-
-1. **Check for an existing `AGENTS.md`**
-   - If it exists, read it first.
-   - Preserve anything that is still accurate and relevant.
-   - Do not remove existing project-specific rules unless they are clearly outdated.
-   - Merge new findings with the existing content.
-
-2. **Read the codebase thoroughly**
-
-   Read important files such as:
-   - `README.md`
-   - `package.json`
-   - `pyproject.toml`
-   - `go.mod`
-   - `Cargo.toml`
-   - `pom.xml`
-   - `build.gradle`
-   - `CONTRIBUTING.md`
-   - `docs/`
-   - `.github/workflows/`
-   - `docker-compose.yml`
-   - `Dockerfile`
-   - config files such as:
+- what repository-specific rules agents should follow
+
+## Core Rule
+
+`/init` must not duplicate the work of `/repo-map`.
+
+Use `docs/PROJECT_MAP.md` if it exists. If it does not exist, recommend running `/repo-map`.
+
+When creating or updating `AGENTS.md`, ensure it contains this line exactly once:
+
+> Use `docs/PROJECT_MAP.md` if it exists. If it does not exist, recommend running `/repo-map`.
+
+Do not add duplicate copies of this line if it already exists.
+
+## What `/init` Should Do
+
+1. Check whether `AGENTS.md` exists.
+2. Check whether `docs/PROJECT_MAP.md` exists.
+3. If `docs/PROJECT_MAP.md` exists:
+   - Read it.
+   - Use it as the primary source for repository structure and important files.
+   - Do not re-map the full repository.
+
+4. If `docs/PROJECT_MAP.md` does not exist:
+   - Do not perform full repository mapping.
+   - Recommend running `/repo-map`.
+   - Inspect only lightweight top-level files needed to create a useful minimal `AGENTS.md`, such as:
+     - `README.md`
+     - `package.json`
+     - `pnpm-workspace.yaml`
      - `tsconfig.json`
-     - `vite.config.*`
-     - `next.config.*`
-     - `webpack.config.*`
-     - `eslint.config.*`
-     - `prettier.config.*`
-   - main source directories such as:
-     - `src/`
-     - `app/`
-     - `lib/`
-     - `packages/`
-     - `extensions/`
-     - `prompts/`
-     - `skills/`
-     - `themes/`
-   - test files and test configuration
-   - `.env.example` files only
+     - `pyproject.toml`
+     - `Cargo.toml`
+     - `go.mod`
+     - `.github/workflows/*`
+
+   - Clearly mention in `AGENTS.md` that the repository map is missing.
+
+5. Create or update `AGENTS.md`.
+6. Preserve any existing useful project-specific instructions.
+7. Remove or rewrite outdated, duplicated, or generic content only when clearly safe.
+8. Keep `AGENTS.md` concise and durable.
+
+## What `/init` Should Not Do
+
+Do not:
+
+- scan the entire repository when `docs/PROJECT_MAP.md` is missing
+- duplicate large sections from `docs/PROJECT_MAP.md`
+- turn `AGENTS.md` into a full repository map
+- include long file trees
+- include temporary investigation notes
+- include speculative rules
+- overwrite existing project-specific instructions without reason
+- remove safety, testing, build, or deployment rules unless clearly outdated
+- add the required `docs/PROJECT_MAP.md` line more than once
+
+## AGENTS.md Content Requirements
+
+The final `AGENTS.md` should include these sections when relevant.
+
+### Project Overview
+
+Briefly describe what the project is and what it does.
 
-   Do not read actual `.env` files.
+Keep this section short.
 
-3. **Identify the project structure**
+### Repository Map
 
-   Find:
-   - main entry points
-   - important directories and their purposes
-   - config files
-   - generated/build output directories
-   - files that should be treated carefully
+Reference the project map instead of duplicating it.
 
-4. **Detect the development workflow**
+This section must include the following line exactly once:
 
-   Find commands for:
-   - install
-   - dev
-   - build
-   - test
-   - lint
-   - typecheck
-   - format
-   - reload or local development, if applicable
+> Use `docs/PROJECT_MAP.md` if it exists. If it does not exist, recommend running `/repo-map`.
 
-5. **Identify safety risks**
+If `docs/PROJECT_MAP.md` exists, summarize only the most important locations from it.
 
-   Look for:
-   - secrets or env files
-   - deployment files
-   - database migrations
-   - production config
-   - generated files
-   - lockfiles
-   - destructive scripts
-   - commands that should require confirmation
+If it does not exist, write that the repository map is missing and that `/repo-map` should be run.
 
-6. **Infer coding conventions**
+### Common Commands
 
-   Look for:
-   - language/framework
-   - naming style
-   - error handling style
-   - testing style
-   - API conventions
-   - dependency management
-   - state management and data flow, if applicable
+Include important commands for:
 
-7. **Create a task-focused project map inside `AGENTS.md`**
+- installing dependencies
+- running locally
+- building
+- testing
+- linting
+- formatting
+- type-checking
 
-   Add a section that tells future agents where to look first for common tasks.
+Only include commands that are supported by files in the repository.
 
-   Example:
-   - For branding/UI changes, read `extensions/brand-ui.ts`.
-   - For update behavior, read `extensions/update.ts`.
-   - For safety behavior, read `extensions/safety.ts` and `extensions/git-guard.ts`.
-   - For prompt workflows, read `prompts/`.
-   - For skills, read `skills/<skill-name>/SKILL.md`.
+Do not invent commands.
 
-## Output
+### Important Files and Directories
 
-Create or update `AGENTS.md` in the repository root with this structure:
+List only high-value files and directories that future agents should know about.
 
-```markdown
-# Agent Guidelines: <project name>
+Prefer concise bullets.
 
-## Project Summary
+Do not include a full tree.
 
-Briefly explain what this project does.
+### Development Rules
 
-## Tech Stack
+Include repository-specific rules, such as:
 
-Languages, frameworks, libraries, and tools.
+- preferred package manager
+- coding style
+- branch or commit expectations
+- test requirements
+- generated file rules
+- environment variable rules
+- API or security constraints
 
-## Project Map
+Do not add generic rules unless they are clearly useful for this repository.
 
-| Path   | Purpose          |
-| ------ | ---------------- |
-| `src/` | Main source code |
+### Risky Areas
 
-## Common Task Map
+Mention files or areas that require extra caution, such as:
 
-| Task                   | Read These Files First                            |
-| ---------------------- | ------------------------------------------------- |
-| Change branding/UI     | `extensions/brand-ui.ts`, `themes/`               |
-| Change update behavior | `extensions/update.ts`                            |
-| Change safety behavior | `extensions/safety.ts`, `extensions/git-guard.ts` |
+- authentication
+- billing
+- migrations
+- deployment
+- generated files
+- config files
+- shared types
+- public APIs
+- data deletion
+- security-sensitive code
 
-## Development Commands
+### Before Making Changes
 
-| Command    | Purpose   |
-| ---------- | --------- |
-| `npm test` | Run tests |
+Include a short checklist future agents should follow before editing.
 
-## Coding Conventions
+Example:
 
-Naming, error handling, testing, API patterns, state management.
+- Read `AGENTS.md`.
+- Read `docs/PROJECT_MAP.md` if available.
+- Inspect the files directly related to the requested change.
+- Run the smallest relevant validation command.
+- Avoid broad rewrites unless explicitly requested.
 
-## Safety Rules
+### Notes for Future Agents
 
-Files, directories, and commands to treat carefully.
+Include any durable notes that will help future Pi sessions.
 
-## Architecture Notes
+Avoid temporary notes like “today I checked…” or “currently investigating…”.
 
-Key patterns, data flow, important abstractions.
+## Update Strategy
 
-## Agent Rules
+When updating an existing `AGENTS.md`:
 
-Repo-specific rules for AI agents working in this codebase.
+1. Read the full existing file.
+2. Preserve accurate project-specific content.
+3. Add missing required sections.
+4. Add the required `docs/PROJECT_MAP.md` line if missing.
+5. Remove duplicate copies of the required line.
+6. Keep the file organized and easy to skim.
+7. Prefer small, careful edits over full rewrites.
+8. If a full rewrite is necessary, preserve all accurate rules from the old file.
 
-## Open Questions
+## Minimal AGENTS.md Template
 
-Anything unclear or missing.
+Use this structure when creating a new `AGENTS.md`.
 
-## Inspection Notes
+```md
+# AGENTS.md
 
-Mention important areas that were not inspected.
+## Project Overview
+
+Briefly describe what this project does.
+
+## Repository Map
+
+Use `docs/PROJECT_MAP.md` if it exists. If it does not exist, recommend running `/repo-map`.
+
+## Common Commands
+
+- Install:
+- Run:
+- Build:
+- Test:
+- Lint:
+- Type-check:
+
+Only keep commands that are confirmed by repository files.
+
+## Important Files and Directories
+
+- `README.md` — project overview and usage.
+- Add only important confirmed paths here.
+
+## Development Rules
+
+- Add repository-specific rules here.
+- Do not invent rules.
+
+## Risky Areas
+
+- Add files or workflows that require extra caution.
+
+## Before Making Changes
+
+- Read this file.
+- Read `docs/PROJECT_MAP.md` if it exists.
+- Inspect the files directly related to the requested change.
+- Run the smallest relevant validation command.
+- Avoid broad rewrites unless explicitly requested.
+
+## Notes for Future Agents
+
+Add durable notes that will help future sessions.
 ```
-````
 
-## Rules
+## Output Requirements
+
+After running `/init`, respond with:
+
+1. Whether `AGENTS.md` was created or updated.
+2. Whether `docs/PROJECT_MAP.md` was found.
+3. A short summary of the important changes made.
+4. Any recommended next step, especially running `/repo-map` if the project map is missing.
+
+Keep the response concise.
 
-- Be thorough but concise.
-- `AGENTS.md` should be scannable.
-- Do not include secrets, API keys, tokens, passwords, or sensitive data.
-- Do not read actual `.env` files.
-- If `AGENTS.md` already exists, merge with it instead of blindly replacing it.
-- Focus on information that helps an AI agent write better code.
-- Prefer specific file paths over vague explanations.
-- Do not modify source code during initialization.
-- Only create or update `AGENTS.md`.
-- After creating or updating `AGENTS.md`, report:
-  - file path
-  - what sections were added or updated
-  - anything that was unclear
+## Success Criteria
 
+The task is successful when:
 
+- `AGENTS.md` exists.
+- It contains the required `docs/PROJECT_MAP.md` line exactly once.
+- Existing useful instructions were preserved.
+- Repository details are accurate and not invented.
+- `/init` did not perform full repository mapping.
+- The file is concise, durable, and useful for future Pi sessions.