A fictional example pack for Claude Code

# Lantern Garden Club
## North-star
Help a garden club member reserve one volunteer spot without guessing at availability.
## Principles
- Keep the first version focused on a clear reservation and confirmation.
## Hard constraints
- A reservation must remain visible after a new session.
## Non-goals
- This fictional example does not collect payment or promise event attendance.

# Lantern Garden Club — fictional example
## What it is
A small website for a fictional neighborhood garden club to list volunteer workdays and let a member reserve one open spot.
## Who it's for
- **ACTOR-1 — Garden club member.**
## Core workflow
1. **FLOW-1 — ACTOR-1 completes reserving an open volunteer spot and observes the reservation confirmation.**
## Entry points & access
- **ACCESS-1 — ACTOR-1 opens the workday list and reaches the open volunteer spots.**
## Key screens
- Workday list
## Data it stores
- **DATA-1 — The member's volunteer reservation.**
## Outside services
None.
## Out of scope (your app)
- Collect payments or manage memberships.
- Coordinate emergency services or guarantee event attendance.
## Acceptance criteria
- [ ] **AC-1 — ACTOR-1 opens the workday list and reaches the open volunteer spots.** *Covers: ACTOR-1, ACCESS-1.*
- [ ] **AC-2 — ACTOR-1 completes reserving an open volunteer spot and observes the reservation confirmation.** *Covers: ACTOR-1, FLOW-1, ACCESS-1.*
- [ ] **AC-3 — DATA-1 is saved, survives a reload in a new session, and is read back to show the member's reservation.** *Covers: DATA-1.*

## Agent guardrails (technical)
Standard rules for the coding agent — they apply to every build, whatever the idea:
- Build only what's in spec.md / tasks.md; don't add features, screens, or endpoints that weren't requested.
- Prefer the simplest implementation that meets the spec; don't over-engineer.
- Don't swap, upgrade, or re-scaffold the tech stack mid-build.
- Don't refactor or rewrite working code unless the current task requires it.
- Don't add dependencies that aren't needed for the current task.
- Don't invent workflows, business rules, or data the spec doesn't define — ask instead.
- Ask before destructive actions (deleting files, dropping data, force-pushing).
- Stay within the current phase/task; don't jump ahead.
- Keep secrets out of client code, and run security-checklist.md before launch.

# Tasks — Lantern Garden Club

- [ ] **Phase 1 — Set up the workday list.** Build the Workday list screen described in design-brief.md and show open volunteer spots. *Covers:* ACTOR-1, ACCESS-1, AC-1. *Verify:* A browser test opens the list and finds an open volunteer spot.
- [ ] **Phase 2 — Reserve a volunteer spot.** Let a garden club member reserve an open spot and show the reservation confirmation. *Covers:* FLOW-1, AC-2. *Verify:* An integration test reserves one open spot and observes the confirmation.
- [ ] **Phase 3 — Save the reservation.** Persist the volunteer reservation and show it after a new session. *Covers:* DATA-1, AC-3. *Verify:* A fresh browser session reads back the saved reservation.
- [ ] **Phase 4 — Readiness and real-world proof.** Run verify-handoff.md, the deterministic completion audit, and security-checklist.md. *Covers:* every spec ID by reference. *Verify:* Every criterion passes, no required control is inert, and any unresolved launch blocker keeps this phase unchecked and the build NO-GO.

# Design brief — Lantern Garden Club fictional example

## Mental model
Lantern Garden Club fictional example is one focused journey across the reviewed screens, with a clear beginning and visible finish.

## Sitemap
- Workday list

## Navigation
Use compact navigation on narrow layouts and persistent navigation between reviewed screens only when width supports it.

## Key flows
- Follow FLOW-1 exactly as defined in spec.md → Core workflow; do not add steps or outcomes.

## Content (by reference)
Entities and what the app stores live in spec.md → Data it stores.

## Required states
- **Workday list:** loading, empty, error, and populated states with honest recovery beside the affected content.
- Every interactive control has visible focus, pressed, disabled, and in-progress states.

## Responsive behavior
- Start with one readable column on narrow screens.
- Use extra width for supporting detail without changing content order.
- Preserve content order, readable contrast, visible focus, reduced motion, and complete keyboard, pointer, and touch access.

## Access control (by reference)
Who can enter and what they can reach stays exactly as defined in spec.md → Entry points & access.

## Design tokens
- **Default visual values:** Apply the complete code-owned Fallback section whenever a receipt-backed selected direction does not resolve an Open id.
- **Direction mode:** Explore exactly two or three materially distinct directions before implementation.

## Fixed
- **DESIGN-FIXED-1** — Product behavior and hierarchy remain exactly as reviewed in spec.md.
- **DESIGN-FIXED-2** — Every main screen provides loading, empty, error, populated, focus, disabled, and in-progress states without claiming unfinished work succeeded.
- **DESIGN-FIXED-3** — Every supported layout remains keyboard reachable with visible focus, sufficient contrast, and a reduced motion path.
- **DESIGN-FIXED-4** — The installable website preserves content order and supported input across its reviewed device sizes.
- **DESIGN-FIXED-5** — Access, money, data, security, delivery, service, and acceptance authority remains in spec.md and its named owning artifacts.
- **DESIGN-FIXED-6** — Exact content and legal constraints named by spec.md remain unchanged in every presented state.

## Open
- **DESIGN-OPEN-1** — Visual direction and mood may vary while preserving reviewed product behavior.
- **DESIGN-OPEN-2** — Type family and pairing may vary within the required semantic roles.
- **DESIGN-OPEN-3** — Density and reading measure may vary within accessible limits.
- **DESIGN-OPEN-4** — Surface and elevation treatment may vary without changing hierarchy.
- **DESIGN-OPEN-5** — Imagery treatment may vary without inventing product content.
- **DESIGN-OPEN-6** — Composition may vary while preserving every reviewed action and state.
- **DESIGN-OPEN-7** — Motion may vary within the accessibility and reduced motion rules.
- **DESIGN-OPEN-8** — Responsive distribution may vary while preserving content order.

## Forbidden
- **DESIGN-FORBIDDEN-1** — Do not invent or change product scope, behavior, people, actions, routes, or outcomes.
- **DESIGN-FORBIDDEN-2** — Do not change access, permissions, money, delivery, or ownership through visual treatment.
- **DESIGN-FORBIDDEN-3** — Do not change security, data, outside-service, deployment, or acceptance authority.
- **DESIGN-FORBIDDEN-4** — Do not remove keyboard access, visible focus, readable contrast, reduced motion, or required states.
- **DESIGN-FORBIDDEN-5** — Do not hide a required action behind hover-only, gesture-only, or decorative interaction.
- **DESIGN-FORBIDDEN-6** — Do not install software, authenticate, spend money, grant permissions, or transfer data without informed consent.
- **DESIGN-FORBIDDEN-7** — Do not edit canonical product artifacts to make a visual proposal appear compliant.

## Fallback
- **DESIGN-FALLBACK-1** — For: DESIGN-OPEN-1; Use primary #315C55, background #F7F4EC, surface #FFFFFF, text #1D2927, and muted text #66736F.
- **DESIGN-FALLBACK-2** — For: DESIGN-OPEN-1; Use accent #B85C38, danger #B42318, success #197A4A, border #D7DDD8, and focus #2457D6 with at least 3:1 focus-indicator contrast.
- **DESIGN-FALLBACK-3** — For: DESIGN-OPEN-2; Use system-ui with platform fallbacks for every text role.
- **DESIGN-FALLBACK-4** — For: DESIGN-OPEN-2; Use a 32px title, 22px heading, 16px body, and 13px caption scale.
- **DESIGN-FALLBACK-5** — For: DESIGN-OPEN-3; Use the spacing scale 4px, 8px, 12px, 16px, 24px, and 32px.
- **DESIGN-FALLBACK-6** — For: DESIGN-OPEN-3; Use comfortable density with a 45–75 character reading measure and clear grouping.
- **DESIGN-FALLBACK-7** — For: DESIGN-OPEN-4; Use 12px card radii, 10px control radii, and one light raised-surface shadow.
- **DESIGN-FALLBACK-8** — For: DESIGN-OPEN-4; Use quiet solid surfaces, visible borders, and elevation only for real layering.
- **DESIGN-FALLBACK-9** — For: DESIGN-OPEN-5; Use imagery only where it explains content, with fixed aspect ratios, alt text, and honest loading placeholders.
- **DESIGN-FALLBACK-10** — For: DESIGN-OPEN-6; Give every control visible hover, focus-visible, active, disabled, loading, error, and empty treatment where applicable.
- **DESIGN-FALLBACK-11** — For: DESIGN-OPEN-6; Use one clear primary region, group related controls, and keep supporting content secondary.
- **DESIGN-FALLBACK-12** — For: DESIGN-OPEN-7; Use transform and opacity motion only, under 200ms for controls and under 500ms for secondary reveals.
- **DESIGN-FALLBACK-13** — For: DESIGN-OPEN-7; Under prefers-reduced-motion, remove decorative movement and preserve instant understandable state changes.
- **DESIGN-FALLBACK-14** — For: DESIGN-OPEN-8; Start with one readable column and add columns only when available width preserves comprehension.
- **DESIGN-FALLBACK-15** — For: DESIGN-OPEN-8; Preserve source order while providing large touch targets plus complete keyboard and pointer access.
- **DESIGN-FALLBACK-16** — For: DESIGN-OPEN-1; Use a clear, calm mood with restrained decoration and product-specific visual emphasis.

# Build rules
## Start here
Read constitution.md, spec.md, tasks.md, design-brief.md, verify-handoff.md, and security-checklist.md.
## What we're building
Build exactly the approved fictional Lantern Garden Club spec.
## Golden rules
Keep ownership explicit and do not add work outside the approved plan.
## Build, run & test
Run each phase's proof before moving to the next one.
## Security
Fail closed at trust boundaries and keep secrets out of source control.
## Commits
Commit each green phase.
## Working conventions
Keep changes small and readable.
## Definition of done
Every required check passes.

## Agent guardrails (technical)
Standard rules for the coding agent — they apply to every build, whatever the idea:
- Build only what's in spec.md / tasks.md; don't add features, screens, or endpoints that weren't requested.
- Prefer the simplest implementation that meets the spec; don't over-engineer.
- Don't swap, upgrade, or re-scaffold the tech stack mid-build.
- Don't refactor or rewrite working code unless the current task requires it.
- Don't add dependencies that aren't needed for the current task.
- Don't invent workflows, business rules, or data the spec doesn't define — ask instead.
- Ask before destructive actions (deleting files, dropping data, force-pushing).
- Stay within the current phase/task; don't jump ahead.
- Keep secrets out of client code, and run security-checklist.md before launch.

## Working memory (progress files)
- Before any task, read progress/state.md and the last 3 entries of progress/log.md — they are the build's memory between sessions; tasks.md is the build order.
- progress/protocol.md is the full manual protocol: one phase at a time, verify, tick the box, update state, append to the log, commit. Activated Autorun instead uses its exact task-checkbox + plan-bound completion receipt + final status transaction; progress is its readable mirror, and serial Autorun does not invent a commit.
- The progress files aren't in the plan download — create them from progress/protocol.md on the first run, and never replace existing ones with blank copies.
- After every manually built phase — however small the change: tick tasks.md, update progress/state.md, append one progress/log.md line, commit. An unrecorded change is how the next session loses the thread.
- If tasks.md was replaced by a newer plan, manual work uses progress/log.md + git history to re-tick what is built; activated Autorun uses its receipt-aware replan path and reopens readiness.

# Read the plan back first — Lantern Garden Club

Before Claude Code builds anything, make it prove it understood your plan. This catches a misread
now — while fixing it costs one message — instead of after it has built the wrong thing. It's the
fastest way to know your plan actually landed.

## Paste this as your **very first prompt** — before Claude Code writes any code:

> Before writing any code, read **constitution.md**, **spec.md**, **tasks.md**, **design-brief.md**, **monetization-plan.md** (if present), **security-checklist.md**, and **CLAUDE.md**. Then tell me, in plain language:
> 1. The **one core workflow** this app is built around.
> 2. The **top 3 features** it must have.
> 3. **Three things this app will NOT do** (out of scope).
> 4. How **each person reaches** the part they use, including any guest/public/invite/link route, and where their path ends.
> 5. For every **primary action**, its trigger, authoritative state change, **observable result**, and the tasks.md phase that implements it — especially publish/share/send/pay/approve/cancel/export.
> 6. Which data must **persist and survive a reload/new session**, who establishes each money/access-controlling value, and which stored record is authoritative.
> 7. Every **outside service**: the product job, whether current official API/support really exists, required credentials/provisioning, the server boundary that holds secrets, and what is proven only by a mock versus a real sandbox.
> 8. The complete design authority: which design-brief.md rules are **Fixed** or **Forbidden**, which ids are **Open**, and every matching **Fallback** entry used for an Open id that has no separate human-selected direction. Product behavior, security, accessibility, access, money, data, delivery, Fixed, and Forbidden outrank bounded brand constraints; those constraints outrank a receipt-backed selected Open choice; unresolved Open ids use Fallback. Full autonomy never makes the subjective selection.
>
> List blockers first. If any person has no entry path, a primary action has no defined result, stored data has no durable owner, an outside capability is unavailable/unverified, the design contract is missing or incomplete, an Open id lacks a Fallback, or a mock-only/stub path is being called complete, **STOP and ask me before writing a single line of code.** Never scaffold an inert control or placeholder and call it done.
> Once I confirm your read-back is right — and before writing any code — set up the build's
> memory: create the progress files exactly as **progress/protocol.md** describes.

## What a good read-back looks like
- It describes **your** core workflow — not a generic version of it.
- Its top 3 match what you actually care about most.
- Its "won't do" list matches the boundaries you set.
- Every person can get from a real entry point to a real outcome; no guest input appears from nowhere.
- Every primary action has its observable result and implementing phase — none is inert.
- Stored values survive reload and outside-service claims separate mock proof from real readiness.
- Fixed and Forbidden remain intact, and each unresolved Open id names every matching Fallback entry actually used.

## If it gets something wrong
Correct it in plain words ("the core flow is X, not Y"), then ask it to read the plan again before
building. Don't let it start coding until the read-back is right — a wrong start is exactly what
drift is made of.

---
description: Build the next unchecked phase from tasks.md, update the progress files, and stop.
---

Advance this build by exactly one verified phase:

1. Read **CLAUDE.md**, **constitution.md**, **spec.md**, and **tasks.md** — then **progress/state.md** and the last 3 entries of **progress/log.md**. If the progress files don't exist yet, create them first, exactly as **progress/protocol.md** describes.
2. Pick the SINGLE next unchecked phase in tasks.md. Build only that phase — nothing more.
3. Run that phase's *Verify:* check and show me the result — the phase isn't done until its check passes.
4. Then, in this order: tick the phase's checkbox in tasks.md → update progress/state.md (last completed, now building, anything decided or discovered) → append one line to progress/log.md → commit with a one-line message.
5. Stop there and wait for me. In a manual session, only do more than one phase if I've explicitly asked — and even then, at most 3 in one run. The only exception, when this pack includes it, is separately consented, activated Autorun with explicit `AUTONOMY=full`; it stays behind runtime gates and uses isolated worktrees for eligible parallel phases.
6. Never delete files, drop data, or force-push without asking first. If a phase is too big for one session, split it into smaller checkboxes in tasks.md, then do only the first.
7. If every phase is already ticked, reply **ALL PHASES COMPLETE** and stop.

---
name: review
description: Fresh-context review pass — diff a change against the plan and run the security review before a phase is called done.
---

# Review a change before it's done

Run this as a SEPARATE pass with a fresh context after you finish a phase — one session builds, a clean reviewer checks. Don't review in the same thread that wrote the code.

1. Diff what you just built against **spec.md** (what was asked) and the current phase's *Verify:* line in **tasks.md** (what "done" means). Anything built that isn't in spec.md or the current phase is out of scope — flag it.
2. Run the security review in **security-checklist.md** — use the paste-ready prompt in its "Paste this into your builder before launch" section against the diff. Report each issue it surfaces by file and line; don't copy the checklist here, run it.
3. Confirm the phase's *Verify:* check actually passes, with the evidence shown — not asserted.
4. Return a verdict of **promote** or **block**, then findings grouped as **must-fix**, **should-fix**, and **optional**. Each finding needs `file:line`, what's wrong, how serious it is, and the smallest fix. A missing required workflow, failed verification, security defect, or inert control is always must-fix. An unprovisioned launch dependency is must-fix when this phase claims that real integration is ready, and always in the final Readiness and real-world proof phase. In an earlier phase that does not claim live readiness, record it as a deferred launch blocker in the summary—not as an optional caveat and not as proof the product is launch-ready.

Any must-fix finding means **block**: do not tick the phase, promote it, or call the build complete. Hand the findings back to the building session to fix, one set at a time, then run a fresh review again. A reviewer only reports — never delete files, drop data, or force-push from a review pass.

# Progress files — how this build keeps its memory

The plan files say what to build. The files described here record where the build **is** —
so a future session picks up exactly where the last one stopped.
**For the coding tool:** follow this protocol exactly. **For the human:** keep this folder
in your project — you never need to edit it.

## The three memory files (create them on your first run)
They are deliberately **not** in the plan download — create them in this folder the first
time you work on the project, exactly as templated at the end of this file. If they already
exist, **never replace or blank them**: they are the build's memory.

- **progress/state.md** — where the build is right now. Keep it under 60 lines: newest
  truth replaces old notes (delete stale lines rather than adding more).
- **progress/log.md** — append-only history, one line per finished phase. Never edit or
  delete old lines.
- **progress/decisions.md** — decisions and discoveries worth keeping. Read it when
  state.md points to it; prune lines that stop being true.

## The build loop
1. Read **CLAUDE.md**, **constitution.md**, **spec.md**, and **tasks.md** — then **progress/state.md** and the last 3 entries of **progress/log.md**. If the progress files don't exist yet, create them first, exactly as **progress/protocol.md** describes.
2. Pick the SINGLE next unchecked phase in tasks.md. Build only that phase — nothing more.
3. Run that phase's *Verify:* check and show me the result — the phase isn't done until its check passes.
4. Then, in this order: tick the phase's checkbox in tasks.md → update progress/state.md (last completed, now building, anything decided or discovered) → append one line to progress/log.md → commit with a one-line message.
5. Stop there and wait for me. In a manual session, only do more than one phase if I've explicitly asked — and even then, at most 3 in one run. The only exception, when this pack includes it, is separately consented, activated Autorun with explicit `AUTONOMY=full`; it stays behind runtime gates and uses isolated worktrees for eligible parallel phases.
6. Never delete files, drop data, or force-push without asking first. If a phase is too big for one session, split it into smaller checkboxes in tasks.md, then do only the first.
7. If every phase is already ticked, reply **ALL PHASES COMPLETE** and stop.

The numbered loop above is the **manual-session** protocol. When separately activated Autorun performs
a phase, its canonical completion is the matching checked phase in tasks.md plus a current
`state/completion/<phase-id>.v1.json` receipt and final `state/<phase-id>.status` of `done`.
The receipt is bound to the exact adapted task-unit bytes; progress files are the human-readable mirror,
not a competing authority. Serial Autorun does not claim or require a Git commit; eligible isolated
worktree integration records the history it actually creates.

## Ending a session
Before stopping: update state.md (what's done, what's next, anything half-finished),
append a log.md line if a phase finished, and commit. Record decisions and
discoveries the moment they happen — don't batch them for later.

## If the plan files were replaced
A newer plan download may replace tasks.md with fresh, unchecked boxes. For manual work,
**progress/log.md and the git history outrank checkbox state**: re-tick the phases that are
already built, reconcile state.md against the new plan, then continue. For activated Autorun,
use its explicit replan path: it reimports only checked prior work through fresh plan-bound
completion receipts and always reopens final readiness.

## Working unattended in a manual session — only when the human explicitly asks
If — and only if — the human explicitly asks for more than one phase in a run:
- Do **at most 3 phases**, then stop and report, even if more remain.
- A phase is done only when its *Verify:* check passes — show the evidence, don't assert it.
- Never act destructively unattended: no deleting files, dropping data, force-pushing, or
  changing deployment/billing settings.
- If anything is ambiguous, stop and say what's finished and what's blocked — don't guess.
- Reply **ALL PHASES COMPLETE** only when every box in tasks.md is ticked.
- Longer runs belong in a safe, isolated workspace — at minimum, a fresh branch.

## Templates — create each file exactly like this

### progress/state.md

```markdown
# Where the build is — Lantern Garden Club

## Last completed phase
(none yet)

## Now building
(the first unchecked phase in tasks.md)

## Half-finished or blocked
(nothing)

## Pointers
- Decisions and discoveries: progress/decisions.md
```

### progress/log.md

```markdown
# Build log — Lantern Garden Club

One line per finished phase, append-only, newest last:
`YYYY-MM-DD — Phase N — what changed — how it was verified`
```

### progress/decisions.md

```markdown
# Decisions & discoveries — Lantern Garden Club

One line each, newest first. Prune lines that stop being true.
```

# Build the next phase — Lantern Garden Club

tasks.md breaks this build into 4 phases. Paste this at the start of **every** work session: it asks your tool to do one
phase, update the progress notes, and stop. A fresh session per phase keeps it sharp — the
progress files carry everything that matters forward.

## Paste this:

> 1. Read **CLAUDE.md**, **constitution.md**, **spec.md**, and **tasks.md** — then **progress/state.md** and the last 3 entries of **progress/log.md**. If the progress files don't exist yet, create them first, exactly as **progress/protocol.md** describes.
> 2. Pick the SINGLE next unchecked phase in tasks.md. Build only that phase — nothing more.
> 3. Run that phase's *Verify:* check and show me the result — the phase isn't done until its check passes.
> 4. Then, in this order: tick the phase's checkbox in tasks.md → update progress/state.md (last completed, now building, anything decided or discovered) → append one line to progress/log.md → commit with a one-line message.
> 5. Stop there and wait for me. In a manual session, only do more than one phase if I've explicitly asked — and even then, at most 3 in one run. The only exception, when this pack includes it, is separately consented, activated Autorun with explicit `AUTONOMY=full`; it stays behind runtime gates and uses isolated worktrees for eligible parallel phases.
> 6. Never delete files, drop data, or force-push without asking first. If a phase is too big for one session, split it into smaller checkboxes in tasks.md, then do only the first.
> 7. If every phase is already ticked, reply **ALL PHASES COMPLETE** and stop.

## Why one phase at a time
Small, verified steps are what keep an AI build on track. Each phase ends checked, recorded,
and saved — so even weeks later, the next session starts exactly where this one stopped.

# Fixing a bug

Use this when something already built is broken — one bug at a time. It works like building a phase, but it starts from the broken behaviour instead of the next phase.

1. **Reproduce it.** Write down the exact steps that trigger the bug and what you expected instead. If you can't reproduce it, gather more detail first — don't guess at a fix.
2. **Isolate it.** Find the smallest piece of code responsible. Check it against **spec.md**: if the app isn't doing what spec.md says, it's a bug — fix it here. If spec.md never asked for it, it's a new feature — take it back through the plan, not this runbook.
3. **Write a failing check first** — a test, or one concrete manual step, that fails *because* of the bug. That's how you'll know it's truly fixed.
4. **Make the smallest fix** that turns the check green. Don't refactor unrelated code while you're in here.
5. **Re-verify:** run your failing check (now passing) and re-run the affected phase's *Verify:* line in **tasks.md**. Show the result — don't assert it.
6. **Record it** like any phase: update **progress/state.md**, append one line to **progress/log.md**, then commit.

Stay safe: fix one bug per pass, then stop and report. Follow the never-destructive rules in **progress/protocol.md** — don't delete files, drop data, force-push, or change deployment or billing settings to "fix" a bug without asking first.

# Security checklist — Lantern Garden Club

Read this once **before building trust boundaries**, then run it in a fresh context **before launch** so your app isn't easy to hack. Work through it in order.

## 1. Run a security review in Claude Code
Claude Code has a built-in security reviewer — **/security-review**. Use it:
- type `/security-review` in your Claude Code session and let it scan the whole project.
- Fix everything it flags as high or critical **before** you launch. Re-run it until it's clean.

## 2. Paste this into your builder before launch
Read this checklist before building auth, shared data, payments, AI calls, or public endpoints. Then copy this prompt to a fresh-context reviewer before launch and have it work through every item:

```
Do a thorough security review of this entire codebase before I launch it to real users.
Check specifically for, and fix, each of these:
- Secrets or API keys committed in the code or exposed to the browser (they belong in server-side environment variables only).
- A backend "service role" / admin key used anywhere the browser can reach it.
- API endpoints or database tables with no authentication, or that don't check the logged-in user owns the data (broken access control / IDOR).
- Database access built by gluing strings together instead of parameterized queries (injection).
- User input that's rendered without escaping (cross-site scripting / XSS).
- Untrusted input inserted into a URL path/query, header, redirect, storage key, or outbound destination without strict format/length validation and the right sink encoding (including SSRF/open redirects).
- File or image storage that's publicly readable when it shouldn't be.
- A value spec.md says the app stores but that lives only in component/in-memory state and disappears on reload.
- Client/request-controlled amount, price, currency, owner, role, entitlement, quota, or status fields being trusted instead of derived server-side from the authoritative persisted record.
- Payment success recorded without comparing the provider's actual amount, currency, account, and final status to the expected server-derived transaction.
- Approve/cancel/capture/refund/consume operations that can replay, race, run twice, revive a terminal state, or strand partial work; require allowed transitions, an atomic claim/unique constraint, idempotency, and a resumable failure path.
- A failed read of a refund, access, price, or safety policy silently falling back to a more permissive/default value instead of failing closed.
- No shared, concurrency-safe rate limiting on sign-in, sign-up, anonymous writes, or sensitive endpoints. A count-then-insert/write throttle is best-effort, not an atomic rate limit.
- A secret-bearing, privileged, or abuse-sensitive external/AI operation called directly from browser/phone code instead of an owned server proxy/function with validation and abuse controls. A provider-designed public client with a scoped/restricted public key is allowed only for its documented public operation; privileged outcomes are still verified server-side.
- Handling raw credit-card details instead of a hosted checkout (e.g. Stripe Checkout).
- Production dependencies with high/critical known vulnerabilities; distinguish them from dev-only toolchain advisories and document any deferred compatibility/major-upgrade decision.
For each issue: name the file and line, rate its severity, and apply the fix. Don't stop at the first one — review the whole project.
```

## 3. Don't launch until each of these is true
This stack uses a hosted database (like Supabase), so these come first:
- [ ] **Row Level Security is ON for every table** — without it, anyone can read or change anyone's data. This is the #1 way AI-built apps get breached.
- [ ] **No service-role or secret key is in front-end code** — that key bypasses every protection. Front-end uses the public "anon" key only.
- [ ] **Every endpoint checks who's logged in and that they own the data** — guessing an ID shouldn't reveal someone else's record.
- [ ] **File/image storage buckets are private by default** — public only where you truly intend it.
- [ ] **Database queries are parameterized** — never built by concatenating user input into a string.
- [ ] **User input is validated, and anything shown back is escaped** — blocks injection and XSS.
- [ ] **Secrets and API keys live in server-side environment variables**, never shipped to the browser.
- [ ] **Sign-in/sign-up, anonymous writes, and sensitive actions use a shared concurrency-safe rate limit** — a local/count-then-write check is only best-effort under a burst.
- [ ] **The app is served only over HTTPS.**
- [ ] **Payments use a hosted checkout** (e.g. Stripe Checkout) — you never store raw card numbers.
- [ ] **Production dependency advisories are cleared or launch-blocked** — run the production audit; triage and document dev-only advisories separately, and never hide a risky major stack upgrade inside a security fix.

## 4. Prove the trust boundaries, not just the happy path
- [ ] **Everything in spec.md → Data it stores really persists** — save it, reload in a new session, read it back, and prove later behavior uses that same authoritative record rather than temporary UI state.
- [ ] **The server derives trusted business values** — amount, price, currency, owner, role, entitlement, quota, availability, and status are derived from authenticated/persisted authority; a client request never gets the final word.
- [ ] **If money moves, the provider result is reconciled before success** — expected amount, currency, account, and final status match what the provider actually returned, and the provider's actual transaction result is what gets recorded.
- [ ] **State transitions are allowlisted and terminal states stay terminal** — approval/cancellation/capture/refund/consume operations reject illegal reversals, fail closed when policy reads fail, and have replay/concurrency/partial-failure tests.
- [ ] **Money and irreversible operations are atomic and idempotent** — concurrent/retried calls cannot charge, capture, refund, grant, reserve, or message twice; use a database claim/unique constraint plus provider idempotency where available.
- [ ] **If the app spends someone's money at an outside service, the sign-in details live only on the server** — the person's account details for that outside service are held server-side and never sent to the browser or the phone, never written to a log, and never included in an error report.
- [ ] **A person confirms the real amount before any outside spend goes through** — show the amount the outside service actually came back with, get an explicit yes for that exact amount, and treat a changed amount as a new confirmation. An app that can spend without a person seeing the figure is not ready to launch.
- [ ] **Every outside spend has a ceiling the app enforces** — a most-it-can-ever-spend limit per purchase and per run, refused on the server; and it can be run in a practice mode that does everything except actually pay, so the whole path can be proven before real money moves.
- [ ] **An amount an outside service reports is recorded as unconfirmed until it is checked** — store it as what the outside service claimed, reconcile it against that service's own record before anything treats it as settled, and make the whole path safe to repeat so a retry cannot buy the same thing twice.
- [ ] **Every outbound dynamic value is safe at its sink** — validate length/format on entry, URL-encode dynamic path/query pieces, allowlist outbound hosts/redirects, and never interpolate raw input into a provider URL.
- [ ] **Secret-bearing, privileged, and abuse-sensitive operations are behind an owned server proxy/function** — browser/phone code calls that boundary, and it validates ownership/input, rate-limits abuse, and holds the credential. Provider-documented public clients may use only scoped public keys for their intended public operation; the server still verifies privileged outcomes.
- [ ] **Anonymous/sensitive write limits hold under concurrency** — use a shared edge/server atomic limiter; a count-then-insert/write query is documented only as best-effort and cannot count as a passed launch control.
- [ ] **Real launch infrastructure is proven, not mocked** — required migrations are applied, server/edge functions are deployed, HTTPS and security headers are active, and each outside service passes its real sandbox/staging smoke test. Mocks prove local behavior only.

---
*Before launch, get a professional security review — especially for anything handling real users, money, or personal data.*

# Quality checklist — Lantern Garden Club

These are the things people expect without ever asking for them out loud. Nobody says "and it should
not take nine seconds to open" — they just leave when it does. Work through this before you call the
build finished.

They are sensible defaults, not rulings. If **spec.md**, **constitution.md**, or **design-brief.md**
says something different for this app, those files win and this one is wrong.

## Feels fast

- The first screen is usable within a few seconds on an ordinary phone connection, not office wifi.
- Every tap or click shows something happened straight away — the thing it did, or a sign that it is
  working on it. Nobody should be left wondering whether the press registered.
- Anything that takes more than a moment says so while it runs, rather than going quiet.
- Nothing that the person is waiting on sits behind something they are not waiting on.

## Stays standing when busy

- It still works when more people turn up than expected — a good day, a link that spread further than
  planned, everyone arriving at once.
- Going slower under load is fine. Breaking, losing work, or showing one person another person's data
  is not.
- Whether two people acting at the same moment can corrupt anything is a correctness question, and it
  is proven in **security-checklist.md** — not here.

## Breaks honestly

- When something fails, the person sees a plain sentence about what happened and what to do next.
  Never a blank screen, a spinner that never stops, or a wall of technical text.
- Nothing the person already saved is lost because a later step failed.
- Trying the same thing again works, and does not leave a half-finished mess behind the first time.
- A failure the person cannot fix themselves still leaves them somewhere they can act from.

## The data survives

- Anything the person saved is still there after the site restarts and after the next release goes out.
- Before anything risky — moving data around, a big release — there is a way back that has actually
  been tried, not just assumed.
- Losing the whole thing costs at most whatever the last save-and-copy missed, and you know what that
  window is.

## Where the rest lives

Each of these is owned by another file in this pack. Read them there rather than here — there is only
ever one place to correct.

- How it looks, how it moves, and who can comfortably use it — **design-brief.md**.
- What the app must actually do, and the exact behaviour that counts as finished — **spec.md**.
- Trust boundaries, sign-in, and anything involving money — **security-checklist.md**.

# How to build Lantern Garden Club

This is your build plan — clear instructions your AI builder can follow without losing the thread.

*Tailored for Claude Code.*

## What's inside
- **constitution.md** — the non-negotiables. The north-star and what must always be true.
- **spec.md** — what to build: the core workflow, screens, and what "done" looks like.
- **tasks.md** — the build broken into small phases, each with a way to check it's done.
- **design-brief.md** — the app's required structure, states, responsive rules, and design boundaries.
- **CLAUDE.md** — rules your coding tool loads automatically so it stays on track.
- **verify-handoff.md** — use this **before it writes any code**: your tool reads the plan back and flags missing entry paths, undefined actions, ephemeral data, or outside-service gaps.
- **next-phase.md** — paste this to start each work session: one phase, progress notes updated, stop.
- **progress/protocol.md** — how the build keeps progress notes between sessions (your tool creates the notes on its first run).
- **security-checklist.md** — read it before auth/data/payment/public work, then run it again before launch.
- **.claude/commands/next-phase.md** — a Claude Code-ready companion file; open it to see how to use it.
- **.claude/skills/review/SKILL.md** — a Claude Code-ready companion file; open it to see how to use it.

## Build it in Claude Code
1. Unzip these files into a new, empty project folder.
2. Open Claude Code in that folder — it reads **CLAUDE.md** automatically.
3. Tell it to follow **verify-handoff.md** first. Read its plan-gap check and confirm the read-back before any code is written.
4. Then tell it: *"Build tasks.md one phase at a time, committing after each."*
5. For every session after that, paste **next-phase.md** — it asks Claude Code to do one phase, update the progress notes, and stop. A fresh chat per phase keeps it focused.

## Progress notes (so nothing gets lost between sessions)
Your plan instructs Claude Code to keep short progress notes as it builds — what's done,
what's next, and what was decided — in a `progress` folder it creates on its first run. You
can open that folder anytime to see exactly where the build stands.

## Installing it on phones
This is a website first — it deploys to a web address like any other site. On top of that, people can **add it to their phone's home screen**, where it opens full-screen and works like an app:
- It is **not** in the App Store or Google Play — there are no store fees, accounts, or review waits.
- Some phone-only features are limited (especially on iPhone), so think of it as a great app-like website rather than a full native app.
- Your plan already includes what makes it installable (a web app manifest, an offline service worker, and app icons) — just build those phases.

## Get the most out of Claude Code
- Turn on **Plan Mode** and let Claude Code lay out the steps before it writes code — read the plan, then let it build.
- Switch on the **command/test auto-run allowlist** so it can run each phase's *Verify:* check itself instead of stopping to ask.
- Lean on its built-in self-checking/debug loop — but still read each phase's *Verify:* result yourself before moving on.
- Before you call a phase done, ask it to run the **review skill** at **.claude/skills/review/SKILL.md** in a fresh context — one session builds, a clean one checks.
- In a manual session, want it to keep going? Ask for "the next 3 phases" — the plan asks it to verify each, record it, and stop after three.

## Ready-made skills (one download away)
Run `npx pogoprompt skills` in this folder and it adds a set of ready-made skills under
`.claude/skills/` — extra know-how Claude Code picks up automatically. You don't run
them; you just say what you want:
- *"fix the login button"* → the **fix** skill reproduces the bug as a test, then repairs it.
- *"add CSV export"* → the **feature** skill adds one capability, test-first.
- *"is it safe to launch?"* → the **ship-check** skill runs the plan's own checks and gives a plain GO / NO-GO.
- *"did I leak a secret?"* / *"can someone skip paying?"* → quick one-shot safety checks.
- *"make it a marketplace instead"* → the **pack-change** skill updates the plan without starting over.
- "explore design directions" → the **design** skill prepares distinct choices, waits for your next message, and implements only the direction you select.
They coexist with the plan — say what you want and Claude Code routes it to the right skill (the **pogoprompt-run** skill is the front door).

## Connect it to your other tools (optional)
Claude Code can reach outside services through MCP connectors — add only what your app actually needs:
- **Payments** — if your app takes money, the Stripe MCP wires up hosted checkout + webhooks.
- **Database & sign-in** — the Supabase MCP, if that's your backend.
- **Error tracking** — Sentry (or similar) so you see real crashes once people use it.
Every connector is one more thing to keep secure — keep it to what the app needs today.

## Autorun (optional — activate on first use)
This plan supports **Autorun**, but it is **off**. Nothing runs merely because the
files are present. On first use, Claude Code must explain this offer and ask exactly:
**“Would you like to enable Autorun for this project?”** It must wait for a clear yes. If you say no,
it follows **tasks.md** manually, one phase at a time, and does not activate or run the scripts.

Before you decide:
- **Selected coding account:** Autorun uses your Claude Code account on this machine — the same
  subscription, request allowance, or API billing that its command-line tool normally uses.
  **pogoprompt charges nothing at build time** and never receives your project code; the exact price and allowance depend on
  Anthropic and your account plan.
- **Supervised by default:** it builds **one phase, then stops** so you can read the check and review
  before deciding whether to continue. Walk-away mode is a separate later choice.
- **One extra download is required:** the runner itself is not in this pack. It is identical for every
  plan, so it ships on its own — in this project folder run `npx pogoprompt skills`, or use
  **Add skills and Autorun** on your plan page and unzip it here. The plan itself needs a file channel too:
  **Download the zip**, save to a project folder, Send to GitHub, the `npx pogoprompt` pull, or the
  saved-plan connection. **Copy plan & open** carries readable text only and cannot enable Autorun.
- **Your computer needs bash 4+, python3, and git.** The runner is shell scripts, so:
  - **Windows:** they do not run in PowerShell or Command Prompt. Use **WSL** (`wsl --install`), or
    **Git Bash** with Python installed — and open this project from inside that shell. Installing
    Python from the Microsoft Store is not enough on its own: a bare `python3` there is a stub that
    exits without running.
  - **macOS:** the built-in bash is 3.2 and too old. `brew install bash`. Get python3 with
    `xcode-select --install`.
  - **Linux:** usually already set up.

  Not sure? Run `bash --version && python3 --version && git --version` first. If any of those fail,
  say **no** to Autorun and build **tasks.md** by hand instead — the plan works exactly the same, one
  phase at a time.

A manual session can cover at most three phases. The separately consented, activated
`AUTONOMY=full` Autorun path is the only exception. It remains behind activation, handoff,
generated-check, and read-only-review runtime gates; eligible parallel phases run in isolated worktrees
and merge back only after verification.

**The easy way.** Open this folder in Claude Code and say *"build my app"* (or *"build the next
phase"*). It reads **pogoprompt.json** and the **pogoprompt-run** skill from that download. After it
gives the summary above and you explicitly say yes, it records activation, follows
**verify-handoff.md**, and stops again for your plan confirmation before any code.

**Prefer to drive it from the terminal?** Do this only after the same explicit yes:
1. **Get the runner once** — `npx pogoprompt skills` in this folder downloads the scripts and skills for Claude Code.
2. **Activate once** — `bash runtime/activate.sh . --confirmed` records consent for this manifest and selected account.
3. **Confirm the plan read-back once** — follow **verify-handoff.md**, approve it, then run `bash runtime/confirm_handoff.sh . --confirmed`.
4. **Adapt the plan once** — `bash runtime/adapt_pack.sh .` turns tasks.md into phase-by-phase build steps.
5. **Generate the checks once** — `bash runtime/gen_verify.sh .` pins a command/browser check or honest human checklist for every phase.
6. **Build it** — `DRY_RUN=0 RUN_REVIEW=1 bash runtime/orchestrate.sh`. The default builds one phase,
   verifies it, reviews the diff, and stops. `AUTONOMY=bounded` runs a few phases; explicit
   `AUTONOMY=full` can walk away through the remaining machine-verifiable phases, but any failed
   check or must-fix review stops it and final readiness always needs you. A bare
   `bash runtime/orchestrate.sh` is only a dry preview.

Autorun refuses common destructive commands, keeps deployment human-controlled, and runs review read-only.
You are still the reviewer: a green project check is evidence for that phase, not proof the result is
exactly what you pictured — **review the diff**.

## Why this plan won't drift
This plan is built to keep your AI builder on the rails — four things hold it together:
- **You close the plan first.** Start with **verify-handoff.md** — it has your builder repeat the
  plan and trace each person's entry, action result, stored data, and outside dependency before it
  writes code, so a missing public path or inert button is caught before a day of building.
- **It says what NOT to build.** The *Out of scope* list in **spec.md** is explicit, so your
  builder doesn't invent features you never asked for.
- **The non-negotiables are locked.** **constitution.md** fixes the core rules — including no
  mid-build switch of the tech stack — so the foundations can't quietly change underneath you.
- **You check security before you ship.** **security-checklist.md** is a plain-language pass to
  run before launch, so nothing risky slips through.

## Tips to avoid drift
- Do one phase from tasks.md at a time, and check its *Verify:* line before moving on.
- Build in **tight loops**: make a small piece, look at the result, describe one or two concrete changes, then go again. Start a fresh session between unrelated phases to keep it focused.
- In a manual session, want it to run further? Ask for "the next 3 phases" — the plan asks your tool to verify each phase, record it, and stop after three.
- If the builder wanders off, paste the relevant part of spec.md back in — the spec is the source of truth, over any earlier message.

---
*Before you launch, review the plan and get a professional security review.*

{
  "origin": "pogoprompt",
  "schema_version": "1.3",
  "pack": {
    "id": "lantern-garden-club",
    "name": "Lantern Garden Club",
    "version": "1.0"
  },
  "entrypoint": "tasks.md",
  "runtime": "runtime",
  "execution_adapter": "claude",
  "build_target": "website_installable",
  "design_direction": {
    "schema_version": 1,
    "candidate": {
      "record_id": "pogo-design.claude-code",
      "capability_id": "pogo-design",
      "display_name": "Pogo Design",
      "publisher": "PogoPrompt",
      "kind": "installed_skill",
      "facets": {
        "asset_generation": "unknown",
        "deterministic_verification": "unknown"
      },
      "consent_before": [
        "spend",
        "external_data_transfer"
      ],
      "permissions": [
        "Read design-brief.md, spec.md, and relevant UI or design-system files using ordinary Claude Code session permissions.",
        "After a valid selection receipt, write selected UI changes and run local checks using ordinary host approvals; the skill grants no additional permission."
      ],
      "data_destination": {
        "kind": "external_provider",
        "name": "Anthropic or the active configured model provider under that provider account"
      },
      "cost": {
        "kind": "selected_account",
        "note": "Uses the active Claude plan, Anthropic API account, or configured-provider billing; exact incremental cost is unknown."
      },
      "builder_id": "claude-code",
      "target": "website_installable",
      "path": ".claude/skills/pogo-design/SKILL.md",
      "sha256": "15400a864faaaa6b4091bf4a27fbd8f47a80a4e98e80692c6b78e287dc4444df",
      "verified_on": "2026-07-25",
      "valid_through": "2026-08-24"
    },
    "fallback": {
      "record_id": "pogo-design.fallback-v1",
      "capability_id": "pogo-design.fallback-v1",
      "display_name": "Pogo local design path",
      "publisher": "PogoPrompt",
      "kind": "fallback",
      "facets": {
        "asset_generation": "unknown",
        "deterministic_verification": "unknown"
      },
      "consent_before": [],
      "permissions": [
        "Use only the existing project repository and its selected coding-agent permissions."
      ],
      "data_destination": {
        "kind": "repository_local",
        "name": "Current project repository; no additional design service"
      },
      "cost": {
        "kind": "selected_account",
        "note": "Adds no Pogo model call; later implementation uses the selected coding account."
      }
    }
  },
  "activation": {
    "required": true,
    "marker": "state/autorun-activation.v1.json"
  },
  "autonomy_default": "supervised",
  "verify_note": "Autorun stays off until first-run consent is recorded with runtime/activate.sh. Before code, follow verify-handoff.md and record plan approval with runtime/confirm_handoff.sh. Then run runtime/adapt_pack.sh and runtime/gen_verify.sh; real builds use RUN_REVIEW=1. A phase with no automatable check pauses for human confirmation.",
  "generated_by": "pogoprompt"
}

# pogoprompt autorun — runtime working dirs (regenerated each run; never commit).
# Root-anchored (leading /) so they never match a same-named dir nested in YOUR app
# source (a bare `state/` etc. would also ignore src/app/plan/, src/lib/state/, …).
/.claude/worktrees/
/state/
/logs/
/contracts/
/plan/
/verify/
# pogoskills working dirs: an in-place pogo-feature/pogo-fix run drops the engine scaffold here
# (evidence/ = the shipped checkers; deliverables/ = the code-domain change-map; .autorun/ = the
# in-place originals teardown restores). Regenerated each run; never commit. Root-anchored so a
# nested app dir of the same name (src/app/evidence/, …) is never ignored.
/evidence/
/deliverables/
/.autorun/
# Playwright (UI builds): the gates run under the runtime-owned runtime/pw.verify.config.ts and
# Playwright writes test-results/ — an autorun working artifact, not your committed suite.
# Ignoring it keeps the tree clean across re-runs (an explicit MERGE_BACK=1 fan-out needs a
# clean tree). Your own test config is never written or touched by autorun, so it stays yours.
/test-results/
# Build Memory state files — your tool creates and maintains these on its first run
/progress/state.md
/progress/log.md
/progress/decisions.md