@preapexis/pi-kit 1.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish Package
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          registry-url: "https://registry.npmjs.org"
+
+      - run: npm ci
+
+      - run: npm test
+
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.pi/settings.json

@@ -0,0 +1,3 @@
+{
+  "packages": []
+}

package/AGENTS.md

@@ -0,0 +1,199 @@
+# AGENTS.md
+
+Guidance for AI agents working in this repository.
+
+## Project
+
+This repository is `preapexis-pi-kit`, a personal Pi coding-agent package.
+
+It contains:
+
+- `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.
+
+## Core Rules
+
+- 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.
+- Do not edit secrets, `.env` files, `.git`, build output, or generated files.
+
+## Package Structure Rules
+
+The Pi package should continue to use this structure:
+
+```txt
+preapexis-pi-kit/
+  package.json
+  README.md
+  LICENSE
+  AGENTS.md
+  extensions/
+  prompts/
+  skills/
+  themes/
+```
+
+Each skill must live in its own folder:
+
+```txt
+skills/
+  safe-coding/
+    SKILL.md
+  component-implementation/
+    SKILL.md
+  frontend-onboarding/
+    SKILL.md
+  frontend-quality/
+    SKILL.md
+```
+
+Do not place skill files directly inside `skills/` unless Pi explicitly supports that format.
+
+## Extension Rules
+
+Extensions are TypeScript files in `extensions/`.
+
+Current expected extensions:
+
+- `safety.ts` — general safety protection.
+- `git-guard.ts` — Git-specific safety.
+- `status.ts` — footer/status display.
+- `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`.
+
+Do not reintroduce duplicate `/plan`, `/commit`, `/security`, or similar commands in extensions if matching prompt files already exist.
+
+## Prompt Rules
+
+Prompt files live in `prompts/`.
+
+The filename becomes the slash command.
+
+Examples:
+
+```txt
+prompts/plan.md -> /plan
+prompts/security.md -> /security
+```
+
+Do not create `prompts/prompts.md` because `/prompts` is already provided by `extensions/prompts.ts`.
+
+Current expected prompts:
+
+- `init.md`
+- `plan.md`
+- `save-plan.md`
+- `implement.md`
+- `commit.md`
+- `review-safe.md`
+- `security.md`
+
+Prompt behavior rules:
+
+- Planning prompts should be read-only.
+- Review prompts should be read-only.
+- Commit prompt should suggest a commit message only; it must not commit.
+- Implement prompt may edit files, but should follow the saved plan and ask if unclear.
+- Save-plan prompt should save plans under `docs/plans/`.
+- Do not edit `AGENTS.md` from a prompt unless the user approves.
+
+## Skill Rules
+
+Skill files must start with valid frontmatter:
+
+```md
+---
+name: skill-name
+description: Short description.
+---
+```
+
+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
+
+When code changes are made, run the narrowest relevant check if available:
+
+- typecheck
+- lint
+- test
+- build
+
+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
+
+Keep `README.md` aligned with the actual files.
+
+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
+
+- Use clear, simple language.
+- Prefer plain Markdown.
+- Avoid unnecessary complexity.
+- Avoid adding comments that only repeat the code.
+- Prefer explicit names over clever names.

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to `preapexis-pi-kit` will be documented in this file.
+
+This project follows a simple changelog format:
+- `Added` for new features
+- `Changed` for updates to existing behavior
+- `Fixed` for bug fixes
+- `Removed` for deleted features/files
+- `Security` for safety-related changes
+
+## [1.0.0] - 2026-06-26
+
+### Added
+
+- Initial Pi package setup.
+- Added `package.json` with Pi package entries for:
+  - `extensions`
+  - `prompts`
+  - `skills`
+  - `themes`
+- Added safety-focused extensions:
+  - `safety.ts`
+  - `git-guard.ts`
+  - `status.ts`
+  - `prompts.ts`
+  - `brand-ui.ts`
+- Added prompt workflows:
+  - `init.md`
+  - `plan.md`
+  - `save-plan.md`
+  - `implement.md`
+  - `commit.md`
+  - `review-safe.md`
+  - `security.md`
+- Added reusable skills:
+  - `safe-coding`
+  - `component-implementation`
+  - `frontend-onboarding`
+  - `frontend-quality`
+- Added `README.md`.
+- Added `AGENTS.md`.
+- Added `LICENSE`.
+- Added `.gitignore`.
+
+### Changed
+
+- Renamed workflow helper concept to `/prompts`.
+- Updated `plan.md` to include:
+  - batch planning
+  - recommended model
+  - effort level
+  - risk level
+  - approval requirement
+  - final execution summary
+- Updated `save-plan.md` to save plans under `docs/plans/`.
+- Cleaned skill files to remove extra frontmatter separators.
+- Simplified `settings.json` recommendations.
+
+### Fixed
+
+- Removed duplicate `/plan`, `/commit`, `/security`, and related command behavior by keeping real workflows in prompt files.
+- Removed duplicate branch display from `status.ts`.
+- Kept Git branch display inside `git-guard.ts`.
+
+### Security
+
+- Added protection rules for risky shell commands.
+- Added `.env` read/edit blocking.
+- Added protected path checks for generated files, dependency folders, and Git internals.
+- Added Git protection for dirty worktrees, force-push, and `git reset --hard`.

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Varun Gaikwad
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,370 @@
+# preapexis-pi-kit
+
+A personalized kit for the [Pi Agent Harness](https://github.com/earendil-works/pi) that bundles extensions, prompts, skills, and themes to improve AI-assisted coding workflows.
+
+## What’s inside
+
+- **extensions/** – TypeScript extensions that add custom behavior to Pi:
+  - `safety.ts` – blocks risky shell commands, protects secrets, blocks unsafe paths, and injects safety rules.
+  - `git-guard.ts` – warns on dirty Git worktrees, blocks force-push, confirms `git reset --hard`, creates checkpoint branches before edits, and shows the current branch.
+  - `status.ts` – shows useful footer info such as model, mode, repo trust state, and test status.
+  - `usage-tracker.ts` – tracks session token usage and estimated cost, with `/usage` and `/usage-reset`.
+  - `prompts.ts` – adds `/prompts`, a small menu listing available prompt workflows.
+  - `brand-ui.ts` – adds custom Pi branding/UI.
+
+- **prompts/** – prompt templates for common workflows:
+  - `init.md` – inspect a repository and create an onboarding report.
+  - `plan.md` – create a read-only implementation plan with batches, model choice, and effort guidance.
+  - `save-plan.md` – save a generated plan as a markdown file.
+  - `implement.md` – implement a saved or pasted plan.
+  - `commit.md` – generate a conventional commit message from current Git changes.
+  - `review-safe.md` – run a safe read-only project review.
+  - `security.md` – run a read-only security review.
+
+- **skills/** – reusable skills for focused agent behavior:
+  - `safe-coding`
+  - `component-implementation`
+  - `frontend-onboarding`
+  - `frontend-quality`
+
+- **themes/** – custom Pi themes.
+
+- **package.json** – declares this repository as a Pi package.
+
+## Installation
+
+### Install from npm
+
+If the package is published to npm, install it with:
+
+```bash
+pi install npm:preapexis-pi-kit
+```
+
+After installing, restart Pi or reload extensions:
+
+```txt
+/reload
+```
+
+### Install from GitHub
+
+Install directly from GitHub:
+
+```bash
+pi install git:github.com/VarunGaikwad/preapexis-pi-kit@master
+```
+
+After installing, restart Pi or reload extensions:
+
+```txt
+/reload
+```
+
+### Install from a local clone
+
+Clone this repository:
+
+```bash
+git clone https://github.com/VarunGaikwad/preapexis-pi-kit.git
+cd preapexis-pi-kit
+```
+
+Install or link it with Pi:
+
+```bash
+pi install -l .
+```
+
+Then restart Pi or reload extensions:
+
+```txt
+/reload
+```
+
+## Updating
+
+### Update from npm
+
+If installed from npm, run:
+
+```bash
+pi install npm:preapexis-pi-kit
+```
+
+Then reload Pi:
+
+```txt
+/reload
+```
+
+### Update from GitHub
+
+If installed from GitHub, run:
+
+```bash
+pi install git:github.com/VarunGaikwad/preapexis-pi-kit@master
+```
+
+Then reload Pi:
+
+```txt
+/reload
+```
+
+### Update a local linked copy
+
+If installed with local link mode, pull the latest changes in the local repo:
+
+```bash
+git pull
+```
+
+Then reload Pi:
+
+```txt
+/reload
+```
+
+To update from GitHub, run:
+
+```bash
+pi install git:github.com/VarunGaikwad/preapexis-pi-kit@master
+```
+
+Then reload Pi:
+
+```txt
+/reload
+```
+
+## Usage
+
+### Prompt workflow
+
+Recommended flow:
+
+```txt
+/init
+/plan <your request>
+/save-plan <paste generated plan>
+/implement <saved plan path or pasted plan>
+/commit
+```
+
+Use review prompts when needed:
+
+```txt
+/review-safe
+/security
+```
+
+### `/prompts`
+
+Run:
+
+```txt
+/prompts
+```
+
+This shows all available prompt workflows and how to use them.
+
+## Prompt details
+
+### `/init`
+
+Reads the project and creates an onboarding report.
+
+Use this when opening a new repo or unfamiliar feature area.
+
+### `/plan`
+
+Creates a read-only plan.
+
+The plan includes:
+
+- implementation batches
+- likely files to change
+- risk level
+- recommended model
+- recommended effort level
+- approval needs
+- final execution summary
+
+Example summary:
+
+```txt
+Use Haiku with low effort for batches 1 and 2.
+Use Sonnet with medium effort for batches 3 and 4.
+Use Opus with high effort for batch 5.
+```
+
+### `/save-plan`
+
+Saves a generated plan to:
+
+```txt
+docs/plans/YYYY-MM-DD-plan-name.md
+```
+
+It asks before editing `AGENTS.md`.
+
+### `/implement`
+
+Implements a saved or pasted plan.
+
+It should:
+
+- follow the plan closely
+- keep changes small
+- ask if something is unclear
+- run tests, lint, or typecheck when available
+- summarize what changed
+
+### `/commit`
+
+Reads Git changes and suggests a commit message.
+
+It does not commit automatically.
+
+### `/review-safe`
+
+Runs a read-only project review.
+
+### `/security`
+
+Runs a read-only security review.
+
+## Extensions
+
+### safety.ts
+
+General safety layer.
+
+Protects against:
+
+- risky shell commands
+- reading or editing `.env` files
+- editing dependency folders
+- editing build output
+- editing `.git` internals
+- unsafe package install/remove commands without confirmation
+
+It also injects safety and clarification rules into the agent prompt.
+
+### git-guard.ts
+
+Git-specific safety layer.
+
+Handles:
+
+- dirty working tree warning
+- branch display with `*` when dirty
+- force-push blocking
+- `git reset --hard` confirmation
+- checkpoint branch creation before risky edits
+
+Example status:
+
+```txt
+⎇ master*
+```
+
+The `*` means there are uncommitted changes.
+
+### status.ts
+
+Shows project status in the footer:
+
+```txt
+mode: safe model: openrouter/... repo: trusted tests: none
+```
+
+Commands:
+
+```txt
+/test-pass
+/test-fail
+/test-none
+```
+
+### prompts.ts
+
+Adds:
+
+```txt
+/prompts
+```
+
+This command lists available prompt workflows.
+
+### brand-ui.ts
+
+Adds custom Pi branding and visual UI customization.
+
+## Skills
+
+Each skill should live in its own folder:
+
+```txt
+skills/
+  safe-coding/
+    SKILL.md
+  component-implementation/
+    SKILL.md
+  frontend-onboarding/
+    SKILL.md
+  frontend-quality/
+    SKILL.md
+```
+
+## Development
+
+To add a new extension:
+
+```txt
+extensions/my-extension.ts
+```
+
+It should export a default function that receives `ExtensionAPI`.
+
+To add a new prompt:
+
+```txt
+prompts/my-prompt.md
+```
+
+The filename becomes the slash command.
+
+Example:
+
+```txt
+prompts/security.md → /security
+```
+
+To add a new skill:
+
+```txt
+skills/my-skill/SKILL.md
+```
+
+## Package structure
+
+```txt
+preapexis-pi-kit/
+  package.json
+  LICENSE
+  README.md
+  extensions/
+  prompts/
+  skills/
+  themes/
+```
+
+## License
+
+ISC. See the `LICENSE` file for details.
+
+---
+
+Built for a safer, cleaner Pi coding-agent workflow.