@devshop/crew 0.11.2 → 0.13.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "crew",
+  "owner": {
+    "name": "devshop-software"
+  },
+  "description": "Project-agnostic Claude Code skills for spec → implement → qa → review → ship.",
+  "plugins": [
+    {
+      "name": "plan",
+      "source": "./skills/plan",
+      "description": "Turn rough intent into agent-ready, testable GitHub Issues (plan:ticket)."
+    }
+  ]
+}

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.13.0](https://github.com/devshop-software/crew/compare/v0.12.0...v0.13.0) (2026-06-11)
+
+
+### Features
+
+* **plan:** namespace ticket as plan:ticket via a plugin marketplace ([95affac](https://github.com/devshop-software/crew/commit/95affac6d7f19d050fe1e6e3cb9e19850039015c))
+
+# [0.12.0](https://github.com/devshop-software/crew/compare/v0.11.2...v0.12.0) (2026-05-12)
+
+
+### Features
+
+* **prep:** folder-per-brief + interactive HTML companion ([c3b7a38](https://github.com/devshop-software/crew/commit/c3b7a383ba7e622c6bdcda9bab0085f21d84c9fb))
+
 ## [0.11.2](https://github.com/devshop-software/crew/compare/v0.11.1...v0.11.2) (2026-05-12)
 
 

package/README.md

@@ -30,6 +30,18 @@ To pull newer skill content later, run `pnpm exec crew update`. The flow:
 
 This copies the skills into `./.claude/skills/`, writes a manifest, and appends a `## Workflow Config` block to `CLAUDE.md` (creating it if absent).
 
+### Namespaced skills (plugins)
+
+Some skills ship as Claude Code **plugins** so they're invoked under a namespace — e.g. the planning skill is **`/plan:ticket`**. No extra step is needed: `crew init` copies the plugin to `.claude/skills/plan/` (it carries a `.claude-plugin/plugin.json`), and Claude Code auto-loads any such folder as `plan@skills-dir`, exposing `/plan:ticket` on the next session.
+
+Prefer Claude Code's own plugin system over the CLI? Install straight from the marketplace instead:
+
+```sh
+# run inside Claude Code
+/plugin marketplace add devshop-software/crew
+/plugin install plan@crew
+```
+
 ## Commands
 
 ```

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@devshop/crew",
-  "version": "0.11.2",
+  "version": "0.13.0",
   "description": "Project-agnostic Claude Code skills for spec → implement → qa → review → ship",
   "bin": {
     "crew": "scripts/cli.js"
   },
   "files": [
+    ".claude-plugin/",
     "skills/",
     "templates/",
     "scripts/",

package/skills/plan/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "plan",
+  "description": "Planning skills — turn rough intent into agent-ready, testable GitHub Issues.",
+  "version": "0.1.0"
+}

package/skills/plan/skills/ticket/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: ticket
+description: "Interactive ticket-writer. Interviews the user about a feature, then opens a well-formed GitHub Issue (mechanical and testable: Context / Out of scope / Acceptance criteria) that reads clearly for humans and implementation agents alike, then labels it for the implementation loop to pick up. Project conventions are read from CLAUDE.md at runtime — the skill contains no project-specific knowledge. Use when the user invokes /plan:ticket."
+---
+
+# Ticket
+
+## Role
+
+You produce **well-written GitHub Issues** — the unit of work that gets picked up and shipped, read by humans and implementation agents alike. A ticket captures the _outcome contract_ (what must be true when done), the _boundary_ (what's excluded and why), and how the work is _verified_ — and nothing more.
+
+You are an interviewer first, a writer second. Your job is to pull out of the user's head the decisions and constraints that only the user knows and that no amount of code-reading will reveal, then compress them into one mechanical issue body.
+
+**You capture the outcome and the boundary; the mechanism is chosen later, at implementation time, after the code has been read.** This division is load-bearing: if the ticket prescribes hooks, CSS strategies, or file-level edits, it pre-decides work that should be reconsidered after exploring the codebase, and creates double-specification that silently drifts.
+
+The output is a GitHub Issue — it lands in a reviewable queue that humans triage and agents implement, so it must stand on its own without you there to explain it.
+
+## When to Apply
+
+Activate when called from the `/plan:ticket` command. Otherwise ignore.
+
+---
+
+## Step 0 — Preflight
+
+Confirm the issue can actually be filed before interviewing:
+
+1. `gh auth status` — must be logged in. If not, stop and tell the user to run `gh auth login`.
+2. `gh repo view --json nameWithOwner -q .nameWithOwner` — confirms a default GitHub remote and prints the target repo. If it fails (no remote, or multiple remotes with no default), tell the user and ask which repo to target (`gh repo set-default`).
+
+If `gh` is unavailable, fall back to **draft mode**: run the full interview and draft, then print the issue body for the user to paste manually instead of creating it. Say so up front.
+
+---
+
+## Step 1 — Read project conventions
+
+Read `CLAUDE.md` from the CWD (walking upward until found). Extract:
+
+- Tech stack signals (package manager, test framework, lint/build commands, CI config locations).
+- The `## Workflow Config` table if present — note the **test / lint / build commands**. The lean ticket has no dedicated verify section, so verification folds into the **acceptance criteria** as testable outcomes; these commands inform how those criteria are phrased.
+- Any "do not do X" constraints the ticket should echo as guardrails.
+
+Never hardcode tool names, package managers, or framework names. Pull them from `CLAUDE.md` fresh each run. If `CLAUDE.md` is absent, warn the user — a ticket without project conventions (especially verify commands) will drift.
+
+---
+
+## Step 2 — Ground in the codebase (light)
+
+Before asking questions, spend a few minutes verifying the feature maps to real files:
+
+- Grep/Glob for the symbols, files, or commands the user mentioned.
+- Identify the 2–5 files most likely to be affected so the Context and acceptance criteria are concrete.
+
+**Do not** explore to implementation depth. The goal is to ground the ticket in real paths, not to plan the implementation.
+
+---
+
+## Step 3 — Interview
+
+Ask targeted questions in **one batch** (not drip-fed). Choose 3–6 from:
+
+1. **What's needed** — one sentence in the user's own words, if the rough description was vague.
+2. **Why now** — a concrete motivating source (a PR, bug, incident, prior ticket). Often opens the issue's Context.
+3. **Decisions already made** — what has the user already ruled in or out? Non-obvious constraints no code-reading reveals.
+4. **Boundary** — name 2–5 adjacent things (files, capabilities, flows) you saw in Step 2 and ask **which are in scope** (positive enumeration, never "what's excluded?"). The Out-of-scope list is derived from the candidates the user did _not_ mark in-scope.
+5. **Acceptance shape** — what must be observably true when done? 1–3 items; you'll flesh them out at draft time.
+6. **Verification** — how should "done" be checked? The answer becomes a testable acceptance criterion (pull exact test/lint/build commands from `CLAUDE.md` if it has them).
+
+If an answer is vague, follow up once. Two rounds max — don't interrogate.
+
+---
+
+## Step 4 — Draft the issue body
+
+Write the body to a temp file (`mktemp`) so `gh` reads it cleanly. Use this structure exactly:
+
+```markdown
+## Context
+
+<2–4 sentences for human triage: what's needed and why. State the outcome, not the mechanism. If the work has a special path — e.g. only an admin can do it — say so here (e.g. "if an admin must do this, leave a comment on the ticket with instructions").>
+
+## Out of scope
+
+Phrased as _"do not add X"_, _"do not touch Y"_ — guardrails the agent must obey. Derived from the boundary candidates the user did _not_ mark in scope.
+
+## Acceptance criteria
+
+- [ ] Specific, testable item — observably true when done, verifiable by a reviewer and/or an e2e test. Verification lives here: bake the check into the criterion itself (e.g. _"when creating an MR the branch is accessible via Vercel and testable"_).
+- [ ] Specific, testable item.
+```
+
+### Anti-spec rule
+
+The ticket restates intent as context, testable outcomes, and constraints. **It does not outline implementation steps.** If an item reads like a to-do for a coder — "modify X to call Y", "add a hook", "extract a component" — rephrase it as an outcome and leave the mechanism to implementation.
+
+---
+
+## Step 5 — Create the issue
+
+1. Ensure the label exists (idempotent):
+   `gh label create agent-ready --color 0E8A16 --description "Ready for the implementation loop" 2>/dev/null || true`
+2. Create the issue:
+   `gh issue create --title "<feature title>" --body-file <tmpfile> --label agent-ready`
+3. Capture the URL `gh` prints.
+
+The `agent-ready` label is the queue _and_ the kill switch: the implementation loop only picks up issues carrying it. The label name is a convention — if the user's loop uses a different label, ask and substitute.
+
+In **draft mode** (no `gh`), skip this step and print the body in a fenced block for manual paste.
+
+---
+
+## Step 6 — Present
+
+Report in three lines:
+
+1. **Issue** — the URL (or "draft — paste below" in draft mode).
+2. **Label** — `agent-ready` (so the loop will pick it up).
+3. **Next** — how the loop consumes it (e.g. assign to the agent, or it fires on the label).
+
+Then ask: _"Want to tweak anything before the loop picks this up?"_ If the user requests changes, edit the issue in place with `gh issue edit <number> --body-file <tmpfile>` (and `--title` if the title changed) — don't open a second issue.
+
+---
+
+## Constraints
+
+**DO:**
+
+- Read `CLAUDE.md` at runtime for conventions and verify commands — never hardcode them.
+- Verify every concrete file reference by actually looking at it before writing it into the ticket.
+- Keep the body mechanical — three sections only: Context / Out of scope / Acceptance criteria. A few sentences of human context at most.
+- Fold verification into the acceptance criteria as testable outcomes — there is no separate How-to-verify section.
+
+**DON'T:**
+
+- Embed project-specific tool, framework, or package-manager names into this skill file. It must work in any repo that has a `CLAUDE.md`.
+- Prescribe mechanisms (hooks, CSS utilities, component layout, which file to edit) unless the user explicitly committed to one in the interview. The mechanism is explored and decided at implementation time; pre-deciding here strips that option and drifts.
+- Skip the interview. The point of `/plan:ticket` is to extract what only the user knows.
+- Explore the codebase to implementation depth. Grounding the ticket in real paths is enough — planning the build is a later step.
+- Open a second issue when refining — edit the existing one.
+
+---
+
+## Red flags
+
+If you catch yourself thinking any of these, stop:
+
+- _"The user said 'make it good', I'll just draft something"_ — STOP. Ask concrete questions.
+- _"The acceptance criteria are general on purpose, to leave flexibility"_ — STOP. Vague criteria are the #1 reason unattended runs drift. Be specific and testable.
+- _"The acceptance criteria don't say how to check it"_ — STOP. Each criterion must be observably testable; bake the check into the criterion (pull commands from `CLAUDE.md` if relevant). A criterion an agent can't verify is a top cause of drift.
+- _"I didn't ask about out-of-scope because the user didn't mention it"_ — STOP. Ask. Out-of-scope is where tickets silently fail.
+- _"I'll ask the user to list what's NOT in scope"_ — STOP. The boundary question is positive enumeration (_"which of these are in scope?"_); derive Out-of-scope from what they didn't mark.
+- _"The user stated an outcome and I'm writing a mechanism"_ — STOP. `useSidebar()`, CSS strategy, which file to modify — those are implementation-time calls after exploration, not the ticket's.

package/skills/prep/SKILL.md

@@ -1,17 +1,22 @@
 ---
 name: prep
-description: Interactive brief-writer. Produces a two-part `<FEATURE>-BRIEF.md` under `<project-root>/_brief/` (human-readable section + agent brief) intended to be fed to `/indie-agent`. Project root is auto-detected: nearest ancestor whose `CLAUDE.md` contains `## Workflow Config` (works for both single-repo and multi-repo workspaces), falling back to bare-clone via `.bare/` or git toplevel if no workflow config is set yet. Reads project conventions from `CLAUDE.md` at runtime — contains no project-specific knowledge. Use when the user invokes /prep.
+description: Interactive brief-writer. Produces a timestamped folder under `<project-root>/_brief/` containing `BRIEF.md` (agent brief for `/indie-agent`) and `brief.html` (interactive single-file offline view for humans, with persistent acceptance-criteria checkboxes). Project root is auto-detected: nearest ancestor whose `CLAUDE.md` contains `## Workflow Config` (works for both single-repo and multi-repo workspaces), falling back to bare-clone via `.bare/` or git toplevel if no workflow config is set yet. Reads project conventions from `CLAUDE.md` at runtime — contains no project-specific knowledge. Use when the user invokes /prep.
 ---
 
 # Prep
 
 ## Role
 
-You produce **feature briefs** — handoff documents the user feeds to `/indie-agent` to start a full autonomous implementation. A brief captures the *why*, *what's already decided*, and *what's explicitly not included* in a form a teammate could read in 60 seconds, then reformats the mechanical detail for a downstream agent.
+You produce **feature briefs** — handoff documents the user feeds to `/indie-agent` to start a full autonomous implementation. A brief captures the *why*, *what's already decided*, and *what's explicitly not included*.
 
 **Prep captures the outcome contract (what must be true when done) and the boundary (what's excluded and why). `/spec` picks the mechanism after reading the code.** This division is load-bearing: if the brief prescribes hooks, CSS strategies, or component layouts, it pre-decides work that spec-writer should reconsider after codebase exploration — and creates double-specification that silently drifts.
 
-You are an interviewer first, a writer second. Your job is to pull context out of the user's head — specifically the decisions and constraints that only the user knows and that no amount of code-reading will reveal. Then you compress that context into a two-part document: a short human-readable section, and a separate agent brief containing testable outcomes, constraints, and pointers.
+You are an interviewer first, a writer second. Your job is to pull context out of the user's head — specifically the decisions and constraints that only the user knows and that no amount of code-reading will reveal. Then you compress that context into two artifacts that live together in a per-brief folder:
+
+- **`BRIEF.md`** — the agent brief, fed to `/indie-agent`. Mechanical, testable, no narrative. Contains In scope outcomes, Out-of-scope guardrails, Acceptance criteria checklist, and References.
+- **`brief.html`** — an interactive single-file view for human readers. Carries all the human-readable context (TL;DR, Why this exists, Decisions, the user-facing Out-of-scope discussion, References, Post-merge manual steps) plus persistent acceptance-criteria checkboxes the human can tick post-merge to verify the work matches the brief. Strict offline — inline CSS + vanilla JS, no CDN, no web fonts.
+
+The two artifacts are different surfaces for different audiences. Do not duplicate human-readable narrative into `BRIEF.md`; do not put agent-brief mechanics into `brief.html` (other than the embedded JSON data block that powers the page).
 
 ## When to Apply
 
@@ -25,7 +30,7 @@ Activate when called from the `/prep` command. Otherwise ignore.
 
 - **Empty** — ask: *"What's the feature? A one-sentence description works."*
 - **Free text** — a rough description. Treat it as the interview's starting point, not the final feature statement.
-- **Path to an existing `*-BRIEF.md`** — read it, identify which sections are empty or thin, run the interview only for those gaps.
+- **Path to an existing brief folder OR a `BRIEF.md` inside one** — read both `BRIEF.md` and `brief.html` (extract the embedded JSON block from the HTML), identify which sections are empty or thin across either file, run the interview only for those gaps. Normalize a `.md` path to its parent folder; both forms resolve to the same brief.
 
 ---
 
@@ -68,11 +73,11 @@ If an answer is vague, follow up once. Two rounds max — don't interrogate.
 
 ---
 
-## Step 4 — Draft the brief
+## Step 4 — Draft `BRIEF.md`
 
 ### Resolve the output location
 
-Briefs live in `<project-root>/_brief/<SLUG>-BRIEF.md`. Resolve the project root generically, in this order:
+Each brief is a folder at `<project-root>/_brief/<YYYYMMDD-HHMMSS>-<SLUG>/` containing `BRIEF.md` and `brief.html`. Resolve the project root generically, in this order:
 
 1. **Workflow Config anchor (preferred)** — walk up from CWD. The first ancestor whose `CLAUDE.md` contains a `## Workflow Config` heading is the project root. This works for both shapes:
    - **Single-repo project** — the project-root `CLAUDE.md` has `## Workflow Config` (written by `/adjust`). Found at the project root.
@@ -81,104 +86,300 @@ Briefs live in `<project-root>/_brief/<SLUG>-BRIEF.md`. Resolve the project root
 3. **Regular git repo (fallback)** — otherwise, run `git rev-parse --show-toplevel`. The result is the project root.
 4. **Final fallback** — if none of the above applies, use the CWD and warn the user that no project root was detected.
 
-In workspace mode, the resolved project root is the **workspace root** — the brief lives there, not inside any sub-repo. This is intentional: a brief for a cross-stack feature is workspace-scoped, not stack-scoped.
-
-Create `<project-root>/_brief/` if it does not exist. Write the file there.
-
-### Lifecycle — the brief is ephemeral
-
-The brief lives at the **top layer** of the project — the bare-clone root in single-repo projects, or the workspace root in multi-repo workspaces — outside any tracked working copy. It is not committed and will be deleted once consumed. History of a feature lives in `<workflow-dir>/<folder>/`, which itself lives at the same top layer (workspace root in workspace mode, bare-clone root in single mode) — that is where spec, implementation, QA, and review artifacts persist.
-
-Consequence for downstream skills: **ingest the brief's content, do not cite its path**. A `_workflow/.../01-spec.md` that references `../_brief/FOO-BRIEF.md` will break the first time someone cleans up `_brief/`. Spec-writer (and anything else that needs the information) should copy the relevant facts into the persisted artifact rather than linking to the brief file.
-
-### Filename
-
-`<SLUG>-BRIEF.md` — uppercase kebab-case slug derived from the feature title (e.g. `MIGRATION-CONSOLIDATION-BRIEF.md`, `DARK-MODE-BRIEF.md`). The `-BRIEF.md` suffix is intentional even though the folder already signals the type: it makes the file recognizable when grepped, referenced, or opened in isolation.
-
-### Structure
-
-The brief has two clearly-delimited sections. The human section comes first so a reader can stop there.
-
-```markdown
-# <Feature title>
+In workspace mode, the resolved project root is the **workspace root** — the brief folder lives there, not inside any sub-repo. This is intentional: a brief for a cross-stack feature is workspace-scoped, not stack-scoped.
 
-<!-- ============================================================
-     HUMAN SECTION — readable in ≤60 seconds.
-     Prose, not checklists. A teammate should finish this section
-     and understand the "why" well enough to stop reading here.
-     ============================================================ -->
+Create `<project-root>/_brief/<folder-name>/` if it does not exist. Write `BRIEF.md` and `brief.html` inside.
 
-## TL;DR
+### Folder + file naming
 
-One sentence: what's happening and why.
+| Element | Format | Example |
+|---|---|---|
+| Folder | `YYYYMMDD-HHMMSS-<SLUG>` | `20260512-211530-PRODUCT-VARIANTS-SCHEMA` |
+| Slug | UPPERCASE-KEBAB-CASE from feature title | `PRODUCT-VARIANTS-SCHEMA` |
+| Agent brief | `BRIEF.md` (no slug prefix — folder carries it) | `BRIEF.md` |
+| Human view | `brief.html` (lowercase per HTML convention) | `brief.html` |
 
-## Why this exists
+Timestamp uses **second precision** (matches the `_workflow/` folder convention). Second precision supports parallel `/prep` invocations without folder collisions.
 
-2–5 sentences. The motivating incident, PR, constraint, or deadline. Include concrete references (dates, versions, commit SHAs, ticket numbers, workflow folders) whenever the user gave them. This is the paragraph that makes the brief feel grounded.
+### Lifecycle
 
-## Decisions already made
+The brief folder lives at the **top layer** of the project — the bare-clone root in single-repo projects, or the workspace root in multi-repo workspaces — outside any tracked working copy. It is gitignored (Step 5).
 
-- Decision — *half-a-line on why*.
-- Decision — *why*.
+Unlike `<workflow-dir>/<folder>/` (the permanent paper trail of a feature), the brief folder is the human's working artifact: `BRIEF.md` is throwaway once `/indie-agent` consumes it, but `brief.html` is the human's verification reference — keep it as long as it's useful, prune when stale. **The skill does not auto-delete; the user owns cleanup.**
 
-Non-obvious choices only. Skip anything derivable from the code.
+Consequence for downstream skills: **ingest the brief's content, do not cite its path**. A `_workflow/.../01-spec.md` that references the brief by path will break the first time someone prunes `_brief/`. Spec-writer (and anything else that needs the information) should copy the relevant facts into the persisted artifact rather than linking to the brief file.
 
-## Out of scope
+### `BRIEF.md` content — agent brief only
 
-- Thing not included — *why not*.
-- Thing not included — *why not*.
+`BRIEF.md` carries **only** the agent brief. No TL;DR, no Why, no Decisions narrative — that lives in `brief.html`. The agent reads this; the human reads the HTML.
 
-## Post-merge manual steps *(optional — omit if none)*
-
-1. Numbered action for the human to take after the PR merges.
-2. ...
-
----
-
-<!-- ============================================================
-     AGENT BRIEF — feed this (or the whole file) to /indie-agent.
-     Mechanical. Testable. Exact paths and checklists.
-     No narrative. Every item should be diff-able or verifiable.
-     ============================================================ -->
-
-## Feed to `/indie-agent`
+```markdown
+# <Feature title>
 
 > Base: <base-branch from CLAUDE.md workflow config>
 
-### In scope
+## In scope
 
 Outcomes the feature must produce, framed as user-visible behavior or structural boundaries — **not** implementation steps. Paths, function names, and line numbers belong in References, not here. Spec-writer will choose the mechanism after exploring the code; pre-deciding it here removes that option.
 
 - **Good:** *"Sidebar header swaps between wordmark and diamond when toggling between expanded and icon-collapsed states."*
 - **Bad:** *"In `app-sidebar.tsx`, read `state` from `useSidebar()` and conditionally render `<Image>`."* (That's a spec step — picks the hook, the file, and the render strategy before anyone has read the code.)
 
-### Out of scope (as constraints)
+## Out of scope (as constraints)
 
 Phrased as *"do not add X"*, *"do not touch Y"*. These become guardrails the agent is expected to obey.
 
-### Acceptance criteria
+## Acceptance criteria
 
 - [ ] Specific, testable item (verifiable by a reviewer and/or an e2e test).
 - [ ] Specific, testable item.
 
-### References — where to look
+## References — where to look
 
 - `path/to/file.ext:LN` — one-line note on what lives there.
 - `<workflow-dir>/<folder>/01-spec.md` — prior related work, if any.
 - PR #N, issue #M, incident date — whatever grounds the brief.
 ```
 
+The `## Out of scope (as constraints)` heading here is intentionally distinct from `brief.html`'s user-facing "Out of scope" section. In `BRIEF.md` it is a narrow list of explicit "do not touch X" guardrails for the agent; in `brief.html` it is the broader human-facing context derived from the boundary interview. Different audiences, different specificity.
+
 ### Anti-spec rule
 
-The human section states decisions as prose; the agent section restates them as testable outcomes, constraints, and pointers. **It does not outline implementation steps.** If an item reads like a to-do for a coder — "modify X to call Y", "add a hook that does Z", "extract a component" — it's in the wrong layer. Either rephrase it as an outcome (what must be observably true) or move the file reference down to References and let `/spec` decide the mechanism.
+The agent brief restates the user's intent as testable outcomes, constraints, and pointers. **It does not outline implementation steps.** If an item reads like a to-do for a coder — "modify X to call Y", "add a hook that does Z", "extract a component" — it's in the wrong layer. Either rephrase it as an outcome (what must be observably true) or move the file reference down to References and let `/spec` decide the mechanism.
+
+---
+
+## Step 4b — Render `brief.html`
+
+Write `brief.html` in the same folder as `BRIEF.md`. Use the template below **verbatim**, replacing only two placeholders:
+
+- `__TITLE__` — the feature title, HTML-escaped, inserted into the `<title>` tag.
+- `__JSON_DATA__` — the JSON object describing this brief, inserted inside the `<script type="application/json" id="prep-data">` block. The JSON schema:
+
+```json
+{
+  "title": "<Feature title>",
+  "slug": "<SLUG>",
+  "created": "<ISO 8601 timestamp, e.g. 2026-05-12T21:15:30Z>",
+  "tldr": "<one sentence: what's happening and why>",
+  "why": "<2-5 sentence prose paragraph (or paragraphs separated by blank lines); the motivating incident, PR, constraint, or deadline with concrete references>",
+  "decisions": [
+    {"point": "<decision>", "why": "<half-a-line on why>"}
+  ],
+  "outOfScope": [
+    {"thing": "<item not included>", "why": "<why not — user-facing context, broader than BRIEF.md's agent constraints>"}
+  ],
+  "acceptance": [
+    "<specific, testable item — same wording as BRIEF.md's Acceptance criteria>"
+  ],
+  "references": [
+    "<path/to/file.ext:LN — note>",
+    "<PR #N, issue #M, incident date>"
+  ],
+  "postMerge": [
+    "<numbered action for the human after PR merges; omit the array if none>"
+  ],
+  "agentBrief": "<full BRIEF.md content as a single string, with real \\n newlines>"
+}
+```
 
-Related: if a sentence could live in either the human or agent section, it belongs in the human section. The agent section should contain *zero* narrative.
+Notes on filling the JSON:
+
+- `acceptance` should mirror `BRIEF.md`'s checklist items verbatim — the HTML's persistent checkboxes track exactly those items. If you edit one, edit both.
+- `agentBrief` is the full `BRIEF.md` text. The HTML's "Copy agent brief" button puts this on the clipboard so the human can paste it elsewhere.
+- `outOfScope` in the HTML is **user-facing context** — the broader "we considered this, ruled it out, here's why" content. Distinct from `BRIEF.md`'s narrower `## Out of scope (as constraints)` guardrails. They will often overlap but should be written for their respective audiences.
+- `postMerge` may be omitted (or set to `[]`) when there are no manual steps. The HTML hides the section when empty.
+
+### HTML template
+
+Save this verbatim as `brief.html` in the brief folder, with the two placeholders filled:
+
+````html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>__TITLE__</title>
+<style>
+:root { --bg:#fff; --fg:#1a1a1a; --muted:#666; --accent:#2563eb; --border:#e5e5e5; --card:#fafafa; --done:#16a34a; }
+@media (prefers-color-scheme: dark) {
+  :root { --bg:#0a0a0a; --fg:#e5e5e5; --muted:#9aa0a6; --accent:#60a5fa; --border:#2a2a2a; --card:#141414; --done:#22c55e; }
+}
+* { box-sizing: border-box; }
+html, body { background: var(--bg); color: var(--fg); }
+body { font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; max-width: 760px; margin: 2.5rem auto; padding: 0 1.25rem; line-height: 1.6; }
+h1 { font-size: 1.875rem; margin: 0 0 0.5rem; letter-spacing: -0.01em; }
+h2 { font-size: 0.8125rem; margin: 0 0 0.5rem; font-weight: 600; letter-spacing: 0.08em; text-transform: uppercase; color: var(--muted); }
+p { margin: 0.75rem 0; }
+.tldr { font-size: 1.125rem; margin: 1.25rem 0 2rem; padding: 1rem 1.25rem; background: var(--card); border-left: 3px solid var(--accent); border-radius: 6px; }
+details { margin: 0.5rem 0; border: 1px solid var(--border); border-radius: 6px; background: var(--bg); }
+details > summary { cursor: pointer; padding: 0.75rem 1rem; font-weight: 500; user-select: none; list-style: none; display: flex; align-items: center; gap: 0.5rem; }
+details > summary::before { content: "▶"; font-size: 0.7rem; color: var(--muted); transition: transform 0.15s; display: inline-block; }
+details[open] > summary::before { transform: rotate(90deg); }
+details > summary::-webkit-details-marker { display: none; }
+details > .body { padding: 0.25rem 1.25rem 1rem 1.75rem; }
+ul, ol { padding-left: 1.25rem; margin: 0.5rem 0; }
+li { margin: 0.35rem 0; }
+li em { color: var(--muted); font-style: normal; }
+.ac-section { margin: 2rem 0; padding: 1.25rem 1.5rem; background: var(--card); border-radius: 8px; border: 1px solid var(--border); }
+.ac-list { margin: 0.75rem 0 0; }
+.ac-item { display: flex; gap: 0.75rem; align-items: flex-start; padding: 0.5rem 0; border-top: 1px solid var(--border); }
+.ac-item:first-child { border-top: none; }
+.ac-item input { margin-top: 0.35rem; flex-shrink: 0; cursor: pointer; width: 1rem; height: 1rem; accent-color: var(--done); }
+.ac-item label { flex: 1; cursor: pointer; }
+.ac-item input:checked + label { color: var(--muted); text-decoration: line-through; }
+.progress { font-size: 0.8125rem; color: var(--muted); margin-top: 1rem; padding-top: 1rem; border-top: 1px solid var(--border); }
+.copy-btn { display: inline-flex; align-items: center; gap: 0.5rem; padding: 0.625rem 1rem; background: var(--accent); color: white; border: none; border-radius: 6px; font-size: 0.875rem; cursor: pointer; font-family: inherit; font-weight: 500; }
+.copy-btn:hover { filter: brightness(1.1); }
+.copy-btn.copied { background: var(--done); }
+footer { margin: 3rem 0 1rem; padding-top: 1.5rem; border-top: 1px solid var(--border); display: flex; justify-content: space-between; align-items: center; flex-wrap: wrap; gap: 1rem; }
+.meta { font-size: 0.8125rem; color: var(--muted); font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; background: var(--card); padding: 0.125rem 0.375rem; border-radius: 3px; font-size: 0.875em; }
+a { color: var(--accent); }
+</style>
+</head>
+<body>
+<h1 id="title"></h1>
+<div class="tldr" id="tldr"></div>
+
+<details open>
+  <summary>Why this exists</summary>
+  <div class="body" id="why"></div>
+</details>
+
+<details>
+  <summary>Decisions already made</summary>
+  <div class="body" id="decisions"></div>
+</details>
+
+<details>
+  <summary>Out of scope</summary>
+  <div class="body" id="out-of-scope"></div>
+</details>
+
+<div class="ac-section">
+  <h2>Acceptance criteria</h2>
+  <div class="ac-list" id="acceptance"></div>
+  <div class="progress" id="progress"></div>
+</div>
+
+<details>
+  <summary>References</summary>
+  <div class="body" id="references"></div>
+</details>
+
+<details id="post-merge-wrapper" hidden>
+  <summary>Post-merge manual steps</summary>
+  <div class="body" id="post-merge"></div>
+</details>
+
+<footer>
+  <span class="meta" id="meta"></span>
+  <button class="copy-btn" id="copy-btn" type="button">📋 Copy agent brief</button>
+</footer>
+
+<script type="application/json" id="prep-data">
+__JSON_DATA__
+</script>
+
+<script>
+(function () {
+  const data = JSON.parse(document.getElementById('prep-data').textContent);
+  const slug = data.slug;
+  const acKey = (i) => 'prep:' + slug + ':ac:' + i;
+
+  document.title = data.title;
+  document.getElementById('title').textContent = data.title;
+  document.getElementById('tldr').textContent = data.tldr || '';
+
+  document.getElementById('why').innerHTML = formatProse(data.why);
+
+  const decEl = document.getElementById('decisions');
+  decEl.innerHTML = (data.decisions || []).length
+    ? '<ul>' + data.decisions.map(d => '<li><strong>' + esc(d.point) + '</strong> — <em>' + esc(d.why) + '</em></li>').join('') + '</ul>'
+    : '<p><em>None recorded.</em></p>';
+
+  const outEl = document.getElementById('out-of-scope');
+  outEl.innerHTML = (data.outOfScope || []).length
+    ? '<ul>' + data.outOfScope.map(o => '<li><strong>' + esc(o.thing) + '</strong> — <em>' + esc(o.why) + '</em></li>').join('') + '</ul>'
+    : '<p><em>None recorded.</em></p>';
+
+  const acEl = document.getElementById('acceptance');
+  (data.acceptance || []).forEach((ac, i) => {
+    const wrap = document.createElement('div');
+    wrap.className = 'ac-item';
+    const cb = document.createElement('input');
+    cb.type = 'checkbox';
+    cb.id = 'ac-' + i;
+    cb.checked = localStorage.getItem(acKey(i)) === '1';
+    cb.addEventListener('change', () => {
+      localStorage.setItem(acKey(i), cb.checked ? '1' : '0');
+      updateProgress();
+    });
+    const lbl = document.createElement('label');
+    lbl.htmlFor = 'ac-' + i;
+    lbl.textContent = ac;
+    wrap.appendChild(cb);
+    wrap.appendChild(lbl);
+    acEl.appendChild(wrap);
+  });
+  function updateProgress() {
+    const total = (data.acceptance || []).length;
+    const done = (data.acceptance || []).filter((_, i) => localStorage.getItem(acKey(i)) === '1').length;
+    document.getElementById('progress').textContent = total
+      ? 'Progress: ' + done + '/' + total + ' verified (saved in this browser)'
+      : '';
+  }
+  updateProgress();
+
+  const refEl = document.getElementById('references');
+  refEl.innerHTML = (data.references || []).length
+    ? '<ul>' + data.references.map(r => '<li><code>' + esc(r) + '</code></li>').join('') + '</ul>'
+    : '<p><em>None recorded.</em></p>';
+
+  if ((data.postMerge || []).length) {
+    document.getElementById('post-merge-wrapper').hidden = false;
+    document.getElementById('post-merge').innerHTML = '<ol>' + data.postMerge.map(s => '<li>' + esc(s) + '</li>').join('') + '</ol>';
+  }
+
+  document.getElementById('meta').textContent = 'Created ' + data.created + ' · ' + data.slug;
+
+  const btn = document.getElementById('copy-btn');
+  btn.addEventListener('click', async () => {
+    try {
+      await navigator.clipboard.writeText(data.agentBrief || '');
+      btn.classList.add('copied');
+      btn.textContent = '✓ Copied';
+      setTimeout(() => {
+        btn.classList.remove('copied');
+        btn.textContent = '📋 Copy agent brief';
+      }, 1800);
+    } catch (e) {
+      alert('Copy failed: ' + (e && e.message ? e.message : e));
+    }
+  });
+
+  function esc(s) {
+    return String(s == null ? '' : s).replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+  }
+  function formatProse(text) {
+    if (!text) return '<p><em>Not recorded.</em></p>';
+    return esc(text).split(/\n\n+/).map(p => '<p>' + p.replace(/\n/g, '<br>') + '</p>').join('');
+  }
+})();
+</script>
+</body>
+</html>
+````
+
+The template is strict offline: inline `<style>`, inline `<script>`, no `<link>`, no `<script src=>`, no `@font-face`, no `@import`. Do not modify it to add CDN-loaded resources. If the styling needs to evolve, update this template in the SKILL itself — every brief should render identically.
 
 ---
 
 ## Step 5 — Gitignore the `_brief/` folder
 
-Briefs are ephemeral handoff artifacts and should not be committed.
+Briefs are working artifacts and should not be committed. The `_brief/` pattern catches the entire folder tree (every per-brief sub-folder inside).
 
 1. Determine whether the **project root** (from Step 4) is inside a git working copy (`git -C <project-root> rev-parse --is-inside-work-tree`).
 2. If yes, read the project root's `.gitignore` and check whether `_brief/` (or a matching broader pattern) is already present.
@@ -193,13 +394,13 @@ Never create a `.gitignore` that didn't already exist — that's a project-struc
 
 After writing, report in three lines:
 
-1. **Path** of the file written.
-2. **Human section length** — confirm it fits the 60-second target, or flag if it doesn't.
-3. **Next command** — `/indie-agent <path-to-brief>` (or the appropriate invocation given the user's workflow).
+1. **Folder** — absolute path of the brief folder.
+2. **Files written** — `BRIEF.md` (agent brief) and `brief.html` (interactive view). Suggest the user open the HTML to read (`open <folder>/brief.html` on macOS, `xdg-open` on Linux, double-click on Windows).
+3. **Next command** — `/indie-agent <folder>/BRIEF.md` (or the appropriate invocation given the user's workflow).
 
 Then ask: *"Want to tweak anything before this is fed to `/indie-agent`?"*
 
-If the user requests changes, update in place. Re-present only the changed section — don't reprint the whole file.
+If the user requests changes, update in place — edit `BRIEF.md` and/or the JSON block inside `brief.html`, then re-present only the changed section. Don't reprint the whole file.
 
 ---
 
@@ -208,18 +409,22 @@ If the user requests changes, update in place. Re-present only the changed secti
 **DO:**
 - Read `CLAUDE.md` at runtime to learn project conventions — do not hardcode tool names, package managers, or paths into this skill.
 - Verify every concrete file reference by actually looking at it before writing it into the brief.
-- Keep the human section prose-first. Bullets are for lists of decisions/out-of-scope only.
-- Keep the agent section mechanical — paths, checkboxes, references. Zero narrative.
-- Derive the output filename from the feature title (uppercase kebab-case, `-BRIEF.md` suffix).
+- Put human-readable narrative (TL;DR, Why, Decisions, user-facing Out-of-scope context) in `brief.html` only. `BRIEF.md` is the agent brief and contains no narrative.
+- Keep `BRIEF.md` mechanical — outcomes, constraints, checkboxes, references. Zero narrative.
+- Mirror Acceptance criteria verbatim between `BRIEF.md`'s checklist and `brief.html`'s `acceptance` array — the HTML's persistent checkboxes track those items by identity.
+- Embed all source data as a `<script type="application/json" id="prep-data">` block inside `brief.html` so re-runs (gap-fill mode) can read it back.
+- Use the verbatim HTML template in Step 4b. Only fill `__TITLE__` and `__JSON_DATA__`; do not modify CSS, JS, or markup.
+- Derive folder names from the feature title (UPPERCASE-KEBAB-CASE slug, `YYYYMMDD-HHMMSS-` prefix).
 
 **DON'T:**
 - Embed project-specific tool names, framework names, or conventions into the skill file itself. This skill must work in any codebase that has a `CLAUDE.md`.
-- Duplicate content across the two sections — state each thing once, in the section where it belongs.
-- Pad the human section with mechanical detail. If it's longer than one screen, it's failing.
+- Put TL;DR, Why, or other human-readable narrative in `BRIEF.md`. That content lives in `brief.html`.
+- Fetch external resources in `brief.html` — no CDN, no web fonts, no `<link rel="stylesheet">`, no `<script src=>`. Strict offline, single file.
 - Skip the interview. The point of `/prep` is to extract what only the user knows.
 - Explore the codebase to spec-writer depth. This is *pre-spec* work.
 - Prescribe mechanisms (hooks, CSS utilities, component layout, file-level changes) unless the user explicitly committed to one during the interview. The downstream `/spec` does its own exploration; pre-deciding the mechanism removes its ability to reconsider and creates double-specification that silently drifts.
 - Pre-stamp the spec's depth. `/spec` picks `lightweight | standard | deep` after exploring the code — the brief should not guess it.
+- Auto-delete the brief folder. The user owns cleanup — `BRIEF.md` becomes throwaway once `/indie-agent` consumes it, but `brief.html` is the human's verification reference and stays as long as it's useful.
 
 ---
 
@@ -229,7 +434,8 @@ If you catch yourself thinking any of these, stop:
 
 - *"The user said 'make it good', I'll just draft something"* — STOP. Ask concrete questions.
 - *"I know this codebase uses X, I'll reference X in the brief"* — if X is not in `CLAUDE.md` or in a file you just read, you're hallucinating convention. Verify first.
-- *"The human section needs more detail to be complete"* — STOP. If a reader can't stop after that section, you've overloaded it. Move the detail to the agent section.
+- *"I'll add a TL;DR or Why section to BRIEF.md so the agent has context"* — STOP. Human-readable narrative belongs in `brief.html`. `BRIEF.md` is for `/indie-agent`, which reads outcomes, constraints, ACs, and references — not narrative. Narrative bloats the agent's context with content it doesn't act on.
+- *"The HTML would look nicer with Tailwind / a Google Font / lucide-icons via CDN"* — STOP. Strict offline is a hard rule. Single file, inline CSS/JS, no external resources. The brief must render in 5 years when the CDN is dead.
 - *"The acceptance criteria are general on purpose, to leave flexibility"* — STOP. Vague criteria are the #1 reason `/indie-agent` drifts. Be specific.
 - *"This brief is ready — I didn't ask about out-of-scope because the user didn't mention it"* — STOP. Ask. Out-of-scope is where briefs silently fail.
 - *"I'll ask the user to list what's NOT in scope"* or *"I'll show a multi-select of things to exclude"* — STOP. The boundary question is positive enumeration (*"which of these are in scope?"*). Negation framing, especially as multi-select, is ambiguous (✓ could mean include or exclude) and produces vague or empty answers. Derive the Out-of-scope section from the candidates the user did NOT mark in-scope.