ship-task

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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-playwright` is in the available skills list.
- [ ] `semantic-commit` is 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:

- [ ] `gh` CLI is authenticated (`gh auth status` succeeds).
- [ ] `bun run setup:attach` has 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 dev` is 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:

```sh
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:

1. **Quote the acceptance criteria back** to the user verbatim (or paraphrase tightly if none are explicit).
2. **State the implementation plan** in 2–4 bullets — what files you'll touch and why.
3. **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 build` to 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:

```sh
rg -n "<symbol>" --type ts --type tsx
rg -n "from ['\"].*<file-stem>" --type ts --type tsx
```

For 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.

From aiatelie/ai-atelie, MIT.

More from aiatelie/ai-atelie