@boopkit/cap-workflows 0.2.2 → 0.2.3

package/capability.json

@@ -1,6 +1,6 @@
 {
   "name": "workflows",
-  "description": "Reusable end-to-end development and writing workflows",
+  "description": "Reusable end-to-end development and audit workflows for code",
   "type": "development",
   "package": "@boopkit/cap-workflows",
   "dependencies": [],
@@ -11,11 +11,28 @@
     "boop-light-dev-workflow",
     "boop-refactor-dev-workflow",
     "boop-test-audit-workflow",
-    "boop-architecture-audit-workflow",
-    "boop-issue-sweep-workflow",
-    "boop-website-dev-workflow",
-    "boop-design-handoff-workflow",
-    "boop-knowledge-backfill",
-    "boop-stray-disposition"
-  ]
+    "boop-architecture-audit-workflow"
+  ],
+  "file_moves": {
+    "skills/boop-website-dev-workflow/": {
+      "capability": "web",
+      "path": "skills/boop-web-website-dev-workflow/"
+    },
+    "skills/boop-design-handoff-workflow/": {
+      "capability": "web",
+      "path": "skills/boop-web-design-handoff-workflow/"
+    },
+    "skills/boop-issue-sweep-workflow/": {
+      "capability": "project-mgmt",
+      "path": "skills/boop-project-mgmt-issue-sweep-workflow/"
+    },
+    "skills/boop-stray-disposition/": {
+      "capability": "project-mgmt",
+      "path": "skills/boop-project-mgmt-stray-disposition/"
+    },
+    "skills/boop-knowledge-backfill/": {
+      "capability": "product-design",
+      "path": "skills/boop-product-design-knowledge-backfill/"
+    }
+  }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@boopkit/cap-workflows",
-  "version": "0.2.2",
-  "description": "Reusable end-to-end development and writing workflows for AI agents",
+  "version": "0.2.3",
+  "description": "Reusable end-to-end code development and audit workflows for AI agents",
   "files": [
     "skills/",
     "capability.json"

package/skills/boop-architecture-audit-workflow/SKILL.md

@@ -183,7 +183,7 @@ The last three are the same problem at different scales, and together they are t
 | Judge an area's structural health, decide what is worth fixing, and plan it | **this** |
 | Execute a structural change you have already decided on | [`boop-refactor-dev-workflow`](../boop-refactor-dev-workflow/SKILL.md) |
 | The tests around the area cannot catch a behaviour change | [`boop-test-audit-workflow`](../boop-test-audit-workflow/SKILL.md) first |
-| Clear a noisy backlog of small lingering items in a themed sweep | [`boop-issue-sweep-workflow`](../boop-issue-sweep-workflow/SKILL.md) |
+| Clear a noisy backlog of small lingering items in a themed sweep | `boop-project-mgmt-issue-sweep-workflow` |
 | Extend an existing system toward a goal, wiring new behaviour from parts that exist | [`boop-light-dev-workflow`](../boop-light-dev-workflow/SKILL.md) |
 | Find bugs in a diff | `boop-coding-review-changes` |
 

package/skills/boop-feature-dev-workflow/SKILL.md

@@ -53,7 +53,7 @@ Read all three for any code-touching task. They cover different layers, and the
 
 - `boop-testing-testing` — the foundational testing skill: pairwise producer/consumer contracts, integration vs. unit decisions, mock boundaries, data-driven config coverage. Read this **before** picking a test shape; it tells you which shape the change actually needs.
 - `boop-testing-tdd-light` — the Light TDD cycle: the Red / Green / Verify loop applied to features and bug fixes.
-- `boop-testing-testing-express-web` — the domain-specific test skill for services, controllers, middleware, and route tests in the Express stack.
+- `boop-web-testing` — the domain-specific test skill for services, controllers, middleware, and route tests in the Express stack.
 
 ### Documentation 
 - `boop-product-design-feature-documentation` — when you need to write feature documentation.
@@ -165,7 +165,7 @@ Create tasks as child issues of the feature issue. The descriptions below are th
 
    **UX paired-lens pass (when the feature includes new or substantially modified UI surface):** If the spec touches the app's UI surface, run a paired-lens pass during planning so the plan and downstream punch-list carry explicit UI work and acceptance criteria. The two cases are not symmetric:
    - **Brand-new surface (the page does not exist yet):** run `boop-ux-purpose-judgement` against the spec, reference docs, and any existing nearby templates that anchor the register. **Do not try to screenshot a not-yet-built surface** — the purpose lens has an explicit fallback for missing inputs; use it and label each finding by which inputs supported it. The output validates the spec's interaction-shapes table: each affordance traced to a job, mechanism matched against frequency × consequence, anything underspecified flagged as a plan or punch-list candidate. Optionally run `boop-ux-visual-judgement` against a nearby existing surface for **register calibration only** (output is "the calm/loud target the new surface should match," not findings about the unbuilt page); skip it if no nearby surface is a useful anchor.
-   - **Modified existing surface (the page exists and is being changed):** capture a screenshot of the current surface with the capture script cap-ux ships (`scripts/ux-eval-capture.ts`), then run both lenses in order — purpose first, visual second.
+   - **Modified existing surface (the page exists and is being changed):** capture a screenshot of the current surface with `npm run ux:capture -- <path> <label>`, then run both lenses in order — purpose first, visual second.
    Write the lens findings into the same `specs/{feature-name}-plan-findings.md`, labelling each with the lens that produced it (`[purpose]` or `[visual]`) and noting which inputs were loaded.
 
 3. **Decompose the plan**: Next task (don't *do* this work, this is the content of the task issue): **Start by reading the engineering 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, never a task — holding smaller, manageable `task` children, following the `boop-project-mgmt-beads-planning` skill for the issue mechanics (hierarchy, dependencies, breadcrumb links). 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 `email-capability`. All sub-tasks work within this branch.
@@ -286,7 +286,7 @@ Create tasks as child issues of the feature issue. The descriptions below are th
    **UX paired-lens pass (when the change touched UI files):** if `git diff main...HEAD -- views/ styles/ src/controllers/` shows changes, the surface needs a post-build UX review. The page now exists, so both lenses run normally against it:
 
    1. Pick a port and confirm it is free before you start anything: `lsof -ti tcp:<port>` prints nothing when the port is free. Then start the dev server in the feature worktree: `PORT=<port> npm --prefix <absolute-worktree-path> run dev` — the `--prefix` form is required; `cd <worktree> && npm run dev` silently falls back to the project root and screenshots the wrong build. If the port is already held, do not kill what is there and do not assume it serves your code — several worktrees and loops can run at once. Identify the holder with `lsof -a -d cwd -p <pid> -Fn` and reuse the server only when that directory is this feature's worktree; otherwise move to the next free port.
-   2. Capture each changed surface with `scripts/ux-eval-capture.ts`.
+   2. Capture each changed surface with `npm run ux:capture -- <path> <label>`, passing `BASE_URL=http://localhost:<port>`.
    3. Run `boop-ux-purpose-judgement` first against the screenshot plus the rendered HTML, template, controller, and route. Run `boop-ux-visual-judgement` second against the screenshot.
    4. Label findings by lens (`[purpose]`, `[visual]`) in `labs/claude-runs/{feature-issue-id}-review-summary.md`, alongside the code-review findings, and feed them into the punch-list the same way code-review findings do.
    5. **Stop the dev server before this task closes**, unless you reused one you found already running. Stop it by port: `lsof -ti tcp:<port> | xargs kill`. Never pattern-kill (`pkill -f nodemon`, `pkill -f tsx`, and the like) — a pattern matches every other worktree's server and the operator's own, and this project routinely has several alive at once. Never stop a server you did not start, including any port a concurrently running loop owns.

package/skills/boop-light-dev-workflow/SKILL.md

@@ -93,7 +93,7 @@ The trap is symmetric across all three: designing from the summary (the issue, t
 | Greenfield: a new subsystem, data model, or API driven from a spec | [`boop-feature-dev-workflow`](../boop-feature-dev-workflow/SKILL.md) |
 | An open-ended "make this page better / find what's wrong" eval that should grow the judgement skill | `boop-ux-eval-and-refine-workflow` |
 | A page UX delivery campaign with a finding budget and per-finding decomposition | `boop-ux-app-ui-dev-workflow` |
-| A noisy backlog of small lingering items to clear in a themed sweep | [`boop-issue-sweep-workflow`](../boop-issue-sweep-workflow/SKILL.md) |
+| A noisy backlog of small lingering items to clear in a themed sweep | `boop-project-mgmt-issue-sweep-workflow` |
 
 **Bounded on both ends.** *Above:* if *investigate* or *design* reveals the work is actually greenfield — a genuinely new subsystem, a real data-model design, no existing pattern to extend — it has left this workflow's domain; say so and escalate to `boop-feature-dev-workflow` rather than forcing a redesign through a single grounded session. *Below:* if the change is a one-liner or a lone edit that does not decompose into several grounded issues, it is beneath this workflow — a plain bd issue or a direct fix is the right tool, not an epic.
 

package/skills/boop-test-audit-workflow/SKILL.md

@@ -138,7 +138,7 @@ This is the work of the coverage and review children, and the loop's own closeou
 | Remove tests that do not exercise the purpose of the code, and re-level the ones written against the mechanism, without losing coverage | **this** |
 | Extend an existing system toward a goal, wiring new behaviour from parts that already exist | [boop-light-dev-workflow](../boop-light-dev-workflow/SKILL.md) |
 | Build a genuinely new subsystem, data model, or API from a spec | [boop-feature-dev-workflow](../boop-feature-dev-workflow/SKILL.md) |
-| Clear a noisy backlog of small lingering items in a themed sweep | [boop-issue-sweep-workflow](../boop-issue-sweep-workflow/SKILL.md) |
+| Clear a noisy backlog of small lingering items in a themed sweep | `boop-project-mgmt-issue-sweep-workflow` |
 
 If the set of tests is small enough that the audit is a handful of edits with no real decomposition, skip the epic and do the rewrite under a plain bd issue. This workflow is for a surface big enough that classifying first, then executing, earns its keep.
 

package/skills/boop-design-handoff-workflow/SKILL.md

@@ -1,97 +0,0 @@
----
-name: boop-design-handoff-workflow
-description: "When the operator hands off a design package (a README plus a drop-in view template and CSS) for a redesigned surface, follow this process: read the README, VERIFY its claims against the real code, surface any buried decision to the operator, file an issue, run it as a sub-agent (branch for UAT or merge-on-clean-visual-check), then close out with knowledge integration and archival. The README is confident; confidence is not correctness — verify before you run."
-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.
-
-# Design-handoff workflow — turn a design package into shipped, reviewed code.
-
-A design handoff package is a high-leverage input: someone has already done the design work and grounded it against the real view-model, so the implementation is mostly mechanical. The leverage is real, but so is the risk, and the risk lives in one place — **the README's claims about the existing code.** A handoff that says "the service already computes X, just re-expose it" is trivial if true and a hidden architectural decision if false. The whole process turns on verifying those claims before any code is written.
-
-## What a handoff package looks like
-
-Three files, typically grouped under a per-handoff directory in the project's design/eval reference area:
-
-- **`README.md`** — the authoritative spec. Names what is being built, which files it replaces, a "Data to surface" list (the view-model fields the redesign needs that the controller does not pass yet), what was deliberately dropped, and any follow-ons that are explicitly out of scope.
-- **A drop-in view template** — replaces an existing view. Every new field is guarded (rendered only when the field is present) with a live fallback, so the template renders *today* against the current view-model and "lights up" as each data field lands. Ship the template first, work the data list independently.
-- **A CSS file** — appended into an existing style block; its header comment names the rules it supersedes.
-
-## The process
-
-### 1. Read the README in full
-
-It is the spec — read it before touching anything. Note the "Data to surface" items (the view-model gaps), what it claims already exists, what it dropped and why, and the named follow-ons.
-
-### 2. Verify the README's claims against the real code (the load-bearing step)
-
-The README makes assertions about the current code: "X already exists," "Y was retired," "field Z is right there on the type," "this renders today with zero controller changes." **Every one of those is a feasibility claim, and each must be checked against the actual code before you judge the package.** This is the step that separates a clean run from a buried decision.
-
-- Confirm each "already exists" / "is right there" claim by reading the named symbol. (In a real run: a handoff claimed a field was "right there" — it was, on the underlying type, just dropped on the way to the view-model; trivial. Another claimed an upstream surface "already computed" a value — it deliberately did *not*, behind a documented boundary; that was a hidden architectural decision, not a re-expose.)
-- Confirm the template's "renders today" claim: the fields it depends on now exist on the view-model (or are provided by the controller), and the genuinely-new fields are guarded with a fallback.
-- Confirm any "retired" / "dropped" claim — a value the README says is gone may still be live and reusable.
-
-When every claim checks out, it is a clean single sub-agent run. When a claim is wrong — especially when "re-expose this" turns out to mean "reverse a deliberate architectural boundary" — there is a design decision hiding inside the package.
-
-### 3. Judge feasibility for a single sub-agent run
-
-Ask: is the work bounded with a clear path, or is there a judgment call hiding — an architectural decision, a premise error in the README, a spec ambiguity, a value that has to be derived rather than re-exposed? If the path is clear, it is one sub-agent run. If a decision is hiding, **do not let a sub-agent silently resolve it** (it will take the easy path — e.g. calling the function that reverses the boundary — because that is what "makes it work").
-
-### 4. Surface the verdict and any decision to the operator
-
-Report: feasible or not, the scope, and the one question that is genuinely theirs — the buried architectural decision, framed at their altitude with a recommendation. Use `boop-product-design-thought-partnership` here. Get the call, then bake the decision into the issue so the sub-agent inherits it rather than re-deriving it. (Example: "derive the value from the shared source, not by duplicating — the README's 're-expose' framing assumed an upstream surface already had it, which it didn't.")
-
-### 5. File a bd issue (goal/approach/context shape)
-
-Per `boop-project-mgmt-beads-planning`. Breadcrumb the handoff README as the authoritative spec, and **if the operator settled a decision in step 4, state it in the issue and say it supersedes the README where they differ** — otherwise the sub-agent will follow the README's wrong premise. Note the template's graceful-degradation (template + CSS can drop first; view-model edits light it up). Name the visual-check as the done-gate.
-
-### 6. Run it as a sub-agent
-
-- **Isolated worktree on a non-default port.** The operator's dev server on the main checkout (e.g. `:3000`) is theirs — never touch it. Create a worktree branch off main (e.g. `work/<id>`), run the worktree's dev server on a different port (`:3001`/`:3002`/etc.), copy `.env` in if tests/capture need it (gitignored, don't commit).
-- **Apply template + CSS**, removing the rules the CSS header names as superseded.
-- **Make the view-model edits** per the (corrected) data list.
-- **Trim brittle tests rather than lovingly rework them.** A redesigned surface is in flux; the operator's visual UAT is the safety net. Keep the full suite green; do not invest in expanding coverage on a surface that is still moving.
-- **The visual-check is the gate.** Build the CSS bundle, capture the affected states at desktop (1280) and mobile (390), and *read* the captures — the render is the proof, not the diff. (Auth caveat: the default capture tool may log in as a demo account and not reach the populated data you need; use a capture path that authenticates as the fully-populated account so the render shows real content.)
-- **Never `pkill` or pattern-kill a process** — an over-broad `pkill -f "<server command>"` can kill the operator's main-checkout server. Stop only your own server, by precise PID via `lsof -i:<port>`.
-- **Disposition:**
-  - **Branch for UAT** when the change is a substantial visual redesign the operator will want to see — leave the branch, the worktree, and the captures; do not merge, do not close.
-  - **Merge on a clean visual-check** when the change is quick, clear, and additive — merge to main only if the capture clearly confirms the result and tests are green; if verification is blocked or ambiguous, fall back to branch-for-UAT rather than merging blind.
-
-### 7. Close out (after the operator's UAT, or on a clean merge)
-
-Often itself a sub-agent. Per [`boop-knowledge-backfill`](../boop-knowledge-backfill/SKILL.md):
-
-- **Merge** the branch to main; run the full suite green first.
-- **Integrate the knowledge** — update the relevant reference page (e.g. the web-UI reference for a redesigned surface) to describe the new shape, and fix any reference line the redesign made stale. Commit docs direct to main.
-- **Archive the handoff package** (unedited) to `specs/history/<name>-handoff/`.
-- **Clean up** — close the issue, remove the worktree, delete the branch, stop the server by precise PID. Do not push to origin unless asked.
-
-## When to use this vs the other workflows
-
-| Situation | Workflow |
-|---|---|
-| A design handoff package (README + drop-in template + CSS) for a surface | **this** |
-| A goal-framed improvement to an existing surface, no package | [`boop-light-dev-workflow`](../boop-light-dev-workflow/SKILL.md) |
-| A backlog cleanup sweep of lingering P1/P2 items | [`boop-issue-sweep-workflow`](../boop-issue-sweep-workflow/SKILL.md) |
-| A feature with backend work driven by a spec | [`boop-feature-dev-workflow`](../boop-feature-dev-workflow/SKILL.md) |
-
-## Anti-patterns
-
-- **Running the package without verifying its claims.** The README reads as authoritative; authority is not accuracy. The verify-against-code step (2) is the whole game — skip it and you ship a hidden decision or hit a wall mid-run.
-- **Letting a sub-agent resolve a buried architectural decision.** When "re-expose X" actually means "reverse a documented boundary," a sub-agent will reverse it because that is the path of least resistance. Surface it to the operator instead.
-- **Auto-merging a substantial visual redesign without the operator's eye.** Branch for UAT. Reserve merge-on-clean-visual-check for quick, clear, additive fixes.
-- **Lovingly reworking brittle tests on a surface in flux.** Trim them; the visual UAT is the safety net. Reworking assertions that the redesign is about to invalidate again is wasted effort.
-- **`pkill`.** It can kill the operator's main-checkout server. Precise PID only, and never the main checkout's server.
-- **Following the README's premise after the operator corrected it.** If step 4 settled a decision, the issue must say it supersedes the README, or the sub-agent inherits the wrong framing.
-- **Taking a package's scope at face value against the full mockup.** A handoff package may be a *subset* of the designer's full vision: a package redesigned only the primary list and scoped the header and empty-state out as "unchanged," but the full mockup redesigned them too — the gap only surfaced at the operator's UAT. In step 2/4, confirm the package's scope against the full design mockup; a package that says parts are "unchanged / out of scope" may still leave the surface divergent from what the operator expects. Surface that at UAT.
-
-## Related
-
-- [`boop-knowledge-backfill`](../boop-knowledge-backfill/SKILL.md) — the archive + reference-integration discipline for the closeout.
-- `boop-web-web-ui-design` — the visual-check-before-done rule the run leans on.
-- [`boop-light-dev-workflow`](../boop-light-dev-workflow/SKILL.md) — the per-issue beats that run inside the sub-agent.
-- `boop-product-design-thought-partnership` — surfacing the buried decision at the operator's altitude.

package/skills/boop-issue-sweep-workflow/SKILL.md

@@ -1,180 +0,0 @@
----
-name: boop-issue-sweep-workflow
-description: "When the bd queue has accumulated a noisy backlog of lingering P1/P2 items — paper-cuts, small refactors, dead code, cosmetic bugs, taxonomy drift — and you want to clear them autonomously in a sequence that supports the week's goals, follow this process: inventory → cluster by theme → pick a cluster with the operator → run autonomously in one sweep worktree → hand off for a single UAT pass → log. The work lands in a worktree for one operator review rather than on main; it arrives with no decisions left in it."
-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.
-
-# Issue sweep workflow — clear lingering backlog noise without spending the operator's judgment.
-
-The bd queue accumulates a long tail of lingering items: small refactors that didn't get done at the time, cosmetic bugs that nobody had cycles for, dead code that got noticed but not removed, taxonomy drift that someone filed and then moved on from. Each one is small. The cost is not the work; the cost is **carrying them in mind** — every `bd ready` listing them, every plan revisited with them open, every "should I do this now or later" decision. The mental load is the load.
-
-Issue-sweep clears that load. The workflow's deliverable is **one sweep worktree carrying N verified fixes, ready for a single operator UAT pass, with no decisions left in it** — not main with the issues already merged and closed.
-
-The load being cleared is **decision** load, not review load. The operator still looks at the result once, but they never have to answer a question to get there: N issues that each carried a "should I, and how?" collapse into one "does this look right?" That is a real reduction, and it is the only one the workflow promises. Anything that survives the run and grows the queue instead — a branch full of open questions, a findings doc to read, a follow-up issue to triage, a list of next steps to weigh — relocates noise from the bd list into the operator's review queue. That is not a reduction; it is a transfer.
-
-## When to use this vs the other workflows
-
-| Situation | Workflow |
-|---|---|
-| A backlog of lingering P1/P2 paper-cuts, small refactors, dead code, cosmetic fixes that the operator wants cleared in the background | **this** |
-| A concrete improvement to one existing surface, framed as a goal, whose design the operator wants to weigh in on | `boop-light-dev-workflow` |
-| A new feature with backend work driven by a spec | `boop-feature-dev-workflow` |
-| A page UX delivery campaign with a finding budget | `boop-ux-app-ui-dev-workflow` |
-
-The contrast with light-dev is no longer *where the work lands* — both end in a worktree the operator reviews. It is *what the operator has to bring to that review*. Light-dev hands back a change whose design the operator is expected to weigh in on. Issue-sweep hands back a batch of fixes that were only eligible because no weighing was needed, so the review is a look rather than a decision. If an issue requires operator judgment to ship — a copy choice, a design tradeoff, a fix path that isn't already named — it is not eligible for issue-sweep this pass, regardless of priority. The operator's judgment is exactly what the workflow exists to avoid spending.
-
-## Authority granted on launch
-
-When the operator invokes issue-sweep, they grant the agent authority — scoped to that run — to:
-
-- Create the sweep branch and worktree, plus a separate worktree for any item that routes as its own light-dev run.
-- Claim the issues it takes on, so they leave `bd ready` and stop presenting as open decisions.
-- Commit, run tests, run the visual-check for UI changes.
-- Close issues it finds were **already shipped** — those need no review, and the queue should shrink immediately.
-- Delete branches and worktrees for items it abandons.
-
-Two things the sweep may **not** do: merge to main, and close an issue as fixed before the operator has taken the worktree through UAT. Everything else stays on the worktree; issues it works stay **claimed and open** until sign-off. The audit trail is `git log`, the claimed/closed state in bd, and the append-only log file (below). This is a deliberate but bounded exception to the conservative-profile default in `CLAUDE.md`, scoped to the sweep run — a per-invocation grant, not a standing default. If the operator did not explicitly launch a sweep, none of this authority applies.
-
-## Stages
-
-### 1. Inventory
-
-**First, check that no sweep is already outstanding.** One sweep worktree exists at a time. If a previous sweep is still sitting unmerged, stop and say so rather than starting a second — an unmerged worktree the operator hasn't taken is the same mental load as an open issue, only harder to see, and two of them are worse than the backlog they replaced. The operator decides whether to take the outstanding one through UAT, rebase it onto current main, or abandon it.
-
-```bash
-git worktree list
-```
-
-Then read the open queue at P1 and P2 across all types:
-
-```bash
-bd list --status=open --priority=1
-bd list --status=open --priority=2
-```
-
-If both tiers are empty, fall back to P3. Do not filter by `--type=bug`; the workflow covers anything the operator carries in their queue — refactors, dead code, docs drift, paper-cut bugs, taxonomy decisions whose answer is already known, scaffolds that need finishing.
-
-**Then dedupe, before clustering.** The same problem gets filed repeatedly across sessions that could not see each other's work, and the duplicates rarely share wording — they share a *subject*: the same test, the same template, the same symbol, the same surface. Read the inventory for that subject rather than for matching titles.
-
-Where several issues turn out to be the same thing, pick one as the survivor and note the others as its duplicates. They then travel together: one investigation, one fix, and all of them close together on merge. This is the cheapest win the workflow has — it closes N issues for the cost of one, and more to the point it prevents N separate investigations of the same problem.
-
-### 2. Cluster by theme
-
-Group the inventory by surface or system theme, not by priority. Theme is the cheaper sort because issues that share a surface often share investigation cost. A first pass on a backlog might yield clusters like *one surface's paper-cuts*, *a status-taxonomy refactor*, *a CSS cleanup*, *an upstream-package batch* — and a handful of standalone items that don't cluster with anything.
-
-A cluster of one is fine. It means the item routes as a single light-dev-shaped run inside the sweep, not that it does not belong.
-
-### 3. Pick a cluster with the operator
-
-Propose one or two candidate clusters to the operator with a one-sentence rationale per candidate: how many items it carries, what surface it touches, whether it lines up with a named outcome in the project's active weekly next-steps doc, if one exists. The operator picks. **The picker is the operator, not the agent** — even though the rest of the workflow is autonomous, the selection step is where the operator's strategic judgment enters.
-
-The project's active weekly next-steps doc (if one exists) is one input, not a hard filter. A cluster that doesn't serve a named outcome may still be the right pick (correctness, developer-experience, mental-noise reduction). Goal alignment is a tiebreaker between otherwise comparable clusters.
-
-### 4. Decide the worktree shape
-
-The default is **one sweep worktree carrying the whole cluster**. Independent fixes that merely share a surface still belong in it: they are independent to *implement*, but they get reviewed together, gated together, and handed off together, so splitting them buys nothing while costing a worktree apiece.
-
-Split an item out into its own light-dev run and its own worktree only when it is genuinely larger than sweep-shaped — it needs its own design pass, its own review, or a UAT story that would be lost inside a batch. That is an escape hatch, not the common case. If more than an item or two in a cluster needs it, the cluster was mis-picked.
-
-Create the worktree from a **freshly fetched main**, and copy any local env files into it rather than symlinking — a symlink into a sibling worktree dangles when that worktree is removed.
-
-### 5. Run autonomously
-
-For each issue in the cluster, work through the light-dev beats (`goal → investigate → design → critique → implement → verify`), with the additions below, specific to issue-sweep.
-
-**The already-done check, before investigation.** Issues sometimes ship without being closed, or get partially addressed by unrelated work that touched the same code path. Before claiming an issue, look at the actual surface, the actual code, and the recent commits that touched it. Three outcomes:
-
-- **Already shipped.** The work is fully done. Close the issue with a one-line note pointing at the commit(s) that did it (`bd close <id> --reason="shipped in <commit>"`), record it under *Closed as already-done* in the log, and move on. This is the one close that does not wait for UAT, because there is nothing to review.
-- **Partially done.** Some of the work has shipped, some hasn't. If the remainder is itself autonomously fixable, finish it in the sweep worktree like any other item — it closes at merge, not now. If the remainder hides a judgment call, bail (same shape as the eligibility bail below) — leave a one-line note on the issue describing what's done and what's left.
-- **Not started.** Proceed to the eligibility check.
-
-This is cheap to run — one read of the relevant file or one `git log -- <path>` — and it prevents the worst paper-cut version of the workflow: an agent doing work that was already done, or re-litigating a decision the codebase already made.
-
-**The eligibility check at investigate-time.** During investigation, ask explicitly: *does this fix require me to pick between alternatives?* If yes — multiple reasonable approaches exist, the spec is ambiguous, the data model has a question hiding in it, the copy choice is not obvious — bail.
-
-The decision filter is the first gate, not the only one. Bail on any of the following too, regardless of how obvious the fix looks — each reaches past what a single unattended pass and a local gate can safely cover:
-
-- **Changes the database schema.** Migrations are coordinated; a sweep is the wrong vehicle even for an obviously-correct column addition.
-- **Has external side effects.** Anything that sends a message, calls a paid or third-party provider, touches real customer data, or deletes something not plainly dead.
-- **Changes dependencies, secrets, or environment config.** These fail in ways a local gate won't catch.
-- **Has unbounded blast radius.** See the stop-loss below.
-
-**Bail behavior:**
-
-- Add a one-line note to the bd issue via `bd update <id> --notes "issue-sweep skipped <YYYY-MM-DD>: needs decision on <X>"`. **Do not use `bd close` to record a bail, not even with `--reason="..."`.** A bail leaves the issue OPEN and visible in `bd ready`; closing it — even with a thoughtful close-reason — drops the issue out of the queue, which is the noise transfer the workflow exists to prevent. The bail note belongs in the issue's notes field; the issue's open status keeps it in the operator's review path.
-- Leave the issue in its current status. Do not file a follow-up issue, do not write a findings doc, do not update memory.
-- Move to the next item in the cluster.
-
-The skipped issue stays in the operator's queue exactly where it was. The operator periodically reaps the skipped ones and either decides them, promotes to feature-dev, or hands them back to issue-sweep with more guidance.
-
-**The stop-loss.** The eligibility check catches *this needs a decision*. It does not catch *this is simply bigger than it looked*. If a fix spreads past roughly three files, or its investigation keeps opening new ground, stop and bail (same shape as the eligibility bail) — it is a light-dev candidate that was mis-filed as a paper-cut. Sunk cost is the failure mode here; the twenty minutes already spent is not a reason to spend an hour more.
-
-**The "did I just decide something" critique.** In the critique beat from light-dev, in addition to the stranger test and the omission check, run an explicit check on the implementation itself: *did I pick between alternatives anywhere in the fix?* If yes, the issue was not actually eligible and the autonomy filter missed it. Revert the work, unclaim the issue so it returns to `bd ready`, apply the bail behavior above, and skip. False negatives (bailing on something that was actually safe) cost nothing; false positives (auto-deciding something operator-altitude) cost trust.
-
-**The verification gate before handoff.** A fix stays on the worktree only when:
-
-- Tests pass (`npm test` for the targeted area, full suite before handoff).
-- Build is green where relevant.
-- For UI changes, the visual-check from `boop-web-web-ui-design` is run: build the CSS bundle, capture the affected page at desktop and mobile widths, read the captures. A green test suite is not evidence that the surface looks right; only the render is.
-
-If verification fails, revert that fix and bail on its issue (same shape as the eligibility bail). Never hand back a red worktree, and never hold the whole batch hostage to one bad fix.
-
-### 6. Hand off for UAT
-
-Leave the sweep branch and worktree in place. Tell the operator what is in it: the branch name, the worktree path, the command to run the app against it, and the per-issue checklist from the log file below. The issues stay **claimed and open** until the operator has taken the worktree through UAT — claimed keeps them out of `bd ready`, so they stop presenting as decisions, and open keeps them honest, because nothing has shipped yet.
-
-Verify the whole batch on the worktree before you call it ready: full suite green, the visual-check done for every UI change, each fix confirmed against its issue. Handoff is a single checkpoint — one look for the operator, no open questions attached.
-
-After sign-off, the closeout is the usual one: merge the branch to main, close the shipped issues (`bd close <id1> <id2> ...`), then remove the worktree and delete the local branch. If the operator rejects one fix, revert its change, unclaim its issue with a one-line note, and merge the rest.
-
-### 7. Log
-
-Append a block to a sweep log file (e.g. `labs/issue-sweep/log.md`). Write it *during* the run rather than after, so it is ready at handoff: it doubles as the checklist the operator does UAT from and the record of what the sweep did.
-
-```
-## <YYYY-MM-DD> — <cluster name>
-
-Branch: <sweep branch>
-Worktree: <path>
-
-Shipped (UAT checklist):
-- <id> — one-line outcome — look at: <page or surface, or "tests only">
-- <id> — one-line outcome — look at: <…>
-
-Closed as already-done:
-- <id> — shipped in <commit>
-
-Bailed:
-- <id> — one-line reason (the decision needed, or the limit hit)
-
-Learned:
-- <pattern> → updated <skill-path>   (only if a skill edit was warranted)
-```
-
-No headers beyond the date+cluster line. No formatting ceremony. No calls to action. The "look at" note is what earns the file its keep at handoff: it is what turns N reviews into one pass. The audit trail is `git log` and the bd queue; the log is the human-readable summary the operator skims. If nothing was learned that warranted a skill edit, omit the Learned section.
-
-If the sweep discovers a pattern that warrants a skill update, the skill update lives in the skill — not in the bd queue and not in the log body. The log just notes the pointer.
-
-## Anti-patterns
-
-- **Handing back a decision.** The worktree is a single batched checkpoint, not a queue of open questions. A findings doc to read, a follow-up issue to triage, a "which of these did you want?" — each means the eligibility filter failed, because the operator is now spending exactly the judgment the sweep existed to save. The win is clearing decision load: the operator does one look and never answers a question.
-- **Merging to main yourself.** The sweep's authority ends at a verified worktree, and issues stay claimed-and-open until the operator has taken it through UAT. The one exception is an issue that turns out to have shipped before the sweep started: close that immediately, since there is nothing to review.
-- **Starting a second sweep while one is unmerged.** An unmerged worktree the operator has not taken is the mental load the workflow was supposed to remove, wearing a disguise.
-- **Investigating the same problem twice.** Duplicate filings are common and rarely share wording. Dedupe by subject at inventory, or pay the investigation cost once per filing.
-- **Auto-deciding a judgment call to keep the cluster moving.** The autonomy filter is restrictive on purpose. Skipping an eligible-looking issue because it turned out to hide a design call costs nothing; shipping a design decision the operator hasn't made costs trust.
-- **Filing follow-up bd issues during a sweep.** A sweep that closes three issues and files two is a wash, not a reduction. If a bail surfaces something worth tracking, the bail note on the original issue is the tracking. Skill edits go in the skill.
-- **Filtering by type at inventory.** Most P1/P2 items aren't tagged `[bug]`. Refactors, dead code, taxonomy decisions whose answer is known, scaffolds that need finishing — all are eligible if they're autonomously fixable.
-- **Letting goal alignment become a hard filter.** A P2 paper-cut that doesn't serve this week's named outcome is still a paper-cut. Alignment is a tiebreaker, not a gate.
-- **Skipping the visual-check for UI work because tests pass.** The render is the proof. A green test suite proves the structure compiles; only the capture proves the surface still looks right after the fix.
-- **Asking the operator mid-run.** The operator picked the cluster at stage 3; the rest of the run is autonomous. If a question arises that the operator would have to answer, that issue is not eligible — bail and move on, do not interrupt.
-
-## Related
-
-- [`boop-light-dev-workflow`](../boop-light-dev-workflow/SKILL.md) — the per-issue beat structure that issue-sweep uses inside its run stage. Each cluster item is a light-dev-shaped pass, with the eligibility filter and the shared hand-back worktree added on top. Both workflows hand back a worktree; the difference is whether the operator has to bring judgment to it.
-- `boop-web-web-ui-design` — the source of the visual-check rule for UI changes.
-- `boop-writing-technical-prose` — the translation test still applies to anything the agent writes (commit messages, log entries, bail notes).

package/skills/boop-knowledge-backfill/SKILL.md

@@ -1,28 +0,0 @@
----
-name: boop-knowledge-backfill
-description: "When you need to integrate new knowledge from a set of specs or completed work that was not documented in reference at the time it shipped. This often happens when a feature is developed under a tight deadline and the team prioritizes shipping over documentation, or when work was done before the reference system was fully established."
-metadata:
-  category: docs
----
-> **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.
-
-# Knowledge Backfill
-
-   **a. Integrate into reference:**
-   - Follow the `boop-product-design-reference-integration` skill to blend the new feature's knowledge into existing `reference/` pages.
-   - This is NOT "create a new page for the feature" — it's merging knowledge into the existing concept pages (and creating new concept pages only when a genuinely new concept has no home).
-   - Update cross-links between affected reference pages.
-   - Remove or update any reference content that is now outdated.
-  
-   **b. Archive the spec:**
-   - Move the completed 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.
-
-## Related
-
-- `boop-product-design-reference-integration` — for step a of every spec you process; this workflow decides what to backfill and in what order, and that skill decides where each piece lands on the page.
-- `boop-writing-technical-prose` — when extracting the unimplemented remainder into a revised spec; that spec is read cold by someone with none of the backfill's context.

package/skills/boop-stray-disposition/SKILL.md

@@ -1,84 +0,0 @@
----
-name: boop-stray-disposition
-description: "When an autonomous run (a loop, a sweep, a sub-agent session) has finished and filed follow-up issues along the way, settle each one before you write the closing summary. Every stray gets a recorded disposition — re-parented and reachable from the roadmap, folded into a spec and closed, or triaged away. Use this whenever a run ends with issues in the queue that nobody has decided to do."
-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.
-
-# Stray disposition — settle what a run filed before you call it done
-
-Agents working through an autonomous run routinely file follow-up issues during review and
-punch-list work without parenting them to the epic they arose from. Those issues land in the
-ready queue disconnected from the context that produced them. After every run, before the
-closing summary, audit for these strays and give each one a **disposition** — the deliberate
-settling of what becomes of it — so nothing is left in limbo.
-
-Find them by running `bd ready` and `bd list --status=open` and identifying the issues this run
-filed: they cite the run's findings or the files it touched.
-
-## The three dispositions
-
-1. **Re-parent** — the stray belongs to the work that just ran. Move it under the run's epic, or
-   group several strays under a new discovered-from epic (`Group: <work> hardening`) for a
-   follow-on run scoped to that prefix on the same branch, so the operator still reviews and
-   merges once.
-
-2. **Fold** — the stray is requirements or evidence for a spec that is already planned. Move the
-   substance into that spec's text and close the issue with a reason pointing at the spec. A
-   future run plans from the spec, never from the closed queue, so content left behind in the
-   issue would never reach it.
-
-3. **Triage** — a true orphan. Close it with a reason if it does not survive scrutiny, or surface
-   it to the operator in the closing summary for a decision. Never leave it silently in the queue.
-
-## Re-parenting alone is not a disposition
-
-Nothing polls or sweeps the issue queue. Work reaches an agent only through the plan spec and the
-runs it launches. A stray moved under an epic that no planned run will execute is still stranded —
-just tidier.
-
-A disposition is complete only when the stray is **reachable from the roadmap**: the plan spec
-names the issue and the trigger for picking it up, or the substance is folded into a spec, or the
-issue is closed.
-
-If the stray must wait on an event, encode the sequencing as a dependency (`bd dep`) on the issue
-that produces that event. A dependency is visible and self-releasing. Deferring an issue only
-hides it from the ready queue until a date, which helps nobody who is not already polling.
-
-## Fold versus reference is a judgement call
-
-**Fold** — extract the substance into the spec so it reads complete cold, close the issue, and
-leave pointers at both ends — when the next reader is a planner working from the spec.
-
-**Keep the issue open and give the spec a one-line reference instead** when the finding is
-operational rather than design-shaped (a bug with reproduction steps that will be worked *as* an
-issue), when the issue is a living artifact with discussion or an owner, or when the content is
-too bulky to fold without bloating the spec.
-
-The test under both: put the substance where its next reader will actually look, and leave a
-pointer at the other end.
-
-## Archiving a spec orphans the issues it rooted
-
-When closeout moves a spec to a history location, any open issue whose only roadmap reference
-lived in that spec is stranded again. Migrate those references to the successor document — the
-remainder spec, or the plan — as part of the same sweep.
-
-## The test at the end
-
-Every stray filed during the run has a recorded disposition, each disposition ends at the roadmap
-or at a closed issue, and the ready queue contains only work someone has actually decided to do.
-
-A queue that accumulates undispositioned findings makes every future `bd ready` call more
-expensive to read. That noise is what this practice exists to prevent.
-
-## Related
-
-- `boop-project-mgmt-beads-planning` — how to write and parent the issues a disposition re-parents
-  or folds, so the next agent can pick one up cold.
-- `boop-issue-sweep-workflow` — when the strays have already accumulated into a backlog and want
-  clearing as a batch rather than settling one run's output.

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

@@ -1,206 +0,0 @@
----
-name: boop-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`](../boop-feature-dev-workflow/SKILL.md) — 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-testing-testing-express-web` — 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 feature → task → sub-task for most work. 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:
-
-> feature (parent) → understand → plan → decompose → implement → review → punch-list → closeout
-
-The first issue is the feature parent; 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 feature issue**: Create a new feature issue in beads for the requested website work. This is the parent issue for all work tasks. 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.
-
-### 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" task issue plus smaller sub-tasks 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.
-
-   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.
-
-   **Re-wire the Review dependency (critical):** Decompose only plans the work, it does not perform it. So Review (step 4) must depend on the "do the work" task, not on this Decompose task. If Review already exists with a Review→Decompose dep, fix it:
-   ```
-   bd dep remove <review-task-id> <this-decompose-task-id>
-   bd dep add    <review-task-id> <do-the-work-task-id>
-   ```
-   If Review doesn't exist yet, create it now with the correct dep on the do-the-work task.
-
-4. **Review the work done**: Next task (don't *do* this work, this is the content of the task issue). Depends on the "do the work" task from step 3 (step 3 is responsible for rewiring this if pre-created with the wrong dep). 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 audience-register drift, 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, wrong-audience register) 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>` 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. **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 (`lsof -ti tcp:<port> | xargs kill`), by port only. Never pattern-kill (`pkill -f <runner>` reaches every other worktree's server and the operator's own — this project runs several worktrees and loops at once). Never stop a server you did not start: 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.
-   - 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, wrong register), 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.
-
-  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. 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" — it's merging knowledge into the existing concept pages. The integration targets are the **guardrail registry** captured in the findings file:
-     - 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. `bd close <closeout-task-id>`.
-   5. `bd close <feature-issue-id>` (all child work is now done).
-   6. 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` — 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-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.