@boopkit/cap-workflows 0.1.0

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

@@ -0,0 +1,195 @@
+---
+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
+---
+# 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
+- [When you need to plan work with beads](../../../cap-project-mgmt/skills/boop-project-mgmt-beads-planning/SKILL.md) — from project-mgmt
+- [When you need to plan engineering work](../../../cap-project-mgmt/skills/boop-project-mgmt-engineering-planning/SKILL.md) — from project-mgmt
+
+### Design
+- [When you need to design a feature or system](../../../cap-product-design/skills/boop-product-design-engineering-design/SKILL.md) — from product-design
+- [When you need to design web UIs](../../../cap-web/skills/boop-web-web-ui-design/SKILL.md) — from web (**primary design skill for this workflow**)
+- [When you need to design controllers](../../../cap-services/skills/boop-services-controllers/SKILL.md) — from services (route handlers that render views)
+
+### Coding
+- [When you need to start working on a claimed issue](../../../cap-coding/skills/boop-coding-beads-flow/SKILL.md) — from coding
+- [When you need to develop or modify code](../../../cap-coding/skills/boop-coding-development/SKILL.md) — from coding
+- [When you need to commit code changes](../../../cap-coding/skills/boop-coding-commit-changes/SKILL.md) — from coding
+- [When you need to review uncommitted code changes](../../../cap-coding/skills/boop-coding-review-changes/SKILL.md) — from coding
+
+### Testing
+- [When you need to write or run tests](../../../cap-testing/skills/boop-testing-testing/SKILL.md) — from testing
+- [When you need to test Express web endpoints](../../../cap-testing/skills/boop-testing-testing-express-web/SKILL.md) — from testing
+
+### Documentation
+- [When you need to integrate knowledge into reference docs](../../../cap-product-design/skills/boop-product-design-reference-integration/SKILL.md) — from product-design
+
+### 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 [engineering planning skill](../../../cap-project-mgmt/skills/boop-project-mgmt-engineering-planning/SKILL.md). 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 [beads-planning skill](../../../cap-project-mgmt/skills/boop-project-mgmt-beads-planning/SKILL.md).
+
+   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 [reference integration skill](../../../cap-product-design/skills/boop-product-design-reference-integration/SKILL.md) 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.