ship-cli

Rules

1. NEVER run via bash: jj, gh pr, git, ship, pnpm ship - use the ship tool instead
2. ALWAYS use workdir parameter for all commands when in a workspace
3. NEVER ask user to cd - use workdir instead
4. 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:

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

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.

Pull Requests

Use these for advanced PR workflows. Note: stack-submit handles basic PR creation automatically.

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

Troubleshooting