Store workspace path from output, use for all subsequent workdir params Skill

Rules

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

Agent Skills: Store workspace path from output, use for all subsequent workdir params

Install this agent skill to your local

Skill Files