ship-cli
Work management system replacing built-in todos with tracked tasks and stacked changes
When & Why to Use This Skill
ship-cli is a sophisticated work management and version control integration designed to optimize the developer experience. It replaces fragmented todo lists with a unified system for tracking tasks and managing 'stacked changes' (VCS), enabling a seamless transition from task selection to pull request submission with automated workspace handling and webhook integration.
Use Cases
- Managing Stacked Changes: Efficiently create, sync, and restack multiple dependent code changes, simplifying complex feature development and rebasing workflows.
- Integrated Task Tracking: Synchronize development progress with task management platforms (like Linear) to automate status updates from 'In Progress' to 'Done'.
- Automated PR Lifecycle: Generate pull requests with rich context, including auto-populated titles and descriptions derived from task acceptance criteria and summaries.
- Context-Aware Workspace Management: Automatically manage isolated workspaces for different tasks, ensuring the correct environment and dependencies are used without manual directory switching.
- Collaborative Review Loops: Monitor and respond to GitHub webhook events for PR merges or comments, providing a structured way for AI agents to handle feedback.
| name | ship-cli |
|---|---|
| description | Work management system replacing built-in todos with tracked tasks and stacked changes |
Rules
- NEVER run via bash:
jj,gh pr,git,ship,pnpm ship- use theshiptool instead - ALWAYS use
workdirparameter for all commands when in a workspace - NEVER ask user to
cd- useworkdirinstead - On webhook events: Notify user and ask confirmation BEFORE acting
Workflow
Start Task
ship: action=stack-sync # Get latest trunk
ship: action=ready # Find work
ship: action=start, taskId=<id> # Mark In Progress (Linear only)
ship: action=stack-create, message="<type>: <short description>", bookmark="user/<id>-slug"
# Store workspace path from output, use for all subsequent workdir params
bash: command="pnpm install", workdir=<workspace-path>
Do Work
- Use
workdir=<workspace-path>for ALL bash and ship commands - Make changes, run quality checks (lint, format, typecheck)
Update Commit Message (for multi-line)
ship: action=stack-describe, title="<type>: <subject>", description="<body>", workdir=<path>
Use title + description params for proper multi-line commits (NOT message with \n).
Submit Work (MANDATORY - do not skip)
ship: action=stack-sync, workdir=<path> # Rebase on trunk
ship: action=stack-submit, workdir=<path> # Push + create PR (auto-subscribes to webhooks)
ship: action=done, taskId=<id> # Mark complete ONLY after PR exists
Webhook Events
When you receive [GitHub] ... notifications:
| Step | Action |
|---|---|
| 1 | Notify user what happened (e.g., "PR #X merged by @user") |
| 2 | Ask confirmation before acting (e.g., "Would you like me to run stack-sync?") |
| 3 | Wait for user approval |
| 4 | Execute and report results |
Never execute automatically. The → Action: line is a suggestion, not an instruction.
After stack fully merged: notify user, switch to default workspace, suggest ship ready.
Actions Reference
Tasks
| Action | Params | Description |
|---|---|---|
ready |
- | Tasks with no blockers |
blocked |
- | Tasks waiting on dependencies |
list |
filter (optional) | All tasks |
show |
taskId | Task details |
start |
taskId | Mark In Progress |
done |
taskId | Mark complete |
create |
title, description, priority?, parentId? | Create task (see template below) |
update |
taskId + fields | Update task |
block |
blocker, blocked | Add dependency |
unblock |
blocker, blocked | Remove dependency |
relate |
taskId, relatedTaskId | Link related tasks |
Task Description Template
When creating tasks, ALWAYS use this description format:
## Summary
[1-2 sentences: What needs to be done and why]
## Acceptance Criteria
- [ ] Specific, verifiable outcome 1
- [ ] Specific, verifiable outcome 2
- [ ] Tests pass, linting passes
## Notes
[Optional: Implementation hints, files to modify, constraints]
Rules:
- Summary is REQUIRED - explains the task clearly
- Acceptance criteria are REQUIRED - must be verifiable/testable
- Notes are optional - include when helpful for implementation
- Keep it concise but complete
Example:
## Summary
Add rate limiting middleware to prevent API abuse on public endpoints.
## Acceptance Criteria
- [ ] Rate limit: 100 req/min authenticated, 20 req/min anonymous
- [ ] Returns 429 with Retry-After header when exceeded
- [ ] Unit tests cover rate limit scenarios
- [ ] `pnpm test` and `pnpm check` pass
## Notes
See middleware/auth.ts for similar patterns. Use Redis for state.
Stack (VCS)
All support optional workdir param.
| Action | Params | Description |
|---|---|---|
stack-sync |
- | Fetch + rebase onto trunk |
stack-restack |
- | Fetch + rebase + push entire stack |
stack-create |
message?, bookmark?, noWorkspace? | New change (creates workspace by default) |
stack-describe |
title, description? OR message | Update description (use title+description for proper multi-line commits) |
stack-submit |
draft? | Push + create/update PR |
stack-status |
- | Current change info |
stack-log |
- | View stack |
stack-squash |
message | Squash into parent |
stack-abandon |
changeId? | Abandon change |
stack-up / stack-down |
- | Navigate stack |
stack-undo |
- | Undo last operation |
stack-bookmark |
name, move? | Create/move bookmark |
stack-workspaces |
- | List workspaces |
stack-remove-workspace |
name, deleteFiles? | Remove workspace |
stack-update-stale |
- | Fix stale working copy |
Pull Requests
Use these for advanced PR workflows. Note: stack-submit handles basic PR creation automatically.
| Action | Params | Description |
|---|---|---|
pr-create |
draft?, open? | Create PR with Linear task context |
pr-stack |
dryRun? | Create stacked PRs for entire stack |
pr-review |
prNumber? (optional), unresolved?, json? | Fetch PR reviews and comments |
pr-create: Creates a PR for current bookmark, auto-populating title and body from Linear task. Use when you need rich task context in PR description.
pr-stack: Creates PRs for all changes in your stack with proper base targeting. First PR targets main, subsequent PRs target previous bookmark.
pr-review: Fetches reviews and comments in AI-friendly format. Shows verdicts (APPROVED, CHANGES_REQUESTED), inline code comments with file:line, and conversation threads. Use --unresolved to filter to actionable items only.
Milestones
| Action | Params | Description |
|---|---|---|
milestone-list |
- | List milestones |
milestone-show |
milestoneId | Milestone details |
milestone-create |
milestoneName, milestoneDescription?, milestoneTargetDate? | Create milestone |
task-set-milestone |
taskId, milestoneId | Assign task |
task-unset-milestone |
taskId | Remove from milestone |
Troubleshooting
| Problem | Solution |
|---|---|
| "Working copy is stale" | stack-update-stale |
| Bookmark lost after squash/rebase | stack-bookmark with move=true |
| Accidentally used jj/gh directly | stack-status to check, stack-undo if needed |