# Ship Loop

> ship-loop

- Skill: `kartikmehta8/ship-loop` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kartikmehta8/ship-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kartikmehta8/ship-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kartikmehta8 (https://skillmd.com/u/kartikmehta8)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kartikmehta8/ship-loop

---


# ship-loop

Two parts: (A) how to do the work, (B) how to talk about it.

## A. Workflow rules

### Context first, always

Before writing code, read `.claude/ship-loop/PROJECT.md` in the current project. It holds the plan document link, the project issues link, and standing instructions. If it doesn't exist, ask the user to create one from the plugin's `templates/PROJECT.md`. Fetch the plan doc and the ticket from Linear via MCP. Never implement from the ticket title alone.

### Implementation

- Implement exactly what the spec says. If the spec is ambiguous, ask ONE clarifying question instead of guessing.
- After implementing, strip unnecessary comments from touched files. Keep only comments explaining non-obvious "why". No "// increment counter" noise.
- Lint must pass. Full test suite must pass. The Stop hook (`verify.sh`) enforces this; do not try to end the turn with red tests.

### Git conventions (non-negotiable)

- Branch name: `<ticket-id>` (example: `team-142`)
- Commit messages: conventional style (`feat:`, `fix:`, `chore:`), imperative, concise.
- NEVER add `Co-Authored-By: Claude` or any AI attribution to commits.
- NEVER add "Generated with Claude Code", "Written by Claude", robot emojis, or any AI mention in commit messages, PR titles, or PR descriptions.

### PR conventions

- Title: conventional style, describes the change, not the ticket number. Example: `feat: add SBT mint flow for onchain verification`
- Description structure:

```
## Summary
2-4 sentences: what changed and why.

## Changes
- bullet per meaningful change (max 5)

## Testing
- what was run, what passed

Fixes TICKET-XXX
```

- `Fixes <TICKET-ID>` on its own line is mandatory: Linear picks up the magic word and links + auto-transitions the issue.
- Confirmation gate: show the diff summary + proposed title/description in chat and wait for explicit "yes" before `git push` or `gh pr create`. No exceptions, even if everything is green.

## B. Output style (reader has ADHD)

Rules:

1. Lead with the next action. First line = something the reader can do. Command, path, or snippet first; prose after.
2. Number multi-step tasks. One bounded action per step.
3. End with ONE concrete next action doable in under 2 minutes.
4. Suppress tangents. Finish the first issue, offer the second as a separate question.
5. Restate state every turn: "Step 3 of 5 done: X. Next: Y."
6. Specific time estimates. "About 15 minutes", never "some work".
7. Make wins visible and concrete: "Login works. Try: npm run dev, open /login."
8. Matter-of-fact errors. State cause and fix. Never "Uh oh."
9. Cap lists at 5 items. Split into "do now" vs "later" if longer.
10. No preamble ("Let me...", "Great question"), no recaps, no closers ("Hope this helps").

Break rules only for: explicit "explain/walk me through" requests, destructive actions (confirm first: force push, migrations, rm -rf), debug spirals (after 3 failed turns, question the assumption instead of iterating), or genuine ambiguity (one short clarifying question).

Pre-send check: delete any sentence announcing what you are about to do, any "by the way" sidebar, any closing pleasantry. First line + last line alone must tell the reader what just happened and what to do next.