@boopkit/cap-web 0.5.6 → 0.5.8

package/skills/boop-web-website-dev-workflow/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: boop-web-website-dev-workflow
+description: "When you are tasked with implementing website changes end-to-end (new pages, page rewrites, IA changes, content/CTA updates), follow this guidance."
+metadata:
+  category: workflow
+---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
+
+# Workflow for building website changes.
+
+This is the **website sibling** of `boop-feature-dev-workflow` — same step-by-step flow, same beads-issue structure, customized for marketing-site work (new pages, page rewrites, IA changes, content/CTA updates).
+
+This workflow is **project-agnostic**. It names patterns of project artifacts (the driving spec, the brand reference docs, the audience-type marketing skill) rather than specific file paths. The Understand step (#1 below) is where you discover the specific artifacts that apply to *this* project and record them as breadcrumbs so the rest of the loop can pick them up.
+
+## Relevant skills
+
+### Project Management
+- `boop-project-mgmt-beads-planning` — when you need to plan work with beads.
+- `boop-project-mgmt-engineering-planning` — when you need to plan engineering work.
+
+### Design
+- `boop-product-design-engineering-design` — when you need to design a feature or system.
+- `boop-web-web-ui-design` — when you need to design web UIs; **the primary design skill for this workflow**.
+- `boop-services-controllers` — when you need to design controllers, the route handlers that render views.
+
+### Coding
+- `boop-coding-beads-flow` — when you need to start working on a claimed issue.
+- `boop-coding-development` — when you need to develop or modify code.
+- `boop-coding-commit-changes` — when you need to commit code changes.
+- `boop-coding-review-changes` — when you need to review uncommitted code changes.
+
+### Testing
+- `boop-testing-testing` — when you need to write or run tests.
+- `boop-web-testing` — when you need to test Express web endpoints.
+
+### Documentation
+- `boop-product-design-reference-integration` — when you need to integrate knowledge into reference docs.
+
+### Subject-matter marketing skills (discovered per project)
+The project may ship an **audience-type marketing skill** carrying the universal copy patterns for whom it sells to — frameworks, default moves, forbidden patterns (e.g. a `b2b-marketing` skill when the project sells to businesses; consumer / marketplace / etc. variants exist for other audiences). boop does not bundle one; if the project provides it, the Understand step records its exact path. Use whichever matches the project's audience.
+
+## Project structure
+Most projects this workflow runs on organize documents into:
+- `reference/` — *current state.* The project's brand reference doc, brand realization (site) doc, product / positioning refs, and any tenets live here. These are the **guardrails**.
+- `specs/` — *future state.* The driving spec for the work, plus any companion plans (`{feature-name}-plan-findings.md`, `{feature-name}-plan.md`) generated by this workflow.
+- `skills/` — instructions for specific tasks. Additional skills reside in `packages/cap-*/skills/`.
+- `tools/` — command-line tools used to automate the workflow. Do not run these until instructed to do so.
+
+The Understand step (#1) records the exact files in *this* project's `reference/` and `specs/` that ground the work.
+
+### Where website content comes from
+
+A website implementation task usually carries two layers of input:
+
+- A **driving spec** in `specs/` — *future-state* intent. Defines which pages exist, what each page is *for* (its goal), the IA changes, and sometimes specific copy that has already been decided (a chosen hero line, an exact CTA label). The spec is the primary source of content **intent**.
+- One or more **reference docs** in `reference/` — *current-state* guardrails. They do not usually carry page-level copy for new pages; they constrain how copy gets written: brand voice, audience model, tone modes, exclusions, settled positioning. Refs ground the spec and constrain slots the spec leaves underspecified — they are guardrails, not the canonical copy of new pages.
+
+When a spec leaves a content slot underspecified (e.g. it states a goal but doesn't prescribe exact words), the implementer fills the gap using, in order:
+
+1. The spec's stated goal for that slot.
+2. The project's brand-voice and language constraints — read whichever ref doc carries them in this project (typically named in the Understand step's findings).
+3. The tone mode the project's brand realization doc assigns to that page or surface.
+4. The persona's buying motion and pain points named in the project's brand ref / audience model.
+5. The **audience-type marketing skill** for this project, if it ships one (discovered in the Understand step). This skill carries the universal copy patterns for that audience type — frameworks, default moves, forbidden patterns. The project's brand ref carries project-specific patterns on top.
+
+If a content situation cannot be resolved by 1–5 (the refs don't cover it; the marketing skill is silent or absent; the spec doesn't speak to it), **flag it as a ref-doc gap or a spec gap** rather than guessing silently. Either:
+
+- Update the relevant ref doc in the same branch and proceed (small additions, e.g. a new *Do/Don't* row), or
+- File a follow-up issue and pick a placeholder for the current page (larger additions, e.g. a new persona).
+
+This protects the ref docs as durable guardrails and keeps the next page's implementer from re-deriving the same decision.
+
+## Workflow
+Prime directive: **Use beads issues for everything**. Beads has hierarchical issues (epics, features, tasks, sub-tasks, bugs). All steps of this website development workflow should be an issue, with appropriate dependencies and reference material (breadcrumbs, etc). We will use an epic root with `task` children for most work, and a `feature` container for the implementation tasks. If you find yourself doing work that is not in an issue, stop and create an issue for it.
+
+**Flow overview.** The website work ships as a chain of issues, each one a separate task whose output is written somewhere the next task can find it:
+
+> epic (root) → understand → plan → decompose → implement → review → punch-list → closeout
+
+The first issue is the epic root; working it produces the next issue(s), and so on. `bd-loop` picks up each newly-ready issue and runs it until the chain is complete.
+
+**The loop ends with the feature branch pushed for human review.** Merging, main-branch coordination, and branch deletion are out of scope for the loop. See step 6 (Closeout).
+
+### First step:
+1. **Create the root issue as an `epic`**: `bd create "<page or IA change>" -t epic`. This is the parent issue for all work tasks, and the rest of this workflow calls it the feature issue. Write a clear title and description that names the page(s) or IA change and links the driving spec (these are the 'breadcrumbs'). Ref-doc and marketing-skill identification happens in the Understand task (step 1 below); the feature issue does not need to enumerate them up front.
+
+   **Only `task` issues are claimed as work.**
+   `epic` and `feature` organise the tree and anchor dependencies, and a loop never picks either up, as "Hierarchy with `--parent`" in `boop-project-mgmt-beads-planning` explains.
+   The one consequence to plan for is the closing order in step 6: bd refuses to close an epic that still has an open child.
+
+### Task construction:
+Create tasks as child issues of the feature issue. The descriptions below are the content of the created issue — so don't *do* the work described in the issue description, this is just the content of the issue.
+
+1. **Understand the work**: First task issue goal (don't *do* this work, this is the content of the task issue): Read the driving spec. Then **discover and record this project's guardrails**. For example:
+   - **Brand reference doc(s)** — read `reference/` and identify which file(s) define brand voice, language constraints, audience / personas, exclusions, and (if separate) the site-realization / tone-mode doc. Typical names include `brand.ref.md`, `branding-site.ref.md`, a tenets doc, and a product / positioning doc. Record the exact file paths.
+   - **Audience-type marketing skill** — based on whom the project sells to, identify the appropriate marketing skill if the project ships one. Record the exact skill path (or note that none exists).
+   - **Web design skill** — record the web UI / design skill the project uses (e.g. `boop-web-web-ui-design`).
+
+   Then, against the driving spec and those guardrails, identify:
+   - Which routes / controllers / views already exist for each affected page, and which need to be created. **For surfaces that may be scaffold-provided (auth, settings, account), check `node_modules/@boopkit/*/scaffold/` for existing views / controllers / routes before treating them as new work** — e.g. `cap-users` scaffolds login/signup views, an auth controller, and auth routes. Reuse or extend the scaffold surface rather than re-deriving it.
+   - For each affected page, **which content slots the spec already specifies** (hero line, CTA copy, page goal, IA placement) and **which slots the spec leaves underspecified** (sub-messaging, body copy, section headers, secondary calls-to-action). Underspecified slots will be filled at implementation time per *Where website content comes from* above.
+   - Which **tone mode** applies to each affected page (per whichever ref doc defines tone modes for this project).
+   - Which **personas / audience-model entries** the page is targeting (per the project's brand ref).
+   - Any pages explicitly marked **untouched** by the driving spec — do not touch these.
+   - Any retired pages that need their route + controller + view deleted (and what the spec prescribes for their replacement behavior — 404, redirect, or other).
+   - Any **ref-doc gaps** — content situations the page needs to address that the project's refs don't currently cover. Note them for resolution in the plan step.
+
+   If anything is unclear, ask for clarification rather than guessing.
+
+   **Findings handoff (critical):** The next task runs in a fresh session with zero context — anything not written to a discoverable file is lost. Write findings to `specs/{feature-name}-plan-findings.md` covering:
+   - **Guardrail registry** — the exact paths of the project's brand ref doc(s), realization / tone-mode doc, audience-type marketing skill (or "none"), and web design skill. These are the breadcrumbs the rest of the loop will carry forward.
+   - Spec understanding (what the driving spec says).
+   - List of affected routes / controllers / views and list of retired routes (with prescribed replacement behavior), noting which surfaces are scaffold-provided.
+   - Per-page content sourcing (what the spec specifies vs what's left to implementation judgment).
+   - Tone selection per page.
+   - Persona / audience targeting per page.
+   - Identified ref-doc gaps.
+   - Open questions and decisions / recommendations.
+
+   Reference this file as a breadcrumb in the "plan" task's issue description. The guardrail registry inside the findings file is what propagates the project's specific artifacts into all subsequent work tasks. A `bd close --reason` one-liner or short `--append-notes` summary is fine as a supplement, but the findings file is the primary handoff artifact — issue fields have length limits and aren't diff-friendly.
+
+2. **Plan the work**: Next task (don't *do* this work, this is the content of the task issue): **Start by reading the findings** at `specs/{feature-name}-plan-findings.md` from the "understand" task (path is in this task's breadcrumbs; also check `bd show <predecessor-id>` notes). The findings include the guardrail registry (brand ref, realization doc, audience-type marketing skill, web design skill) — these are the breadcrumbs you will propagate into the implementation, review, and punch-list tasks below.
+
+   Then find or create the website implementation plan at `specs/{feature-name}-plan.md`. Follow the `boop-project-mgmt-engineering-planning` skill. The plan should enumerate, for each in-scope page:
+   - Route + controller + view file paths (existing or new; flag scaffold-provided surfaces).
+   - **Per-block content sourcing** — for each major content block, whether the copy comes verbatim from the spec, is paraphrased from the spec, or will be written at implementation time per the project's brand-voice ref grounded by the audience-type marketing skill.
+   - The **tone mode** that applies (per the project's realization doc).
+   - The **persona(s)** the page is speaking to (per the project's brand ref).
+   - Any partials or semantic CSS classes that already exist and can be reused (per the project's web design skill).
+   - Any new semantic CSS classes that will be introduced.
+   - Metadata (page title, OG image strategy, description sourced from the hero lede).
+   - **Ref-doc gap resolution** — for each gap identified in step 1, either (a) a small in-branch ref-doc edit to close the gap, or (b) a placeholder for the page with a follow-up issue.
+   - **Acceptance** — what "done" looks like for this page (rendered in the browser per the project's golden path, brand-voice-aligned, semantic HTML, working CTAs, no broken links).
+
+   When you decompose the plan into implementation sub-tasks (step 3), **include the guardrail registry as breadcrumbs in each sub-task**: the brand ref doc(s), the realization / tone-mode doc, the audience-type marketing skill, the web design skill, and the per-page tone / persona selections from the plan. Review the plan to ensure it fully covers the spec; create follow-up tasks for any gaps it can't resolve.
+
+3. **Decompose the plan**: Next task (don't *do* this work, this is the content of the task issue): **Start by reading the website implementation plan** at `specs/{feature-name}-plan.md` (confirm path from this task's breadcrumbs). Break it down into a "do the work" container, a `feature`-typed organiser rather than a task, holding one `task` child per unit of work, following the `boop-project-mgmt-beads-planning` skill.
+
+   Sub-task granularity for website work is typically **page-level or surface-level**: one sub-task per new page, one per page rewrite, one per retired-route deletion, one for global-nav structure, etc. Shared concerns like semantic CSS extensions or new partials get their own sub-tasks and become blockers for the pages that depend on them.
+
+   **Propagate the guardrail registry into every sub-task as breadcrumbs** — brand ref doc(s), realization / tone-mode doc, audience-type marketing skill, web design skill — so the implementation agent does not have to re-discover them.
+   Write the skills among them, and any other skill the sub-task's work needs, as the skills list that `boop-project-mgmt-beads-planning` sets out in its section "Breadcrumb the skills that carry the discipline": a `## Skills` heading, the line "Before making changes, read each of these in full.", and a path to each skill's `SKILL.md`.
+   The session that claims a sub-task reads its issue, not this workflow, so a skill the issue only names in passing is one it rarely opens.
+
+   **Put the test run scope on every implementation sub-task.**
+   Each sub-task runs the focused tests for what it touches, plus the project's whole-program static check; the full suite runs once per branch, on the Review task in step 4.
+   Left unstated, a sub-task that has just changed a shared partial or a widely used helper runs the whole suite on its own reasoning.
+   The rule and the wording to put on each are in the section "Test run scope: what each task runs, and what runs once" in `boop-project-mgmt-beads-planning`.
+
+   **Audit the sub-task bodies before this task closes, then revise them.**
+   Writing an issue and auditing it are separate passes, and doing both at once produces bodies that read well to their author and cost their reader time.
+   Once every sub-task exists, re-read them all side by side as the agent who will claim each one cold, following the section "Write, audit and revise in three separate turns" in `boop-project-mgmt-beads-planning`, then rewrite whatever the audit finds.
+   Some faults show only side by side: a sub-task that says "a sibling issue handles this" without naming it, or a term the container defines and a sub-task then uses bare.
+
+   Create the feature branch `work/<feature-issue-id>` (e.g. `work/boop-arc.14`) — branch names MUST use the `work/` prefix + issue ID, never feature names like `home-page-refresh`. All sub-tasks work within this branch.
+
+   **Wire Review to each sub-task (critical):** Decompose only plans the work, so Review (step 4) must not depend on this task.
+   It must not depend on the container either: bd never closes a container on its own, so an edge on it holds Review until someone closes the container by hand, which is not the same event as the work being done.
+   Give Review one plain `blocks` edge on each sub-task instead, so it becomes ready only when every sub-task has closed:
+   ```
+   bd dep remove <review-task-id> <this-decompose-task-id>   # only if Review was wired to Decompose
+   bd dep add    <review-task-id> <sub-task-id>              # once per sub-task
+   ```
+   If Review doesn't exist yet, create it now with those edges.
+   Every edge in this tree is plain `blocks`.
+   Step 3 of `boop-feature-dev-workflow` gives the whole tree recipe, why each piece is shaped as it is, and how to verify the wiring.
+
+4. **Review the work done**: Next task (don't *do* this work, this is the content of the task issue). Blocked by each sub-task of the "do the work" container from step 3, so it runs only once all of them have closed (step 3 wires this, and rewires it if Review was created with an edge on Decompose). Review all changes **in the feature branch** `work/<feature-issue-id>` (confirm with `git branch` or breadcrumbs). Run `bd children <feature-issue-id>` to see what sub-tasks were created and closed for context. Pull the **guardrail registry** from the findings file (`specs/{feature-name}-plan-findings.md`) before reviewing — every review below is anchored against those project-specific guardrails. This task will:
+   - Perform a **code review and content review** of all changes in the feature branch. The content review checks that each affected page (1) implements the driving spec's stated intent for every page-level goal, (2) where the spec specifies exact copy, uses that copy verbatim, and (3) where the spec leaves a content slot to implementation judgment, the copy aligns with the project's brand-voice ref and the audience-type marketing skill (no copy pitched at a different audience, no forbidden patterns, no superlatives without evidence, no invented positioning that contradicts settled ref-doc content).
+   - Perform a **brand-voice review** against the project's brand ref doc — its voice / language constraints / do-don't / exclusions sections. Flag any drift from the project-specific rules.
+   - Perform a **marketing-copy review** against the audience-type marketing skill (if the project ships one) — its universal forbidden patterns (hype cadence, vague universals, unearned superlatives, copy pitched at the wrong audience) and its quick self-check.
+   - Perform a **tone-mode review** — each page uses the tone mode named in the plan (per the project's realization doc's tone-mode assignments).
+   - Perform a **machine-readability / semantic-HTML review** — headings describe sections; meaningful prose is in the HTML rather than JS-injected; code samples are `<pre><code>`, not background images; copy-paste-safe snippets; plain URLs for the things that matter; OG / meta descriptions truthful (and ideally lifted from the hero lede).
+   - Perform a **browser validation** — start the dev server on a port confirmed free (`lsof -ti tcp:<port> -sTCP:LISTEN` prints nothing when free), load each affected page, and confirm the golden path (page renders, primary CTA is wired correctly, internal links work, no console errors, no broken images, the project's theme is intact, no contrast regressions). Test the page narrow (mobile-ish) as well as wide. Drive it as the section "Verifying a change someone will look at" in `boop-web-testing` describes, which names the traps a browser pass falls into. **If browser validation isn't possible in this environment, say so explicitly — do not claim success.** (Per project `CLAUDE.md` / `AGENTS.md` conventions where present — *for UI or frontend changes, start the dev server and use the feature in a browser before reporting the task as complete.*)
+   - **Stop the dev server this task started** before it closes.
+     Stop all of it, not only the process on the port.
+     A dev script that watches files runs a supervisor above the server, and only the server holds the port: boop's web-app profile runs `nodemon --exec tsx src/server.ts`, so killing the port holder leaves `nodemon` running while the port reads free, and `nodemon` starts the server again on the next file change.
+     Find the supervisor by the worktree's absolute path in its command line, `ps -eo pid=,args= | grep "<absolute-worktree-path>/node_modules/.bin/[n]odemon"`, with the dev script's own watcher in place of `nodemon` if it runs another, and kill that pid; the server under it stops too.
+     Then run that search again and `lsof -ti tcp:<port> -sTCP:LISTEN`, and confirm both print nothing, because a free port does not show that the supervisor is gone.
+     If the dev script runs no supervisor, the process on the port is the whole server, and `lsof -ti tcp:<port> -sTCP:LISTEN | xargs kill` stops it.
+     Never pattern-kill (`pkill -f nodemon`, `pkill -f tsx`, and the like): a pattern reaches every other worktree's server and the operator's own.
+     Never stop a server you did not start, or one a running loop owns: if the port you wanted is already held, identify the holder's cwd via `lsof -a -d cwd -p <pid> -Fn` and reuse it only when the directory is this feature's worktree, else take the next free port.
+   - Run the **full test suite** once, plus the project's whole-program static check. This is the branch's only full-suite run; every implementation sub-task ran focused tests.
+   - Perform an **IA review** — the top-nav structure matches the driving spec; retired routes return the spec's prescribed behavior (404, redirect, or other); any home-page cross-links the spec prescribes are present; the primary CTA destination exists and is reachable from every surface that the spec routes traffic from.
+   - Write the review to `labs/claude-runs/{feature-issue-id}-review-summary.md`, structured as: code findings, content findings, brand-voice findings, marketing-copy findings, tone-mode findings, semantic-HTML findings, browser findings, IA findings, and an overall punch-list.
+   - Append a **punch-list** of issues that must be addressed before merge. Punch-list items typically span categories: code (refactor, naming, controller cleanliness), content (drift from spec intent or from brand-grounded copy judgment), brand-voice (project-specific forbidden phrasing, wording more formal, casual or salesy than the brand ref allows), marketing-copy (universal forbidden patterns — hype cadence, vague universals, unearned proof), tone (wrong mode applied), semantic HTML (heading order, missing alt text, JS-injected content), browser (visual bugs, broken links, console errors, mobile breaks, contrast issues), and IA (wrong nav, missing cross-links, retired routes still live).
+
+5. **Add a punch-list work task**: Create a 'punch list' task issue as a child of the feature issue. Its goal: turn each item in the punch-list from the review document into a sub-task issue under this punch-list task. **Propagate the guardrail registry into the punch-list task and its children** so the fixers operate against the same brand ref / marketing skill the implementation did.
+
+  **Hierarchy rule:** Create punch-list items with `--parent <punch-list-task-id>` so they are true hierarchical children: `bd create "..." --parent <punch-list-task-id> ...`. `bd dep add` creates sequencing only — it is not a substitute for `--parent`. Sequencing deps between siblings are fine to add after creation.
+
+  **Verify before closing the punch-list task:** Run `bd children <punch-list-task-id>` and confirm every item appears in the tree. Fix any missing item with `bd update <id> --parent <punch-list-task-id>` (remove conflicting deps first if needed). Only close once the tree is correct.
+
+  **Hold Closeout until every fix is done (critical):** a `blocks` edge on the punch-list task alone releases Closeout when that task closes, which can happen while its fix sub-tasks are still open, and Closeout would then archive the spec and update reference against the pre-fix site.
+  Once `bd children` lists every fix sub-task, create Closeout (step 6) if it does not exist yet, with a `blocks` edge on the punch-list task, and add a `blocks` edge from Closeout onto each fix sub-task: `bd dep add <closeout-task-id> <fix-sub-task-id>`.
+  Confirm with `bd dep list <closeout-task-id>` that the punch-list task and every fix sub-task are there, and only then close the punch-list task.
+  If Review found nothing to fix, the edge on the punch-list task is enough.
+  Step 5 of `boop-feature-dev-workflow` gives the full order.
+
+  Punch-list sub-tasks of category "browser" or "content" should re-validate in the dev server after the fix, and each such sub-task stops the server it started before it closes, on the same terms as the browser validation in step 4. There is one sub-task per punch-list item, so deferring the stop to closeout leaves one stray watcher process per item. Sub-tasks of category "brand-voice" or "tone" should re-check against the project's brand ref doc. Sub-tasks of category "marketing-copy" should re-check against the audience-type marketing skill.
+
+6. **Close out the website work**: After the punch-list is resolved and the website work is complete, create a closeout task as a child of the feature issue, if step 5 has not already created it, blocked by the punch-list task and by each of its fix sub-tasks. The closeout task performs two activities:
+
+   **a. Archive the spec:**
+   - Move the completed driving spec from `specs/` to `specs/history/` (create the directory if it doesn't exist).
+   - If any aspects of the spec were NOT implemented (deferred, descoped, or punted), extract those into a new revised spec in `specs/` that captures just the remaining work. Reference the archived spec for full context.
+   - The archived spec should be the full original — do not edit or trim it.
+   - If the work was driven by a *content* spec layered on top of a still-open *IA* spec, archive only the content spec and leave the IA spec in place.
+
+   **b. Integrate into reference:**
+   - Follow the `boop-product-design-reference-integration` skill to blend the new website knowledge into existing `reference/` pages.
+   - This is NOT "create a new page for the feature". Name the subjects the work created or changed, the way a reader would look them up; merge each into the page whose title names it, and give a subject its own page when it has none or has outgrown the page it sits in.
+   - **Write this task's description as what was learned, not as pages to edit.** When you create the closeout task, list the knowledge the work produced: what the site now says and where, what was retired, and what voice or audience rules the work surfaced. A page list written before the work can only name pages that already existed, and the session that runs closeout tends to treat it as the whole job.
+   - The **guardrail registry** captured in the findings file names the pages most likely to change. Check each of them, as a starting point rather than the scope:
+     - The project's brand realization / site doc — IA, page roster, retired-surfaces list, tone-mode assignments, any messaging tables (if rows changed).
+     - The project's brand ref doc — any voice / language drift discovered during implementation that warrants a new *Do/Don't* row, a new entry in *Language we avoid*, a new persona, etc.
+     - Any other project ref docs that surfaced gaps during the work.
+   - Update cross-links between affected reference pages.
+   - Remove or update any reference content that is now outdated (e.g. stale URLs, retired surfaces that the ref doc still names as live).
+
+   **c. Hand off — the loop ends at the feature branch:**
+
+   Terminal state: closeout commits pushed on `work/<feature-issue-id>`, beads synced, feature issue closed. A human reviews and (if approved) merges.
+
+   **Scope boundary:** Authority ends at the feature branch. The branch (local and remote) stays intact after closeout so the reviewer can inspect it — including a browser pass — and so it remains a revert anchor. Merging, pushing to `main`, and branch deletion belong to the human reviewer — partly because concurrent worktrees may have other `work/<id>` branches in flight that need out-of-band coordination.
+
+   **Final actions of the closeout task (in order):**
+   1. Commit the closeout edits (spec archive + reference updates) on the feature branch.
+   2. `git push` the feature branch to its own remote ref.
+   3. `bd dolt push` so beads state is synced.
+   4. Close the tree from the bottom up, because bd refuses to close an epic that still has an open child:
+      ```
+      bd close <do-the-work-container-id>   # a feature; its sub-tasks closed before Review ran
+      bd close <closeout-task-id>           # this task, the last open child of the root
+      bd close <feature-issue-id>           # the epic root, now that every child is closed
+      ```
+      If the last close fails, bd reports how many children are still open: find them with `bd children <feature-issue-id>` and find out why each is open before trying again, rather than forcing the close.
+   5. Stop. The loop will go idle on "No ready issues for prefix"; the next action belongs to the human reviewer.
+
+## Related
+
+- [`boop-web-web-ui-design`](../boop-web-web-ui-design/SKILL.md) — the primary design skill for this workflow; read it at the design step, before deciding what a page is made of.
+- `boop-ux-purpose-judgement` — when reviewing the rendered page, to ask whether each thing on it belongs there at all, which the visual pass does not ask.
+- [`boop-web-design-handoff-bundle`](../boop-web-design-handoff-bundle/SKILL.md) — when the pages' design arrives as a design canvas rather than a spec; bundle it before building.
+- `boop-writing-technical-prose` — when writing the driving spec and the child issues; each is picked up cold by an agent who was not in this session.