@oaklandzoo/ostup 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oaklandzoo/ostup",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Scaffolds a new repo with the Ostup Agent Kit pre-installed: slash commands, doc templates, and a clean working state.",
   "type": "module",
   "bin": {

package/src/templates.mjs

@@ -28,6 +28,9 @@ export const REGISTRY = [
   { src: '.claude/commands/add-storage.md',   dest: '.claude/commands/add-storage.md' },
   { src: '.claude/commands/generate-image-prompt.md', dest: '.claude/commands/generate-image-prompt.md' },
   { src: '.claude/commands/generate-image.md', dest: '.claude/commands/generate-image.md' },
+  { src: '.claude/commands/resume.md',         dest: '.claude/commands/resume.md' },
+  { src: '.claude/commands/handoff-doctor.md', dest: '.claude/commands/handoff-doctor.md' },
+  { src: '.claude/commands/break-into-stories.md', dest: '.claude/commands/break-into-stories.md' },
   { src: 'CLAUDE.md',                          dest: 'CLAUDE.md' },
   { src: 'AGENTS.md',                          dest: 'AGENTS.md' },
   { src: 'START_HERE.md',                      dest: 'START_HERE.md' },
@@ -39,6 +42,7 @@ export const REGISTRY = [
   { src: 'tasks/.gitkeep',                     dest: 'tasks/.gitkeep' },
   { src: 'inputs/README.md',                   dest: 'inputs/README.md' },
   { src: 'scripts/screenshot.sh',              dest: 'scripts/screenshot.sh', executable: true },
+  { src: 'scripts/verify.sh',                  dest: 'scripts/verify.sh', executable: true },
 ];
 
 export const OPTIONAL_REGISTRY = [

package/templates/.claude/commands/break-into-stories.md

@@ -0,0 +1,101 @@
+---
+description: Break a PRD into vertical stories (each story is independently shippable) before generating granular tasks. Sits between /create-prd and /generate-tasks. Borrowed pattern from BMAD; kept light.
+---
+
+# /break-into-stories
+
+A PRD is a description. Tasks are atoms. **Stories are the missing middle layer.** A story is a small vertical slice that can be shipped on its own and feels meaningful to the operator on a deployed URL.
+
+Use this command after `/create-prd` and before `/generate-tasks`. It produces `tasks/stories-<feature>.md` with 3-7 stories.
+
+## Step 1: locate the PRD
+
+```bash
+ls tasks/prd-*.md
+```
+
+If the operator named a feature (e.g. `/break-into-stories user-auth`), use `tasks/prd-user-auth.md`.
+
+If no name: ask the operator which PRD.
+
+## Step 2: read the PRD + the brief
+
+```bash
+cat tasks/prd-<feature>.md
+[ -f docs/brief.md ] && head -80 docs/brief.md
+```
+
+## Step 3: derive stories
+
+For each story, fill this shape:
+
+```markdown
+## Story <N>: <one-line goal>
+
+**Why this is a story:** <one sentence on why this is a meaningful vertical slice>
+
+**User journey:** <2-3 sentences describing what the operator or end user does>
+
+**Acceptance:**
+- <observable behavior 1>
+- <observable behavior 2>
+
+**Deployable check:** <one sentence on what you can show on the live URL after this story ships>
+
+**Out of scope for this story:** <bullets of things explicitly NOT in this story; they belong to other stories>
+```
+
+### Rules for cutting stories
+
+1. **Vertical, not horizontal.** A story crosses UI + API + data if needed. It does NOT say "build the API for X" as a story; that is a task.
+2. **Shippable.** Each story can be merged + deployed and produces an observable change on the live URL.
+3. **Small.** 30 minutes to 2 hours of agent work each. If a story feels bigger, split it.
+4. **Independent where possible.** Story 2 should not require Story 1's completion unless there is a hard dependency (then state it).
+5. **Acceptance is observable.** "Visitor can click X and see Y" not "The reducer handles X."
+6. **3 to 7 stories per PRD.** More than 7 means the PRD is too big; less than 3 means you do not need stories, just tasks.
+
+## Step 4: write `tasks/stories-<feature>.md`
+
+```markdown
+# Stories: <feature>
+
+> Source PRD: `tasks/prd-<feature>.md`
+> Generated by `/break-into-stories` on <YYYY-MM-DD>.
+> Each story is independently shippable.
+
+## Story order (recommended)
+
+1. Story 1 — <goal>
+2. Story 2 — <goal>
+3. ...
+
+## Stories
+
+<the N stories from Step 3>
+
+## Dependencies
+
+<if any: "Story 3 depends on Story 1 because ..." else "All stories are independent.">
+
+## Next step
+
+For the first story, run `/generate-tasks` referencing `Story 1` to break it into atoms. Implement, deploy, verify, then move to the next story.
+```
+
+## Step 5: report
+
+```
+Stories generated: tasks/stories-<feature>.md (N stories)
+
+Recommended first story: Story 1 — <goal>
+  Estimated agent work: <30 min | 1 hr | 2 hr>
+
+Next: /generate-tasks for Story 1, then implement.
+```
+
+## Hard rules
+
+- Stories never cross PRDs. One PRD → one stories file.
+- Each story's acceptance criteria must be observable from the live URL after deploy, or via a `curl` probe (for backend stories).
+- If a story has no deployable check, it is not a story; it is a task. Roll it into another story.
+- Mark dependencies explicitly. Do not pretend stories are independent when one needs another's API.

package/templates/.claude/commands/handoff-doctor.md

@@ -0,0 +1,93 @@
+---
+description: Audit HANDOFF.md against actual repo state. Flags stale claims, missing follow-throughs, and orphan files not mentioned anywhere. Read-only; surfaces a punch list for /prompt-end to fix.
+---
+
+# /handoff-doctor
+
+HANDOFF.md should reflect repo reality. When it does not, agents (including you) make decisions based on lies. This command catches lies before they cause work loss.
+
+## Step 1: probe
+
+```bash
+echo "=== HANDOFF claims ==="
+grep -E "^(\*\*Status:\*\*|\*\*Branch:\*\*|\*\*Working tree:\*\*|\*\*Last session ended:\*\*)" HANDOFF.md | head -8
+
+echo ""
+echo "=== Repo reality ==="
+echo "Branch:       $(git branch --show-current)"
+echo "Last commit:  $(git log -1 --oneline)"
+echo "Ahead of origin: $(git rev-list --count origin/$(git branch --show-current)..HEAD 2>/dev/null || echo 'no upstream')"
+echo "Behind origin:   $(git rev-list --count HEAD..origin/$(git branch --show-current) 2>/dev/null || echo 'no upstream')"
+echo "Working tree:"
+git status --short
+
+echo ""
+echo "=== Files HANDOFF claims were touched ==="
+grep -E "^\s*-\s*\`[^\`]+\`" HANDOFF.md | head -20
+
+echo ""
+echo "=== Files actually changed in last 5 commits ==="
+git log --name-only --oneline -5 | grep -v "^[0-9a-f]\{7\}" | sort -u | head -30
+
+echo ""
+echo "=== Tasks mentioned in HANDOFF ==="
+grep -E "tasks/|prd-|\.md" HANDOFF.md | head -10
+
+echo ""
+echo "=== Tasks actually in tasks/ ==="
+ls tasks/ 2>/dev/null
+
+echo ""
+echo "=== Manual blockers claimed ==="
+[ -f docs/MANUAL_TASKS.md ] && grep -c "^\s*-\s*\[ \]" docs/MANUAL_TASKS.md
+```
+
+## Step 2: diagnose
+
+Audit each of these axes. For each finding, state CLAIM vs ACTUAL.
+
+1. **Branch mismatch.** HANDOFF says branch X, git is on branch Y.
+2. **Push lag.** HANDOFF says "push commit X" but `git log origin/$(git branch --show-current)` already includes X.
+3. **Working tree drift.** HANDOFF says "clean" but `git status` shows N dirty files.
+4. **Last-session timestamp.** HANDOFF "Last session ended" is more than 7 days old. Mark as STALE.
+5. **Orphan tasks.** Files in `tasks/` not referenced by HANDOFF.
+6. **Phantom files.** HANDOFF references files that do not exist (`ls` them to verify).
+7. **Phantom commits.** HANDOFF references SHAs not in `git log`.
+8. **Manual-task drift.** HANDOFF says no blockers but MANUAL_TASKS.md has Active items (or vice versa).
+9. **Brief drift.** docs/brief.md exists but HANDOFF makes no reference to it; or HANDOFF references a brief that does not exist.
+10. **Test-pass lie.** HANDOFF says "N/N tests green" — run `npm test` (or similar) and compare.
+
+## Step 3: print findings
+
+```
+HANDOFF DOCTOR REPORT
+
+Overall: <CLEAN | NEEDS REWRITE | CRITICAL>
+
+Findings:
+
+[CRITICAL]   <description>      Fix: <what to do>
+[STALE]      <description>      Fix: <what to do>
+[ORPHAN]     <description>      Fix: <what to do>
+[PHANTOM]    <description>      Fix: <what to do>
+[CLEAN]      No issues on this axis: <axis name>
+
+Recommended actions:
+  1. <action>
+  2. <action>
+
+Run /prompt-end to rewrite HANDOFF.md with current reality.
+```
+
+## Hard rules
+
+- Read-only. Never modify HANDOFF.md from this command. `/prompt-end` is the writer.
+- Be specific in findings. "HANDOFF says push 9a4708f but it is already at origin/main" is useful. "HANDOFF is wrong" is not.
+- If a finding is borderline (e.g. timestamp 6 days old, threshold is 7), mark it CLEAN with a note rather than STALE.
+- If everything passes, say so. Do not invent issues.
+
+## When to run
+
+- Before `/prompt-start` if you suspect HANDOFF is wrong.
+- After a long AFK session before a new agent picks up.
+- Any time HANDOFF claims something that does not match what you just saw in git.

package/templates/.claude/commands/resume.md

@@ -0,0 +1,102 @@
+---
+description: Resume an in-progress session by reading git diff, HANDOFF, tasks, and the brief if present. Briefs the agent on actual current state vs claimed state. Use instead of /prompt-start when you suspect HANDOFF.md is stale.
+---
+
+# /resume
+
+`/prompt-start` reads HANDOFF and trusts it. `/resume` reads HANDOFF and **verifies it against git reality**. Use when:
+
+- You stopped mid-feature and HANDOFF was not rewritten.
+- You came back after several days and are not sure HANDOFF is current.
+- A teammate worked in this repo while you were away.
+- Something feels off about the briefing.
+
+## Step 1: collect ground truth
+
+Run all of these in one bash block:
+
+```bash
+echo "=== Git reality ==="
+git status --short
+git log --oneline -10
+git diff --stat HEAD~5..HEAD 2>/dev/null || git diff --stat
+
+echo ""
+echo "=== HANDOFF.md (claimed state) ==="
+[ -f HANDOFF.md ] && head -60 HANDOFF.md || echo "no HANDOFF.md"
+
+echo ""
+echo "=== Active tasks / PRDs ==="
+ls tasks/ 2>/dev/null
+[ -f tasks/prd-initial-build.md ] && head -30 tasks/prd-initial-build.md
+
+echo ""
+echo "=== Brief (if present) ==="
+[ -f docs/brief.md ] && head -40 docs/brief.md || echo "no brief"
+
+echo ""
+echo "=== Manual blockers ==="
+[ -f docs/MANUAL_TASKS.md ] && grep -A 2 "## Active" docs/MANUAL_TASKS.md | head -20
+```
+
+## Step 2: compare claimed vs actual
+
+Build a diff in your head between:
+
+| Source | Status they show |
+|---|---|
+| HANDOFF.md "What to do next" | What the last session said is queued |
+| `git log` | What actually got committed |
+| `git status` | What is in-flight and uncommitted |
+| `tasks/` PRDs and PRD-seeds | What features are scoped |
+| `docs/brief.md` (if any) | What the project is supposed to be |
+
+Flag every mismatch. Examples of mismatches:
+
+- HANDOFF says "push commit X" but `git log` shows X is already pushed (HANDOFF is stale; rewrite at session close).
+- HANDOFF lists a "next action" but uncommitted work in `git status` shows that action was started and abandoned.
+- `tasks/prd-foo.md` exists but is not mentioned in HANDOFF (forgotten artifact).
+- Brief says profile is `booking` but the codebase has no booking-related files.
+
+## Step 3: print the resume brief
+
+```
+RESUMED
+
+Last commit:     <SHA + subject>
+Working tree:    <clean | N dirty files: list>
+HANDOFF claim:   <one-line status>
+Git reality:    <does it match? if not, what's the gap?>
+
+In-flight (uncommitted) work:
+  <git status summary>
+
+What the brief expects (if brief exists):
+  <profile + add-ons + must-have sections> 
+
+Queued from HANDOFF:
+  1. <action>
+  2. <action>
+
+Mismatches surfaced:
+  - <mismatch 1, or "none">
+  - <mismatch 2>
+
+Recommended next move:
+  <pick one: continue queued action / resolve mismatch / pivot>
+```
+
+## Step 4: ask before doing
+
+```
+Continue with the recommended next move? Or pivot?
+```
+
+Wait for confirmation. Do NOT modify any files until the operator picks.
+
+## Hard rules
+
+- Never silently rewrite HANDOFF to match git. Surface the mismatch; let the operator decide.
+- Never silently amend or rebase to "fix" git history.
+- If `git status` shows uncommitted changes that the operator might not remember making, ask before doing anything that could lose them.
+- This command is read-only by default. The only writes are after the operator confirms the next move.

package/templates/AGENTS.md

@@ -27,9 +27,9 @@ Operator materials live in `{{INPUTS_PATH}}`. Read `{{INPUTS_PATH}}README.md` fo
 
 ## Slash commands available
 
-Session lifecycle: `/bootstrap`, `/prompt-start`, `/prompt-mid`, `/prompt-end`, `/preflight`
+Session lifecycle: `/bootstrap`, `/prompt-start`, `/prompt-mid`, `/prompt-end`, `/preflight`, `/resume`, `/handoff-doctor`
 
-Building: `/create-prd`, `/generate-tasks`, `/update-image`, `/update-gui`, `/update-backend`, `/add-storage`, `/generate-image-prompt`, `/generate-image`
+Building: `/create-prd`, `/break-into-stories`, `/generate-tasks`, `/update-image`, `/update-gui`, `/update-backend`, `/add-storage`, `/generate-image-prompt`, `/generate-image`
 
 See each file under `.claude/commands/` for the full routine.
 
@@ -42,6 +42,7 @@ See each file under `.claude/commands/` for the full routine.
 ## Helpers
 
 - `scripts/screenshot.sh <url> [out] [WxH]` — headless Chrome screenshot. Required for visual verification per `CLAUDE.md` Part 19.
+- `scripts/verify.sh [profile] [deploy_url]` — profile-aware verification gate. Auto-detects profile from `docs/brief.json` and deploy URL from `.vercel/project.json`. Runs common checks (build, env, live URL) plus profile-specific checks (e.g. `/api/contact` for lead-gen, `/rss.xml` for blog).
 
 ## If `docs/brief.md` is present in this project
 

package/templates/START_HERE.md

@@ -63,6 +63,9 @@ Type these in your CLI agent. Each runs a structured routine.
 | `/add-storage` | Provision a Vercel Blob, KV, Postgres, or Edge Config store + scaffold a typed `src/lib/<type>.ts` helper + pull env vars. | When you need persistent storage. |
 | `/generate-image-prompt` | Compose an image-generation prompt from the project brief + 2-3 questions. No API call. Paste the prompt into your preferred image tool. | When you need a visual asset and want to use Midjourney, DALL-E, Imagen, etc. directly. |
 | `/generate-image` | Compose the prompt AND call Vercel AI Gateway, saving the image to `inputs/images/`. Requires `VERCEL_AI_GATEWAY_KEY`. | When you want the image generated in-line without leaving your agent. |
+| `/resume` | Read git diff + HANDOFF + tasks + brief, surface mismatches between claimed and actual state. | When HANDOFF.md feels stale, you came back after several days, or something feels off about the briefing. |
+| `/handoff-doctor` | Audit HANDOFF.md against actual repo reality (commits, working tree, files, tasks, manual blockers). Read-only punch list. | Before `/prompt-start` if you suspect HANDOFF is wrong; after a long AFK session. |
+| `/break-into-stories` | Break a PRD into 3-7 vertical, shippable stories before generating granular tasks. | Between `/create-prd` and `/generate-tasks` for any non-trivial feature. |
 
 ## Three workflows
 

package/templates/scripts/verify.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# Profile-aware verification gate. Runs the right checks for the project's profile.
+# Called after /update-image, /update-gui, /update-backend, or at any time the operator wants to verify.
+#
+# Usage:   scripts/verify.sh [profile] [deploy_url]
+# Reads:   docs/brief.json (for profile) if no profile arg
+# Defaults: profile=marketing, deploy_url from .vercel/project.json if available
+
+set -e
+
+PROFILE="${1:-}"
+DEPLOY_URL="${2:-}"
+
+# Auto-detect profile from brief.json if not given
+if [ -z "$PROFILE" ] && [ -f docs/brief.json ]; then
+  PROFILE=$(python3 -c "import json; print(json.load(open('docs/brief.json'))['scaffold']['profile'])" 2>/dev/null || echo "marketing")
+fi
+PROFILE="${PROFILE:-marketing}"
+
+# Auto-detect deploy URL if not given (best-effort; operator may need to pass it)
+if [ -z "$DEPLOY_URL" ]; then
+  if [ -f .vercel/project.json ]; then
+    PROJECT_NAME=$(python3 -c "import json; print(json.load(open('.vercel/project.json'))['projectName'])" 2>/dev/null || echo "")
+    if [ -n "$PROJECT_NAME" ]; then
+      DEPLOY_URL="https://${PROJECT_NAME}.vercel.app"
+    fi
+  fi
+fi
+
+echo "=========================================="
+echo "  Verifying profile: $PROFILE"
+echo "  Deploy URL: ${DEPLOY_URL:-<not detected; pass as arg 2>}"
+echo "=========================================="
+
+PASS=0
+FAIL=0
+
+check() {
+  local desc="$1"
+  local cmd="$2"
+  echo -n "  [$PROFILE] $desc ... "
+  if eval "$cmd" > /tmp/verify-out 2>&1; then
+    echo "PASS"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL"
+    echo "    Output: $(head -3 /tmp/verify-out)"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+# === Common checks (all profiles) ===
+echo ""
+echo "--- common ---"
+check "build succeeds" "npm run build"
+check ".env.example exists" "[ -f .env.example ]"
+check "no {{TOKEN}} placeholders in CLAUDE.md" "! grep -E '\\{\\{[A-Z_]+\\}\\}' CLAUDE.md || true"
+
+if [ -n "$DEPLOY_URL" ]; then
+  check "live URL returns 200" "curl -sI '$DEPLOY_URL' | head -1 | grep -E '200|301|302'"
+fi
+
+# === Profile-specific checks ===
+case "$PROFILE" in
+  lead-gen)
+    echo ""
+    echo "--- lead-gen ---"
+    check "/api/contact route exists" "[ -f src/app/api/contact/route.ts ] || [ -f src/app/api/contact/route.js ] || [ -f app/api/contact/route.ts ]"
+    check "JSON-LD LocalBusiness in HTML" "grep -r 'LocalBusiness' src/ 2>/dev/null"
+    if [ -n "$DEPLOY_URL" ]; then
+      check "POST /api/contact returns 200 or 400" "curl -s -X POST '$DEPLOY_URL/api/contact' -H 'Content-Type: application/json' -d '{\"name\":\"verify\",\"email\":\"verify@example.com\",\"message\":\"verify\"}' -o /dev/null -w '%{http_code}' | grep -E '^(200|400)$'"
+    fi
+    ;;
+  booking)
+    echo ""
+    echo "--- booking ---"
+    check "booking API route exists" "find src/app/api/booking -type f 2>/dev/null | head -1 | grep -q ."
+    check "DATABASE_URL referenced in code or env" "grep -r 'DATABASE_URL' src/ .env.example 2>/dev/null | head -1"
+    ;;
+  saas-dashboard)
+    echo ""
+    echo "--- saas-dashboard ---"
+    check "auth middleware exists" "[ -f src/middleware.ts ] || [ -f src/middleware.js ] || [ -f middleware.ts ]"
+    check "/login or /signup page exists" "find src/app -type d \\( -name 'login' -o -name 'signup' -o -name 'auth' \\) 2>/dev/null | head -1 | grep -q ."
+    check "/dashboard page exists" "find src/app -type d -name 'dashboard' 2>/dev/null | head -1 | grep -q ."
+    if [ -n "$DEPLOY_URL" ]; then
+      check "/dashboard redirects unauthenticated" "curl -s -o /dev/null -w '%{http_code}' '$DEPLOY_URL/dashboard' | grep -E '^(301|302|307|401)$'"
+    fi
+    ;;
+  blog)
+    echo ""
+    echo "--- blog ---"
+    check "content/posts/ exists" "[ -d content/posts ] || [ -d src/content/posts ]"
+    check "mdx package installed" "grep -q '@next/mdx\\|next-mdx-remote\\|@mdx-js' package.json 2>/dev/null"
+    if [ -n "$DEPLOY_URL" ]; then
+      check "/rss.xml returns 200" "curl -sI '$DEPLOY_URL/rss.xml' | head -1 | grep -q 200"
+      check "/sitemap.xml returns 200" "curl -sI '$DEPLOY_URL/sitemap.xml' | head -1 | grep -q 200"
+    fi
+    ;;
+  marketing|*)
+    echo ""
+    echo "--- marketing baseline ---"
+    if [ -n "$DEPLOY_URL" ]; then
+      check "homepage has hero text" "curl -s '$DEPLOY_URL' | grep -iE '<h1' | head -1 | grep -q ."
+    fi
+    ;;
+esac
+
+# === Visual verification reminder ===
+echo ""
+echo "--- visual (per CLAUDE.md Part 19) ---"
+if [ -n "$DEPLOY_URL" ] && [ -x "scripts/screenshot.sh" ]; then
+  scripts/screenshot.sh "$DEPLOY_URL" /tmp/verify-screenshot.png 420,900 > /dev/null && \
+    echo "  Screenshot: /tmp/verify-screenshot.png (READ it to complete Part 19 verification)"
+else
+  echo "  Skipped (no deploy URL or no scripts/screenshot.sh)"
+fi
+
+# === Summary ===
+echo ""
+echo "=========================================="
+echo "  Verify summary: PASS=$PASS FAIL=$FAIL"
+echo "=========================================="
+
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi
+exit 0