pi-packages

A monorepo of Pi extension packages, published to npm under @gotgenes/. Some packages (like pi-permission-system) are designed for broad use; others scratch a personal itch and are shared in case they help others.

Packages

Package	Description	Downloads/month
@gotgenes/pi-permission-system	Permission enforcement for the Pi coding agent
@gotgenes/pi-subagents	Claude Code-style autonomous sub-agents for Pi
@gotgenes/pi-github-tools	Deterministic GitHub CI, release, and issue tools
@gotgenes/pi-autoformat	Prompt-end auto-formatting (Biome, Prettier, etc.)
@gotgenes/pi-colgrep	Semantic code search via ColGrep as an agent tool
@gotgenes/pi-session-tools	Session naming and context bridge for multi-session workflows
@gotgenes/pi-subagents-worktrees	Git worktree isolation WorkspaceProvider for pi-subagents

Each package has its own README with setup instructions, usage, and configuration details.

Install

Install every package in this repo at once:

pi install git:github.com/gotgenes/pi-packages

Or install a single package via npm:

pi install npm:@gotgenes/<package-name>

Uninstall

If installed via git:

pi remove git:github.com/gotgenes/pi-packages

If installed individually via npm:

pi remove npm:@gotgenes/<package-name>

Development

Prerequisites

• Node.js ≥ 22
• pnpm 11

Setup

pnpm install

Commands

pnpm run check    # typecheck all packages
pnpm run test     # test all packages
pnpm run lint     # biome + rumdl
pnpm run lint:fix # auto-fix lint issues

Agentic development workflow

Always start Pi from the repo root:

pi

This gives the agent access to:

• .pi/settings.json — loads all packages from local source (with npm versions disabled)
• .pi/prompts/ — slash commands (/plan-improvements, /plan-issue, /tdd-plan, /ship-issue, etc.)
• Root AGENTS.md — monorepo-wide conventions

Developer workflow

Development is driven by slash commands. A discovery command, /plan-improvements, updates a package's architecture document and opens GitHub Issues for the work it identifies. Each issue is then taken through a manual loop until it ships.

flowchart LR
    PI["/plan-improvements"] -->|architecture doc + GitHub Issues| Plan

    subgraph Loop["Per-issue loop"]
        direction LR
        Plan["/plan-issue #N"] --> Kind{code or docs?}
        Kind -->|code| TDD["/tdd-plan"]
        Kind -->|docs / config| Build["/build-plan"]
        TDD --> Ship["/ship-issue #N"]
        Build --> Ship["/ship-issue #N"]
        Ship --> Retro["/retro"]
    end

Loading

Stage	Command	What happens
1. Discover	/plan-improvements	Updates a package's architecture document and creates GitHub Issues outlining the implementation work.
2. Plan	/plan-issue #N	Reads the issue, explores the codebase, produces a numbered plan, and commits it.
3. Implement	/tdd-plan or /build-plan	Executes the plan — TDD for code changes, build for docs/config. A pre-completion review runs at the end.
4. Ship	/ship-issue #N	Pushes, verifies CI, closes the issue, and merges the release-please PR.
5. Retrospective	/retro	Reviews the session(s) for workflow improvements and persists retro notes.

Each issue repeats stages 2–5. Every stage can run in its own session; the prompt templates set a stage-encoded session name and write a ## Stage: entry to a docs/retro/NNNN-<slug>.md file that bridges context across sessions.

Package-specific context (architecture, priorities, testing strategy) lives in skills. Load the relevant skill before working on a package:

• package-pi-autoformat — for packages/pi-autoformat/
• package-pi-github-tools — for packages/pi-github-tools/
• package-pi-permission-system — for packages/pi-permission-system/
• package-pi-subagents — for packages/pi-subagents/

The remaining packages (pi-colgrep, pi-session-tools, pi-subagents-worktrees) have no dedicated skill — their READMEs cover everything you need.

License

MIT