@preapexis/pi-kit 1.0.10 → 1.0.12

package/extensions/prompts.ts

@@ -4,7 +4,8 @@ export default function (pi: ExtensionAPI): void {
   const prompts = [
     {
       name: "init",
-      description: "Inspect the repository and create an onboarding report",
+      description:
+        "Inspect the repository and create or update AGENTS.md for future Pi sessions",
       usage: "/init"
     },
     {

package/extensions/update.ts

@@ -1,4 +1,4 @@
-// cSpell:words Varun Gaikwad preapexis npm PowerShell
+// cSpell:words preapexis npm PowerShell
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 type EventContext = Parameters<Parameters<ExtensionAPI["on"]>[1]>[1];
@@ -31,11 +31,6 @@ export default function (pi: ExtensionAPI): void {
       label: "Update installed Pi packages/extensions",
       shell: "pi update --extensions"
     },
-    {
-      id: "kit-local",
-      label: "Re-link this local PreApeXis kit",
-      shell: "pi install -l ."
-    },
     {
       id: "kit-npm",
       label: "Update PreApeXis Pi Kit from npm",
@@ -63,18 +58,19 @@ export default function (pi: ExtensionAPI): void {
   }
 
   function startUpdateStatus(ctx: EventContext, label: string): () => void {
+    const frames = ["◐", "◓", "◑", "◒"];
     let seconds = 0;
-    let dots = 0;
+    let frame = 0;
 
-    ctx.ui.setStatus(UPDATE_STATUS_KEY, `update: ${label}...`);
+    ctx.ui.setStatus(UPDATE_STATUS_KEY, `updating: ${label} ${frames[0]} 0s`);
 
     const timer = setInterval(() => {
       seconds += 1;
-      dots = (dots + 1) % 4;
+      frame = (frame + 1) % frames.length;
 
       ctx.ui.setStatus(
         UPDATE_STATUS_KEY,
-        `update: ${label}${".".repeat(dots)} ${seconds}s`
+        `updating: ${label} ${frames[frame]} ${seconds}s`
       );
     }, 1000);
 
@@ -176,15 +172,13 @@ export default function (pi: ExtensionAPI): void {
     const shell = shellCommand(option.shell);
     const stopStatus = startUpdateStatus(ctx, option.label);
 
-    let result: Awaited<ReturnType<typeof pi.exec>>;
+    let result: Awaited<ReturnType<typeof pi.exec>> | undefined;
 
     try {
       result = await pi.exec(shell.command, shell.args, {
         cwd: ctx.cwd
       });
     } catch (error) {
-      stopStatus();
-
       ctx.ui.notify(
         [
           `Update failed: ${option.label}`,
@@ -197,9 +191,14 @@ export default function (pi: ExtensionAPI): void {
       );
 
       return false;
+    } finally {
+      stopStatus();
     }
 
-    stopStatus();
+    if (!result) {
+      ctx.ui.notify(`Update failed: ${option.label}`, "error");
+      return false;
+    }
 
     const stdout = result.stdout?.trim() ?? "";
     const stderr = result.stderr?.trim() ?? "";

package/package.json

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

package/prompts/init.md

@@ -1,43 +1,88 @@
 # Initialize Repository Understanding
 
-Initialize your understanding of this repository.
+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.
 
-Do not edit files.
+If the repository is large, inspect the most important files first and clearly mention what was not inspected.
 
-Your job is to inspect the project and produce a clear onboarding report for future work.
+## Goal
 
-If the repository is large, inspect the most important files first and clearly mention what was not inspected.
+Create a useful `AGENTS.md` file so future Pi sessions can 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. Read the most important project files first:
-   - README.md
-   - AGENTS.md
-   - package.json / pyproject.toml / go.mod / Cargo.toml / pom.xml / build.gradle
-   - CONTRIBUTING.md
-   - docs/
-   - .github/workflows/
-   - docker-compose.yml / Dockerfile
-   - existing test configuration
-
-2. Identify the project structure:
-   - main application entry points
-   - important directories
-   - test locations
+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:
+     - `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
+
+   Do not read actual `.env` files.
+
+3. **Identify the project structure**
+
+   Find:
+   - main entry points
+   - important directories and their purposes
    - config files
    - generated/build output directories
    - files that should be treated carefully
 
-3. Detect the development workflow:
-   - install command
-   - dev command
-   - build command
-   - test command
-   - lint command
-   - typecheck command
-   - formatting command
+4. **Detect the development workflow**
+
+   Find commands for:
+   - install
+   - dev
+   - build
+   - test
+   - lint
+   - typecheck
+   - format
+   - reload or local development, if applicable
+
+5. **Identify safety risks**
 
-4. Identify safety risks:
+   Look for:
    - secrets or env files
    - deployment files
    - database migrations
@@ -47,52 +92,103 @@ If the repository is large, inspect the most important files first and clearly m
    - destructive scripts
    - commands that should require confirmation
 
-5. Infer coding conventions:
+6. **Infer coding conventions**
+
+   Look for:
    - language/framework
    - naming style
    - error handling style
    - testing style
    - API conventions
    - dependency management
+   - state management and data flow, if applicable
+
+7. **Create a task-focused project map inside `AGENTS.md`**
+
+   Add a section that tells future agents where to look first for common tasks.
+
+   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`.
 
 ## Output
 
-Return a repository onboarding report with these sections:
+Create or update `AGENTS.md` in the repository root with this structure:
+
+```markdown
+# Agent Guidelines: <project name>
+
+## Project Summary
+
+Briefly explain what this project does.
+
+## Tech Stack
+
+Languages, frameworks, libraries, and tools.
+
+## Project Map
+
+| Path   | Purpose          |
+| ------ | ---------------- |
+| `src/` | Main source code |
+
+## Common Task Map
 
-# Repository Summary
+| 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` |
 
-Briefly explain what this project appears to do.
+## Development Commands
 
-# Tech Stack
+| Command    | Purpose   |
+| ---------- | --------- |
+| `npm test` | Run tests |
 
-List the detected languages, frameworks, libraries, and tools.
+## Coding Conventions
 
-# Project Map
+Naming, error handling, testing, API patterns, state management.
 
-Explain the important folders and files.
+## Safety Rules
 
-# Common Commands
+Files, directories, and commands to treat carefully.
 
-List install, dev, build, test, lint, typecheck, and format commands if found.
+## Architecture Notes
 
-# Safety Notes
+Key patterns, data flow, important abstractions.
 
-List files, directories, and commands that should be treated carefully.
+## Agent Rules
 
-# Coding Conventions
+Repo-specific rules for AI agents working in this codebase.
 
-Summarize the project’s apparent patterns.
+## Open Questions
 
-# Recommended Agent Rules
+Anything unclear or missing.
 
-Suggest repo-specific rules that should be added to AGENTS.md or team instructions.
+## Inspection Notes
 
-# Open Questions
+Mention important areas that were not inspected.
+```
+````
 
-List anything unclear or missing.
+## Rules
 
-# Inspection Notes
+- 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
 
-Mention important files or areas that were not inspected.
 
-Do not modify the repository unless I explicitly ask.

package/prompts/repo-map.md

@@ -0,0 +1,163 @@
+# Repository Map Generator
+
+Create or update a repository map for this project.
+
+You may create or edit only this file:
+
+```txt
+docs/PROJECT_MAP.md
+```
+
+Do not edit source code, config files, prompts, skills, themes, or extensions.
+
+## Goal
+
+Generate a useful project map so future agent sessions know which files to inspect for common tasks.
+
+## Steps
+
+1. Read existing project guidance:
+   - `AGENTS.md`
+   - `README.md`
+   - `package.json`
+   - existing `docs/PROJECT_MAP.md` if it exists
+
+2. Inspect the repository structure:
+   - top-level files
+   - `extensions/`
+   - `prompts/`
+   - `skills/`
+   - `themes/`
+   - `docs/`
+   - config files
+   - test files
+
+3. Identify important files and responsibilities.
+
+4. Create or update:
+
+```txt
+docs/PROJECT_MAP.md
+```
+
+5. Keep the map practical and easy to scan.
+
+## Output file structure
+
+Write `docs/PROJECT_MAP.md` using this structure:
+
+```md
+# Project Map
+
+## Purpose
+
+Short explanation of what this repository does.
+
+## Important Files
+
+List important root files and what they are for.
+
+## Directory Map
+
+Explain each important directory.
+
+## Extension Map
+
+For each extension, explain:
+
+- file path
+- slash commands added, if any
+- UI/status changes, if any
+- safety behavior, if any
+- when to edit this file
+
+## Prompt Map
+
+For each prompt, explain:
+
+- slash command
+- file path
+- purpose
+- when to use it
+
+## Skill Map
+
+For each skill, explain:
+
+- skill name
+- file path
+- purpose
+- when it should activate
+
+## Theme Map
+
+List available themes and where they live.
+
+## Common Tasks
+
+For each common task, list which files to read first.
+
+Examples:
+
+### 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`
+
+### Change footer/status
+
+Read:
+
+- `extensions/status.ts`
+- `extensions/usage-tracker.ts`
+
+### Change prompt workflows
+
+Read:
+
+- `extensions/prompts.ts`
+- `prompts/`
+
+## Common Commands
+
+List useful commands for development, testing, install, update, and reload.
+
+## Safety Notes
+
+List files and commands that should be handled carefully.
+
+## Agent Rules
+
+Add repo-specific rules future agents should follow.
+```
+
+## Rules
+
+- Be specific.
+- Prefer file paths over vague descriptions.
+- Do not guess if a file was not inspected.
+- If something is unclear, add it under `Open Questions`.
+- Do not modify anything except `docs/PROJECT_MAP.md`.
+
+## Final response
+
+After writing the file, summarize:
+
+- whether the file was created or updated
+- important sections added
+- any open questions