@boopkit/cap-product-design 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,49 @@
+# @boopkit/cap-product-design
+
+**Part of [Boop](https://www.npmjs.com/package/@boopkit/cli)** — a bootstrap platform for AI-first builders. `boop init` scaffolds a running Node/TypeScript web app from composable **capabilities**, each one bundling the code, dependencies, middleware wiring, and agent skills needed for a feature. You pick the capabilities; `boop add` handles the rest.
+
+`cap-product-design` is a skills-only capability covering the "think before you build" stretch of the workflow. It teaches an agent how to pull clear requirements from a vague founder brief, how to write an engineering design doc that exposes trade-offs (not just outcomes), how to document a feature for a specific audience, and how to fold new knowledge into the project's living `reference/` wiki after shipping.
+
+## What You Get
+
+A bundle of agent-facing skill files for requirements, design, feature docs, and reference-doc integration. No runtime code, no dependencies, no server wiring — documentation-as-code for the agents working in your repo.
+
+### Skills installed
+
+Copied into `skills/` on install:
+
+- `reqs.feature-requirements.skill.md` — how to turn a brief or vague directive into real requirements: ask 3-5 focused trade-off questions, push back on ambiguity without interrogating, and know when enough clarity is enough to proceed.
+- `reqs.feature-documentation.skill.md` — how to write feature documentation aimed at a specific audience and activity, with the right tone and grounding for readers who haven't done this before.
+- `design.engineering-design.skill.md` — the engineering design doc structure (Goals, Non-Goals, Approach, Alternatives, Tradeoffs, Open Questions) with a stance: make the *decision* visible, not just the solution.
+- `docs.reference-integration.skill.md` — how to blend new knowledge into `reference/` after a feature lands, keeping it a living wiki of what the system actually is, not a pile of per-feature pages.
+
+## Requirements
+
+**Other capabilities:** none.
+
+**npm dependencies added to your project:** none. `cap-product-design` is pure documentation for agents.
+
+**Environment variables:** none.
+
+**Project files referenced:** several skills point at `reference/tenets.ref.md` for overarching principles. That file is provided by the `web-app` profile's `reference/` directory. In other profiles, the skill will still work — the reference link just won't resolve.
+
+## Usage
+
+Skills are meant to be read by AI agents, not humans (though humans are welcome). Once installed they live in your project's `skills/` directory alongside skills from other capabilities.
+
+How agents find them depends on the harness:
+
+- Projects with a Claude Code `CLAUDE.md` typically instruct the agent to consult `skills/index.md` or the relevant `.skill.md` file before acting.
+- Harnesses with a native skill-discovery system (e.g. slash-command style skills) surface them by filename.
+
+A typical flow: a founder gives the agent a two-sentence feature brief. The agent reads `reqs.feature-requirements.skill.md` and asks a few trade-off questions to fill the gaps. Once the shape is clear it reads `design.engineering-design.skill.md` and writes a design doc with an explicit Alternatives section. After the feature ships, it reads `docs.reference-integration.skill.md` and blends the new behaviour into the existing concept pages in `reference/` — not a new feature-specific page.
+
+## Added by
+
+Included by default in the `web-app` profile.
+
+Add to an existing project with:
+
+```bash
+boop add product-design
+```

package/package.json

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

package/skills/docs.reference-integration.skill.md

@@ -0,0 +1,45 @@
+# 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.
+
+## Goal
+Keep `reference/` as a living wiki of **what the system actually is right now** — not a pile of per-feature pages. New knowledge is blended into existing concept pages; new pages are created only when a genuinely new concept has no home.
+
+## Principles
+
+- **Reference is the current truth.** Specs describe the intended future; reference describes what shipped. After a feature lands, reference must reflect reality.
+- **Entity/concept pages, not feature pages.** Don't create `matching-feature.ref.md` — instead update `matching-system.ref.md`, `database.ref.md`, and any other concept pages the feature touches.
+- **Wiki-style cross-links.** Every reference page should link to related pages using relative markdown links (e.g., `[service layer](service-layer.ref.md)`). When adding content, add links in both directions — the page you're editing and the pages you're referencing.
+- **Blend, don't append.** New content should be woven into the existing narrative at the right location, not dumped at the bottom under a "New: feature X" heading. The reader shouldn't be able to tell which paragraph was added when.
+
+## Process
+
+### 1. Identify affected concepts
+Read the spec/feature summary and list every concept the feature touches. Examples: a new API endpoint affects the REST API ref, the service layer ref, and possibly the database ref. A new background job affects the job system ref and whatever domain it operates in.
+
+### 2. For each concept, check for an existing page
+- **Page exists** → Read it, understand its structure, then merge new content into the appropriate sections. Update any tables, lists, or diagrams. Add cross-links to other affected pages.
+- **No page exists** → Create a new `{concept}.ref.md` page. Follow the structure patterns of existing reference pages in the project. Add cross-links from related existing pages to the new page.
+
+### 3. Merge guidelines
+- Match the voice and style of the existing page — don't introduce a different tone.
+- If a section is getting long after the merge, consider splitting into sub-sections rather than leaving a wall of text.
+- Update any "overview" or "key concepts" sections that provide a high-level map.
+- If the feature introduces new terminology, define it where it first appears and link to it from other pages.
+- Remove or update any content that is now outdated or contradicted by the new feature.
+
+### 4. Cross-linking checklist
+After editing, verify:
+- [ ] Every page you modified links to every other page you modified (where the relationship is meaningful)
+- [ ] New concepts are linked from the most relevant existing overview/index sections
+- [ ] No orphan pages — every new page is reachable from at least one existing page
+
+### 5. Naming conventions
+- File: `{concept}.ref.md` (e.g., `matching-system.ref.md`, `user-auth.ref.md`)
+- Use kebab-case, singular or plural based on what reads naturally
+- Suffix is always `.ref.md`
+
+## 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
+- **Copy-pasting from the spec** — specs use future tense and rationale; reference uses present tense and describes what is, not why it was chosen
+- **Leaving stale content** — if the feature changes existing behavior, update or remove the old description