RnD/EVOLV
3
0
Fork 0
Code Issues 22 Pull Requests Actions Packages Projects Releases Wiki Activity

chore(skills): add workflow chain — grill-me → prd → prd-to-issues → ship-it

Browse Source 
Four workflow skills that take a feature from fuzzy idea to merged code.
Two human-in-the-loop phases (grill-me, prd), one mostly-together (prd-to-issues
files only on explicit 'create'), and one AFK (ship-it).

  grill-me        TOGETHER  pressure-test the idea with hard interview questions
  prd             TOGETHER  synthesize PRD; gaps stay explicit, not papered over
  prd-to-issues   MOSTLY    thin vertical-slice issues with coverage matrix +
                            per-issue Slice check; self-audits before showing
  ship-it         AFK       shell loop ships each slice end-to-end with one
                            commit per issue, status streams to terminal,
                            Ctrl-C-able, survives session close

Vertical-slice principle throughout: every issue cuts end-to-end through every
integration layer (no horizontal "do all the DB work first" issues). The
AFK loop only ships against acceptance criteria already locked in by the PRD
phase — autonomous code never runs against undefined contracts.

ship-it tracker support: gh (GitHub) and tea (Gitea). For this repo, set
SHIP_IT_TRUNK=development to override the main default.

See .claude/skills/README.md for the full how-to and a worked example.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
znetsixe
2026-05-21 16:27:15 +02:00
parent 025bdb4c7e
commit 6ff262e96e
7 changed files with 825 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

180
.claude/skills/README.md Normal file
View File

@@ -0,0 +1,180 @@
# 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 <topic> 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 <topic>` — 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/<name>.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` | `<repo>/.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.