@preapexis/pi-kit 1.2.2 → 1.3.0

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.2",
+  "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,228 +1,253 @@
-# Initialize Agent Guidelines
+# Initialize Repository Understanding
 
-Your job is to create or update the root `AGENTS.md` file for this repository.
-
-This prompt must **not** duplicate the full repository map. The detailed repository map belongs in:
-
-`docs/PROJECT_MAP.md`
-
-If `docs/PROJECT_MAP.md` exists, read it and use it as the main source for repository structure.
-
-If `docs/PROJECT_MAP.md` does not exist, do **not** create a large project map inside `AGENTS.md`. Instead, inspect only the most important project files and add a note in `AGENTS.md` saying that `/repo-map` should be run to generate `docs/PROJECT_MAP.md`.
+> 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 concise, useful `AGENTS.md` file that tells future Pi agents:
+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
-- which repository map file to read
+- where important files live
 - which commands to run
 - which files are risky
-- which files to inspect first for common tasks
-- what rules agents must follow
+- which files to inspect for common tasks
+- what repository-specific rules agents should follow
 
-`AGENTS.md` should be short, scannable, and task-focused.
+## Core Rule
 
-It should act as an **agent operating guide**, not a full file inventory.
+`/init` must not duplicate the work of `/repo-map`.
 
-## Important Rule
+Use `docs/PROJECT_MAP.md` if it exists. If it does not exist, recommend running `/repo-map`.
 
-Do not copy the full contents of `docs/PROJECT_MAP.md` into `AGENTS.md`.
+When creating or updating `AGENTS.md`, ensure it contains this line exactly once:
 
-Instead, summarize only the most important paths and link to it.
+> Use `docs/PROJECT_MAP.md` if it exists. If it does not exist, recommend running `/repo-map`.
 
-Good:
+Do not add duplicate copies of this line if it already exists.
 
-- For the full repository map, read `docs/PROJECT_MAP.md`.
+## What `/init` Should Do
 
-Bad:
+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.
 
-- Listing every source file, prompt file, skill file, theme file, test file, and config file again inside `AGENTS.md`.
+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`
+     - `pyproject.toml`
+     - `Cargo.toml`
+     - `go.mod`
+     - `.github/workflows/*`
 
-## Steps
+   - Clearly mention in `AGENTS.md` that the repository map is missing.
 
-1. Check for an existing `AGENTS.md`
-   - If it exists, read it first.
-   - Preserve accurate project-specific rules.
-   - Remove duplicated or overly detailed file inventory if it is already covered by `docs/PROJECT_MAP.md`.
-   - Keep the file concise.
+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.
 
-2. Check for `docs/PROJECT_MAP.md`
-   - If it exists, read it.
-   - Use it to understand the project structure.
-   - Reference it from `AGENTS.md`.
-   - Do not duplicate it.
+## What `/init` Should Not Do
 
-3. Read key project files
+Do not:
 
-   Read only the files needed to create good agent guidance:
-   - `README.md`
-   - `package.json`
-   - `AGENTS.md`, if present
-   - `docs/PROJECT_MAP.md`, if present
-   - `.github/workflows/`, if present
-   - important config files such as:
-     - `tsconfig.json`
-     - `eslint.config.*`
-     - `prettier.config.*`
+- 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.
+
+Keep this section short.
+
+### Repository Map
+
+Reference the project map instead of duplicating it.
+
+This section must include the following line exactly once:
+
+> Use `docs/PROJECT_MAP.md` if it exists. If it does not exist, recommend running `/repo-map`.
+
+If `docs/PROJECT_MAP.md` exists, summarize only the most important locations from it.
+
+If it does not exist, write that the repository map is missing and that `/repo-map` should be run.
+
+### Common Commands
+
+Include important commands for:
+
+- installing dependencies
+- running locally
+- building
+- testing
+- linting
+- formatting
+- type-checking
+
+Only include commands that are supported by files in the repository.
 
-   - main package directories such as:
-     - `extensions/`
-     - `prompts/`
-     - `skills/`
-     - `themes/`
-     - `tests/`
+Do not invent commands.
 
-   Do not read actual `.env` files.
+### Important Files and Directories
 
-4. Detect the development workflow
+List only high-value files and directories that future agents should know about.
 
-   Find commands for:
-   - install
-   - test
-   - typecheck
-   - release
-   - local Pi usage
-   - package publishing, if applicable
+Prefer concise bullets.
 
-5. Identify safety risks
+Do not include a full tree.
 
-   Look for:
-   - auth files
-   - env files
-   - GitHub Actions publishing workflows
-   - release scripts
-   - package version files
-   - lockfiles
-   - destructive commands
-   - workspace boundary rules
+### Development Rules
 
-6. Create or update `AGENTS.md`
+Include repository-specific rules, such as:
 
-   Use this structure:
+- preferred package manager
+- coding style
+- branch or commit expectations
+- test requirements
+- generated file rules
+- environment variable rules
+- API or security constraints
 
-   # Agent Guidelines: <project name>
+Do not add generic rules unless they are clearly useful for this repository.
 
-   ## Project Summary
+### Risky Areas
 
-   Briefly explain what this project does.
+Mention files or areas that require extra caution, such as:
 
-   ## Start Here
+- authentication
+- billing
+- migrations
+- deployment
+- generated files
+- config files
+- shared types
+- public APIs
+- data deletion
+- security-sensitive code
 
-   Tell future agents which files to read first.
+### Before Making Changes
 
-   Include:
-   - `README.md`
-   - `docs/PROJECT_MAP.md`, if present
-   - `package.json`
-   - key task-specific files
+Include a short checklist future agents should follow before editing.
 
-   If `docs/PROJECT_MAP.md` is missing, say:
-   - Run `/repo-map` to generate `docs/PROJECT_MAP.md`.
+Example:
 
-   ## Repository Map
+- 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.
 
-   Keep this section short.
+### Notes for Future Agents
 
-   If `docs/PROJECT_MAP.md` exists, write:
-   - Full repository map: `docs/PROJECT_MAP.md`
+Include any durable notes that will help future Pi sessions.
 
-   Then include only a small high-level table, not a full inventory.
+Avoid temporary notes like “today I checked…” or “currently investigating…”.
 
-   Example:
+## Update Strategy
 
-   | Path          | Purpose                |
-   | ------------- | ---------------------- |
-   | `extensions/` | Pi extension modules   |
-   | `prompts/`    | Slash prompt workflows |
-   | `skills/`     | Packaged Pi skills     |
-   | `themes/`     | Pi themes              |
-   | `tests/`      | Vitest tests           |
+When updating an existing `AGENTS.md`:
 
-   ## Common Task Map
+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.
 
-   Keep this task-focused.
+## Minimal AGENTS.md Template
 
-   Example:
+Use this structure when creating a new `AGENTS.md`.
 
-   | 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 prompt workflows | `prompts/`, `extensions/prompts.ts`                                                |
-   | Change LiteLLM provider | `extensions/litellm-provider.ts`                                                   |
-   | Change release behavior | `scripts/git-release.mjs`, `.github/workflows/`                                    |
+```md
+# AGENTS.md
 
-   ## Development Commands
+## Project Overview
 
-   Include only commands that are present in the project.
+Briefly describe what this project does.
 
-   Example:
+## Repository Map
 
-   | Command                       | Purpose                                        |
-   | ----------------------------- | ---------------------------------------------- |
-   | `npm test`                    | Run tests                                      |
-   | `npm run git --msg="message"` | Commit, optionally bump version, tag, and push |
+Use `docs/PROJECT_MAP.md` if it exists. If it does not exist, recommend running `/repo-map`.
 
-   ## Coding Conventions
+## Common Commands
 
-   Summarize important conventions only.
+- Install:
+- Run:
+- Build:
+- Test:
+- Lint:
+- Type-check:
 
-   Include language, module style, formatting style, testing style, and extension patterns.
+Only keep commands that are confirmed by repository files.
 
-   ## Safety Rules
+## Important Files and Directories
 
-   Include rules agents must follow.
+- `README.md` — project overview and usage.
+- Add only important confirmed paths here.
 
-   Mention:
-   - Do not read `.env` files.
-   - Do not expose secrets.
-   - Do not modify files outside the current workspace unless explicitly allowed.
-   - Be careful with release scripts, npm publishing, GitHub workflows, and package version files.
-   - Ask before destructive Git commands.
-   - Do not duplicate `docs/PROJECT_MAP.md` inside `AGENTS.md`.
+## Development Rules
 
-   ## Architecture Notes
+- Add repository-specific rules here.
+- Do not invent rules.
 
-   Summarize important architecture patterns.
+## Risky Areas
 
-   Keep this short.
+- Add files or workflows that require extra caution.
 
-   ## Agent Rules
+## Before Making Changes
 
-   Include direct rules for future agents.
+- 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.
 
-   Example:
-   - Prefer editing existing extension files over creating duplicates.
-   - Keep `AGENTS.md` concise.
-   - Put detailed repository mapping in `docs/PROJECT_MAP.md`.
-   - Do not add GitHub install instructions if this package should be installed from npm.
-   - Do not duplicate Pi’s built-in status/footer information.
-   - Keep workspace guard behavior strict by default.
+## Notes for Future Agents
 
-   ## Open Questions
+Add durable notes that will help future sessions.
+```
 
-   List anything unclear.
+## Output Requirements
 
-   ## Inspection Notes
+After running `/init`, respond with:
 
-   Mention what was inspected and what was not inspected.
+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.
 
-## Output Rules
+Keep the response concise.
 
-- Only create or update `AGENTS.md`.
-- Do not modify source code.
-- Do not modify `docs/PROJECT_MAP.md`.
-- Do not create a second project map inside `AGENTS.md`.
-- Keep `AGENTS.md` concise.
-- Prefer references to `docs/PROJECT_MAP.md` over duplicated file lists.
-- Do not include secrets, API keys, tokens, passwords, or sensitive data.
-- Do not read actual `.env` files.
+## Success Criteria
 
-After updating `AGENTS.md`, report:
+The task is successful when:
 
-- file path
-- sections added or updated
-- whether `docs/PROJECT_MAP.md` was found and used
-- anything unclear
+- `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.