ship-task
Skill9 starsChanged 6 months agoMITView on GitHub
Take an AI Atelie task — issue, ticket, or ad-hoc ask — all the way from description to merged-ready PR. Use whenever the user says "implement X and ship it", "work on issue #N", "ship this task", or any phrasing that implies the full implement → verify → commit → PR loop, not just a code change. Coordinates the verify-with-playwright and semantic-commit skills, runs a blast-radius regression check, and opens a PR with browser evidence attached.
- Commits and pushes
1 other project uses a version of this.
Adopted by
Most recently taken up by
- Koushik890/ship-tasktheir own version, first seen Oct 13, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- Koushik890/ship-task★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- canvas-syncSkill
- cuj-guardianSkill
- frontend-designSkill
- grill-meSkill
- pr-evidenceSkill
- semantic-commitSkill
- verify-with-playwrightSkill
- animated-videoSkill
- create-design-systemSkill
- design-aesthetic-presetsSkill
- design-critiqueSkill
- design-md-authorSkill
- exportSkill
- frontend-designSkill
- handoff-to-claude-codeSkill
- interactive-prototypeSkill
- make-tweakableSkill
- save-as-standalone-htmlSkill
- send-to-canvaSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 4 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 31
If either is missing, STOP and tell the user: "ship-task needs both verify-with-playwright and semantic-commit loaded.
- Distinctive: line 65
Pause for confirmation: if the criteria are ambiguous.
- Very specific: line 84
Wait for its VERIFY-RESULT: pass block.
- Very specific: line 86
If verify-with-playwright is genuinely inapplicable (e.g.
- Distinctive: line 135
If the work spans multiple logical changes, split into multiple commits — one per change.
- Distinctive: line 155
If the video is a long Playwright recording (typical: 5+ min webm), compress it first so the upload is fast and the inline player loads …
- Very specific: line 212
After creation, output the PR URL.
- Very specific: line 235
When to write a --task spec:
- Very specific: line 240
If bun run journeys reports a failure, walk the cuj-guardian triage protocol before touching either the spec or the feature.
- Distinctive: line 242
Don't ship until the suite is green or the failure is documented.
- Very specific: line 246
"Verified by inspection.": Not allowed. INSTEAD: run verify-with-playwright against the change, or — if the surface genuinely has no UI …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
ship-task
A contributor workflow for AI Atelie. Orchestrates the full end-to-end loop a maintainer follows when shipping a task: understand → implement → verify in browser → blast-radius check → commit with semantic message → open PR with evidence.
This skill is dev-time only. It does not load into adapter sessions spawned by the editor.
When to invoke
- "Ship task / issue #N" — explicit ship request.
- "Implement and PR this" — when a code change must result in a PR, not just a diff.
- "Work on issue #N" when the user expects a finished, reviewable PR rather than a discussion.
Skip when:
- The user is exploring or debugging without a clear acceptance bar.
- The change is a one-line tweak the user wants reviewed verbally before committing.
- The user explicitly says "just edit, don't commit".
Hard preconditions (STOP if unmet)
This skill delegates to two other skills. Skills cannot programmatically invoke each other — Claude must coordinate. Before starting, verify both are loaded:
verify-with-playwrightis in the available skills list.semantic-commitis in the available skills list.
If either is missing, STOP and tell the user: "ship-task needs both verify-with-playwright and semantic-commit loaded. They live at .claude/skills/. Confirm they're present and retry."
Also verify:
ghCLI is authenticated (gh auth statussucceeds).bun run setup:attachhas been run on this machine at least once (Chromium profile at~/.local/state/aiatelie/chromium-profile/exists). Refresh every few weeks. No plaintext cookies/tokens are written anywhere — session data lives in Chromium's own binary store.- You're on a branch that isn't
main(or the user has explicitly OK'd shipping straight to main, which is unusual). bun run devis running on:5173(the verify step needs it).
The loop (paste this checklist into your reply and tick as you go)
- Step 1 — Understand the task (re-read issue, read related code, state acceptance criteria back).
- Step 2 — Implement (minimum change satisfying acceptance criteria; no drive-by refactors).
- Step 3 — Verify in browser (delegate to
verify-with-playwright). - Step 4 — Blast-radius regression check (write a named report, not a vibes summary).
- Step 5 — Commit with semantic message (delegate to
semantic-commit). - Step 6 — Open PR with evidence attached.
Step 1 — Understand the task
For an issue:
gh api repos/aiatelie/ai-atelie/issues/<N> --jq '.title, .body'(Note: gh issue view currently fails on this repo due to the deprecated Projects-classic API; use gh api until cli/cli ships the migration.)
For an ad-hoc ask: the user's message IS the task description.
Then:
- Quote the acceptance criteria back to the user verbatim (or paraphrase tightly if none are explicit).
- State the implementation plan in 2–4 bullets — what files you'll touch and why.
- Pause for confirmation if the criteria are ambiguous. A 30-second clarification beats an hour of wrong direction.
Step 2 — Implement
Rules:
- Minimum change that satisfies the acceptance criteria. No drive-by cleanup, no premature abstractions.
- One logical change per commit is the goal even if you split into several commits later.
- No new dependencies unless the issue justifies it.
- Type-check as you go:
cd web && bun run buildto surface TS errors before the verify step.
Step 3 — Verify (delegate)
Invoke verify-with-playwright with:
- The acceptance criteria from Step 1.
- The route or surface that exercises the change.
- A name for the spec (use the issue slug or a noun for ad-hoc tasks).
Wait for its VERIFY-RESULT: pass block. If it returns fail, go back to Step 2 — don't paper over a failed verify with a "skip the test" commit.
If verify-with-playwright is genuinely inapplicable (e.g. an api/ change with no UI surface), say so explicitly in the PR body's test plan — don't fake a verify step.
Step 4 — Blast-radius regression check
This step is the one that earns this skill's name. "Verify no regressions" without forced artifacts is the #1 handwaving trap.
Produce a Blast Radius Report in this exact format:
## Blast Radius Report
### Symbols I changed
- `<symbol>` in `<file>:<line>` — purpose: ...
- `<symbol>` in `<file>:<line>` — purpose: ...
### Importers / call sites
- `<file>:<line>` calls `<symbol>` — affected? <yes/no/uncertain> — why?
- `<file>:<line>` imports `<file>` — affected? <yes/no/uncertain> — why?
### Shared user flows that touch this code path
- Flow A: <name>. Affected? <yes/no>. Justification or re-test result.
- Flow B: <name>. Affected? <yes/no>. Justification or re-test result.
- Flow C: <name>. Affected? <yes/no>. Justification or re-test result.
### Verdict
- <No regression risk found> | <Risk found, mitigated by ...> | <Risk found, NOT mitigated, flagging in PR>To produce the importers list, use grep / ripgrep:
rg -n "<symbol>" --type ts --type tsx
rg -n "from ['\"].*<file-stem>" --type ts --type tsxFor each "uncertain" entry, you must either prove non-affectation or re-run verify-with-playwright against that flow. No vibes-based dismissals.
For changes touching shared modules (anything imported by ≥3 files), the "shared user flows" section must list at least 3 distinct flows.
Step 5 — Commit (delegate)
Invoke semantic-commit with:
- The diff (
git diff --stagedor stage it first). - A one-line summary of what the change does and why.
- The issue number(s) for
Closes/Refsfooters.
Let it draft the message; show it to the user; on confirm, create the commit.
If the work spans multiple logical changes, split into multiple commits — one per change. Never amend a prior commit on this branch unless the user explicitly asks.
Step 6 — Open PR
Pre-PR checklist:
- Branch is up to date with
main(git fetch origin && git rebase origin/mainif needed). - All commits follow Conventional Commits.
- Evidence is bundled in
.evidence/<run>/. - Blast Radius Report is ready to paste into the PR body.
Upload evidence to GitHub's user-attachments CDN with the in-repo helper. Returns a JSON array of {file, url} you can plug into the PR body. Videos play inline if you embed the bare URL on its own line; images go in <img alt="..." src="..." /> tags.
bun run upload:evidence aiatelie/ai-atelie/pull/<N> \
.evidence/<run>/before.png \
.evidence/<run>/after.png \
.evidence/<run>/video.mp4If the video is a long Playwright recording (typical: 5+ min webm), compress it first so the upload is fast and the inline player loads reasonably:
ffmpeg -i .evidence/<run>/video.webm \
-filter:v "setpts=0.125*PTS,scale=1024:-2" \
-an -c:v libx264 -preset fast -crf 28 -movflags +faststart \
-y .evidence/<run>/video.mp4That's 8× speed + 1024px width + reasonable compression — typical 19MB/5min input → ~1.5MB/30sec output.
Then create the PR with this body template:
## Summary
<1-3 sentence summary>
Closes #<issue-number>
## Acceptance criteria
- [x] <criterion 1>
- [x] <criterion 2>
## Test plan
- [x] `bunx playwright test web/tests/e2e/<slug>.spec.ts` passes
- [x] Manual: <any extra manual checks>
## Evidence
**Before:** <BEFORE_MD>
**After:** <AFTER_MD>
### Run video
<VIDEO_MD>
## Blast Radius
<paste the report from Step 4>
## Notes
<anything reviewers should know — gotchas, follow-ups deferred, etc.>Open with:
gh pr create --title "<conventional-commit header>" --body "$(cat <<'EOF'
... <body above> ...
EOF
)"After creation, output the PR URL. Then prune .evidence/ to the last 5 runs.
Step 7 — Attach evidence to the PR body
Delegate to .claude/skills/pr-evidence/SKILL.md — that skill
owns the contract for the canonical evidence flow (8 baseline
journeys + optional --task <spec> for per-PR feature demos),
including the verification step that confirms the body update
landed.
The short version:
# Canonical: full suite + body update on the current PR
bun run journeys
# With a per-PR feature demo (write a small Playwright spec, then:)
bun run journeys -- \
--task path/to/feature-demo.spec.ts \
--task-title "Feature title" \
--task-description "What this PR proves visually."When to write a --task spec:
- This PR ships a user-visible feature (theme, UI flow, new affordance).
- Skip if the PR is purely API/server/config; baseline alone is enough.
If bun run journeys reports a failure, walk the cuj-guardian
triage protocol before touching either the spec or the feature.
Don't ship until the suite is green or the failure is documented.
Anti-patterns
- "Verified by inspection." Not allowed. INSTEAD: run
verify-with-playwrightagainst the change, or — if the surface genuinely has no UI (api-only, mcp-only, config) — state that explicitly in the PR body's test plan with a one-line reason. - Skipping Step 4. The Blast Radius Report is the most valuable artifact this skill produces; without it, you're a slightly-better-than-nothing autocommitter. INSTEAD: produce the report even when no risk is found — the act of writing it forces the inspection, and "No regression risk found" with the importer list attached is itself the evidence.
- Amending commits to "fix" something. History-tells-the-story is load-bearing for the changelog. INSTEAD: create a new commit. If the prior commit was wrong, write a
revertcommit. If the prior commit needs a follow-up, write afixcommit that references it in the body. --no-verifyon commits. Bypassing hooks hides the failure, not the cause. INSTEAD: read the hook's error, fix the underlying issue, re-stage, commit again. If the hook itself is broken, fix the hook in its own commit before continuing.- Force-pushing to anything that isn't your own branch. INSTEAD: push normally to your branch; if
mainor a shared branch needs to change, open a PR. If your own branch needs history rewrite (e.g. squash before merge), confirm with the maintainer first.
When the loop should bail out
- Step 1 ambiguity the user can't resolve: bail. A wrong implementation is worse than a delayed one.
- Step 3 fail you can't fix in 2 attempts: bail, write up what failed, ask the user to look.
- Step 4 finds a real regression risk you can't mitigate: bail, document the risk in the PR as draft, flag for review.
- Step 6 PR creation fails for credentials: bail, ask user to
gh auth login, do not retry blindly.
See also
.claude/skills/verify-with-playwright/SKILL.md— the verify delegate..claude/skills/semantic-commit/SKILL.md— the commit delegate..claude/skills/pr-evidence/SKILL.md— Step 7 delegate (journey suite + body update).CONTRIBUTING.md— repo-wide commit/release/skill conventions.playwright.config.ts— e2e config the verify step uses.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

