@benjaminthomas/spec-driven-dev 0.0.0-stage → 1.4.0

package/skills/spec-ship/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: spec-ship
+description: >
+  Push the current branch to GitHub and create a pull request. Use this skill when the user says
+  "ship it", "ship this", "push to github", "create a pr", "open a pull request", "send for review",
+  "get this reviewed", or wants to push their work and open a PR. Also use when the user says
+  "/spec-ship" (or their host's equivalent invocation syntax). This skill handles prerequisites,
+  branching, pushing, and PR creation — it does not commit or run quality checks (use
+  spec-checkpoint for that first).
+license: MIT
+---
+
+# Ship It
+
+Push your work to GitHub and open a pull request — handling prerequisites, branch creation, pushing, and PR generation automatically.
+
+This skill complements `spec-checkpoint`. Use `spec-checkpoint` to commit locally (with quality gates), then `spec-ship` to get the code to GitHub for review.
+
+## Project config (read first)
+
+Load `.spec-driven.yml`: walk up from the current directory to the home folder, and the first one
+found wins (a `multi-repo` config only applies inside the repos it lists). Its values beat anything
+you would detect or assume. This skill uses `git.remote`, `git.pr_target`, `git.branch_name`, `tracker` (to link the ticket in the PR), and `layout`/`repos`.
+
+**Multi-repo:** push and open one PR per repo that has unpushed commits, and list the sibling PRs in each PR's body so reviewers see the whole change.
+
+**No config?** If the `spec-setup` skill is available, run it first, then continue here. If it
+isn't, detect what this skill needs from the repo, ask about anything ambiguous, and offer to save
+the answers to `.spec-driven.yml` (keys: `layout`, `repos`, `tracker`, `git`, `commands`,
+`specs_dir`).
+
+## Instructions
+
+### Step 0: Prerequisites
+
+Verify tooling before doing anything else.
+
+1. **GitHub CLI installed?**
+   ```bash
+   gh --version
+   ```
+   If the command fails (not found):
+   - Detect the platform and attempt to install:
+     - **Windows:** `winget install --id GitHub.cli`
+     - **macOS:** `brew install gh`
+     - **Linux (Debian/Ubuntu):** follow the official apt instructions
+   - If auto-install fails, tell the user what to install and stop.
+
+2. **GitHub CLI authenticated?**
+   ```bash
+   gh auth status
+   ```
+   If not authenticated, tell the user:
+   ```
+   GitHub CLI is not logged in. Please run this in the prompt:
+     ! gh auth login
+   Then re-run /spec-ship.
+   ```
+   Stop here — do not proceed until auth is confirmed.
+
+3. **Git remote exists?**
+   ```bash
+   git remote -v
+   ```
+   If no remote named `origin` exists, stop and tell the user:
+   ```
+   No git remote found. Add one with:
+     git remote add origin https://github.com/{user}/{repo}.git
+   ```
+
+### Step 1: Detect the Environment
+
+Run these commands to understand the current state:
+
+1. `git branch --show-current` — get the current branch name
+2. Detect the default branch:
+   ```bash
+   gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
+   ```
+3. `git status --porcelain` — check for uncommitted changes
+
+If there are uncommitted changes, stop and tell the user:
+```
+You have uncommitted changes. Run /spec-checkpoint first to commit them, then /spec-ship to push.
+```
+
+Store the default branch name for use throughout the remaining steps. If `.spec-driven.yml` sets
+`git.pr_target` (anything other than `default`), use that as `{default_branch}` everywhere below,
+including as the PR's `--base`. Use `git.remote` instead of `origin` if it's set.
+
+### Step 2: Check for Unpushed Commits
+
+Determine if there are commits that haven't been pushed yet.
+
+**If on a feature branch with a remote tracking branch:**
+```bash
+git log @{upstream}..HEAD --oneline
+```
+
+**If on a feature branch with no remote tracking branch, or on the default branch:**
+```bash
+git log origin/{default_branch}..HEAD --oneline
+```
+
+If there are **no unpushed commits**, stop and tell the user:
+```
+Nothing to ship — all commits are already pushed.
+```
+
+Save the list of unpushed commit messages for use in later steps.
+
+### Step 3: Handle Branching
+
+**If already on a feature branch** (not the default branch):
+- Stay on it. No branching needed.
+- Skip to Step 4.
+
+**If on the default branch:**
+- If the config sets `git.branch_name`, fill in its placeholders (`{ticket}` from the commits or
+  investigation, `{slug}` and `{type}` as below) and skip the derivation that follows.
+- Otherwise, generate a branch name from the unpushed commit messages:
+  - Read the commit subjects
+  - Derive a kebab-case branch name with a conventional prefix: `feat/`, `fix/`, `refactor/`, `chore/`, `docs/` based on the commit content
+  - Keep it short (3-5 words max after the prefix), e.g., `feat/add-user-auth`, `fix/login-redirect-loop`
+  - Strip special characters, lowercase everything
+- Create and switch to the new branch:
+  ```bash
+  git checkout -b {branch_name}
+  ```
+- Tell the user: `Created branch {branch_name}`
+
+### Step 4: Confirm Before Pushing
+
+Pushing and opening a PR are visible to others and not easily undone — confirm with the user
+before proceeding, even if your host would otherwise run this skill non-interactively without
+prompting. Show:
+
+```
+About to push and open a PR:
+  Branch: {branch_name}
+  Remote: origin
+  Commits:
+    {list of unpushed commit subjects, from Step 2}
+
+Proceed? (yes/no)
+```
+
+Wait for an explicit yes. If the user declines or doesn't respond affirmatively, stop here —
+do not push.
+
+### Step 5: Push to Origin
+
+```bash
+git push -u origin {branch_name}
+```
+
+If the branch already has a remote tracking branch, a regular `git push` is fine.
+
+### Step 6: Check for Existing PR
+
+Before creating a new PR, check if one already exists for this branch:
+
+```bash
+gh pr view --json number,url,title,state 2>/dev/null
+```
+
+If a PR already exists and is **open**:
+- Do NOT create a new one
+- Skip to Step 8 and report the existing PR with a note that new commits were pushed.
+
+If no PR exists (or it is closed/merged), proceed to Step 7.
+
+### Step 7: Create the Pull Request
+
+Generate the PR title and body from the unpushed commits:
+
+- **Title**: concise summary under 70 chars. If single commit, use its subject. If multiple, synthesize a short summary. Imperative mood.
+- **Body**: TL;DR of the changes in 2-4 bullet points max, plus a footer naming whichever
+  agent/model actually generated the PR — never hardcode a specific vendor or model name, since
+  this skill runs under many different hosts. Omit the footer entirely if your host has no clean
+  way to identify itself.
+
+```bash
+gh pr create --base {default_branch} --head {branch_name} --title "{title}" --body "$(cat <<'EOF'
+## Summary
+{2-4 bullet points}
+
+---
+Generated by {agent name}
+EOF
+)"
+```
+
+### Step 8: Report
+
+Display the result clearly:
+
+```
+Shipped to GitHub:
+  Branch: {branch_name}
+  PR: #{number} — {title}
+  URL: {url}
+```
+
+## Important
+
+- Do NOT run lint, type-check, or build — that is spec-checkpoint's job
+- Do NOT commit anything — only push existing commits and create a PR
+- If the user has uncommitted changes, tell them to run /spec-checkpoint first
+- Keep the PR body short — a TL;DR, not an essay
+- Always check for an existing open PR before creating a new one to avoid duplicates
+- Detect the default branch dynamically — do not hardcode `main` or `master`
+- When creating a branch from the default branch, use conventional prefixes (`feat/`, `fix/`, etc.) with kebab-case names
+- Never run destructive git operations (no `--force`, no `reset --hard`)
+- If `gh` is not installed or authenticated, help the user get set up before proceeding
+- Always get explicit user confirmation before pushing or opening a PR (Step 4) — do this even
+  if your host would otherwise let the skill run non-interactively, since pushing and opening a
+  PR are visible to others and not easily undone

package/skills/spec-verify/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: spec-verify
+description: >
+  Verify a completed feature spec by driving the real running app — not just lint/typecheck/build
+  — and checking off every acceptance criterion from its specs/{feature}/ folder one by one. Use
+  this after /spec-implement finishes a spec, when the user says "test this end to end",
+  "verify this feature actually works", "did we actually build this right", or "/spec-verify",
+  and before /spec-ship or opening a PR. This is the spec-aware sibling of the generic /verify and
+  /run skills — /verify checks an arbitrary diff's runtime behavior and /run just launches the
+  app, but this skill specifically reads a spec's requirements.md and task files, builds a master
+  checklist of acceptance criteria, and reports pass/fail per criterion with real evidence
+  (screenshots, API responses, DB state) instead of a vague "looks good." Always invoke this when
+  a specs/{feature}/ folder exists and its implementation just finished, even if the user only
+  says "does this work" or "test it."
+license: MIT
+---
+
+# Verify Feature
+
+Close the loop that `spec-create` → `spec-implement` leaves open: passing lint, typecheck, and
+build proves the code compiles, not that the feature does what the spec says it does. This skill
+reads a spec's acceptance criteria and checks each one against the actual running application —
+clicking through the UI, calling the real API routes, or inspecting real database state produced
+by the real code path. It produces a report the user can trust before shipping.
+
+## Project config (read first)
+
+Load `.spec-driven.yml`: walk up from the current directory to the home folder, and the first one
+found wins (a `multi-repo` config only applies inside the repos it lists). Its values beat anything
+you would detect or assume. This skill uses `commands.dev`, `commands.dev_url`, and `layout`/`repos`.
+
+**Monorepo / multi-repo:** start every app or service the criteria need (e.g. the API and the frontend), each with its own `dev` command.
+
+**No config?** If the `spec-setup` skill is available, run it first, then continue here. If it
+isn't, detect what this skill needs from the repo, ask about anything ambiguous, and offer to save
+the answers to `.spec-driven.yml` (keys: `layout`, `repos`, `tracker`, `git`, `commands`,
+`specs_dir`).
+
+## When there's no spec folder
+
+If the user asks to verify a feature that wasn't built through `spec-create`, don't refuse —
+interview them briefly for what was built and what "working" means (the golden path, the edge
+cases they care about), then skip to [Step 3](#step-3-prepare-the-environment) treating their
+answers as the criteria list. The spec-driven path below is the common case, not the only one.
+
+## Step 1: Locate the spec
+
+1. If the user named a feature, use `specs/{feature}/`.
+2. Otherwise look for a `specs/*/README.md` whose Task Status section is fully checked (all
+   tasks `- [x]`) but has no `verification-report.md` sibling yet — that's the most recently
+   completed, not-yet-verified feature.
+3. If `spec-implement` hasn't finished all batches yet (some tasks still `- [ ]`), tell the user
+   and ask whether to verify what's done so far or wait for the rest — verifying half a feature
+   can produce confusing false failures for criteria that depend on an unbuilt task.
+
+## Step 2: Build the master criteria checklist
+
+Read `requirements.md`'s **Acceptance Criteria** section (feature-level, the whole thing working
+end-to-end) and every `tasks/task-*.md`'s own **Acceptance Criteria** section (task-level). Merge
+them into one ordered list, each item tagged with its source (`requirements` or the task
+filename).
+
+Split the merged list into two kinds, because they're verified completely differently:
+
+- **Static criteria** — things like "lint passes" or "the production build succeeds."
+  `spec-implement`'s review gate already ran these during the build. Re-run them once quickly
+  to confirm nothing regressed since (uncommitted fix-ups, a rebase, etc.), but don't treat this
+  as the interesting part of verification.
+- **Behavioral criteria** — anything that describes what a user, an API caller, or a scheduled
+  job actually observes ("a FREE user sees a Renew button," "the cron doesn't double-send,"
+  "removing a member revokes their access on next request"). These are why this skill exists —
+  they require driving the real app, not reading the diff.
+
+## Step 3: Prepare the environment
+
+Check whether the app is already running (`curl -sf {commands.dev_url}`, or the port the
+project's dev script uses) before starting a new one, since a stray second instance just causes
+confusing port conflicts. If nothing responds, start `commands.dev` from the config (or the
+project's own dev script) in the background and poll until it's ready.
+
+Look at what the behavioral criteria actually need before reaching for tools:
+
+- **UI-observable** (a button appears, a page shows a value, a flow completes) → browser
+  automation. Use whatever browser-automation capability your host provides — a browser MCP
+  server (Playwright, Puppeteer, etc.), a built-in browser tool, or a browser extension — and
+  enable/load it per your host's own convention if it isn't active by default. Take a screenshot
+  as evidence for each criterion you check this way.
+- **API-only** (no UI surface, e.g. a webhook or a cron route) → call the real route. For
+  session-gated routes, log in through the actual UI once (or reuse a session cookie from a
+  browser step) rather than fabricating auth state. For routes gated by a bearer secret (like a
+  cron's `CRON_SECRET`), call them directly with `curl`.
+  Note: if your browser tool can read console/network logs, that's useful when a criterion is
+  best confirmed by watching what the frontend actually sent/received rather than clicking
+  through screenshots.
+- **DB-state-only** (a column got stamped correctly, a row was scoped the way it should be) →
+  drive the real write path first (through the UI or API — never insert the expected state
+  directly, that verifies nothing), then read the resulting row back with the project's own DB client or CLI to
+  confirm it. This mirrors how you'd sanity-check a migration: trust the app's own code path to
+  produce the state, and only use direct DB reads for the *assertion*, never the *setup*.
+- **Timing-dependent** (a reminder email fires N days before expiry, idempotency across cron
+  runs) → don't wait real days. Insert or edit the relevant date field in the test data so it
+  already sits at the boundary the criterion describes, then invoke the real code path (call the
+  cron route, run the actual query) and observe what happens. You're still exercising the real
+  logic — you're just moving the clock via input data instead of a `sleep`.
+
+Create whatever throwaway test data (a second test user, a lapsed subscription row, etc.) each
+criterion needs. Note everything you create — you'll remove it in Step 5.
+
+## Step 4: Verify each criterion
+
+Work through the checklist in order. For each one, record:
+
+- **Verdict**: PASS, FAIL, or SKIPPED (with a reason — e.g. "requires a live payment gateway
+  webhook, not reproducible locally").
+- **Evidence**: a screenshot path, the exact `curl` command and response, or the DB query and
+  the row it returned. Evidence is what makes the report trustworthy instead of another
+  unverified claim — write down enough that someone who wasn't watching could confirm it.
+- **For a FAIL**: the concrete scenario that breaks it (exact input/state → actual vs expected
+  output), not just "doesn't work." This is what turns a failure into something fixable.
+
+Don't stop at the first failure — finish the checklist so the report reflects the feature's real
+state, not just the first thing that went wrong.
+
+## Step 5: Clean up
+
+Remove every test user, record, or row you created in Step 3/4 so the dev database is left the
+way you found it. Never delete data that predates this run — if you're not certain something is
+yours, leave it. If you started the dev server yourself in Step 3, it's fine to leave it running
+(the user likely wants it for their own follow-up testing) — just say so in the report.
+
+## Step 6: Report
+
+Write `specs/{feature}/verification-report.md` — see `references/report-template.md` for the
+exact structure (a summary line, then a table of criterion → source → verdict → evidence, then a
+"Failures" section with full repro detail for anything that didn't pass).
+
+Update `specs/{feature}/README.md` with a short **Verification** section linking to the report
+and stating the overall status (all pass / N of M pass).
+
+Then tell the user directly:
+
+```
+Verified {feature}: {X}/{Y} criteria passed.
+
+{If all pass:} Ready to ship.
+{If failures:} {N} failing — see specs/{feature}/verification-report.md for exact repro steps.
+Options: loop back to /spec-implement to fix, or fix manually.
+```
+
+This skill only verifies and reports — it does not fix failures itself. Mixing "test" and "fix"
+in one pass makes it too easy to quietly patch a failure without recording that it happened;
+keeping them separate means the report is always an honest snapshot of what was actually true
+when you ran it.

package/skills/spec-verify/references/report-template.md

@@ -0,0 +1,57 @@
+# Verification Report Template
+
+Use this structure for `specs/{feature}/verification-report.md`.
+
+## Template
+
+```markdown
+# Verification Report: {Feature Name}
+
+Verified: {date} · {X}/{Y} criteria passed
+
+## Summary
+
+{One or two sentences: overall status, and anything a reviewer should know before reading
+further — e.g. "All criteria pass; the Renew button was tested against all three checkout
+providers by swapping ACTIVE_PAYMENT_PROVIDER." or "2 failures, both in the reminder-email
+idempotency path — see Failures below."}
+
+## Environment
+
+- Dev server: {already running / started fresh, left running or stopped}
+- Test data created: {brief list — removed in cleanup unless noted otherwise}
+- Tools used: {browser automation / curl / psql/Prisma / combination}
+
+## Criteria
+
+| # | Criterion | Source | Verdict | Evidence |
+|---|-----------|--------|---------|----------|
+| 1 | {criterion text} | requirements.md | PASS | {screenshot path / curl command+response / query+result} |
+| 2 | {criterion text} | task-01-{name}.md | PASS | ... |
+| 3 | {criterion text} | task-02-{name}.md | FAIL | see Failures below |
+
+## Failures
+
+{Omit this section entirely if everything passed.}
+
+### {Criterion text}
+
+**Scenario:** {exact input/state that triggers it}
+**Expected:** {what the criterion says should happen}
+**Actual:** {what actually happened}
+**Evidence:** {screenshot, response body, query result}
+
+## Notes
+
+{Anything verified as SKIPPED and why (e.g. requires a live third-party webhook), or edge cases
+noticed but not in the original criteria list that are worth flagging back to the spec.}
+```
+
+## Key Points
+
+- The **Criteria** table is the core deliverable — it should let someone who wasn't in the room
+  trust that "PASS" actually means what it says, because the evidence column backs it up.
+- Keep evidence concise (a path, a one-line command + result) — this file is a report, not a
+  transcript. Full detail belongs in the Failures section, only for things that need it.
+- If a criterion is SKIPPED, say why in the Notes section rather than silently omitting it — a
+  missing row is indistinguishable from forgetting to check it.