# Local fork provenance and development

Audience: developers maintaining `@timmyjl12/pi-subagents` alongside custom Pi extensions.

## Provenance

- Upstream: https://github.com/tintinweb/pi-subagents
- Initial baseline: `e955e29` (upstream package 0.19.0).
- Package: `@timmyjl12/pi-subagents` on npm, first released as `0.20.0`.
- Repository: `github.com/timmyjl12/pi-subagents` (`origin`). Upstream is kept as the `upstream` remote, and upstream Git history, license and attribution are retained.
- Local fork maintainer: Tim L / timmyjl12.
- oh-my-pi is a design reference, not a vendored dependency. Its core focus controller cannot be dropped into stock Pi, which does not expose that private session-focus API.

## Intended integration

`pi-fallback-chains` owns model recovery. Subagent execution must remain tracked through the whole recovery sequence, including delayed model selection, compaction and replacement turns. Do not add a competing provider retry loop to the subagent manager.

Keep public Agent tools, workflow contracts and sibling-extension event consumers intact. Changes to session ownership or event payloads require behavioral integration tests. The shared recovery contract and sibling-extension ownership rules live outside this package, in the workspace that holds the `@timmyjl12/pi-*` extensions.

## Development

Run in this directory:

```sh
npm ci --ignore-scripts
npm run check
npm run test:e2e
```

Development dependencies target Pi 1.1.0; the peer floor stays at 0.86.1. Scripted tests should use fake providers, not paid live requests. Report timeout/skipped suites separately. Do not interpret a passing renderer unit test as a visual test in a real terminal.

For an isolated manual test, use a fresh `PI_CODING_AGENT_DIR` and a scratch working directory. Explicitly load the local fork and local fallback extension; do not load upstream at the same time. Leave the ordinary global configuration untouched until activation is approved.

## Releasing

Publish with `npm publish` after `npm run check` passes (`prepublishOnly` also runs lint, typecheck, tests and the build). Use `--tag next` for a prerelease so it never replaces the stable build. Restart Pi rather than hot-replacing extensions while children are active.

## Upstream maintenance

Review incoming upstream changes against this fork's recovery and UI tests before merging. Avoid renaming established event namespaces merely to change package branding. Preserve original notices for any subsequently copied code; do not assume design inspiration grants permission to omit license attribution.