PiShip is in early development. Documentation, tests for existing behavior, and the first distribution core are useful contributions. The status page shows what current main supports, and the roadmap shows what is next.
Use Node.js 22.19.0 or newer and npm 11 or later (npm install -g npm@11): the tests that lock Pi packages skip with an older npm, and CI runs them on npm 11. On Linux the sandbox tests need bubblewrap with unprivileged user namespaces; see the prerequisites. From the repository root:
npm ci
npm run checknpm run check covers formatting, lint, types, package boundaries, tests, and build. For CLI changes, run npm run test:e2e. For Pi integration changes, run npm run test:compatibility.
CI evidence is routed to three tiers (AGENTS.md); moving a check between tiers changes when it runs, never what it covers.
- Pull requests and
mainpushes: fast merge gate. CI on Ubuntu, macOS, and Windows (formatting, lint, types, and boundaries once on Ubuntu; build, unit tests, and Pi compatibility on every target; the live platform secret-store test on every target: macOS Keychain, Windows Credential Manager, and the Linux Secret Service under GNOME Keyring) and CodeQL. Every pull request runs all of it, so the required checks always report. Superseded runs are cancelled. The critical path should stay around three to five minutes. After a merge, the same gate runs again on themainpush; amainpush starts neither the full Portable E2E nor release qualification. - Nightly and manual: full Portable E2E. The three-target installed E2E (install, managed and personal lifecycles, governance, update, rollback, uninstall) runs every night, through
workflow_dispatch, and inside Release qualification. It is no longer a pull request gate; a scheduled failure opens or updates a tracking issue, a follow-up rather than a block on ordinary pull requests.Reference E2Eruns on the same schedule and triggers on Ubuntu: the AcmeCode reference distribution against the enterprise reference stack (Keycloak, the credential broker, LiteLLM, and the reference container sandbox), with the Linux Secret Service; locally it isnpm run test:referenceand needs Docker. - Nightly and manual early warning: Pi latest canary. Outside the three tiers,
Pi latest canaryinstalls the newest published Pi over the pin in the runner's throwaway checkout and runs the compatibility suite on all three targets. It is read-only (it never changes the pin, commits, or publishes); a scheduled failure opens or updates a tracking issue ahead of the next Pi upgrade. - Release: one-click qualification. The
Release qualificationworkflow runs only throughworkflow_dispatch, on the exactmainHEAD being released. It runsCI, CodeQL, Portable E2E (excluding live Chrome startup), and Reference E2E in parallel, then, once all four pass, theRelease candidateworkflow for the managed demo, personal example, and developer example: two independent builds per target, reproducibility, provenance attestation and verification, tamper rejection, supply-chain gates, and installer verification on Linux, macOS, and Windows, plus the installed personal and developer releases' offline--smokeanddoctor. It does not run for ordinary pull requests ormainpushes. A release requires one green Release qualification run on the candidate HEAD;Release candidatecan still be dispatched alone for a faster artifact check, but that is not release evidence on its own.
Live Chrome startup remains required in nightly and standalone manual Portable E2E. Release qualification excludes that one browser startup test and the Chrome preflight; it retains the developer profile’s package registration, permissions, lifecycle, and release checks. A green qualification run does not establish live browser availability.
Windows jobs disable Defender real-time scanning on the ephemeral runner and keep temp output and the npm cache on the runner's work drive, which is much faster than C: for npm installs.
| Change | Start in |
|---|---|
| Manifest schema, runtime references, and migration | packages/schema |
| Shared contracts, policy decisions, audit events, errors, redaction, and network policy | packages/contracts |
| Policy engine, trust, project discovery, and capability state | packages/policy |
| Audit log, sinks, and local metrics | packages/audit |
| OS sandbox adapters and contained processes | packages/sandbox |
| Governed MCP client and transports | packages/mcp |
| OIDC and identity providers | packages/identity |
| Credential providers, secret stores, and lifecycle | packages/credentials |
| Inference binding and model catalog | packages/inference |
| Lock, payload, install, access orchestration, and configuration | packages/core |
| Public Pi API integration and branded commands | packages/pi |
| Command presentation | packages/cli |
| The supported surface for writing identity, credential, sandbox, and audit adapters | packages/adapter-sdk |
| Conformance kits that test an adapter through the SDK only | packages/adapter-conformance |
| A particular agent's branding or private integration | Its distribution repository |
Generic runtime behavior should be considered upstream in Pi first. identity, credentials, and inference may import only contracts, never each other; policy, audit, sandbox, and mcp are governance leaves composed by core and pi; npm run check:boundaries enforces these rules. Read AGENTS.md and the architecture guide before changing package boundaries or Pi integration. Small documentation and test changes do not require reading the full architecture first.
The CLI supports init [--personal | --managed], dev, validate, migrate [--write | --check], lock, build, test [--model-request], config explain, inspect, doctor, install, uninstall [--purge --yes], and explicit purge, plus the release commands release, verify-release, reproducibility, diff, keygen, sign-channel, update, rollback, repair, trust-root init|next, and migrate-check. init writes piship/v1; migrate --check is read-only and reports migratable (exit 0), requires review (exit 1), or cannot migrate (exit 3). v1alpha2 branded commands add login, logout, doctor, models, version, config explain|set|unset, --model, --smoke, and --smoke-model, plus sandbox login and sandbox logout for a distribution whose remote sandbox declares sandbox.credential: stored; every branded command also accepts --new-session; v1alpha3 adds policy explain and capabilities and the --yolo launch option; v1alpha4 adds update and rollback; a managed v1alpha5 distribution with policy.userAuto: allowed adds auto on|off|status. See the personal, developer, and demo company examples. Managed tests use the deterministic fixtures in examples/demo-company/fixtures/; they are not evidence of a live integration, so describe them that way in PRs.
Keep Pi dependencies exact-pinned and confined to packages/pi. Use public exports only. Update the pin, the sibling pins (the root package.json overrides, from PI_SIBLING_PINS in @piship/pi), compatibility metadata, lockfile, and affected tests together. Every temporary workaround needs a regression test. Follow the compatibility contract and the support policy.
Packages are at 0.13.0, private, and not published. Record every user-visible change in the newest section of CHANGELOG.md (Unreleased), and mark a behavior change as such. Changesets are optional until a publish policy exists; if you add one, use patch for a bug fix, minor for a new user-facing capability, or major for a breaking public API or schema change, and never run changeset version. piship/v1 and piship-lock/v1 are stable: an additive, backward-compatible change keeps them, and a breaking change needs a new major schema (support policy). The piship/v1alpha1 through piship/v1alpha6 schemas are experimental and stay accepted for the migration window; every example uses piship/v1. Every user-visible restriction needs its row in the UX contract. The changesets README records this decision.
Use a descriptive PR title: type(scope): concise summary, or type: concise summary when a scope adds nothing. Common types are feat, fix, perf, docs, test, refactor, ci, and chore. Name the part changed, such as schema, core, pi, or cli; do not force a scope onto every PR. For example, fix(pi): keep the compatibility check on public exports or docs: explain the alpha manifest status.
In the PR body, explain the problem, the change, and how you verified it. Give actual commands and results; for a performance claim, include the baseline, candidate, and measurement setup. A small docs fix needs only a short explanation and its relevant check. Include Pi version and compatibility impact when changing Pi integration, a manifest/schema, or a public API. Update docs when behavior changes. For suspected vulnerabilities, follow SECURITY.md instead of opening a public issue.