minhduydev-pi-harness

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# pi-harness

`pi-harness` is a reusable Pi Coding Agent harness: curated extensions, skills, prompt templates, themes, runtime policy, and a tested source-checkout profile.

## What's new in 2.4.0

- The generated SuperPi router now selects one lifecycle stage plus at most one domain overlay, with catalog coverage validation and model-seat preflight.
- Skills and prompts have clearer ownership: architecture guidance is consolidated, natural user-invoked workflows stay hidden, and research/verification status is preserved.
- Release contracts now ship provenance notices, canonical bootstrap examples, and DCP legacy-state normalization.
- `@minhduydev/pi-todo@0.5.0` adds filtered views, lossless terminal-phase archives, and explicit format migration; the packed Phase 5 gate proves file-backed exactly-once outcomes across restart.

## Requirements

- Node.js `>=22.19.0`
- npm `>=11.12.1`
- Pi Coding Agent `0.81.1` (tested against Pi 0.81.1; the package uses the active host's Pi packages through peer dependencies)

## Bootstrap a consumer repository

One command installs the complete project-local **Full** harness contract; no
separate global or manual `pi install` is required:

```bash
mkdir -p ./my-repo
npx --yes --package=@minhduydev/pi-harness@2.4.0 -- pi-harness-init ./my-repo
```

The bootstrap writes exact project package pins for the executing harness and
its companion packages, portable Full settings, all seven canonical agent
profiles, the complete `.pi/templates/` tree, `.pi/ANTI_PATTERNS.md`, and a
sentinel-managed harness region in `.pi/APPEND_SYSTEM.md`. It also adds a
sentinel-managed runtime-state block to the existing `.gitignore` without
ignoring trackable settings, agents, policy, or templates. The auditable
`.pi/pi-harness.lock.json` records the harness version, exact package suite,
and hashes of every harness-owned file or region.

The initializer does not choose a provider, model, theme, or credentials, and
it does not install global system tools. Srcwalk semantic tools are preferred when
the optional CLI is available; the managed parent and subagent policies explicitly
fall back to built-in repository navigation when it is absent. Full settings enable
the portable provider adapters, but they do not require credentials at startup;
credentials are needed only when that provider is selected. Loaded integrations
report missing optional tools through `/integration` rather than making startup
depend on them.

The Full package set also pins `@mrclrchtr/supi-ask-user@4.0.0`, which provides
the interactive TUI-only `ask_user` decision form used by lifecycle prompts.
Those prompts include a numbered plain-text fallback for non-TUI or degraded
sessions.

### Rerun, preview, and upgrade

Use the same exact-version command for first install and reruns. An unchanged
rerun performs no content or timestamp writes. Preview a first install or
upgrade with:

```bash
npx --yes --package=@minhduydev/pi-harness@2.4.0 -- pi-harness-init --dry-run ./my-repo
```

To upgrade, change only the exact harness version in the `npx` command and run
it again. Files and managed regions still matching the hashes in the lock are
updated safely; consumer packages and settings outside the harness-owned keys
remain. Consumer prose before or after the APPEND policy sentinels is always
preserved.

If a managed file or region differs from its recorded hash, init exits
non-zero, reports every conflict, and changes nothing. Review the new packaged
resource, then either merge it manually and update by rerunning, restore the
recorded content, or delete that one managed file so init can recreate it. Do
not edit lock hashes to bypass conflict detection.

Pi package discovery loads the pinned package's extensions, skills, prompts,
and themes. Project-local materialization is still required because
`pi-subagents` discovers consumer agent profiles locally and templates are
repository assets. Bootstrap intentionally does **not** copy root `AGENTS.md`,
`PROJECT.md`, `.pi/README.md`, `.pi/DESIGN.md`, `.pi/MEMORY.md`, credentials,
hooks, or generated runtime state.

Pi's `/init` has a distinct role: run it after bootstrap when you want Pi to
inspect the consumer repository and create or refresh that project's own
`AGENTS.md`. `pi-harness-init` owns portable harness resources; `/init` owns
observed project context.

## Source-checkout profile

When this repository is used directly, `.pi/settings.json` provides a pinned project profile for task delegation, diagnostics, source lookup, and web/documentation tools. The Full profile pins `@heyhuynhgiabuu/pi-search`, which supplies `websearch`, `codesearch`, `context7`, `deepwiki`, `web_fetch`, `get_fetch_content`, and optional Firecrawl tools. Search works without an API key through Exa MCP; `EXA_API_KEY`, `BRAVE_API_KEY`, and `FIRECRAWL_API_KEY` enable their corresponding optional providers. Optional packages remain optional at runtime: prompts and policies must degrade explicitly when a tool is unavailable.

Context ownership is intentionally layered:

- `AGENTS.md` — maintenance rules for this package checkout.
- `.pi/APPEND_SYSTEM.md` — concise, repository-agnostic runtime policy.
- `.pi/skills/*/SKILL.md` — detailed workflows loaded on demand.
- `.pi/prompts/*.md` — user-invoked lifecycle orchestration.
- `.pi/agents/*.md` — role-specific pi-subagents contracts loaded only in configured checkouts.

`.pi/AGENTS.md` is intentionally absent because Pi discovers project context from root or nested `AGENTS.md` files, not from that duplicate location.

## Prompt lifecycle

- `/init` — inspect a target repository and create or safely merge project guidance.
- `/create` — specify and implement a change.
- `/fix` — diagnose and fix a defect from root cause.
- `/plan` — write an executable plan without implementation.
- `/research` — gather decision-ready evidence.
- `/verify` — run behavior, quality, and scope verification.
- `/ship` — perform final review and repository-defined gates.
- `/handoff` — write and persist a fourteen-section transfer contract.

The Full profile also enables typed workflow state: foundation verdicts,
backlog reconciliation checkpoints, and complete handoffs are validated by
`@minhduydev/pi-core` and stored as immutable digest-bound records. A durable
reconciliation reminder becomes due after four completed TODO items. See
`docs/workflow-state.md`.

Extension bundles, provider opt-ins, and independent Herdr worker-seat
restrictions are documented in `docs/harness-profiles.md`.

Prompt frontmatter uses only Pi-supported fields. Prompt bodies declare skill dependencies as `skill: name`; they do not assume a dedicated skill tool or hard-code this repository's commands into consumer workflows.

## Performance baseline

Run the optional Full-profile baseline without network or provider calls:

```bash
npm run benchmark:full
```

The JSON report records local resource-loader startup timings, the byte size and
labelled token estimate for portable policy plus discovered skill descriptions,
and sequential Todo-file stat timings as a periodic-update I/O proxy. These are
descriptive measurements, not CI thresholds. The report lists its environment
and limitations; collect comparable runs before proposing an optimization.

## Verification

```bash
npm run validate:skills
npm run typecheck
npm run typecheck:extensions
npm run test:all
npm run package:check
npm run pack:check
npm run smoke:resources
npm run release:check:local
npm run release:check:offline
npm run check
```

`release:check:local` builds and packs the four sibling checkouts next to this
repository, so it does not depend on unpublished suite versions. None of the
release scripts runs `npm publish`.

`release:check:offline` runs the same local deterministic gates but skips
`npm audit`, which requires registry access. It is intended for air-gapped or
temporarily disconnected environments and **does not** make a dependency-audit
or supply-chain freshness claim. Use the normal local or registry gate before
publishing once network access is available.

The owner-controlled publish order is:

1. [`@minhduydev/pi-core@0.3.1`](https://www.npmjs.com/package/@minhduydev/pi-core/v/0.3.1)
2. [`@minhduydev/pi-subagents@0.11.0`](https://www.npmjs.com/package/@minhduydev/pi-subagents/v/0.11.0)
3. [`@minhduydev/pi-learning@0.5.0`](https://www.npmjs.com/package/@minhduydev/pi-learning/v/0.5.0)
4. [`@minhduydev/pi-todo@0.5.0`](https://www.npmjs.com/package/@minhduydev/pi-todo/v/0.5.0)
5. [`@minhduydev/pi-harness@2.4.0`](https://www.npmjs.com/package/@minhduydev/pi-harness/v/2.4.0)

After the first four exact versions exist on npm, run the final registry gate
before publishing the harness:

```bash
npm run release:check:registry
```

The registry preflight distinguishes a genuinely missing version from a
network/authentication error or a wrong registry response. The release gate
runs the full project check, validates the npm payload, loads resources from an
installed package in an empty consumer directory, and performs a dependency
audit.

pi-harness

pi-harness is a reusable Pi Coding Agent harness: curated extensions, skills, prompt templates, themes, runtime policy, and a tested source-checkout profile.

What's new in 2.4.0

The generated SuperPi router now selects one lifecycle stage plus at most one domain overlay, with catalog coverage validation and model-seat preflight.
Skills and prompts have clearer ownership: architecture guidance is consolidated, natural user-invoked workflows stay hidden, and research/verification status is preserved.
Release contracts now ship provenance notices, canonical bootstrap examples, and DCP legacy-state normalization.
@minhduydev/pi-todo@0.5.0 adds filtered views, lossless terminal-phase archives, and explicit format migration; the packed Phase 5 gate proves file-backed exactly-once outcomes across restart.

Requirements

Node.js >=22.19.0
npm >=11.12.1
Pi Coding Agent 0.81.1 (tested against Pi 0.81.1; the package uses the active host's Pi packages through peer dependencies)

Bootstrap a consumer repository

One command installs the complete project-local Full harness contract; no separate global or manual pi install is required:

mkdir -p ./my-repo
npx --yes --package=@minhduydev/pi-harness@2.4.0 -- pi-harness-init ./my-repo

The bootstrap writes exact project package pins for the executing harness and its companion packages, portable Full settings, all seven canonical agent profiles, the complete .pi/templates/ tree, .pi/ANTI_PATTERNS.md, and a sentinel-managed harness region in .pi/APPEND_SYSTEM.md. It also adds a sentinel-managed runtime-state block to the existing .gitignore without ignoring trackable settings, agents, policy, or templates. The auditable .pi/pi-harness.lock.json records the harness version, exact package suite, and hashes of every harness-owned file or region.

The initializer does not choose a provider, model, theme, or credentials, and it does not install global system tools. Srcwalk semantic tools are preferred when the optional CLI is available; the managed parent and subagent policies explicitly fall back to built-in repository navigation when it is absent. Full settings enable the portable provider adapters, but they do not require credentials at startup; credentials are needed only when that provider is selected. Loaded integrations report missing optional tools through /integration rather than making startup depend on them.

The Full package set also pins @mrclrchtr/supi-ask-user@4.0.0, which provides the interactive TUI-only ask_user decision form used by lifecycle prompts. Those prompts include a numbered plain-text fallback for non-TUI or degraded sessions.

Rerun, preview, and upgrade

Use the same exact-version command for first install and reruns. An unchanged rerun performs no content or timestamp writes. Preview a first install or upgrade with:

npx --yes --package=@minhduydev/pi-harness@2.4.0 -- pi-harness-init --dry-run ./my-repo

To upgrade, change only the exact harness version in the npx command and run it again. Files and managed regions still matching the hashes in the lock are updated safely; consumer packages and settings outside the harness-owned keys remain. Consumer prose before or after the APPEND policy sentinels is always preserved.

If a managed file or region differs from its recorded hash, init exits non-zero, reports every conflict, and changes nothing. Review the new packaged resource, then either merge it manually and update by rerunning, restore the recorded content, or delete that one managed file so init can recreate it. Do not edit lock hashes to bypass conflict detection.

Pi package discovery loads the pinned package's extensions, skills, prompts, and themes. Project-local materialization is still required because pi-subagents discovers consumer agent profiles locally and templates are repository assets. Bootstrap intentionally does not copy root AGENTS.md, PROJECT.md, .pi/README.md, .pi/DESIGN.md, .pi/MEMORY.md, credentials, hooks, or generated runtime state.

Pi's /init has a distinct role: run it after bootstrap when you want Pi to inspect the consumer repository and create or refresh that project's own AGENTS.md. pi-harness-init owns portable harness resources; /init owns observed project context.

Source-checkout profile

When this repository is used directly, .pi/settings.json provides a pinned project profile for task delegation, diagnostics, source lookup, and web/documentation tools. The Full profile pins @heyhuynhgiabuu/pi-search, which supplies websearch, codesearch, context7, deepwiki, web_fetch, get_fetch_content, and optional Firecrawl tools. Search works without an API key through Exa MCP; EXA_API_KEY, BRAVE_API_KEY, and FIRECRAWL_API_KEY enable their corresponding optional providers. Optional packages remain optional at runtime: prompts and policies must degrade explicitly when a tool is unavailable.

Context ownership is intentionally layered:

AGENTS.md — maintenance rules for this package checkout.
.pi/APPEND_SYSTEM.md — concise, repository-agnostic runtime policy.
.pi/skills/*/SKILL.md — detailed workflows loaded on demand.
.pi/prompts/*.md — user-invoked lifecycle orchestration.
.pi/agents/*.md — role-specific pi-subagents contracts loaded only in configured checkouts.

.pi/AGENTS.md is intentionally absent because Pi discovers project context from root or nested AGENTS.md files, not from that duplicate location.

Prompt lifecycle

/init — inspect a target repository and create or safely merge project guidance.
/create — specify and implement a change.
/fix — diagnose and fix a defect from root cause.
/plan — write an executable plan without implementation.
/research — gather decision-ready evidence.
/verify — run behavior, quality, and scope verification.
/ship — perform final review and repository-defined gates.
/handoff — write and persist a fourteen-section transfer contract.

The Full profile also enables typed workflow state: foundation verdicts, backlog reconciliation checkpoints, and complete handoffs are validated by @minhduydev/pi-core and stored as immutable digest-bound records. A durable reconciliation reminder becomes due after four completed TODO items. See docs/workflow-state.md.

Extension bundles, provider opt-ins, and independent Herdr worker-seat restrictions are documented in docs/harness-profiles.md.

Prompt frontmatter uses only Pi-supported fields. Prompt bodies declare skill dependencies as skill: name; they do not assume a dedicated skill tool or hard-code this repository's commands into consumer workflows.

Performance baseline

Run the optional Full-profile baseline without network or provider calls:

npm run benchmark:full

The JSON report records local resource-loader startup timings, the byte size and labelled token estimate for portable policy plus discovered skill descriptions, and sequential Todo-file stat timings as a periodic-update I/O proxy. These are descriptive measurements, not CI thresholds. The report lists its environment and limitations; collect comparable runs before proposing an optimization.

Verification

npm run validate:skills
npm run typecheck
npm run typecheck:extensions
npm run test:all
npm run package:check
npm run pack:check
npm run smoke:resources
npm run release:check:local
npm run release:check:offline
npm run check

release:check:local builds and packs the four sibling checkouts next to this repository, so it does not depend on unpublished suite versions. None of the release scripts runs npm publish.

release:check:offline runs the same local deterministic gates but skips npm audit, which requires registry access. It is intended for air-gapped or temporarily disconnected environments and does not make a dependency-audit or supply-chain freshness claim. Use the normal local or registry gate before publishing once network access is available.

The owner-controlled publish order is:

After the first four exact versions exist on npm, run the final registry gate before publishing the harness:

npm run release:check:registry

The registry preflight distinguishes a genuinely missing version from a network/authentication error or a wrong registry response. The release gate runs the full project check, validates the npm payload, loads resources from an installed package in an empty consumer directory, and performs a dependency audit.