@boopkit/cli 0.8.1 → 0.8.2

package/README.md

@@ -147,7 +147,7 @@ Adding a capability installs its skills into your project's `skills/` directory.
 **Development capabilities (skills only — no runtime code)**
 
 - **`coding`** — boop-coding-beads-flow, boop-coding-development, boop-coding-commit-changes, boop-coding-review-changes, boop-coding-debugging
-- **`product-design`** — boop-product-design-engineering-design, boop-product-design-feature-documentation, boop-product-design-feature-requirements, boop-product-design-reference-integration, boop-product-design-knowledge-backfill, boop-product-design-thought-partnership, boop-writing-technical-prose, boop-writing-documents, boop-writing-semantic-line-breaks
+- **`product-design`** — boop-product-design-engineering-design, boop-product-design-feature-documentation, boop-product-design-feature-requirements, boop-product-design-reference-integration, boop-product-design-knowledge-backfill, boop-product-design-docs-sweep-workflow, boop-product-design-reference-restructure-workflow, boop-product-design-thought-partnership, boop-writing-technical-prose, boop-writing-documents, boop-writing-semantic-line-breaks
 - **`project-mgmt`** — boop-project-mgmt-beads-planning, boop-project-mgmt-engineering-planning, boop-project-mgmt-issue-sweep-workflow, boop-project-mgmt-stray-disposition
 - **`skills`** — boop-skill-authoring, boop-skills-discovery, boop-skills-agent-surface-design, boop-get-smart, boop-so-what, boop-skills-hyperlinking, boop-skills-edit-triage
 - **`testing`** — boop-testing-tdd-light, boop-testing-testing
@@ -164,7 +164,7 @@ Adding a capability installs its skills into your project's `skills/` directory.
 - **`email`** — boop-email-email-design
 - **`services`** — boop-services-controllers, boop-services-services
 - **`users-and-accounts`** — boop-users-user-data-modeling
-- **`web`** — boop-web-web-ui-design, boop-web-testing, boop-web-website-dev-workflow, boop-web-design-handoff-workflow
+- **`web`** — boop-web-web-ui-design, boop-web-css, boop-web-testing, boop-web-website-dev-workflow, boop-web-design-handoff-workflow, boop-web-design-handoff-bundle
 
 _One-line description of each skill: see the bundled `docs/skills.md`._
 <!-- SKILLS-INDEX:END -->

package/dist/capability-versions.json

@@ -2,22 +2,22 @@
   "@boopkit/cap-api": "0.4.5",
   "@boopkit/cap-background-jobs": "0.5.1",
   "@boopkit/cap-cloud-storage": "0.5.0",
-  "@boopkit/cap-coding": "0.4.8",
+  "@boopkit/cap-coding": "0.4.9",
   "@boopkit/cap-database": "0.4.6",
   "@boopkit/cap-email": "0.4.4",
   "@boopkit/cap-hello": "0.4.1",
   "@boopkit/cap-noticeboard": "0.4.1",
   "@boopkit/cap-oauth-client": "0.1.1",
-  "@boopkit/cap-oauth-server": "0.3.2",
-  "@boopkit/cap-product-design": "0.6.12",
-  "@boopkit/cap-project-mgmt": "0.4.14",
+  "@boopkit/cap-oauth-server": "0.3.3",
+  "@boopkit/cap-product-design": "0.6.13",
+  "@boopkit/cap-project-mgmt": "0.4.15",
   "@boopkit/cap-services": "0.4.3",
-  "@boopkit/cap-skills": "0.5.7",
-  "@boopkit/cap-testing": "0.5.9",
+  "@boopkit/cap-skills": "0.5.8",
+  "@boopkit/cap-testing": "0.5.10",
   "@boopkit/cap-typescript": "0.1.0",
-  "@boopkit/cap-users": "0.9.0",
-  "@boopkit/cap-ux": "0.2.4",
-  "@boopkit/cap-web": "0.5.7",
-  "@boopkit/cap-workflows": "0.2.3",
+  "@boopkit/cap-users": "0.9.1",
+  "@boopkit/cap-ux": "0.2.5",
+  "@boopkit/cap-web": "0.5.8",
+  "@boopkit/cap-workflows": "0.2.4",
   "@boopkit/logger": "0.4.0"
 }

package/dist/commands/init.d.ts

@@ -17,5 +17,10 @@ export interface InitDeps {
  * pins @beads/bd as a devDependency, then whatever is on PATH.
  */
 export declare function findBd(projectDir: string, searchPath?: string): string | null;
+/**
+ * The `bd init` arguments that give a project a beads database in Dolt server
+ * mode, which boop loop requires. bd derives its database name from the prefix.
+ */
+export declare function bdInitArgs(projectName: string): string[];
 export declare function runInit(name: string, options: InitOptions, deps?: InitDeps): void;
 export {};

package/dist/commands/init.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findBd = findBd;
+exports.bdInitArgs = bdInitArgs;
 exports.runInit = runInit;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -106,6 +107,13 @@ function commitScaffold(targetDir, name, run) {
         console.error(`Warning: Unable to commit the scaffold: ${err.message}`);
     }
 }
+/**
+ * The `bd init` arguments that give a project a beads database in Dolt server
+ * mode, which boop loop requires. bd derives its database name from the prefix.
+ */
+function bdInitArgs(projectName) {
+    return ['init', '--non-interactive', '--server', '-p', projectName];
+}
 /** Commit the scaffold, then run `bd init` in the new project; report and return false rather than throw. */
 function initBeads(targetDir, name, args, deps) {
     const findBdFn = deps.findBdFn ?? findBd;
@@ -490,18 +498,17 @@ function runInit(name, options, deps = {}) {
     // they exist but creates them when they don't, and the templates never
     // overwrite an existing file. Server mode, because boop loop refuses a
     // project whose beads runs embedded. Git is touched only here, just before
-    // bd init, because that is when a repository gets created anyway. bd derives
-    // its database name from the prefix.
-    const bdInitArgs = ['init', '--non-interactive', '--server', '-p', projectName];
+    // bd init, because that is when a repository gets created anyway.
+    const initArgs = bdInitArgs(projectName);
     const beadsPending = installedCapabilities.includes('project-mgmt') &&
-        !(shouldInitBeads && initBeads(targetDir, projectName, bdInitArgs, deps));
+        !(shouldInitBeads && initBeads(targetDir, projectName, initArgs, deps));
     console.log(`\nNext steps:`);
     console.log(`  cd ${name}`);
     if (!shouldInstall) {
         console.log('  npm install');
     }
     if (beadsPending) {
-        console.log(`  bd ${bdInitArgs.join(' ')}`);
+        console.log(`  bd ${initArgs.join(' ')}`);
     }
     console.log('  boop status          ← check what needs configuration');
     if (kernel) {

package/dist/commands/loop.d.ts

@@ -66,7 +66,10 @@ export interface WorktreeContext {
 /**
  * Hard requirement: beads must run in Dolt server mode so concurrent worktrees
  * share one issue DB over TCP. Reads `.beads/metadata.json` and throws an
- * actionable error on embedded/missing — call before any `bd` work.
+ * actionable error on embedded/missing — call before any `bd` work. A project
+ * with no `.beads/` at all (one started with `boop add`) is told the `bd init`
+ * command `boop init` would have run. The messages name no skill file, because
+ * an installed project may not have the one boop's own repository does.
  */
 export declare function assertDoltServerMode(projectDir: string, deps?: {
     existsSyncFn?: (p: string) => boolean;
@@ -325,6 +328,7 @@ export declare function splitStreamLines(carry: string, chunk: string): {
     lines: string[];
     rest: string;
 };
+export declare function sessionEnv(model: string, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export declare function runLoop(options: LoopOptions, deps?: {
     /** Runs one Claude session for an issue. Tests substitute this; the planning phase is not affected. */
     runClaudeFn?: RunClaudeFn;

package/dist/commands/loop.js

@@ -57,12 +57,14 @@ exports.buildPrompt = buildPrompt;
 exports.shouldRotateSession = shouldRotateSession;
 exports.sessionDidWork = sessionDidWork;
 exports.splitStreamLines = splitStreamLines;
+exports.sessionEnv = sessionEnv;
 exports.runLoop = runLoop;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const crypto_1 = require("crypto");
 const string_decoder_1 = require("string_decoder");
+const init_1 = require("./init");
 /**
  * Output cap for every `bd … --json` read the loop makes.
  *
@@ -131,13 +133,22 @@ function readReadyQueue(execSyncFn) {
 /**
  * Hard requirement: beads must run in Dolt server mode so concurrent worktrees
  * share one issue DB over TCP. Reads `.beads/metadata.json` and throws an
- * actionable error on embedded/missing — call before any `bd` work.
+ * actionable error on embedded/missing — call before any `bd` work. A project
+ * with no `.beads/` at all (one started with `boop add`) is told the `bd init`
+ * command `boop init` would have run. The messages name no skill file, because
+ * an installed project may not have the one boop's own repository does.
  */
 function assertDoltServerMode(projectDir, deps) {
     const existsSyncFn = deps?.existsSyncFn || fs.existsSync;
     const readFileFn = deps?.readFileFn || ((p, enc) => fs.readFileSync(p, enc));
-    const metaPath = path.join(projectDir, '.beads', 'metadata.json');
-    const fix = 'Migrate beads to Dolt server mode before running the loop; see skills/boop-dolt-recovery/SKILL.md';
+    const beadsDir = path.join(projectDir, '.beads');
+    const metaPath = path.join(beadsDir, 'metadata.json');
+    if (!existsSyncFn(beadsDir)) {
+        const initCommand = `bd ${(0, init_1.bdInitArgs)(path.basename(path.resolve(projectDir))).join(' ')}`;
+        throw new Error(`beads is not set up in ${projectDir}: there is no .beads folder. ` +
+            `The loop tracks its work in beads, running in Dolt server mode. To set it up, run this from the project folder:\n  ${initCommand}`);
+    }
+    const fix = 'Switch this project\'s beads to Dolt server mode before running the loop.';
     if (!existsSyncFn(metaPath)) {
         throw new Error(`beads metadata not found at ${metaPath}. The loop requires Dolt server mode for concurrent worktrees. ${fix}`);
     }
@@ -500,8 +511,10 @@ async function planWork(opts) {
     const prompt = buildPlanningPrompt(workContent, flowContent, opts.prefix);
     const sessionId = (0, crypto_1.randomUUID)();
     const timestamp = new Date().toISOString().replace(/[:.]/g, '-').substring(0, 19);
-    const logFile = path.join(opts.logDir, `_planning_${opts.prefix}_${timestamp}.log`);
-    const readableLogFile = path.join(opts.logDir, `_planning_${opts.prefix}_${timestamp}.readable.log`);
+    // A spec-driven run usually has no prefix, so fall back to the spec's base name.
+    const runName = opts.prefix || path.basename(opts.workPath, path.extname(opts.workPath));
+    const logFile = path.join(opts.logDir, `_planning_${runName}_${timestamp}.log`);
+    const readableLogFile = path.join(opts.logDir, `_planning_${runName}_${timestamp}.readable.log`);
     // Write readable log header
     fs.writeFileSync(readableLogFile, `=== Planning Session ===\nSession: ${sessionId}\nStarted: ${new Date().toISOString()}\n\n`);
     console.log(`\x1b[32m[bd-loop]\x1b[0m 📋 Starting planning phase...`);
@@ -1075,6 +1088,24 @@ function splitStreamLines(carry, chunk) {
     const rest = pieces.pop() ?? '';
     return { lines: pieces.filter(Boolean), rest };
 }
+// Propagate the chosen model beyond this session via the environment.
+// `--model` (in args) sets this session; ANTHROPIC_MODEL additionally
+// (a) reaches a nested `boop loop` — child processes inherit the env — so it
+// doesn't reset to the default, and (b) is honored by any sub-agent whose
+// definition opts into `model: inherit`. We deliberately do NOT set
+// CLAUDE_CODE_SUBAGENT_MODEL: sub-agents keep their own declared model, so a
+// deliberately-cheap agent (e.g. Explore on Haiku) stays cheap. The invoking
+// agent can still override a sub-agent's model per-invocation when it needs
+// to. See resolveModel().
+//
+// CLAUDE_CODE_ENTRYPOINT marks the session as machine-driven, so its transcript
+// is not mistaken for one the operator typed into. CLAUDE_CODE_DISABLE_AUTO_MEMORY
+// keeps the operator's auto-memory index, written for their interactive session,
+// out of a coding session (honoured by Claude Code 2.1.296).
+function sessionEnv(model, env = process.env) {
+    const machineDriven = { ...env, CLAUDE_CODE_ENTRYPOINT: 'boop-loop', CLAUDE_CODE_DISABLE_AUTO_MEMORY: '1' };
+    return model ? { ...machineDriven, ANTHROPIC_MODEL: model } : machineDriven;
+}
 function runClaude(prompt, opts, logFile, readableLogFile) {
     return new Promise((resolve) => {
         const args = [
@@ -1105,19 +1136,7 @@ function runClaude(prompt, opts, logFile, readableLogFile) {
         const readableStream = readableLogFile
             ? fs.createWriteStream(readableLogFile, { flags: 'a' })
             : null;
-        // Propagate the chosen model beyond this session via the environment.
-        // `--model` (in args) sets this session; ANTHROPIC_MODEL additionally
-        // (a) reaches a nested `boop loop` — child processes inherit the env — so it
-        // doesn't reset to the default, and (b) is honored by any sub-agent whose
-        // definition opts into `model: inherit`. We deliberately do NOT set
-        // CLAUDE_CODE_SUBAGENT_MODEL: sub-agents keep their own declared model, so a
-        // deliberately-cheap agent (e.g. Explore on Haiku) stays cheap. The invoking
-        // agent can still override a sub-agent's model per-invocation when it needs
-        // to. See resolveModel().
-        const childEnv = opts.model
-            ? { ...process.env, ANTHROPIC_MODEL: opts.model }
-            : process.env;
-        const child = (0, child_process_1.spawn)(claudeBin, args, { cwd: opts.cwd, stdio: ['pipe', 'pipe', 'pipe'], env: childEnv });
+        const child = (0, child_process_1.spawn)(claudeBin, args, { cwd: opts.cwd, stdio: ['pipe', 'pipe', 'pipe'], env: sessionEnv(opts.model) });
         let limitHit = false;
         // Track context-window pressure from outside the agent (spec: the loop reads
         // the stream it already parses; the agent is never told). Peak occupancy over

package/dist/lib/execute.js

@@ -186,7 +186,17 @@ function executeTask(task, manifest) {
         case 'run-command': {
             const data = task.data;
             console.log(`\nRunning ${data.command}...`);
-            (0, child_process_1.execSync)(data.command, { cwd: targetDir, stdio: 'inherit' });
+            // stderr is captured rather than inherited so that a failure's warning
+            // carries the command's own error text; on success it is passed through.
+            const result = (0, child_process_1.spawnSync)(data.command, { cwd: targetDir, shell: true, stdio: ['inherit', 'inherit', 'pipe'] });
+            if (result.error)
+                throw result.error;
+            const stderr = result.stderr.toString();
+            if (result.status !== 0) {
+                const exit = result.signal ? `signal ${result.signal}` : `exit code ${result.status}`;
+                throw new Error(`Command failed (${exit}): ${data.command}\n${stderr}`);
+            }
+            process.stderr.write(stderr);
             break;
         }
     }

package/dist/lib/stale-scripts.js

@@ -65,19 +65,56 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 /** Jest's in-band flag and its single-letter alias. */
 const IN_BAND_FLAGS = new Set(['--runInBand', '--runInBand=true', '-i']);
+/** Shell operators that end one command and start the next. */
+const COMMAND_SEPARATORS = new Set(['&&', '||', ';', '|']);
 /**
- * Does this command invoke Jest? Matched on the token's basename so that `jest`,
- * `npx jest` and `node_modules/.bin/jest` all count, while a command that merely
- * contains the same characters somewhere does not.
+ * Words that run the command after them, so the word that follows (once their
+ * own flags are skipped) is still in command position: `npx jest`, `exec jest`,
+ * `node --expose-gc node_modules/.bin/jest`.
  */
-function invokesJest(tokens) {
-    return tokens.some((token) => {
-        if (token.startsWith('-'))
-            return false;
-        const base = path.basename(token);
-        return base === 'jest' || base === 'jest.js';
+const LAUNCHERS = new Set(['npx', 'exec', 'node', 'cross-env']);
+/**
+ * Keys that cannot be run as scripts by convention. Projects keep explanatory
+ * prose there, and prose about Jest naturally mentions `jest` and `--runInBand`.
+ */
+function isCommentKey(name) {
+    return name.startsWith('_comment') || name.startsWith('//');
+}
+function isJest(token) {
+    const base = path.basename(token);
+    return base === 'jest' || base === 'jest.js';
+}
+/**
+ * Group a command's words by the chained command each belongs to. A separator
+ * glued to the end of a word (`tsc;`) still ends that command.
+ */
+function groupCommands(tokens) {
+    let current = 0;
+    return tokens.map((token) => {
+        if (COMMAND_SEPARATORS.has(token))
+            return current++;
+        const index = current;
+        if (token.endsWith(';'))
+            current++;
+        return index;
     });
 }
+/**
+ * Does this one command run Jest? Only the word in command position counts —
+ * after any `KEY=value` assignments, launchers and the launchers' own flags —
+ * so `jest`, `npx jest` and `node_modules/.bin/jest` match, while `echo jest`
+ * and a command that merely contains the same characters do not.
+ */
+function runsJest(tokens) {
+    for (const token of tokens) {
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(token))
+            continue;
+        if (LAUNCHERS.has(token) || token.startsWith('-'))
+            continue;
+        return isJest(token);
+    }
+    return false;
+}
 /**
  * Pure: given a package.json `scripts` object, return the scripts whose command
  * forces in-band Jest execution and therefore defeats the shipped config.
@@ -87,18 +124,21 @@ function findStaleRunnerScripts(scripts) {
         return [];
     const findings = [];
     for (const [name, command] of Object.entries(scripts)) {
-        if (typeof command !== 'string')
+        if (typeof command !== 'string' || isCommentKey(name))
             continue;
         const tokens = command.split(/\s+/).filter(Boolean);
-        if (!invokesJest(tokens))
-            continue;
-        const flags = tokens.filter((t) => IN_BAND_FLAGS.has(t));
+        const group = groupCommands(tokens);
+        const jestGroups = new Set([...new Set(group)].filter((g) => runsJest(tokens
+            .filter((t, i) => group[i] === g && !COMMAND_SEPARATORS.has(t))
+            .map((t) => t.replace(/;$/, '')))));
+        const offending = (t, i) => jestGroups.has(group[i]) && IN_BAND_FLAGS.has(t);
+        const flags = tokens.filter(offending);
         if (flags.length === 0)
             continue;
         findings.push({
             name,
             command,
-            rewritten: tokens.filter((t) => !IN_BAND_FLAGS.has(t)).join(' '),
+            rewritten: tokens.filter((t, i) => !offending(t, i)).join(' '),
             flags,
         });
     }

package/docs/loop.md

@@ -68,6 +68,8 @@ If `--prefix` is also provided, it is passed to the planning session as a naming
 | `--no-skip-perms` | off | Don't skip Claude permission prompts |
 | `--json` | off | Output summary as JSON |
 
+Every Claude session the loop spawns, planning and issue sessions alike, runs with `CLAUDE_CODE_ENTRYPOINT=boop-loop`, which marks its transcript as machine-driven, and `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`, which keeps the operator's auto-memory out of it.
+
 ## Worktree Isolation (default)
 
 By default, `boop loop` runs **inside its own git worktree** so that N loops can run concurrently without colliding. On start (with `--run`) the loop:

package/docs/skills.md

@@ -21,7 +21,9 @@ Every capability ships **agent skills** — focused `SKILL.md` guides that `boop
 - **boop-product-design-feature-requirements** — When you need to write a feature spec, draft a spec document, or turn a brief or vague directive into requirements — i.e. define what a feature should accomplish before designing how to build it. This fires even when you frame the task to yourself as just 'writing a spec' or 'matching the house spec format': reading an existing spec to imitate its shape is not a substitute for the method, and the more competent you feel at the raw task the more this applies. Start with the user's jobs to be done, in frequency order; take and defend a stance; then derive goals, non-goals, and success metrics.
 - **boop-product-design-reference-integration** — When you need to integrate new knowledge into the project's `reference/` directory after completing a feature, fixing a bug that changes behavior, or adding a capability.
 - **boop-product-design-knowledge-backfill** — 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.
-- **boop-product-design-thought-partnership** — When the user wants to think out loud through a design — a feature, a capability, a strategic direction — be a thought partner, not an implementer: hold the conversation at user-and-value altitude, honor uncertainty with hypotheses rather than pretend-decisions, and keep software-shaped concerns downstream of the user's lived problems.
+- **boop-product-design-docs-sweep-workflow** — When `specs/` has piled up with documents nobody has looked at in months and you need to know which are finished, which have gone stale, and which are the only surviving record of real work, follow this process: measure the set rather than read it, classify each document against what the issue tracker says (the close reason, not the status), pass the gate before archiving anything, and make the mechanical fixes while surfacing the judgement calls. The document-set sibling of issue-sweep. Not for folding one shipped feature into `reference/`.
+- **boop-product-design-reference-restructure-workflow** — When `reference/` has grown by accretion and subjects a reader would look up have no page of their own (they live as sections inside pages about something else, or in pieces across several pages), follow this process: measure the whole set rather than read it, write down the candidate subjects, then promote each one in a worktree, one commit per subject, for the operator to review as a diff. The whole-set counterpart of reference-integration, which promotes a buried subject one change at a time.
+- **boop-product-design-thought-partnership** — When the user wants to think out loud through a design — a feature, a capability, a strategic direction — or to drive a set of features forward with you interactively, through design, code, review and adjustment, be a thought partner, not an implementer: hold the conversation at user-and-value altitude, honor uncertainty with hypotheses rather than pretend-decisions, record each ruling where the next reader will find it, and keep software-shaped concerns downstream of the user's lived problems.
 - **boop-writing-technical-prose** — When writing chat responses, summaries, bd issue bodies, specifications, specs, or any artifact a fresh reader will pick up cold, write grammatical conversational English. Avoid the agent-shorthand patterns that compress meaning at the cost of legibility.
 - **boop-writing-documents** — When you need to write a document someone will read cold and act on — a proposal, strategy memo, analysis, recommendation, or status write-up — and want the discipline of the Amazon six-pager: narrative prose, a declared length budget, claims that carry their evidence, and the hard questions answered inside the document.
 - **boop-writing-semantic-line-breaks** — When you need to write or edit prose in a markdown file under version control — a spec, a reference page, a README, a skill — break lines at semantic boundaries rather than at a fixed column, so that edits produce readable diffs.
@@ -55,13 +57,13 @@ Every capability ships **agent skills** — focused `SKILL.md` guides that `boop
 ### `ux` — UX design judgement and the discovery/delivery workflows that operate it
 
 - **boop-ux-purpose-judgement** — When you are evaluating a rendered screen or page and need to judge whether each thing on it belongs there, in the right shape, for the right job. Asks the structural question that the visual lens does not — is this affordance the right idea, not just rendered well. Pairs with ux-visual-judgement (the question of how things look and scan).
-- **boop-ux-visual-judgement** — When you are evaluating a rendered screen or page and need to form a principled judgement about how it looks and scans. Visual lens only — eye-path, register, anatomy, scan-line, gestalt, density, voice. Pairs with ux-purpose-judgement (the question of whether each element belongs at all) and with the CSS skill (the grammar of how things are rendered).
+- **boop-ux-visual-judgement** — When you are evaluating a rendered screen or page and need to form a principled judgement about how it looks and scans. Visual lens only — eye-path, loudness, anatomy, scan-line, whitespace, density, voice. Pairs with ux-purpose-judgement (the question of whether each element belongs at all) and, when the project has the web capability, with boop-web-css (the grammar of how things are rendered).
 - **boop-ux-eval-and-refine-workflow** — When you are tasked with iteratively evaluating and improving an existing rendered screen or page (discovery, not delivery), follow this workflow. Inner loop: capture → eval → recommend → implement → re-capture. Outer: knowledge integration.
 - **boop-ux-app-ui-dev-workflow** — When you are tasked with improving an existing app-side screen or page (app UX, not marketing) end-to-end and the input is a target screen or page rather than a written spec, follow this beads-issue-per-step workflow. Sibling to feature-dev-workflow but stripped of backend phases. The judgement lenses are the planning input.
 
 ### `workflows` — Reusable end-to-end development and audit workflows for code
 
-- **boop-feature-dev-workflow** — When you are tasked with building a feature end-to-end, follow this guidance.
+- **boop-feature-dev-workflow** — When you are tasked with building a feature end-to-end, follow this beads-issue-per-step workflow: epic root → understand → plan → decompose → implement → review → punch-list → closeout → reconcile-and-finalize.
 - **boop-light-dev-workflow** — When you are extending an existing system (front-end, back-end, or full-stack) toward a goal — wiring something new from data and patterns that already exist, not building greenfield — follow this grounded flow: goal → investigate the real system → design → critique → decompose into one scoped epic + child issues → run them → close out. Loop-drivable via boop loop --work --flow; lighter than feature-dev-workflow.
 - **boop-refactor-dev-workflow** — When you need to change a contract, cardinality, or shape that existing code already depends on — usually to make a feature buildable — follow this workflow instead of the feature workflow.
 - **boop-test-audit-workflow** — Use when a set of tests is not testing the purpose of the code: mocks that verify data the test itself fed in, tests that exercise the platform rather than our code, or a stubbed seam where the integration is the actual risk. Also use when tests are so coupled to the shape of the implementation that they check a label, an exact string, or a call sequence rather than a behaviour. This workflow removes tests that cannot go red for a real reason, rewrites the ones that check a real goal at the wrong level, merges duplicates, and does not lose coverage. It explicitly does not target good tests merely because a coming change will make them need updating. The sibling of light-dev-workflow for reworking tests rather than building features.
@@ -102,9 +104,11 @@ Every capability ships **agent skills** — focused `SKILL.md` guides that `boop
 ### `web` — Web UI with Handlebars + Tailwind
 
 - **boop-web-web-ui-design** — When you need to design and implement user interfaces — including when you frame the task as 'build a page', 'add a component', 'style this surface', or 'wire up the UI' — following established patterns and philosophy.
-- **boop-web-testing** — When you need to write or run tests for the Express server — services, controllers, middleware, and HTTP routes.
+- **boop-web-css** — When you need to write or change CSS — adding or renaming a class, writing a selector or a stylesheet rule, or editing a class attribute in a template — name classes for what their elements are for, nest each block's children and variants inside it, and never use BEM's __element or --modifier separators.
+- **boop-web-testing** — When you need to write or run tests for the Express server — services, controllers, middleware, and HTTP routes — or to confirm in a browser that a change to something a person looks at does what its issue said, since a green suite proves behaviour but not what renders.
 - **boop-web-website-dev-workflow** — When you are tasked with implementing website changes end-to-end (new pages, page rewrites, IA changes, content/CTA updates), follow this guidance.
 - **boop-web-design-handoff-workflow** — 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.
+- **boop-web-design-handoff-bundle** — When the operator points at a design canvas (an artifact of artboards) and asks for it to be bundled, turned into a handoff, or made ready for the coding agent, turn it into a design handoff bundle under specs/design-handoffs/: a README, drop-in templates and CSS in the project's conventions, the decisions, and an eval checklist. The producing side of boop-web-design-handoff-workflow; the system wins over the prototype, and every departure is written down.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cli",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "boop: the opinionated bootstrap for founder friendly, AI-first web apps - code plus agent skills, composable from day one.",
   "main": "dist/cli.js",
   "workspaces": [