@boopkit/cap-product-design 0.1.0

package/capability.json

@@ -0,0 +1,9 @@
+{
+  "name": "product-design",
+  "description": "Product design skills",
+  "type": "development",
+  "dependencies": [],
+  "devDependencies": [],
+  "files": [],
+  "skills": ["design.engineering-design.skill.md", "reqs.feature-documentation.skill.md", "reqs.feature-requirements.skill.md"]
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@boopkit/cap-product-design",
+  "version": "0.1.0",
+  "description": "Product design skills for AI agents",
+  "files": [
+    "skills/",
+    "capability.json"
+  ],
+  "boopkit": {
+    "capability": true,
+    "skillsDir": "skills",
+    "manifest": "capability.json"
+  },
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/design.engineering-design.skill.md

@@ -0,0 +1,60 @@
+# Engineering Design
+When you need to design a feature or system and communicate the technical decisions.
+
+## Goal
+**Make the decision visible, not just the solution.**
+
+The hardest part of engineering design isn't finding *an* answer — it's showing why *this* answer over the alternatives. A design doc that only describes what was built is a post-hoc narrative. A design doc that shows goals, rejected alternatives, and tradeoffs lets reviewers (and future agents) understand the constraints and extend the design without re-deriving it.
+
+## Design document structure
+
+| Section | Purpose | Required? |
+|---|---|---|
+| **Goals** | What are we trying to achieve? | Yes |
+| **Non-Goals** | What are we explicitly *not* solving? | Yes — constrains scope |
+| **Approach** | High-level design of the system | Yes |
+| **Alternatives** | Other approaches considered and why this was chosen | Yes — this is where judgment lives |
+| **Details** | Key implementation specifics (not exhaustive) | Yes |
+| **Tradeoffs** | Pros and cons of the chosen approach | Yes |
+| **Open Questions** | Unresolved decisions blocking implementation | If applicable |
+| **Future Work** | Deferred improvements or features | If applicable |
+| **References** | External docs, specs, or code consulted | If applicable |
+
+## Guidelines
+- **Non-Goals are as important as Goals** — they prevent scope creep and make trade-off reasoning explicit
+- **Alternatives section earns trust** — showing what you rejected (and why) is what separates a design from a description
+- **Details should be selective** — document the tricky parts and link to the rest; don't rewrite the code in prose
+- **Design docs live in `specs/`** — see [engineering-planning](./proj.engineering-planning.skill.md) for how designs become work plans
+
+## 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:
+
+**Entry points → Logic → Data**
+
+| Layer | Responsibility | Examples |
+|---|---|---|
+| **Entry points** | Parse transport-specific input, delegate to logic layer, format output | HTTP controllers, CLI commands, message consumers, event handlers |
+| **Logic** | Business rules, domain validation, orchestration | Services, use-cases, domain models |
+| **Data** | Persistence, external APIs, file I/O | Repositories, ORM clients, API clients, queue publishers |
+
+### Key principles
+
+- **Dependencies flow inward** — entry points depend on logic; logic depends on data. Never the reverse.
+- **Entry points are thin dispatch** — parse, call, format. No business rules, no direct data access.
+- **Logic owns the rules** — all domain validation, calculations, and orchestration live here. This layer is transport-agnostic and testable in isolation.
+- **Data access is encapsulated** — the logic layer calls data abstractions; it doesn't construct raw queries or import database clients directly.
+- **Each layer has its own design skill** — before writing code in a layer, check `skills/index.md` for the matching design skill (e.g., controller design, service design, data model design).
+
+### Why this matters for agents
+
+Layering violations are the most common architecture mistake in generated code. The typical failure: an agent reads the data-access skill, builds correct services, then writes entry points that bypass those services and call the data layer directly. Reading the entry-point design skill (e.g., controller skill) before writing entry-point code prevents this.
+
+### Applying to different project types
+
+| Project type | Entry points | Logic | Data |
+|---|---|---|---|
+| Web API | Express routes/controllers | Service modules | Prisma, API clients |
+| CLI tool | Command handlers | Core logic modules | File I/O, config |
+| Event-driven | Message consumers | Processing services | Queue publishers, DB |
+| Library/SDK | Public API surface | Internal modules | — |

package/skills/reqs.feature-documentation.skill.md

@@ -0,0 +1,6 @@
+# Feature Documentation
+When you need to document a complex feature, function or system
+- 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.
+- Identify the activity to be explained. For example, designing or operating at scale.
+- Write up an introduction to {audience} that haven’t done this sort of {activity} before. This should be a gentle intro, {group identity} flavored, “this is going to be fun” toned, very precise engineering speak explanation of what is going to be in place for {activity}. Use “we” as needed. Provide as markdown.

package/skills/reqs.feature-requirements.skill.md

@@ -0,0 +1,33 @@
+# Feature Requirements
+
+Be sure to read the [reference/tenets.ref.md](../reference/tenets.ref.md) for overarching principles that apply to all features. 
+
+## When you need to define what a feature should accomplish before designing how to build it
+
+Define product requirements that articulate the problem to be solved, who benefits, and what success looks like—before diving into technical design. Requirements should be clear enough to guide implementation decisions while leaving room for engineering judgment on how to achieve the goals.
+
+## When you receive a brief or vague directive
+
+**Be an advisor, not just an executor.** A major audience for boop is non-technical founders. Their directives are often incomplete — not because they're wrong, but because they haven't thought through all the implications yet. When someone gives you a 2-3 sentence business outline, resist the urge to immediately start designing or building. Instead, ask clarifying questions that help them think through what they actually need.
+
+**Push back on ambiguity, but don't interrogate.** Ask 3-5 focused questions that surface the most consequential unknowns — who the users are, what the core workflow looks like, what "done" means for a first version. Skip questions you can reasonably infer or defer. The goal is to fill gaps that would change your approach, not to produce a comprehensive requirements document before writing a line of code.
+
+**Frame questions as trade-offs, not open-ended prompts.** Instead of "what features do you want?" ask "would you rather launch with X and add Y later, or do you need both on day one?" Concrete options help non-technical users think through implications they wouldn't surface on their own. When you spot a likely edge case or missing piece, name it: "You mentioned user accounts — do you need roles/permissions, or is everyone equal for now?"
+
+**Know when you have enough to proceed.** Once you understand the core user, the primary workflow, and the first-version boundaries, move forward. You can always ask more questions as specifics emerge during design. Don't let clarification become a blocker — the point is to avoid building the wrong thing, not to achieve perfect upfront specification.
+
+## When writing requirements for a new feature
+
+**Start with the user story.** Every feature should articulate a concrete scenario: who is trying to accomplish what, and why it matters. For example, "During a customer demo, we want to show how GPT-4 can analyze publisher data so that sales prospects see advanced capabilities in action." Good stories make trade-offs obvious—they reveal which users to prioritize, which problems are urgent, and which nice-to-haves can wait. Stories create shared context between product, engineering, and stakeholders.
+
+## When defining feature scope
+
+**Frame goals and non-goals explicitly.** Goals define what the feature must accomplish—the specific outcomes or capabilities that constitute success. Non-goals are equally important: they establish boundaries, prevent scope creep, and document intentional trade-offs. For instance, if a feature aims to "provide confidence-of-being-human signals via VAT/ACT" but explicitly does *not* aim to "replace MRC IVT systems," that constraint guides architectural choices and manages stakeholder expectations. When non-goals address common assumptions or adjacent problems, they prevent expensive detours during implementation.
+
+## When choosing between implementation approaches
+
+**Minimize complexity and preserve forward compatibility.** Prefer solutions that solve the immediate problem with minimal new surface area—fewer tables, fewer endpoints, fewer configuration options. Features should extend naturally as needs evolve, not require rewrites. For example, storing permissions in JSON blobs instead of creating multiple relational tables may simplify v1 while keeping the door open for future normalization if query patterns demand it. Always ask: what's the simplest approach that doesn't foreclose future options? This isn't about building for imaginary futures—it's about avoiding premature commitments that make future change expensive.
+
+## When determining how to measure success
+
+**Define success metrics and adoption paths.** Requirements should articulate how you'll know the feature works in practice: which user flows must succeed, which edge cases must degrade gracefully, and what operational characteristics matter (latency, throughput, error rates). For multi-stage rollouts, specify adoption milestones: "SSPs pass-through first, native verification later" clarifies what's needed for launch versus what's a future enhancement. Metrics ground the conversation—they prevent "done" from becoming subjective and help prioritize quality investments.