@boopkit/cap-product-design 0.6.6 → 0.6.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cap-product-design",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "description": "Product design skills for AI agents",
   "files": [
     "skills/",

package/skills/boop-product-design-engineering-design/SKILL.md

@@ -4,6 +4,11 @@ description: "When you need to design a feature or system and communicate the te
 metadata:
   category: design
 ---
+> **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.
+
 # Engineering Design
 
 ## Goal
@@ -98,6 +103,12 @@ The positive form is also more durable. Defects get fixed and the prose goes sta
 
 This is a stronger form of the strawman rule: do not motivate a design against a wrong implementation, real or imagined. State the destination.
 
+## No verify-later breadcrumbs
+
+Do not write "verify X during design" or "confirm the capability supports Y" notes into specs.
+Research always precedes the work, so discovery surfaces these naturally — a pre-written flag adds noise and goes stale.
+State the decision; let the design phase find its own facts.
+
 ## Architecture Layering
 
 Well-designed systems separate concerns into layers with clear responsibilities and one-directional dependencies. The exact layers vary by project type, but the principle is universal:
@@ -205,3 +216,6 @@ Without an explicit interaction-shapes pass, the agent inherits whatever pattern
 ## Related
 
 - [`boop-writing-semantic-line-breaks`](../boop-writing-semantic-line-breaks/SKILL.md) — design docs live in `specs/`; break their lines semantically so edits diff cleanly.
+- [`boop-writing-technical-prose`](../boop-writing-technical-prose/SKILL.md) — when writing Alternatives and Tradeoffs; an alternative rejected in a sentence fragment cannot be re-evaluated later, which defeats the point of recording it.
+- [`boop-writing-documents`](../boop-writing-documents/SKILL.md) — when the design is long enough that reviewers will skim it; the declared length budget and the answered-objections discipline are what keep the Alternatives table from becoming a list nobody reads.
+- `boop-project-mgmt-engineering-planning` — once the decision is settled and the work has to be ordered; sequence by which uncertainty each step retires, not by which part is easiest to show.

package/skills/boop-product-design-feature-documentation/SKILL.md

@@ -4,6 +4,11 @@ description: "When you need to document a complex feature, function, or system
 metadata:
   category: reqs
 ---
+> **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.
+
 # Feature Documentation
 - Identity the intended audience. For example, data engineers who may not have done this sort of exercise before.
 - Identify the audience's "group identity". For example, which company, team, or project they belong to.
@@ -13,3 +18,5 @@ metadata:
 ## Related
 
 - [`boop-writing-semantic-line-breaks`](../boop-writing-semantic-line-breaks/SKILL.md) — when the documentation lands in a markdown file in the repo.
+- [`boop-writing-technical-prose`](../boop-writing-technical-prose/SKILL.md) — before the first paragraph; this skill's whole audience is a reader who has not done this activity before, and agent shorthand is precisely what loses them.
+- [`boop-writing-documents`](../boop-writing-documents/SKILL.md) — when the piece is read start to finish rather than dipped into for a lookup; that is the shape the six-pager discipline is for, and it decides the length before you write.

package/skills/boop-product-design-feature-requirements/SKILL.md

@@ -4,9 +4,14 @@ description: "When you need to write a feature spec, draft a spec document, or t
 metadata:
   category: reqs
 ---
+> **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.
+
 # Feature Requirements
 
-Be sure to read [reference/tenets.ref.md](../reference/tenets.ref.md) for overarching principles that apply to all features.
+Be sure to read the project's own `reference/tenets.ref.md`, where it keeps one, for the overarching principles that apply to every feature.
 
 ## When you need to define what a feature should accomplish before designing how to build it
 
@@ -113,3 +118,5 @@ Steps 1–3 are where this skill earns its keep. Skipping them produces well-str
 ## Related
 
 - [`boop-writing-semantic-line-breaks`](../boop-writing-semantic-line-breaks/SKILL.md) — specs live in `specs/`; break their lines semantically so edits diff cleanly.
+- [`boop-writing-technical-prose`](../boop-writing-technical-prose/SKILL.md) — when you start writing the spec itself; a jobs list compressed into agent shorthand has to be decoded by the implementer before it can be built, and decoding is where the jobs get lost.
+- [`boop-writing-documents`](../boop-writing-documents/SKILL.md) — when the spec has to survive a reader who disagrees with it; the stance this skill tells you to take is a claim, and that skill is how a claim carries its evidence and answers the obvious objection inside the document.

package/skills/boop-product-design-reference-integration/SKILL.md

@@ -4,6 +4,11 @@ description: "When you need to integrate new knowledge into the project's `refer
 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.
+
 # Reference Integration
 
 ## Goal
@@ -43,6 +48,35 @@ After editing, verify:
 - Use kebab-case, singular or plural based on what reads naturally
 - Suffix is always `.ref.md`
 
+## When boop has changed a page this project rewrote
+
+Some pages in `reference/` arrived with a boop capability.
+They are seed content, and a project is expected to rewrite them, so the page is the project's.
+Unlike a skill, it is never split into boop's text and the project's.
+But boop keeps improving its own copy, and a page the project has rewritten does not receive those improvements.
+
+When `boop update` finds a page that both the project and boop have changed since it was installed, it leaves the page alone and prints a line giving the path to boop's current copy in `node_modules`, such as `node_modules/@boopkit/cap-users/scaffold/reference/user-auth.ref.md`.
+The work is to blend what boop added into the project's page:
+
+1. **Read boop's copy in full, then the project's page.**
+   A line diff between them is useless, because the project's rewrite differs from boop's copy almost everywhere.
+2. **List what boop's copy covers that the project's page does not** — each mechanism, function, command or setting it describes.
+3. **Check each item against the project's code.**
+   Blend in what this project actually runs.
+   Leave out what it never installed or has removed, and do not describe code that is not there.
+4. **Blend each item into the section of the page where that concept already lives**, following the rest of this skill.
+   Never paste boop's copy over the page, and never add a section of changes from boop.
+5. **Name the package and version you blended from in the commit message.**
+   The update line appears again on every later update, because the page still differs from boop's copy, and the commit is how the next agent tells whether boop's copy has changed since.
+
+For example, over five months of releases boop's `user-auth.ref.md` gained 121 lines covering bearer-token authentication, the API-key gate and the credential-hashing migration.
+One project ran all of that code, but its rewritten page never mentioned `resolveBearer`, `requireApiKey` or `npm run credentials:migrate`, while boop's post-install steps and `boop status` hints sent readers to that page for exactly those things.
+That page already had a section on the API-key flow, so the blend belongs there: how a key is presented as a bearer token, and how the gate admits it.
+The migration belongs wherever the page describes how credentials are stored.
+
+This is for reference pages only.
+A `SKILL.md` the project has edited is not blended: its edits move into the `PROJECT.md` beside it, through `boop migrate-skill-edits` and the `boop-skills-edit-triage` skill.
+
 ## Anti-patterns
 - **One page per feature** — creates a graveyard of disconnected documents nobody reads
 - **"See also" link dumps** — links should be inline where the concept is discussed, not in a footer list
@@ -52,3 +86,5 @@ After editing, verify:
 ## Related
 
 - [`boop-writing-semantic-line-breaks`](../boop-writing-semantic-line-breaks/SKILL.md) — `reference/` pages are edited far more often than they are written; semantic line breaks are what keep those edits reviewable.
+- [`boop-writing-technical-prose`](../boop-writing-technical-prose/SKILL.md) — when blending new content into an existing page; the merged paragraph has to read as though it was always there, and matching a page's voice starts with writing full sentences.
+- `boop-knowledge-backfill` — when the gap is not one feature's knowledge but a backlog of shipped work that was never written down; that workflow decides what to process and in what order, then sends each spec back here.

package/skills/boop-product-design-thought-partnership/SKILL.md

@@ -4,6 +4,10 @@ description: "When the user wants to think out loud through a design — a featu
 metadata:
   category: design
 ---
+> **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 thought partnership
 

package/skills/boop-writing-documents/SKILL.md

@@ -4,6 +4,10 @@ description: "When you need to write a document someone will read cold and act o
 metadata:
   category: writing
 ---
+> **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.
 
 # Writing Documents
 

package/skills/boop-writing-semantic-line-breaks/SKILL.md

@@ -4,6 +4,10 @@ description: "When you need to write or edit prose in a markdown file under vers
 metadata:
   category: writing
 ---
+> **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.
 
 # Semantic Line Breaks
 

package/skills/boop-writing-technical-prose/SKILL.md

@@ -4,6 +4,10 @@ description: "When writing chat responses, summaries, bd issue bodies, specifica
 metadata:
   category: writing
 ---
+> **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.
 
 # Technical Prose