# Workflow skills — grill-me → prd → prd-to-issues → ship-it A four-skill chain that takes a vague feature idea from "I want to build X" to merged, end-to-end-verified code. Two phases are collaborative (you + Claude), two run autonomously (AFK). ``` /grill-me TOGETHER pressure-test the idea ↓ /prd TOGETHER synthesize a PRD; gaps stay explicit ↓ /prd-to-issues MOSTLY thin vertical-slice issues; file when you say "create" ↓ /ship-it AFK shell loop ships every slice end-to-end ``` ## The TOGETHER vs AFK distinction | Mode | Meaning | Skills | |---|---|---| | **TOGETHER** | Needs your judgment every turn. No autonomous path. | `grill-me` | | **MOSTLY TOGETHER** | Drafts/audits AFK, but a visible-to-team action needs your "go". | `prd`, `prd-to-issues` | | **AFK** | No human in the loop. Logs questions to issues instead of asking. | `ship-it` | Each skill's `SKILL.md` declares its mode in the first body line. The chain is designed so the AFK phase only starts after the human-locked phases have nailed down the contract (PRD requirements, slice acceptance criteria) — AFK code only ships against decisions that already exist on paper. --- ## When to use each ### `/grill-me ` — TOGETHER **Use when:** you have a fuzzy idea and want it pressure-tested before committing to scope. Also useful for interview prep on any technical topic. **Behavior:** acts as a senior staff engineer running a brutal-but-fair interview. One hard question at a time, honest critique (no praise filler), drills into weak spots, demands specifics over buzzwords. Stay on the topic until exhausted; say `stop` for an honest 3-bullet debrief. **Don't use it for:** rubber-stamping a finished idea, or when you want validation. It's designed to find gaps, not to agree with you. ### `/prd` — TOGETHER (drafts AFK after grilling) **Use when:** the grilling exposed enough that you're ready to lock down what's being built. Or standalone when you already know the feature shape. **Behavior:** writes an engineering PRD (Problem, Goals, Non-goals, Users & scenarios, Functional + Non-functional requirements, Constraints, Success metrics, Open Questions, Out of scope). Things you nailed in the grilling become firm requirements. Things you hedged become Open Questions with the specific gap named — gaps don't get papered over. **Output:** inline by default. Say "save it" → writes to `docs/prd/.md`. **Don't use it for:** strategy docs, market sizing, or "why now" sections. This is for engineering. ### `/prd-to-issues` — MOSTLY TOGETHER **Use when:** you have a PRD (just-drafted or path-pointed) and need a backlog of issues a team can pick up. **Behavior:** breaks the PRD into **thin vertical slices** — each issue cuts end-to-end through every integration layer (schema → service → API → UI → tests; or sensor → broker → parser → store → dashboard). The first slice is a walking skeleton. Prerequisites get absorbed into the slice that needs them, not filed separately. Each issue has a visible `Slice check` block proving every layer is covered, plus a coverage matrix at the top of the draft showing PRD → issue mapping. Self-audit runs **before** drafting is shown to you. **Output:** draft inline → you reply `create` → it files to the tracker (`gh` for GitHub, `tea` for Gitea). **Don't use it for:** horizontal task lists ("DB work", "API work", "frontend work"). The skill rejects layer-cake slicing — if your work needs that, you want a different tool. ### `/ship-it` — AFK **Use when:** issues are filed, you want to walk away, you'll review the PRs later. **Behavior:** runs a shell loop that picks the next ready issue, dispatches a fresh headless Claude to ship it end-to-end (failing e2e test first → implement layer by layer → full suite → outermost-layer smoke check → commit `Closes #N` → PR with checked acceptance criteria + smoke evidence → CI gate → merge or leave-for-review), then moves on. One commit per issue. Status streams to the terminal; you can `tail -f` the log from another shell or Ctrl-C anytime. Undecidable issues get labeled `needs-decision` and skipped. Three consecutive failures stops the loop for human review. **Don't use it for:** issues whose acceptance criteria aren't testable (the loop will skip them), or for slices that need real-world side effects with no test harness. --- ## A worked example You want to add live sensor display for a new flow meter on a dashboard. ```bash # 1. Pressure-test the idea /grill-me adding live flow-meter readings to the operator dashboard # (you answer 6-8 hard questions; gaps surface) # 2. Lock down the contract /prd # (PRD drafts; you edit one section; save it) # 3. Slice it /prd-to-issues # (draft shows ~5 slices, each with a Slice check block. Coverage matrix # confirms every PRD requirement maps to a slice. Reply `create`.) # → issues #142..#146 filed # 4. Walk away /ship-it # (preflight, plan, "Start? Reply `go`." → `go` → shell loop runs) # In another terminal: tail -f .ship-it-logs/run-*.log ``` After the loop exits, the summary tells you what shipped, what's open for review, what hit `needs-decision`. --- ## Configuration ### Repo trunk branch `ship-it` defaults to `main`. If your repo uses something else: ```bash SHIP_IT_TRUNK=development bash .claude/skills/ship-it/loop.sh ``` ### Other env vars | Var | Default | Purpose | |---|---|---| | `SHIP_IT_MAX` | 50 | Iteration cap | | `SHIP_IT_MAX_FAIL` | 3 | Consecutive failures before stop | | `SHIP_IT_TIMEOUT` | 30m | Per-issue timeout | | `SHIP_IT_LOG_DIR` | `/.ship-it-logs` | Log directory | ### Tracker support - **GitHub** — uses `gh` CLI (must be installed and authenticated: `gh auth status`). - **Gitea** — uses `tea` CLI (must be installed: `go install code.gitea.io/tea@latest`, then `tea login add`). - Auto-detected from `git remote get-url origin`. ### Issue label expected by `ship-it` The loop filters to open issues with label `slice` and without labels `blocked`, `needs-decision`, or `ci-failed`. `/prd-to-issues` applies the `slice` label by default. If you file issues by hand, add the label or `ship-it` won't pick them up. --- ## File layout ``` .claude/skills/ ├── README.md ← this file ├── grill-me/ │ └── SKILL.md ├── prd/ │ └── SKILL.md ├── prd-to-issues/ │ └── SKILL.md └── ship-it/ ├── SKILL.md ← entry point; chat-side bootstrap ├── loop.sh ← orchestrator (the actual loop) └── iterate.md ← per-issue prompt the loop dispatches ``` --- ## Troubleshooting **`ship-it` won't start: "tea CLI not installed".** The repo's remote is Gitea but you don't have `tea`. Install it (`go install code.gitea.io/tea@latest && tea login add`) or push to a GitHub mirror. **`ship-it` exits immediately: "git tree is dirty".** Commit or stash everything before running. The loop won't risk mixing your work-in-progress into a slice. **`ship-it` says "backlog empty" but I have open issues.** The filter requires label `slice` AND no `blocked`/`needs-decision`/`ci-failed`. Add the label, or check what's blocking. **An issue keeps getting `needs-decision`.** Its acceptance criteria probably aren't testable at the outermost layer. Open the issue, rewrite criteria so they're observable (e.g. "POST /x returns 201 and row appears on dashboard" not "feature works"), remove the label, the loop will pick it up next run. **Three failures in a row, loop stopped.** Something systemic — bad dependency, branch protection blocking, flaky test env. Check `.ship-it-logs/iter-*.log` for the per-issue detail. **Issue had a PR opened but didn't merge.** Branch protection requires human review. The loop reports it as "shipped → open for review" and moves on. Review and merge when you can. --- ## Design principles - **Vertical slices, always.** No "implement the backend first, then the frontend". Every issue exercises every layer. - **Gaps are explicit, never hidden.** Hedged answers in grilling → Open Questions in PRD → `needs-decision` issues, not silent assumptions. - **AFK only after the contract is locked.** Autonomous code only ships against decisions that already exist on paper. - **One commit per slice.** Small, reviewable, revertible. - **Outermost-layer verification.** "Tests pass" isn't enough — the loop confirms the user-observable behavior actually works before reporting shipped.