# Development

```sh
npm ci
npm run check          # typecheck
npm test
npm run format:check
```

Tests run offline with no model credentials. Scripted-provider SDK tests cover nested parallel launches, level limits, pause, persistence and recovery. Generated JSONL scenarios cover multilevel trees, unopened parents, interrupted work, durable mailboxes, root forks and same-file tree navigation.

## Code layout

| Path                                                                         | Responsibility                                                                                                     |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `src/index.ts`                                                               | Parent-session lifecycle and extension wiring                                                                      |
| `src/orch/manager.ts`                                                        | Ownership, lifecycle, retained registry. `scope(caller)` gives tools and UI the same caller-bound `ThreadService`. |
| `src/orch/runtime.ts`                                                        | Isolated pi SDK sessions, providers, safe turn boundaries                                                          |
| `src/orch/paths.ts`                                                          | Canonical ancestry and context snapshots                                                                           |
| `src/orch/mailbox.ts`                                                        | Input persistence, replay, transcript reconciliation                                                               |
| `src/orch/tools.ts`                                                          | Caller-bound model tools                                                                                           |
| `src/orch/prompt.ts`                                                         | System-prompt guidance per mode                                                                                    |
| `src/prefs/config.ts`                                                        | Frontmatter validation, precedence, atomic saves                                                                   |
| `src/prefs/settings.ts`                                                      | Manager settings, validation, safe paths                                                                           |
| `src/prefs/models.ts`                                                        | Model selection                                                                                                    |
| `src/prefs/agent-import.ts`, `import-discovery.ts`, `import-instructions.ts` | Import consent, read-only discovery, migration guidance                                                            |
| `src/ui/`                                                                    | Dialogs, settings, type editor, model and import pickers, thread tree, widget                                      |
| `agents/`                                                                    | Bundled agent definitions                                                                                          |

## Changelog

[CHANGELOG.md](../CHANGELOG.md) is generated by the [changelog workflow](../.github/workflows/changelog.yml) when a version tag is pushed, together with a GitHub Release. Don't edit generated entries — edit the GitHub Release and rerun.

- Headings: major `##`, minor `###`, patch `####`. Missing initial tags get series headings (`0.x`, `0.1.x`).
- Stable releases compare against the previous stable ancestor tag; prereleases against the previous ancestor tag and are listed separately.
- Built from GitHub's generated notes, plus a scan of all closed PRs to catch any merged into the tag range (bots, squash/rebase). Direct commits appear only in compare links.
- Handwritten release highlights survive reruns.
- Needs only `GITHUB_TOKEN` with `contents: write` and `pull-requests: read`. Pushes `CHANGELOG.md` to the default branch without force; branch protection must allow it.

**Backfill:** Actions → Publish changelog → Run workflow. Empty `tag` rebuilds the file only; a tag also publishes/repairs that release.

**Local preview** (needs authenticated `gh` with contents-write):

```sh
git fetch origin --tags
GITHUB_REPOSITORY=championswimmer/pi-subagent-manager npm run changelog
```

Rewrites local `CHANGELOG.md` only. The workflow adds `--publish`.

**Why native notes:** they fit the existing tag-based release without another release manager. Release Drafter adds a draft lifecycle; release-please takes over versioning and needs Conventional Commits; git-cliff is commit-oriented; github-changelog-generator adds Ruby/Docker.

## Publishing

Pushing a `v<version>` tag runs [release.yml](../.github/workflows/release.yml): checks the tag matches `package.json`, typechecks, tests, and publishes to npm with provenance via GitHub OIDC. No `NPM_TOKEN`.

npm trusted publisher: owner `championswimmer`, repo `pi-subagent-manager`, workflow `release.yml`, environment empty.

To release:

```sh
npm version minor --no-git-tag-version   # updates package.json + lock
# validate, commit
git tag -a v<version> -m v<version>
git push && git push --tags
```

The package ships TypeScript sources and `agents/`; check `files` in `package.json` when adding assets.

## Background

Initial design: [`.agents/plans`](https://github.com/championswimmer/pi-subagent-manager/tree/main/.agents/plans). Prior-art research: [Claude](research-claude.md), [Codex](research-codex.md).