From b7d806840a0a9cfbbeb422bc557b75a477221500 Mon Sep 17 00:00:00 2001 From: Avi Fenesh Date: Mon, 16 Mar 2026 15:01:12 +0200 Subject: [PATCH] docs: upgrade README with PR workflow phases, release discovery, and platform detection --- README.md | 105 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 93 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 8db1619..5f2143d 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,110 @@ # ship -Complete PR workflow from commit to production with validation, plus discovery-first release automation. +End-to-end PR workflow - commit, push, create PR, monitor CI, address every review comment, merge, deploy, validate - plus discovery-first release automation. + +## Why + +Shipping code involves a long tail of manual steps after the code is written: staging, committing, pushing, writing PR descriptions, waiting for CI, reading reviewer comments, pushing fixes, re-waiting, merging, cleaning up branches. ship handles all of it. It also enforces a discipline most developers skip: addressing every single review comment before merge. + +**Use cases:** +- Ship a feature branch to production with zero manual steps after invocation +- Let auto-reviewers (Copilot, Gemini, CodeRabbit) run and address all their feedback automatically +- Cut a versioned release without knowing how the repo's release tooling works +- Dry-run a ship or release to see what would happen ## Installation ```bash -# Claude Code -claude mcp add-plugin agent-sh/ship - -# Or install from marketplace agentsys install ship ``` -## Usage +Requires [agentsys](https://github.com/agent-sh/agentsys) runtime. + +## Quick Start ``` -/ship # Create PR, monitor CI, merge -/release # Patch release (auto-discovers release method) -/release minor # Minor version bump -/release major --dry-run # Preview what would happen +/ship # Full workflow: commit, PR, CI, review, merge +/ship --dry-run # Show what would happen without executing +/ship --strategy rebase # Use rebase merge instead of squash +/ship --base develop # Target a non-default branch + +/release # Patch release (auto-discovers release method) +/release minor # Minor version bump +/release major --dry-run # Preview major release +/release --skip-publish # Tag and changelog only, no registry publish +/release --yes # Skip confirmation prompt ``` -## Keywords +## How /ship Works + +| Phase | Description | +|-------|-------------| +| 1 | **Pre-flight** - detect CI platform, deploy platform, branch strategy, verify tools | +| 2 | **Commit** - stage changes (excluding secrets), generate semantic commit message | +| 3 | **Create PR** - push branch, open PR with summary and test plan | +| 4 | **CI & Review Loop** - wait for CI, wait 3 min for auto-reviewers, address all comments, iterate until zero unresolved threads (max 10 iterations) | +| 5 | **Internal Review** - 4 parallel review passes (standalone only; skipped when called from /next-task) | +| 6 | **Merge** - verify mergeable status, confirm zero unresolved threads, merge with chosen strategy | +| 7-10 | **Deploy & Validate** - platform-specific deployment, health checks, auto-rollback on failure | +| 11 | **Cleanup** - remove worktrees, close linked issues, delete branches | +| 12 | **Report** - final status summary | + +### The review loop is mandatory + +Phase 4 always runs - even when invoked from `/next-task`. After PR creation, ship waits 3 minutes for auto-reviewers to post, then enters a loop: + +1. Check CI status (fix failures via ci-fixer agent if needed) +2. Fetch all unresolved comment threads +3. Classify each comment (code fix, style suggestion, question, false positive) +4. Apply fixes or post replies +5. Push, wait 30 seconds, repeat + +The loop exits only when unresolved threads reach zero. + +### Platform detection + +ship auto-detects your project's CI and deployment setup: + +- **CI**: GitHub Actions, GitLab CI, CircleCI, Jenkins +- **Deploy**: Railway, Vercel, Netlify, or branch-based strategies +- **Branch strategy**: single-branch (main) or multi-branch (dev/prod) + +## How /release Works + +The release agent uses a discovery-first approach - it inspects your repo before executing anything. + +**Discovery order:** +1. Release tool configs (semantic-release, release-it, goreleaser, changesets, cargo-release, lerna, standard-version) +2. CI release workflows (tag-triggered publish jobs) +3. Release scripts (Makefile targets, npm scripts, shell scripts) +4. Package manifests for ecosystem detection + +**Supported ecosystems:** npm, Cargo, Python (pyproject.toml, setup.py), Go, Maven, Gradle, RubyGems, NuGet, Dart, Composer, Hex, Swift. + +**Constraints:** Tests must pass before tagging. Version bump is reverted if tests fail. Tags are never force-pushed. + +## Agents + +| Agent | Model | Role | +|-------|-------|------| +| release-agent | Sonnet | Discover release method and execute versioned releases | + +## Integration with /next-task + +When called from the next-task workflow (via `--state-file`), ship skips its internal review (Phase 5) and deslop/docs steps since next-task already ran those. Phase 4 (CI & review loop) still runs because external auto-reviewers comment after PR creation. + +## Requirements + +- [agentsys](https://github.com/agent-sh/agentsys) runtime +- GitHub CLI (`gh`) - required for PR operations +- Git 2.20+ +- Node.js 18+ + +## Related Plugins -`ci-cd`, `deployment`, `pr-workflow`, `automation`, `release`, `versioning`, `semver` +- [next-task](https://github.com/agent-sh/next-task) - full task-to-production orchestrator (calls ship as Phase 12) +- [deslop](https://github.com/agent-sh/deslop) - AI slop cleanup (used in standalone review) +- [sync-docs](https://github.com/agent-sh/sync-docs) - documentation sync (used in standalone mode) ## License