@aduverger/pi-ship

Workspace-aware shipping workflow for the Pi coding agent: rebase, simplify, independently review, test, push, and open cross-linked draft GitHub pull requests.

Requirements

• Pi 0.84 or newer
• Git
• GitHub CLI (gh), authenticated for github.com
• Clean, committed feature branches in repositories included in simplify/review
• Clean default branches synchronized with origin in workspace context/config repositories

Install

From npm:

pi install npm:@aduverger/pi-ship

From a checkout:

git clone https://github.com/aduverger/pi-ship.git
cd pi-ship
npm install
npm run build
pi install .

For a one-off development run:

pi -e ./dist/index.js

Usage

Inside a Git repository, /ship targets only that repository:

/ship

From a workspace directory that is not itself a Git repository, /ship discovers direct child Git roots:

/ship
/ship emidat-api emidat-frontend

Operational commands:

/ship status
/ship resume
/ship abort

/ship is the publication consent boundary. The workflow asks for user input only when independent-review findings require a decision or when conflict resolution requires semantic guidance. Once the approved final changes pass review, it pushes branches and creates or updates PRs without another confirmation.

Workflow

1. Validate that every selected repository is clean and committed.
2. Fetch each origin and resolve its default branch independently of the configured upstream.
3. Keep a default-branch repository only when its HEAD exactly matches the fetched remote, classifying it as workspace context/config; rebase changed feature branches.
4. Simplify the listed changed-feature files, using Git line ranges as guidance rather than hard edit boundaries, then test and commit per repository.
5. Launch one fresh, read-only Pi reviewer over the complete selected workspace. It inherits the active model, always uses high thinking, can page through complete Git diffs, and focuses on concrete, proportionate correctness and maintainability findings.
6. Persist a visible repository-qualified findings summary in the active session branch and return the full review to the main agent for analysis and a user decision. Later review rounds receive every prior user decision and rationale so fixes are verified against updated guidance and accepted or deferred tradeoffs are not reported repeatedly.
7. Apply approved fixes, test, commit each repository with a message describing its actual changes, and independently review the complete workspace again.
8. Verify that every pushed SHA exactly matches the reviewed SHA and that default branches have not advanced.
9. Push all changed branches, create or update one draft PR per changed repository, and cross-link related PRs.

Independent-review results stay in Pi and are not added as a dedicated PR section.

Unchanged feature-branch repositories remain available to the reviewer as integration context and do not produce commits or PRs unless an approved review fix changes them. Default-branch context/config repositories remain available in the workspace but are excluded from simplification and independent review, and must stay unmodified throughout the run.

The changed-line simplification prompt is adapted from MattDevy/pi-simplify. See NOTICE.md.

Safety properties

• No dirty repository enters the workflow; default-branch repositories must exactly match their fetched remote and remain immutable workspace context.
• Reviewer subprocess has no bash, edit, or write tools.
• Rebased existing branches use --force-with-lease against the observed remote SHA.
• A moved default branch restarts rebase, simplification, and review before publication.
• Partial push/PR failures are resumable with /ship resume.
• New PRs are created as drafts; existing PRs preserve their current ready or draft state.
• /ship abort aborts active rebases but preserves already completed rebases and commits.

Development

make check
make pack-check

Release a stable version from a clean, synchronized main branch:

make release VERSION=0.1.1

For a prerelease, use a non-latest npm tag:

make release VERSION=0.2.0-rc.1 NPM_TAG=next

The release target validates Git and npm state, updates package versions, runs all quality gates, publishes the public package, verifies the registry, and pushes the matching Git tag.

.github/workflows/publish.yml also supports npm trusted publishing with provenance. Configure the npm trusted publisher for repository aduverger/pi-ship, workflow publish.yml, and GitHub environment npm; dispatch with dry_run: true to verify release gates before publishing.