superpowers-manager 0.3.0 → 0.5.0

package/README.md

@@ -1,366 +1,104 @@
 # Superpowers Manager
 
-Install and update the latest stable
-[`obra/superpowers`](https://github.com/obra/superpowers) release directly from
-upstream, without waiting for agent marketplaces to catch up.
-Codex supported today.
+Install and explicitly refresh the latest stable [`obra/superpowers`](https://github.com/obra/superpowers) release. Superpowers Manager supports Codex and the Pi coding agent without waiting for a marketplace copy to catch up.
 
-> Unofficial community integration. Not affiliated with the
-> `obra/superpowers` maintainers.
+> Unofficial community integration. Not affiliated with the `obra/superpowers` maintainers.
 
-## Quick start
+## Start with your agent
 
-```sh
-npx superpowers-manager install
-npx superpowers-manager probe
-npx superpowers-manager update
-```
+The two harnesses share upstream selection, while each has independent prepared and installed state. Omitting `--harness` selects Codex.
 
-Use the official marketplace for the simplest native Codex installation. Use
-Superpowers Manager when you want immediate stable-upstream freshness after a
-user-triggered install/update, per-invocation release or commit selection,
-recorded upstream provenance, diagnostics, upstream-owned Codex hook handling,
-and explicit install/update/probe/uninstall lifecycle control.
-
-| Choose | Best fit |
-|---|---|
-| Official marketplace | Simplest Codex-native installation and marketplace-managed cadence |
-| `superpowers-manager` | Direct stable-upstream freshness when invoked, exact ref selection, provenance, diagnostics, and lifecycle control |
-
-### Moving from `superpowers-wrapper`
+### Codex
 
 ```sh
-npx superpowers-wrapper@0.1.1 uninstall
-npx superpowers-manager install
+npx superpowers-manager install --harness codex
+npx superpowers-manager probe --harness codex
+npx superpowers-manager update --harness codex
 ```
 
-The manager detects legacy wrapper-owned Codex state and stops before mutation.
-It never removes the legacy provider automatically.
-
-## Requirements and platforms
-
-Superpowers Manager requires Node 24+, and Codex is the only supported
-integration today. Every other requirement is per command, enforced by
-preflight before any dispatch. This table is checked against production by
-`tests/bin/readme-requirements.test.js`; edit it when a command's requirements
-change, in the same pull request.
-
-<!-- requirements:begin -->
-| Command | git | Python 3 | Codex CLI |
-|---|---|---|---|
-| `pin` | yes | no | no |
-| `track-latest` | no | no | no |
-| `unpin` | no | no | no |
-| `prepare` | yes | only with SUPERPOWERS_VALIDATOR | no |
-| `probe` | yes | no | yes |
-| `install` | yes | no | yes |
-| `update` | yes | no | yes |
-| `uninstall` | no | no | yes |
-<!-- requirements:end -->
-
-See `docs/baseline/behavioral-inventory.md`'s `CLI-PREFLIGHT-01` for the
-behaviour this table describes.
-
-macOS and Linux are tested. WSL2 is supported. The native Windows path is
-untested; the launcher no longer looks for Git Bash at all — every command runs
-in-process, so no POSIX shell is discovered or required — but path handling
-between MSYS and Codex remains a known risk area.
-
-Network needs depend on the saved policy. `pin` verifies its target;
-`track-latest` and invocation overrides resolve from upstream when applied; and
-`prepare`, `install`, and `update` fetch or verify the effective source. A probe
-of a saved exact pin can reuse its recorded identity without upstream access.
-Updates remain user-triggered; the manager does not run automatic or background
-updates.
+Codex installs the Manager-owned marketplace plugin after preparation and
+validation. Review upstream hook definitions with Codex's `/hooks` flow before
+trusting or running them; updates can change a referenced script or surface a
+new definition. The manager neither creates hooks nor changes Codex trust state.
+See the [Codex reference](https://github.com/j7an/superpowers-manager/blob/main/docs/codex.md).
 
-## What it does
+### Pi
 
-- Resolves an upstream ref, defaulting to the latest stable `vX.Y.Z` release
-  tag.
-- Clones/fetches upstream at that commit and assembles a Codex plugin tree under
-  `plugins/superpowers/` (skills, assets, license/readme, manifest, and any
-  hook files that the upstream manifest allows).
-- Stamps the generated manifest with a ref-aware manager version ending in
-  `+manager.<short-sha>` and writes the upstream provenance to
-  `.superpowers-upstream.json`.
-- Validates the generated tree with the manager's shipped contract validator
-  before swapping it into place (a failed run never destroys a previously
-  generated tree).
-- Registers the `superpowers-manager` marketplace and installs or refreshes
-  `superpowers@superpowers-manager` in Codex.
-
-The generated plugin carries upstream skills, assets, documentation, and the
-upstream-owned hook policy. When upstream provides a Codex manifest, its
-`hooks` declaration is preserved: exact `{}` suppresses the `hooks/` subtree;
-active declarations conditionally materialize the upstream hook files; and a
-missing `hooks` key or explicit empty array (`[]`) declaration uses Codex's
-default discovery only when upstream ships `hooks/hooks.json`. Manifest-less
-fallback refs use the committed minimal template and generate neither a manifest
-`hooks` key nor a `hooks/` directory.
-The manager never creates its own hooks or mutates Codex trust state.
-
-Review upstream hook command definitions with Codex's `/hooks` flow. Codex
-trust applies to a command definition, not to the contents of scripts that the
-definition references. An explicit update of an older pin can therefore change
-the contents of a trusted referenced script, or reveal a newly untrusted
-upstream definition; review it before trusting or running it. This policy
-eliminates latent hook-policy drift.
-
-## Runtime architecture
-
-- The in-process TypeScript runtime under `src/` owns lifecycle dispatch,
-  status, and adapter-result handling;
-  see the [in-process adapter result contract](https://github.com/j7an/superpowers-manager/blob/main/docs/adapter-result-contract.md).
-- `src/adapter.ts` owns build, inspection, reconciliation, and Codex mutation.
-- Codex is the only supported adapter today; no public harness selector ships
-  yet.
-
-Validation checks the manager-owned manifest overlay, generated-tree structure,
-skill frontmatter envelope, known local paths, and provenance. It deliberately
-does not implement a general YAML parser or mirror every Codex ingestion rule;
-upstream owns skill semantics and Codex owns its evolving schema.
-
-`SUPERPOWERS_VALIDATOR=/path/to/validator.py` adds an optional Python validator
-after the built-in check. It receives the candidate plugin root as its only
-argument. It cannot replace or bypass built-in validation, and either check
-failing prevents the tree swap and all Codex mutation.
-
-`SUPERPOWERS_VALIDATOR_EXECUTABLE=/path/to/validator` adds an optional external
-validator after the built-in check. It names an executable, receiving the
-candidate plugin root as its only argument. The manager constructs no shell
-command string and supplies argv directly. On Linux, `execvp` may hand that
-same argv to `/bin/sh` after `ENOEXEC`, and the values are preserved rather
-than re-parsed, so a candidate path containing spaces or shell metacharacters
-is passed through intact and cannot inject a command — on either platform. A
-file with the exec bit set but no valid executable format is handled by the
-platform's own `execvp` fallback, not by the manager: on Linux, `/bin/sh` runs
-it as shell source; on darwin, it is
-rejected outright as not runnable. Give the validator a shebang line or make
-it a real binary, or its behavior will differ by platform. Exit 0 accepts;
-any nonzero exit rejects and prevents the tree swap. The manager stops
-waiting after 30 seconds and keeps at most 64 KiB of each of its output
-streams. It cannot replace or bypass built-in validation, and it is not a
-security boundary: it runs with the manager's own privileges, by design.
+```sh
+npx superpowers-manager install --harness pi
+npx superpowers-manager probe --harness pi
+npx superpowers-manager update --harness pi
+```
 
-`SUPERPOWERS_VALIDATOR` is deprecated in favor of `SUPERPOWERS_VALIDATOR_EXECUTABLE`
-and continues to work unchanged. The legacy variable requires `python3`; the
-executable hook does not. Setting both is rejected at preflight, before any
-network or Codex access, rather than silently resolved. Removal of the legacy
-variable is deferred to a future major release.
+Pi installs a separately validated, Manager-owned frozen snapshot. Restart Pi
+after a successful install, activating update, or removal. See the
+[Pi reference](https://github.com/j7an/superpowers-manager/blob/main/docs/pi.md)
+for compatibility, experimental opt-in, and recovery behavior.
 
-The in-process install command keeps harness-specific validation in the Codex
-adapter: phase 1 prepares the exact candidate first, then the adapter performs
-its Codex and refresh-mode preflight before any Codex mutation. The CLI runs
-its Codex preflight before invoking the lifecycle handler.
+To remove a Manager-owned installation, choose one harness explicitly:
 
-## Provider ownership
+### Uninstall Codex
 
-If another `superpowers` provider is installed, remove or disable it yourself
-before installing this one. The manager never removes another provider and
-mutates only `superpowers@superpowers-manager` and the `superpowers-manager`
-marketplace.
+```sh
+npx superpowers-manager uninstall --harness codex
+```
 
-For example, if you intentionally want the manager to take over from the
-official provider:
+### Uninstall Pi
 
 ```sh
-codex plugin remove superpowers@openai-curated
-npx superpowers-manager install
+npx superpowers-manager uninstall --harness pi
 ```
 
-Manager install, update, and uninstall commands inspect both current and legacy
-identities and fail closed when Codex state cannot be read or parsed. If legacy
-`superpowers-wrapper` state remains, use the migration commands above; the
-manager will not remove it for you.
-
-## Lifecycle commands
+The manager never removes another Superpowers provider. See the [ownership guidance](https://github.com/j7an/superpowers-manager/blob/main/docs/usage.md#provider-ownership) before switching providers.
 
-| Command | Codex side effects | Purpose |
-|---|---|---|
-| `npx superpowers-manager pin REF` | None | Resolve and save an exact upstream release tag or full commit |
-| `npx superpowers-manager track-latest` | None | Save a policy that resolves the latest stable release when applied |
-| `npx superpowers-manager unpin` | None | Remove saved selection and return to the packaged fallback policy |
-| `npx superpowers-manager prepare` | None | Resolve upstream, build a staged plugin tree, validate it, and replace the generated tree only on success |
-| `npx superpowers-manager probe` | None | Report requested and resolved refs, desired/generated/installed commits, identity state, and status |
-| `npx superpowers-manager install` | Marketplace and plugin state | Prepare and validate, register the marketplace, install the plugin, and verify installed state |
-| `npx superpowers-manager update` | Marketplace and plugin state when stale | Probe, prepare and/or install as needed, then verify the refresh |
-| `npx superpowers-manager uninstall` | Marketplace and plugin state | Remove only manager-owned Codex state and verify removal |
+## Shared selection and lifecycle
 
-Calling `npx superpowers-manager` without a subcommand is equivalent to
-`update`. `probe` is read-only. Install and update stop before prepare or Codex
-mutation when legacy state is present. Uninstall removes only manager-owned
-state and reports any legacy residue without modifying it. These commands fail
-closed when required state cannot be inspected and refuse to report success
-when resulting manager state cannot be verified.
+Use `pin`, `track-latest`, or `unpin` to save shared upstream intent. They do not activate Codex or Pi; run the selected harness's `install` or `update` to apply that choice. There is no background updater.
 
-## Choosing the upstream version
+| Command | Purpose |
+|---|---|
+| `prepare` | Build and validate the selected harness's prepared output |
+| `install` | Apply the shared selection to the selected harness |
+| `probe` | Inspect the selected harness without mutation |
+| `update` | Explicitly refresh the selected harness when needed and verify it |
+| `uninstall` | Remove only Manager-owned state from the selected harness |
 
-Save a tag pin, commit pin, or explicit latest-stable policy for future
-invocations:
+Use `--harness codex` or `--harness pi` with each targeted lifecycle command.
 
 ```sh
 npx superpowers-manager pin v6.1.1
-npx superpowers-manager pin 0123456789abcdef0123456789abcdef01234567  # replace with a real upstream commit
 npx superpowers-manager track-latest
 npx superpowers-manager unpin
 ```
 
-The selection commands save intent only; they do not prepare generated content
-or change Codex state. Run `npx superpowers-manager install` for a first
-installation or `npx superpowers-manager update` to apply the saved policy to
-an existing installation. There is no background updater: selection changes
-take effect only through a user-triggered `prepare`, `install`, or `update`.
-
-`pin` accepts only an exact `vMAJOR.MINOR.PATCH` tag (optionally with a SemVer
-prerelease suffix) or a full 40-character commit. It resolves and verifies the
-target before saving both the exact commit identity and its source. The saved
-identity is the contract, not the contents of a clone cache: clearing or moving
-`SUPERPOWERS_CACHE_DIR` does not change the selection. `track-latest` saves the
-source and resolves the highest stable `vX.Y.Z` tag each time the policy is
-applied. `unpin` removes only the saved selection and restores the packaged
-`config/upstream-ref` fallback, currently `latest-release`.
-
-The user-wide selection file is `selection.json` under the first configured
-location:
-
-1. `$SUPERPOWERS_CONFIG_DIR`
-2. `$XDG_CONFIG_HOME/superpowers-manager`
-3. `$HOME/.config/superpowers-manager`
-
-Each location must be absolute. The ref and source precedence chains are
-independent:
-
-- Ref: `SUPERPOWERS_REF`, then saved selection, then `config/upstream-ref`.
-- Source: `SUPERPOWERS_UPSTREAM_URL`, then saved source, then the official
-  `https://github.com/obra/superpowers` source.
-
-`SUPERPOWERS_REF` is an invocation-only override and is not persisted. Unlike
-an exact saved pin, it accepts stable tags, full commit SHAs, branches, and
-other resolvable upstream refs for that invocation:
-
-```sh
-SUPERPOWERS_REF=feature/foo npx superpowers-manager probe
+```text
+shared selection -> prepare / inspect / activate Codex
+                 -> prepare / inspect / activate Pi
 ```
 
-`pin` and `track-latest` bind the current `SUPERPOWERS_UPSTREAM_URL`, or the
-official source when that variable is unset, to the saved intent. An invocation
-may override only the ref or only the source; `probe` exposes
-`selection_origin`, `selection_mode`, `upstream_source_origin`,
-`effective_source`, the saved-selection fields, and a mixed-origin warning in
-human output so that combination remains visible.
-
-A saved exact pin lets `probe` determine the desired upstream identity without
-contacting Git, even when the saved source is temporarily unavailable. This is
-not a general offline installation promise: `pin` verifies the requested
-target, `track-latest` must resolve when applied, and `prepare`/`install`/`update`
-must fetch or verify content from the effective source. Codex inspection is
-still required for lifecycle status.
-
-HTTP(S) upstream URLs containing userinfo are now rejected, including
-token-only userinfo. This is an intentional compatibility break: use a Git
-credential helper for HTTP(S) authentication or an SSH source instead of
-embedding credentials in the URL.
-
-Saved selection does not claim or transfer provider ownership. The manager
-continues to mutate only `superpowers@superpowers-manager` and never removes or
-updates the official provider or any other provider automatically.
-
-## How versioning works
-
-- **Upstream manifest first:** when upstream provides
-  `.codex-plugin/plugin.json`, `prepare` uses it as the generated manifest base
-  so future upstream metadata fields, including its hook declaration, are
-  preserved by default.
-- **Fallback template:** `plugins/superpowers/.codex-plugin/plugin.template.json`
-  is committed as a minimal fallback for older upstream refs that do not ship a
-  Codex manifest. It carries the placeholder version
-  `0.0.0+manager.template`, declares no hooks, and produces no `hooks/`
-  directory.
-- **Manager overlay:** `prepare` replaces the version with a ref-aware manager
-  version and forces `skills` to `./skills/`. Unknown upstream manifest fields,
-  including `hooks`, remain preserved; the adapter materializes hook files only
-  according to the upstream declaration.
-- Stable tags generate release-looking versions such as
-  `6.0.3+manager.896224c`; explicit prerelease tags generate versions such as
-  `6.1.0-beta.1+manager.abc1234`.
-- Branch builds deliberately stay below real releases:
-  `main` generates `0.0.0-main+manager.<short-sha>` and other named refs
-  generate `0.0.0-ref-<sanitized-ref>+manager.<short-sha>`.
-- Raw 40-character commit SHAs generate `0.0.0+manager.<short-sha>`.
-- **`.superpowers-upstream.json`** records the authoritative provenance:
-  `source`, `requested_ref`, `resolved_ref`, `commit`, and the upstream manifest
-  version. The generated manifest version is for human readability and Codex
-  package identity; the upstream `commit` is what `probe`/`update` compare
-  against.
-
-## Refresh modes
+The [usage reference](https://github.com/j7an/superpowers-manager/blob/main/docs/usage.md) covers version selection, precedence, offline behavior, `prepare`, validators, and every lifecycle command. The harness references cover [Codex registration and hooks](https://github.com/j7an/superpowers-manager/blob/main/docs/codex.md) and [Pi snapshots and recovery](https://github.com/j7an/superpowers-manager/blob/main/docs/pi.md).
 
-`install` and `update` accept `SUPERPOWERS_INSTALL_REFRESH_MODE`:
-
-- `add-only` (default) — `plugin add` re-reads the local source, which refreshes
-  a mutated tree. Verified sufficient for local marketplaces.
-- `remove-add` — removes the manager's own plugin first, then re-adds it. Use
-  only if a refresh ever fails to take:
-
-  ```sh
-  SUPERPOWERS_INSTALL_REFRESH_MODE=remove-add npx superpowers-manager update
-  ```
-
-## Tests
-
-```sh
-pnpm install --frozen-lockfile
-pnpm run build
-sh tests/run.sh                          # Layers 1-3: host-side hermetic checks while iterating
-sh tests/container.sh                    # Layers 1-4: blocking Docker acceptance command
-sh tests/manual/codex-behavior-probe.sh  # optional native-only compatibility residue
-```
-
-`pnpm run build` deletes `dist/` before compiling, so every build is a clean
-rebuild and stale artifacts of deleted or renamed modules cannot survive.
-
-Layers 1-3 stay offline and hermetic: they use a fake local upstream repo plus
-host-side fixtures, and they perform no mutation of the developer's or runner's
-real Codex state.
+## Requirements and platforms
 
-Layer 4 is the Docker acceptance path. It is the required completion command
-because the isolated-container Codex probe graduated from a temporary
-nonblocking spike to a blocking acceptance gate. `sh tests/container.sh` runs
-the inner `sh tests/run.sh` suite and then the real Codex offline probe inside
-an isolated container home with networking disabled. That container run may
-mutate the throwaway container-local Codex state, but it still performs no
-mutation of the developer's or runner's real Codex state.
+The installed package requires Node >=24. Native source, tests, and packaging tooling require Node >=24.12.0. Every other requirement is command-specific and is checked before dispatch. This table is derived from production by `tests/bin/readme-requirements.test.ts`.
 
-The container probe uses Codex's `hooks/list` only as compatibility evidence
-for the tested Codex build. It is not a stable Superpowers Manager API.
+<!-- requirements:begin -->
+| Command | git | Python 3 | Codex CLI (default) | Pi CLI (`--harness pi`) |
+|---|---|---|---|---|
+| `pin` | yes | no | no | no |
+| `track-latest` | no | no | no | no |
+| `unpin` | no | no | no | no |
+| `prepare` | yes | only with SUPERPOWERS_VALIDATOR | no | no |
+| `probe` | yes | no | yes | no |
+| `install` | yes | no | yes | yes |
+| `update` | yes | no | yes | yes |
+| `uninstall` | no | no | yes | yes |
+<!-- requirements:end -->
 
-The manual probe is opt-in and covers native-only compatibility residue such as
-path/cache and version-precedence behavior against an intentionally real local
-Codex install. It is not part of acceptance. GitHub Actions runs both the
-toolchain check and the blocking container acceptance command on pull requests
-and pushes to `main`.
+macOS and Linux are tested. WSL2 is supported for the established Codex path; Pi in WSL2 and native Windows remain untested. The manager runs in-process and does not require Git Bash. The [Pi reference](https://github.com/j7an/superpowers-manager/blob/main/docs/pi.md#runtime-compatibility) explains its runtime qualification and admission checks.
 
-## Repository layout
+Native test versions qualify integration mechanisms; they are not runtime allowlists, and an untested runtime is not automatically certified as compatible.
 
-```
-.agents/plugins/marketplace.json          # local marketplace definition (tracked)
-.github/                                  # CI, security, dependency, and release workflows (tracked)
-bin/superpowers-manager.js                # public thin loader for dist/cli.js
-config/upstream-ref                       # packaged upstream fallback policy (tracked)
-docs/                                     # adapter result contract and baseline evidence (tracked)
-package.json pnpm-lock.yaml tsconfig.json # package contract and locked toolchain (tracked)
-plugins/superpowers/
-  .codex-plugin/plugin.template.json      # fallback manifest template (tracked)
-  generated plugin tree                   # prepared from upstream (gitignored)
-src/                                      # in-process TypeScript runtime (tracked)
-  cli.ts                                  # CLI parsing, preflight, and command dispatch
-  commands/                               # lifecycle and selection command handlers
-  adapter.ts                              # Codex integration
-tests/                                    # hermetic suite and manual Codex probe (tracked)
-  migration-inventory/                     # frozen historical evidence
-dist/                                     # generated ESM build tree (gitignored)
-```
+## Contributing
 
-Everything under `plugins/superpowers/` except the fallback manifest template is
-generated by `npx superpowers-manager prepare` and ignored by Git; re-run that
-command to regenerate it.
+See [the contributor guide](https://github.com/j7an/superpowers-manager/blob/main/CONTRIBUTING.md) for development, testing, packaging, CI, and repository layout. Architecture details live in the [harness interface](https://github.com/j7an/superpowers-manager/blob/main/docs/harness-interface.md) and [adapter result contract](https://github.com/j7an/superpowers-manager/blob/main/docs/adapter-result-contract.md).