# 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.
- 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 checkout and the local fallback extension; do not load another subagents extension 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

If you bring in changes from tintinweb/pi-subagents, review them against our 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.