Personal pi package — workflows, extensions, skills, prompt templates, and themes primarily for Sofiane.

sof-pi/
├── extensions/   # .ts / .js extensions
├── agents/       # pi-subagents agent overrides
├── skills/       # SKILL.md folders / top-level .md skills
├── prompts/      # .md prompt templates
├── themes/       # .json themes
└── package.json  # pi manifest

Web search and interactive research via the Perplexity API, designed to keep raw search traffic out of the main pi context window. Two pieces:

1. Web tools (web_search, fetch_content, get_search_content) — Perplexity-backed stand-ins for the pi-web-access tools that pi-subagents' researcher and context-builder agents list in their tools: frontmatter. Without them, subagent runs that reference web_search fail with an "unavailable tool" error. They synthesize answers with cited sources rather than returning raw result snippets.
2. /research command — an interactive, full-screen research panel for back-and-forth Perplexity sessions (queries + streamed answers + sources). Build a recap you can shape in an editor and inject into your main thread; intermediate search content stays in the panel and is discarded unless you build a recap.

See extensions/perplexity/README.md for details.

Four LLM tools (bg_start, bg_status, bg_list, bg_kill) for long-running background shell processes — dev servers, watchers, streaming builds. Processes are fire-and-forget with stdin ignored (immediate EOF); the model gets exactly one completion notification when a process exits. A /ps overlay command opens a two-stage full-screen inspector (dashboard → read-only detail with stdout/stderr toggle) to inspect live output and kill terminals interactively. While ≥1 terminal runs, a one-line widget appears above the editor. Output is captured to bounded in-memory buffers plus on-disk spill files; tool and completion output shows a concise tail. Terminals are session-scoped and stopped during shutdown or reload. Bundled in this package — no separate install needed.

Project-based learning mode built around ramps to knowledge rather than syllabi. /learn <concept> asks for the learner's starting point and timebox, proposes a few tiny projects where the concept becomes necessary, and coaches through short need → attempt → friction → minimum lesson → application → proof cycles. /learn-status shows the active ramp and /learn-stop exits it. State is persisted on the current pi session branch, and an active ramp appears in the footer. See extensions/learning/README.md for behavior and examples.

A minimal, reliable software factory. /factory <task> validates the project (trust, clean git baseline, human-authored .pi/factory.json config), then launches a bounded asynchronous pipeline through pi-subagents' in-process RPC: scout → plan → implement (single writer, checked acceptance handoff), deterministic validation (commands come only from .pi/factory.json — never from model output), three parallel fresh reviewers (correctness, tests, simplicity) branching only on structured verdicts, at most one fix pass, and a final rerun of the trusted checks. Machine-consumed child results all use output schemas; malformed output and unresolved human decisions fail closed (needs_attention / needs_approval). /factory-status shows the latest run (phase, run/mission ids, checks, reviewer disposition, decisions). No commit, push, deploy, or release is ever performed. Deliberate deviation: pi-subagents 0.61 grants runs.host only to its named run-ci resource, so the trusted checks run in the extension process from human-authored config instead — same guarantee, no agent in the loop. See extensions/factory/README.md for the pipeline, config schema, and tests.

Shadows the builtin pi-subagents reviewer for every project where sof-pi is installed (package agents load above builtins). It keeps the builtin review structure and appends the sof-pi Review Rubric: flagging discipline, untrusted-input checks, fail-fast error handling, [P0]–[P3] priority tags, and the required non-blocking Human Reviewer Callouts section. Every subagent({ agent: "reviewer" }), /parallel-review, and /review-loop run therefore applies the same rubric automatically. A project can still override locally by dropping its own reviewer.md into the project agents directory.

Read-only implementation planner used as the plan stage of the factory build workflow (/factory). It has no shell or write tools (read, grep, find, ls, high thinking) and returns a structured plan: concrete steps, files expected to change, explicit non-goals, a validation plan drawn only from commands that actually exist in the repository, and any product/architecture/security/scope decisions that require human approval — the factory stops on any unresolved decision instead of assuming.

Beyond the extensions bundled in this package, I rely on a couple of npm-installed pi packages that add their own extensions/skills.

Live OpenRouter visibility and environment sync for pi: usage/account TUI overlays, automatic session_id tagging, full or free-only model catalog sync, API key management, and local model field overrides. Exposes a set of /openrouter commands:

• /openrouter usage — spend/usage overlay
• /openrouter account — credits, key limits, account health, key toggle UI
• /openrouter session — current OpenRouter session_id
• /openrouter api-key-create — create an API key (management key required)
• /openrouter models-sync / --free — sync user-scoped (or free-only) models into pi
• /openrouter models-status / --free / --skipped — show model sync/cache status
• /openrouter model-override-set|list|clear — local model field overrides

Install: pi install npm:@robhowley/pi-openrouter

Lets pi delegate work to focused child agents — for code review, scouting, implementation, parallel audits, saved workflows, and background jobs. Supports single-agent delegation, sequential chains, parallel fan-out, async/background runs, forked-context review, and a /research-style TUI clarification flow. Plain-language delegation works out of the box (no config or slash commands needed), with builtin agents like reviewer, scout, and oracle ready to go.

Install: pi install npm:pi-subagents

This package includes a version-controlled mise control plane for one private, persistent exe.dev VM: sof-pi-workspace (sof-pi-workspace.exe.xyz), tagged sof-pi. It clones only https://sof-pi.int.exe.xyz/BbrSofiane/sof-pi.git; the pre-attached tag-scoped sof-pi GitHub integration must provide that access.

Prerequisites: local mise, ssh with an identity registered at exe.dev, Python 3, jq, git, and the pre-attached GitHub integration. First inspect, then explicitly provision:

mise run workspace:status
mise run workspace:provision

provision creates the fixed name only when it is absent, polls the control plane until the exact host/tag and explicit private state are verified, then waits for direct SSH and bootstraps. Repeating create, bootstrap, or sync is intended to converge; an unexpected VM tag/host, dirty checkout, or wrong Git origin stops rather than repairing or deleting data. No task exposes a port, makes the VM public, or attaches/detaches integrations.

Only reviewed scalar-string tool versions from the local mise global config's [tools] and the explicitly allowlisted [settings].experimental boolean are projected to the VM (workspace:sync). The mirror is exact on each successful sync: locally removed tools/settings disappear remotely. Tables, lists, URLs, paths, whitespace-bearing specs, credentials/options/hooks, unknown tools, and non-boolean settings are rejected rather than copied. [env] is never read into output or copied. SSH keys/config, Pi auth/settings, GitHub/cloud credentials, and API keys are never copied. Every mutable or direct operation verifies an explicit sharing.public_proxy = false state and stops on public, missing, or malformed privacy state; workspace:status may report such an unsafe VM without connecting to it.

mise run workspace:sync
mise run workspace:update
mise run workspace:ssh                         # interactive direct SSH
mise run workspace:ssh -- uptime
mise run workspace:pi                          # tmux session: sof-pi-interactive
mise run workspace:job:start -- --id docs-01 --prompt-file ./prompt.md
mise run workspace:job:status -- --id docs-01
mise run workspace:job:logs -- --id docs-01
mise run workspace:job:attach -- --id docs-01
mise run workspace:job:stop -- --id docs-01

Jobs have an isolated pi/<id> branch and VM-local worktree; they never edit main concurrently. Each job branches from the verified canonical checkout's current HEAD; run mise run workspace:update first when a job needs the latest remote main. Bootstrap installs the checked-in VM job helper from that verified checkout, and every job action invokes that installed copy as the sole runtime implementation—the laptop sends only the prompt over stdin. Prompts, logs, and status are private at rest on the VM with restrictive permissions; logs and status stream only to the authenticated invoking SSH client when explicitly requested. Package installation is automated and pins npm:@robhowley/[email protected] and npm:[email protected], but Pi provider access needs a separately approved VM-native authentication/integration route; neither interactive nor unattended jobs receive copied credentials.

Deletion is intentionally opt-in and permanently removes the VM disk and all VM-local state. It is never part of another task:

CONFIRM_DESTROY=sof-pi-workspace mise run workspace:destroy

Run offline controller/sanitizer tests with mise run workspace:test. The first live bootstrap requires this workflow to be committed and available on the integration clone's main branch, because the checked-in job helper is installed only from that verified checkout; after publishing it, rerun mise run workspace:bootstrap (or workspace:update).

Impeccable (impeccable.style) is the design skill used across projects — a frontend design language with design commands (shape, craft, audit, polish, critique, etc.) and deterministic anti-pattern detection. It's installed as a standalone pi skill (not bundled into this package) so it updates independently via its own CLI.

Install globally so it's available in every project:

npx impeccable skills install -y --providers=pi --scope=user

This writes to ~/.pi/skills/impeccable/. Reload pi, then run /impeccable init in a project to generate its PRODUCT.md / DESIGN.md context. Update later with npx impeccable skills update.

Apache License 2.0