ultimate-pi

Ultimate AI coding harness for pi.dev — extensible skills, Obsidian wiki knowledge layer, compressed context, deterministic output

Packages

Package details

extensionskillprompt

Install ultimate-pi from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:ultimate-pi

Package: ultimate-pi
Version: 0.12.0
Published: May 18, 2026
Downloads: 3,983/mo · 3,169/wk
Author: aryaniyaps
License: MIT
Types: extension, skill, prompt
Size: 17.1 MB
Dependencies: 5 dependencies · 1 peer

Pi manifest JSON

{
  "extensions": [
    "./.pi/extensions"
  ],
  "skills": [
    "./.agents/skills",
    "./.pi/skills"
  ],
  "prompts": [
    "./.pi/prompts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

The ultimate AI coding harness on top of pi.dev.

ultimate-pi is a pi package that adds a governed coding workflow: plan first, then implement, then independent review—so agents cannot silently skip planning or merge unsafe changes.

Quick start

Requirements: Node 18+, npm 9+, git.

Install (from your project directory):

pi install npm:ultimate-pi
/reload

Bootstrap (once per project):

/harness-setup

Run a task (full pipeline in one command):

/harness-auto "implement feature X safely"

That runs: plan → execute → evaluate → adversary → policy decision. It does not auto-merge.

If something blocks, inspect status (no run id needed):

/harness-run-status
/harness-policy-status
/harness-trace-last

Commands

Command	What it does
`/harness-setup`	One-time project bootstrap (tools, harness dirs, extensions)
`/harness-auto "<task>"`	End-to-end pipeline (recommended)
`/harness-plan "<task>"`	Create or revise the active plan in context (no plan path to copy)
`/harness-run`	Execute the active plan from context (no `--plan` on happy path)
`/harness-eval`	Eval for active run (optional `--run`; spawns isolated `harness/evaluator`)
`/harness-review`	Independent review (optional `--run`)
`/harness-critic`	Adversarial review (optional `--run`)
`/harness-trace`	Trace summary (optional `--run`)
`/harness-run-status`	Where you are + what to run next (no run id shown)
`/harness-new-run`	Abandon current run and start fresh
`/harness-use-run <id>`	Advanced recovery only
`/harness-trace-last`	Last phase / handoff (no run id)
`/harness-policy-status`	Current policy / block reasons
`/harness-abort [reason]`	Stop and replan path

Manual workflow

Use this when you want each step separate:

/harness-plan "your task"
/harness-run
/harness-eval
/harness-review
/harness-critic

The harness remembers the active run and plan per project — you do not pass plan-packet.json paths or run ids between steps. The live widget shows phase/policy; after each step the agent (and UI notify) suggests the next command.

Recovery: --run and --plan remain for scripts; /harness-use-run and /harness-run-status for operators.

Defaults you should know

System prompt — .pi/extensions/00-ultimate-pi-system-prompt.ts sets the base prompt from packaged .pi/SYSTEM.md, or from your workspace override .pi/system.md (lowercase) if you create one. Nothing is copied into your project by default. After upgrading the package or editing either file, run /reload.
Model routing (vendored + gated) — pi-model-router ships inside this package (vendor/pi-model-router/). .pi/extensions/pi-model-router-harness.ts activates it only after .pi/model-router.json exists (generation: /harness-setup Step 3.5), so router/auto does not appear beforehand. See THIRD_PARTY_NOTICES.md. .pi/scripts/harness-sync-model-router.mjs may set defaultProvider/defaultModel to router/auto when the project sets no default — run /reload afterward. Do not add npm:@yeliu84/pi-model-router to .pi/settings.json; it duplicates the fork. Maintainer refresh: npm run vendor:sync-router.
Active run + plan context — PlanPacket lives at a fixed path per run; the extension injects it for /harness-plan (revise) and /harness-run (execute). Session state plus .pi/harness/active-run.json; no run ids or plan paths to copy.
Review isolation — /harness-eval, /harness-review, and /harness-critic spawn isolated subagents (inherit_context: false); stay in the same session (see ADR 0032).
Concurrent plans — a second /harness-plan while a run is active is blocked until /harness-abort or /harness-new-run (except drift replan / amend after needs_clarification).
Plan before mutate — write/edit/shell that changes the repo is blocked until execute phase.
No auto-merge — you decide when to open or merge a PR.
Structured runs — each run writes artifacts under .pi/harness/runs/ for replay and audit.

Optional: copy .env.example to .env if you use PostHog or other integrations wired by /harness-setup.

Troubleshooting

Problem	Try
Setup fails	`node --version` (need 18+), rerun `/harness-setup`
"No active run" on eval	Finish plan+run first, or `/harness-run-status`
Forgot where you left off	`/harness-run-status`
Second plan rejected	`/harness-abort` or `/harness-new-run`
Blocked in evaluate/review	Spawn review via Agent (`harness/evaluator` / `harness/adversary`); do not run review tools inline in execute phase
High plan drift	`harness-drift-replan` or abort then replan (ADR 0007)
Budget / scope stop	`/harness-budget-status`, narrow the task or split the plan
Test integrity warning	`/harness-test-integrity-last`, fix or justify test changes

Contributing

Local development, harness internals, and quality gates: CONTRIBUTING.md and .pi/harness/README.md.