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:
- Lead with the next action. First line = something the reader can do. Command, path, or snippet first; prose after.
- Number multi-step tasks. One bounded action per step.
- End with ONE concrete next action doable in under 2 minutes.
- Suppress tangents. Finish the first issue, offer the second as a separate question.
- Restate state every turn: "Step 3 of 5 done: X. Next: Y."
- Specific time estimates. "About 15 minutes", never "some work".
- Make wins visible and concrete: "Login works. Try: npm run dev, open /login."
- Matter-of-fact errors. State cause and fix. Never "Uh oh."
- Cap lists at 5 items. Split into "do now" vs "later" if longer.
- 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.
1---2name: ship-loop3description: ship-loop4---56# ship-loop78Two parts: (A) how to do the work, (B) how to talk about it.910## A. Workflow rules1112### Context first, always1314Before 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.1516### Implementation1718- Implement exactly what the spec says. If the spec is ambiguous, ask ONE clarifying question instead of guessing.19- After implementing, strip unnecessary comments from touched files. Keep only comments explaining non-obvious "why". No "// increment counter" noise.20- 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.2122### Git conventions (non-negotiable)2324- Branch name: `<ticket-id>` (example: `team-142`)25- Commit messages: conventional style (`feat:`, `fix:`, `chore:`), imperative, concise.26- NEVER add `Co-Authored-By: Claude` or any AI attribution to commits.27- NEVER add "Generated with Claude Code", "Written by Claude", robot emojis, or any AI mention in commit messages, PR titles, or PR descriptions.2829### PR conventions3031- Title: conventional style, describes the change, not the ticket number. Example: `feat: add SBT mint flow for onchain verification`32- Description structure:3334```35## Summary362-4 sentences: what changed and why.3738## Changes39- bullet per meaningful change (max 5)4041## Testing42- what was run, what passed4344Fixes TICKET-XXX45```4647- `Fixes <TICKET-ID>` on its own line is mandatory: Linear picks up the magic word and links + auto-transitions the issue.48- 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.4950## B. Output style (reader has ADHD)5152Rules:53541. Lead with the next action. First line = something the reader can do. Command, path, or snippet first; prose after.552. Number multi-step tasks. One bounded action per step.563. End with ONE concrete next action doable in under 2 minutes.574. Suppress tangents. Finish the first issue, offer the second as a separate question.585. Restate state every turn: "Step 3 of 5 done: X. Next: Y."596. Specific time estimates. "About 15 minutes", never "some work".607. Make wins visible and concrete: "Login works. Try: npm run dev, open /login."618. Matter-of-fact errors. State cause and fix. Never "Uh oh."629. Cap lists at 5 items. Split into "do now" vs "later" if longer.6310. No preamble ("Let me...", "Great question"), no recaps, no closers ("Hope this helps").6465Break 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).6667Pre-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.
kartikmehta8