@oaklandzoo/ostup 0.1.2 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oaklandzoo/ostup",
-  "version": "0.1.2",
+  "version": "0.2.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/mvp-flow.mjs

@@ -1,6 +1,7 @@
 // mvp-flow.mjs: orchestrate the full MVP scaffold: preflight, prompts, creds, scaffold, GitHub, Vercel, inject, summary.
 import { existsSync } from 'node:fs';
-import { readdir, mkdir, writeFile, readFile, rm } from 'node:fs/promises';
+import { readdir, mkdir, writeFile, readFile, rm, chmod } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import { resolve, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { preflightOrExit } from './preflight.mjs';
@@ -56,6 +57,7 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
   const targetDir = resolve(cwd, answers.projectName);
   await ensureFreshTarget(targetDir, flags.force);
   await mkdir(targetDir, { recursive: true });
+  await ensureMemoryDir(targetDir);
 
   await maybeScaffoldStack({ stack: answers.stack, projectName: answers.projectName, targetDir });
 
@@ -179,6 +181,16 @@ async function writeOne({ entry, targetDir, tokens, defer }) {
   const out = substitute(raw, tokens, { defer });
   await mkdir(dirname(dest), { recursive: true });
   await writeFile(dest, out, 'utf8');
+  if (entry.executable) {
+    await chmod(dest, 0o755);
+  }
+}
+
+export async function ensureMemoryDir(targetDir) {
+  const sanitized = targetDir.replace(/[/ ]/g, '-');
+  const memoryDir = join(homedir(), '.claude', 'projects', sanitized, 'memory');
+  await mkdir(memoryDir, { recursive: true });
+  return memoryDir;
 }
 
 async function writeProjectEnvFiles({ targetDir, collected }) {

package/src/scaffold.mjs

@@ -1,5 +1,6 @@
 import { existsSync } from 'node:fs';
-import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, readdir, chmod } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import { dirname, resolve, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execSync } from 'node:child_process';
@@ -38,6 +39,7 @@ export async function scaffold({ targetDir, flags, stdinIsTTY = process.stdin.is
   const tokens = buildTokenMap(values);
 
   await mkdir(absTarget, { recursive: true });
+  await ensureMemoryDir(absTarget);
 
   for (const entry of REGISTRY) {
     await writeOne({ entry, absTarget, tokens });
@@ -60,6 +62,15 @@ async function writeOne({ entry, absTarget, tokens }) {
   const out = substitute(raw, tokens);
   await mkdir(dirname(dest), { recursive: true });
   await writeFile(dest, out, 'utf8');
+  if (entry.executable) {
+    await chmod(dest, 0o755);
+  }
+}
+
+async function ensureMemoryDir(absTarget) {
+  const sanitized = absTarget.replace(/[/ ]/g, '-');
+  const memoryDir = join(homedir(), '.claude', 'projects', sanitized, 'memory');
+  await mkdir(memoryDir, { recursive: true });
 }
 
 async function ensureTargetReady(absTarget, force) {

package/src/templates.mjs

@@ -21,6 +21,11 @@ export const REGISTRY = [
   { src: '.claude/commands/prompt-end.md',    dest: '.claude/commands/prompt-end.md' },
   { src: '.claude/commands/create-prd.md',    dest: '.claude/commands/create-prd.md' },
   { src: '.claude/commands/generate-tasks.md', dest: '.claude/commands/generate-tasks.md' },
+  { src: '.claude/commands/preflight.md',     dest: '.claude/commands/preflight.md' },
+  { src: '.claude/commands/update-image.md',  dest: '.claude/commands/update-image.md' },
+  { src: '.claude/commands/update-gui.md',    dest: '.claude/commands/update-gui.md' },
+  { src: '.claude/commands/update-backend.md', dest: '.claude/commands/update-backend.md' },
+  { src: '.claude/commands/add-storage.md',   dest: '.claude/commands/add-storage.md' },
   { src: 'CLAUDE.md',                          dest: 'CLAUDE.md' },
   { src: 'AGENTS.md',                          dest: 'AGENTS.md' },
   { src: 'START_HERE.md',                      dest: 'START_HERE.md' },
@@ -31,6 +36,7 @@ export const REGISTRY = [
   { src: 'docs/ARCHITECTURE.md',               dest: 'docs/ARCHITECTURE.md' },
   { src: 'tasks/.gitkeep',                     dest: 'tasks/.gitkeep' },
   { src: 'inputs/README.md',                   dest: 'inputs/README.md' },
+  { src: 'scripts/screenshot.sh',              dest: 'scripts/screenshot.sh', executable: true },
 ];
 
 export const OPTIONAL_REGISTRY = [

package/templates/.claude/commands/add-storage.md

@@ -0,0 +1,112 @@
+---
+description: Provision a Vercel storage product (Blob, KV, Postgres, Edge Config), pull its env vars, and scaffold a typed lib helper.
+---
+
+# Add storage
+
+## Step 1: which type
+
+If the operator named a type (e.g. `/add-storage blob`), use it. Otherwise ask:
+
+| Type | What it is | When to pick |
+|---|---|---|
+| `blob` | File storage with public URLs | Image uploads, downloads, generated PDFs |
+| `kv` | Redis-style key/value | Sessions, caches, counters, rate limits |
+| `postgres` | Relational SQL | Users, transactions, anything with joins |
+| `edge-config` | Read-heavy small config (<8 KB) | Feature flags, A/B variants, allowlists |
+
+## Step 2: check what already exists
+
+```bash
+vercel <type> list-stores --all 2>&1 | head -10
+```
+
+If a suitable store already exists, ask the operator if they want to reuse it instead of creating a new one. Skip to Step 4 if reusing.
+
+## Step 3: provision a new store
+
+Ask for a store name. Default to `<project-name>-<type>`. Then run:
+
+```bash
+vercel <type> create-store <name> \
+  --environment production --environment preview --environment development --yes
+```
+
+For `blob`, also include `--access public` if the stored objects should be served via public URLs:
+
+```bash
+vercel blob create-store <name> --access public --yes \
+  --environment production --environment preview --environment development
+```
+
+Capture the output (store ID, etc.) and surface it.
+
+## Step 4: pull env vars
+
+```bash
+vercel env pull .env.local
+```
+
+Confirm `.env.local` got the new keys. Common ones:
+
+| Type | Keys |
+|---|---|
+| blob | `BLOB_READ_WRITE_TOKEN` |
+| kv | `KV_URL`, `KV_REST_API_URL`, `KV_REST_API_TOKEN`, `KV_REST_API_READ_ONLY_TOKEN` |
+| postgres | `POSTGRES_URL`, `POSTGRES_PRISMA_URL`, `POSTGRES_URL_NON_POOLING`, `POSTGRES_USER`, etc. |
+| edge-config | `EDGE_CONFIG` |
+
+## Step 5: install the SDK and scaffold the lib helper
+
+```bash
+npm install @vercel/<type>
+```
+
+Create `src/lib/<type>.ts` with typed helpers. Example for blob:
+
+```typescript
+// src/lib/blob.ts
+import { put, list, del } from '@vercel/blob';
+
+export async function uploadFile(path: string, body: Blob | ArrayBuffer | string) {
+  return put(path, body, { access: 'public' });
+}
+
+export async function listFiles(prefix?: string) {
+  return list({ prefix });
+}
+
+export async function deleteFile(url: string) {
+  return del(url);
+}
+```
+
+Match the project's existing TypeScript conventions (named exports, no defaults, etc.).
+
+## Step 6: update AGENTS.md
+
+Append under a `## Storage` section:
+
+```markdown
+## Storage
+
+- `<type>`: `src/lib/<type>.ts`. Store: `<name>`. Env vars in `.env.local`.
+```
+
+## Step 7: commit and push
+
+```bash
+git add src/lib/<type>.ts AGENTS.md package.json package-lock.json
+git commit -m "feat(storage): add <type> via src/lib/<type>.ts"
+git push
+```
+
+## Step 8: report
+
+```
+Added <type> storage:
+- Store:  <name>
+- Lib:    src/lib/<type>.ts
+- Env:    <list of keys>
+- Deploy: <url>
+```

package/templates/.claude/commands/bootstrap.md

@@ -22,6 +22,9 @@ find . -maxdepth 2 -type d ! -path '*/node_modules*' ! -path '*/.git*' ! -path '
 [ -f inputs/INGEST_MANIFEST.md ] && cat inputs/INGEST_MANIFEST.md
 [ -f inputs/README.md ] && cat inputs/README.md
 [ -d inputs ] && ls -la inputs/
+# Helpers available in this kit
+[ -x scripts/screenshot.sh ] && echo "scripts/screenshot.sh ready (required for visual verification per CLAUDE.md Part 19)"
+ls .claude/commands/ 2>/dev/null
 ```
 
 ## Step 2: Determine what you know

package/templates/.claude/commands/preflight.md

@@ -0,0 +1,57 @@
+---
+description: Surface what is already provisioned for this project (Vercel auth, blob stores, gh auth, env vars, Chrome). Prevents the agent from assigning CLI work it could do itself.
+---
+
+# Preflight
+
+Run at the start of any session where you might touch Vercel, gh, the GUI, or storage. The output tells you what already exists so you do not duplicate setup or assign the operator CLI work that is already done.
+
+## Step 1: probe everything in one block
+
+```bash
+echo "=== Vercel ==="
+vercel whoami 2>&1 | head -3
+if [ -f .vercel/project.json ]; then
+  echo "Linked:"
+  cat .vercel/project.json
+else
+  echo "Not linked (no .vercel/project.json)"
+fi
+echo ""
+echo "Blob stores:"
+vercel blob list-stores --all 2>&1 | head -10
+echo ""
+echo "Env vars:"
+vercel env list 2>&1 | head -15
+
+echo ""
+echo "=== GitHub ==="
+gh auth status 2>&1 | head -5
+git remote -v 2>&1 | head -2
+
+echo ""
+echo "=== Local tools ==="
+node --version
+[ -d "/Applications/Google Chrome.app" ] && echo "Chrome: present" || echo "Chrome: MISSING (operator must install for visual verification per CLAUDE.md Part 19)"
+[ -x "scripts/screenshot.sh" ] && echo "scripts/screenshot.sh: ready" || echo "scripts/screenshot.sh: MISSING or not executable"
+```
+
+## Step 2: print the SESSION READY summary
+
+After reading the output, print exactly:
+
+```
+SESSION READY
+
+Vercel:     <authed as X | linked to project Y | N blob stores | M env vars>
+GitHub:     <authed | remote URL>
+Chrome:     <present | MISSING>
+Screenshot: <ready | missing>
+Node:       <version>
+
+Anything missing above must be flagged before claiming any work that depends on it.
+```
+
+## Step 3: hard rule
+
+Do NOT propose CLI steps the operator should run for anything Vercel or gh already covers per the SESSION READY line above. CLAUDE.md Part 3 Rule 9 is the constraint: agent does what the agent can do.

package/templates/.claude/commands/update-backend.md

@@ -0,0 +1,74 @@
+---
+description: Make a backend logic change (API route, lib function, server action), deploy, and verify the new behavior via API call before claiming done.
+---
+
+# Update backend
+
+Non-visual analog to `/update-gui`. Verify behavior, not just compile.
+
+## Step 1: confirm intent
+
+Restate the change in one sentence. Get a thumbs-up before editing if scope is non-trivial.
+
+## Step 2: edit
+
+Make the change. Minimal diff.
+
+## Step 3: write or run a test
+
+If a test framework is configured, run the test suite:
+
+```bash
+npm test 2>&1 | tail -10
+```
+
+If no tests exist for the touched code, write one that exercises the new behavior (preferred), or capture an expected response shape for Step 6.
+
+If no test framework exists at all, skip to Step 4 and rely on the curl probe in Step 6.
+
+## Step 4: build
+
+```bash
+npm run build 2>&1 | tail -10
+```
+
+If the build fails, fix before deploying.
+
+## Step 5: deploy
+
+```bash
+git add <changed-files>
+git commit -m "<short message>"
+git push
+```
+
+Wait ~60 seconds for Vercel auto-deploy.
+
+## Step 6: probe the live endpoint
+
+For an API route change:
+
+```bash
+curl -s -i "<deploy-url>/api/<route>" | head -20
+```
+
+For a route that takes a body:
+
+```bash
+curl -s -X POST "<deploy-url>/api/<route>" \
+  -H "Content-Type: application/json" \
+  -d '{"key":"value"}' | head -20
+```
+
+Compare the response to the expected shape from Step 3.
+
+## Step 7: report
+
+```
+Backend change shipped: <one-line description>
+Deploy: <url>
+Verified via: <test name or curl command>
+Response: <status, key field, whatever proves it works>
+```
+
+If verification fails, do NOT claim done. Diagnose, fix, re-deploy, re-probe.

package/templates/.claude/commands/update-gui.md

@@ -0,0 +1,55 @@
+---
+description: Make a UI change, deploy it, and verify visually before claiming done. Enforces CLAUDE.md Part 19.
+---
+
+# Update GUI
+
+This command exists so that CLAUDE.md Part 19 (visual verification) is the default for any UI change, not an afterthought.
+
+## Step 1: confirm intent
+
+The operator described the change. Restate it in one sentence and get a thumbs-up before editing if the scope is non-trivial. Skip the thumbs-up for tiny changes (typo, single color, single class).
+
+## Step 2: edit
+
+Make the change. Keep the diff minimal. No unrelated cleanup in the same commit.
+
+## Step 3: build locally
+
+```bash
+npm run build 2>&1 | tail -10
+```
+
+If the build fails, fix before deploying.
+
+## Step 4: deploy
+
+```bash
+git add <changed-files>
+git commit -m "<short message>"
+git push
+```
+
+Wait ~60 seconds for Vercel auto-deploy.
+
+## Step 5: screenshot
+
+```bash
+scripts/screenshot.sh <deploy-url> /tmp/gui-check.png 420,900
+```
+
+## Step 6: read the PNG
+
+Use the Read tool on `/tmp/gui-check.png`. Confirm the visual change matches what the operator asked for. If it does not, diagnose (CSS regression, z-index, cache, stale file path) and re-deploy. Do NOT claim done.
+
+## Step 7: report
+
+```
+GUI change shipped: <one-line description>
+Deploy: <url>
+Screenshot: /tmp/gui-check.png (read, change confirmed)
+```
+
+## Hard rule
+
+HTTP 200, build success, lint pass, byte counts: none of these count as visual verification. Only a read PNG counts.

package/templates/.claude/commands/update-image.md

@@ -0,0 +1,57 @@
+---
+description: Swap an image referenced in the codebase (background, hero, logo) using a candidate from inputs/images/. Always ends with screenshot verification per CLAUDE.md Part 19.
+---
+
+# Update an image
+
+## Step 1: figure out the slot
+
+If the operator named a slot (e.g. `/update-image bg-week`), use that.
+
+If not, list every image reference in the codebase:
+
+```bash
+grep -rln -E "/(bg|hero|logo|images?)/[a-zA-Z0-9_-]+\.(png|jpg|jpeg|svg|webp|avif)" src/ public/ 2>/dev/null
+```
+
+Show the operator the slots and ask which to update.
+
+## Step 2: pick the source
+
+List candidates in `inputs/images/`:
+
+```bash
+ls -la inputs/images/ 2>/dev/null
+```
+
+If there is an `inputs/images/MANIFEST.md`, read it for filenames and captions.
+
+If multiple candidates and the choice is not obvious, ask the operator. Do NOT Read more than 3 image files at a time — each Read returns a vision payload that is heavy in context.
+
+## Step 3: swap it in
+
+1. Copy the chosen file from `inputs/images/` to the right path under `public/`.
+2. Update any code references if the filename changed.
+3. `git add <changed files>` (the new image plus any code).
+4. `git commit -m "feat(images): swap <slot>"`
+5. `git push` (Vercel auto-deploys).
+
+## Step 4: verify visually (REQUIRED per CLAUDE.md Part 19)
+
+Wait ~60 seconds for Vercel to deploy. Then:
+
+```bash
+scripts/screenshot.sh <deploy-url> /tmp/after-swap.png 420,900
+```
+
+Read the resulting PNG with the Read tool. Confirm the new image is showing in the slot.
+
+## Step 5: report
+
+```
+Swapped <slot>: <old-filename> -> <new-filename>
+Deploy: <url>
+Screenshot: /tmp/after-swap.png (read and verified)
+```
+
+If the screenshot does not show the change, do NOT claim done. Diagnose (CSS z-index, wrong path, wrong file) and re-deploy before reporting.

package/templates/AGENTS.md

@@ -27,7 +27,12 @@ Operator materials live in `{{INPUTS_PATH}}`. Read `{{INPUTS_PATH}}README.md` fo
 
 ## Slash commands available
 
-- `/bootstrap`, `/prompt-start`, `/prompt-mid`, `/prompt-end`
-- `/create-prd`, `/generate-tasks`
+Session lifecycle: `/bootstrap`, `/prompt-start`, `/prompt-mid`, `/prompt-end`, `/preflight`
 
-See each file under `.claude/commands/` for details.
+Building: `/create-prd`, `/generate-tasks`, `/update-image`, `/update-gui`, `/update-backend`, `/add-storage`
+
+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.

package/templates/CLAUDE.md

@@ -254,3 +254,16 @@ Detailed file map: `docs/ARCHITECTURE.md`.
 | What happened recently | `docs/SESSION_NOTES.md` |
 | Stack and file map | `docs/ARCHITECTURE.md` |
 | How to behave | `CLAUDE.md` (this file) |
+
+---
+
+# PART 19: VISUAL VERIFICATION
+
+Any change that affects what the operator sees in a browser (HTML, CSS, Tailwind classes, image swaps, layout, copy in JSX, fonts, colors, hero sections, anything rendered) is NOT done until BOTH of the following are true:
+
+1. `scripts/screenshot.sh <deployed-url>` has been run after the change is deployed.
+2. The resulting PNG has been read with the Read tool and the visual change is confirmed to match the intent.
+
+HTTP 200, build success, lint passing, byte counts of the deployed HTML: none of these count as visual verification.
+
+If `scripts/screenshot.sh` is missing or Chrome is not installed, surface the gap before claiming the change is done. Do not assume.

package/templates/START_HERE.md

@@ -47,11 +47,16 @@ Type these in your CLI agent. Each runs a structured routine.
 | Command | What it does | When to run it |
 |---|---|---|
 | `/bootstrap` | Scans the repo and asks up to 5 clarifiers, then fills in `CLAUDE.md` Parts 13 to 17 and `docs/ARCHITECTURE.md` with your project's real facts. | Once, on the first session. |
+| `/preflight` | Surfaces what is already provisioned (Vercel auth, blob stores, gh auth, env vars, Chrome). Stops the agent from assigning CLI work it could do itself. | Start of any session where you might touch Vercel, gh, the GUI, or storage. |
 | `/prompt-start` | Reads HANDOFF, MANUAL_TASKS, git status. Briefs the agent on the current state. Asks "Proceed or pivot?" | Start of every session after the first. |
 | `/prompt-mid` | Checks context budget, restates progress, verifies any files the agent claimed to write actually exist. | Mid-session, if you feel lost or the agent seems off-track. |
 | `/prompt-end` | Rewrites HANDOFF, appends to SESSION_NOTES, surfaces any new blockers to MANUAL_TASKS. | End of every session. Always. Without this the next session has no memory of what just happened. |
 | `/create-prd` | Asks 3 to 5 clarifying questions, then writes a PRD to `tasks/prd-<feature>.md`. | Before building a significant new feature. Optional for small changes. |
 | `/generate-tasks` | Reads a PRD, breaks it into a phased task list at `tasks/tasks-<feature>.md` (parent tasks first, then sub-tasks after you say "Go"). | After a PRD is approved, before the agent starts coding. |
+| `/update-image` | Swap an image (background, hero, logo) using a candidate from `inputs/images/`. Ends with screenshot verification. | Any time you want to change a visual asset. |
+| `/update-gui` | Make a UI change, deploy, screenshot, confirm the visual change matches intent. Enforces visual verification. | Any UI tweak. |
+| `/update-backend` | Make a backend/API change, deploy, probe the live endpoint, confirm behavior. | Any server/API change. |
+| `/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. |
 
 ## Three workflows
 

package/templates/scripts/screenshot.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Headless Chrome screenshot helper. Use to visually verify a UI change.
+# Required by CLAUDE.md Part 19 (Visual Verification).
+#
+# Usage:   scripts/screenshot.sh <url> [output-path] [width,height]
+# Example: scripts/screenshot.sh https://your-app.vercel.app /tmp/check.png 420,900
+
+set -e
+
+if [ -z "$1" ]; then
+  echo "Usage: $0 <url> [output-path] [width,height]" >&2
+  echo "Example: $0 https://your-app.vercel.app /tmp/check.png 420,900" >&2
+  exit 1
+fi
+
+URL="$1"
+OUT="${2:-/tmp/screenshot-$(date +%s).png}"
+SIZE="${3:-420,900}"
+
+CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+if [ ! -x "$CHROME" ]; then
+  CHROME="$(command -v chromium 2>/dev/null || command -v google-chrome 2>/dev/null || echo '')"
+fi
+
+if [ -z "$CHROME" ] || [ ! -x "$CHROME" ]; then
+  echo "ERROR: Chrome not found. Install Google Chrome from https://www.google.com/chrome/" >&2
+  exit 1
+fi
+
+"$CHROME" \
+  --headless=new --disable-gpu --hide-scrollbars \
+  --window-size="$SIZE" --virtual-time-budget=4000 \
+  --screenshot="$OUT" "$URL" 2>/dev/null
+
+echo "$OUT"