Product ↔ R&D Handoff

How a feature travels from idea to shipped code without screenshots, without duplicate components, and without ambiguous handoffs. The guiding principle:

For an agent, the contract is code and tokens — not pixels. The @bewith-dev/design-system repo is the single source of truth. Both design production and implementation anchor to it.

This page is the map. The artifacts it produces are described in the PRD template and Design Doc template.

Product-author's side: how a feature is explored and normalized into a PRD before it reaches this pipeline is documented in Product Authoring. This page picks up where that one leaves off.

TL;DR

Stage	Owner	Artifact	Tool
1. Capture intent	Product	PRD (`docs/prds/<slug>-<cu-id>.md`)	`prd-writer` agent
2. Design reference	Designer	Figma frame (Dev Mode) OR Claude Design code branch	Path A or B (below)
3. Hand off	Product	PRD status: `ready-for-rd`	`/handoff` → `gatekeeper` validates
3b. CTO review	Product → CTO	CTO-review ticket in the ClickUp "CTO Review" list (tag `cto review`, full handoff package)	`/cto-review`
4. Translate to design	R&D	Design Doc (`docs/designs/<slug>-<cu-id>.md`) — §7.2.a deltas become design-system prerequisite tasks	`/plan-feature`
4b. Approve design	R&D	Design Doc status: `approved`	`gatekeeper` agent validates (Mode B)
5. Break into tasks	R&D	GitHub Issues, each linked to ClickUp parent	`/breakdown`
6. Build	R&D	Code	`architect`, Claude Code, design-system catalog
7. Verify	Product + R&D	DoD checked off	`process-guardian` agent

The pipeline at a glance

                ┌─────────────────────────────────────────────────┐
                │   @bewith-dev/design-system (source of truth)   │
                │ tokens (palette.ts) · components · CLAUDE.md    │
                │ · COMPONENTS.md catalog · Storybook             │
                └─────────────▲────────────────────▲──────────────┘
                              │ anchors to         │ anchors to
        ┌─────────────────────┴────┐     ┌─────────┴────────────────┐
        │ Path A — Figma (mature)  │     │ Path B — Claude Design   │
        │ Dev Mode MCP + Code      │     │ (greenfield exploration) │
        │ Connect → structured ref │     │ prompt → code branch     │
        └───────────────┬──────────┘     └──────────┬───────────────┘
                        │  design reference (code + component refs)
                        ▼
              PRD §7.2 names components from COMPONENTS.md
              PRD §7.2.a lists each design-system delta
                 (reuse · variant · element · component · composite)
                        │
                        ▼
              /handoff → ready-for-rd  ──▶  /cto-review opens
                        │                    CTO-review ticket (ClickUp)
                        ▼
              R&D runs /plan-feature → Design Doc draft
                 ├─ §7.2.a deltas → design-system tasks (ship FIRST)
                 └─ consuming-app tasks depend on them
                        │
                        ▼
              /breakdown → GitHub Issues → ClickUp tasks
                        │
                        ▼
              Implementation: Claude Code reads design-system + tokens
                        │
                        ▼
              process-guardian verifies DoD → shipped

Status (2026-06): COMPONENTS.md + the npm run catalog generator ship with design-system PR #326 (in review). Until it merges, the live catalog is Storybook (https://bewith-dev.github.io/design-system/) + src/components. Treat COMPONENTS.md as the target contract.

Roles & responsibilities

Role	Owns	Reads	Output
Product	PRD content, UI Composition table, Acceptance Criteria	`docs/company/` (brand) + COMPONENTS.md (component names)	PRD at `docs/prds/<slug>-<cu-id>.md`; design reference
Designer (often the same person)	Design reference (Figma frame or Claude Design output)	PRD §1-6, COMPONENTS.md, palette.ts	Figma frame published for Dev Mode access OR Claude Design code branch
R&D / Engineer	Design Doc, code, tests	PRD, design reference, COMPONENTS.md, repo CLAUDE.md	Design Doc at `docs/designs/<slug>-<cu-id>.md`; GitHub Issues; shipped code

The boundary between Product and R&D is enforced by the PRD template ("what does NOT belong here") and by the gatekeeper agent reviewing the PRD against the Definition of Ready before hand-off.

Independent human review at each gate (no self-approval)

A gate is only real if an independent human stands behind it — the producer self-assessing its own output is not a gate.

Hand-off (PRD): the product owner ratifies the PRD before ready-for-rd. A P0 requirement may not be weakened by an open question the producer resolved on its own — that is the product owner's decision, recorded.
Design review (DR): the CTO / engineering reviewer approves the Design Doc before approved, with particular attention to the source-of-truth and reuse checks (gatekeeper Mode B, section G).
A gate run only by the producer (the agent that authored the artifact) is flagged, not accepted; it must be signed by the independent reviewer above. (POC lesson: gates were self-run, P0 open questions self-resolved, the Design Doc self-"approved" — so the data-source and product decisions slipped to build time.)

Product-side note — no reject-and-redo loop. When the product author plans once and will not rewrite (their own environment, e.g. the bewith-product-handoff flow), "reject and send back" is not a usable backstop. Alignment must succeed in that single pass — the author sees the design-system UI reference and confirms it before hand-off. There the gatekeeper acts as a safety-net / signal (a gap it finds points to a fix in the front-end tooling), not a bounce that asks the author to redo the work.

Lifecycle & statuses

Status	What it means	Who sets it
`draft`	PRD is being written. Not yet hand-off ready.	Author
`ready-for-rd`	PRD passes Definition of Ready. R&D can start the Design Doc.	Author after Gatekeeper approves
`in-progress`	R&D has started building.	R&D lead
`shipped`	All DoD items checked.	R&D + Product
`deprecated`	Feature removed or replaced.	Owner

The same statuses apply to the Design Doc (with in-review and approved between draft and in-progress). The draft → approved transition is gated by gatekeeper in Mode B — the same independent readiness check it runs on the PRD, applied to the Design Doc's §1-§15 (completeness, design soundness, traceability to the PRD, a filled §13 Task Breakdown). §16 Definition of Done is not part of this gate — that is process-guardian's check at closure.

Stage 3b — the CTO-review ticket

When a PRD reaches ready-for-rd, /handoff opens a CTO-review ticket via /cto-review so the CTO sees every feature before R&D commits to building it. The ticket lands in the dedicated ClickUp "CTO Review" list, tagged cto review, and carries the whole handoff package in one place — problem/outcome, scope, UI composition (components from COMPONENTS.md), the design reference, acceptance criteria, and links to the PRD + parent task. The review needs no extra digging.

Title convention, so the list scans cleanly:

[Feature name] informative title

The [Feature name] prefix stays regardless; the rest is a one-line plain statement of scope (editable after creation). Example: [WhatsApp OTP] Add WhatsApp as an OTP delivery channel for the consumer app.

The same command runs manually on a task that did not come through the flow — a one-off the CTO should still see — gathering whatever handoff fields exist and marking the rest as not provided (never invented). It opens the ticket and stops there; the CTO drives the review.

Path A — Figma (mature library, existing designs)

For features that already have Figma designs, turn Figma into something an agent consumes deterministically:

Dev Mode MCP server (Figma) lets Claude Code read frames as structured data (layout, tokens, generated code) — not screenshots.
Code Connect (Figma) maps each Figma component to the real component in @bewith-dev/design-system, so the MCP returns "use <Button variant="primary"> from the library" instead of a generic <div>. This is the lever that kills screenshots and guarantees reuse.

Connecting it (once)

Dev Mode MCP is declared in @bewith-dev/design-system/.mcp.json. The endpoint is Figma's local Dev Mode server (typically http://127.0.0.1:3845/mcp), which runs inside the Figma desktop app — open the file in Figma desktop and enable the Dev Mode MCP server for it to connect.
Code Connect mappings live as *.figma.tsx files next to each component in @bewith-dev/design-system, published with the Code Connect CLI. Each maps a Figma component (by node URL) to the real @bewith-dev/design-system component + props.

Verify current setup on Figma's side — Dev Mode MCP and Code Connect are Figma features and their configuration evolves (the endpoint may be /mcp or /sse depending on version).

Path B — Claude Design (greenfield, fast exploration)

When there is no Figma yet, Product describes intent and the output is code. The critical input: give Claude Design this design system's context — the tokens and the COMPONENTS.md catalog — so the output uses our components instead of inventing them. Because the output is code landing in a repo/branch, Claude Code reads it directly: code-to-code handoff, zero images.

Use Path B for early exploration; once a pattern stabilizes, promote shared pieces into @bewith-dev/design-system (Path A territory) so they are reused, not re-created.

What a good PRD §7 looks like

Instead of attaching a mockup and saying "build this," the UI section:

Names components from COMPONENTS.md (e.g. "header uses SummaryCard + Chip; primary action is Button").
References tokens for any color/spacing intent (e.g. "use semantic.success"), never raw hex.
Links the Figma frame (Path A) and/or the Claude Design branch (Path B).
Itemizes every design-system delta in §7.2.a: each component the feature touches gets a row with a delta type (reuse / variant / element / component / composite) and the exact design-system command it maps to. This is the structured list /plan-feature turns into tasks, not a prose aside, and nothing is hand-rolled in the consuming app.

This makes the R&D task implementable pixel-perfect on the first pass.

Design-system deltas ship first

The PRD's §7.2.a is the deterministic bridge between "what the UI needs" and "what the shared design system must grow." It lists every component the feature touches, each tagged with a delta type drawn from the catalog's own vocabulary, so each maps 1:1 to a design-system command:

Delta type	What it is	Design-system task
`reuse`	already in `COMPONENTS.md`	none — reference the import path
`variant`	a new prop / state / style on an existing component (never a fork)	`/add-variant <Component> <desc>`
`element`	a brand-new primitive	`/add-component <Name> element`
`component`	a brand-new composed / feature-level component	`/add-component <Name> component`
`composite`	a new component assembled only from existing catalog pieces	`/add-composite <Name> <desc>`

/plan-feature reads §7.2.a row by row and emits one design-system task per non-reuse row, recording them in the Design Doc's §13 Task Breakdown as prerequisites: the /add-variant · /add-component · /add-composite work runs in @bewith-dev/design-system and ships before the feature is built in organization-dashboard (or whichever consuming app §2 names). The consuming-app frontend tasks Depend on the design-system tasks, so the ordering is enforced by the dependency graph, not by a reviewer remembering.

Why this matters: it is the operational form of "the contract is code and tokens, not pixels." A component the feature needs is either in the catalog (reuse) or a tracked change to the shared system (a delta with a command). There is no third path where the app quietly hand-rolls a one-off. gatekeeper enforces it — it sends the PRD back unless §7.2.a is well-formed and every component named in §7.2 is either in COMPONENTS.md or carries a §7.2.a row whose command matches its delta type.

The task pipeline (ClickUp ↔ GitHub Issues)

PRD created → corresponding ClickUp parent task (CU-XXXXX) created. The clickup_parent frontmatter on the PRD links the two.
PRD reaches ready-for-rd → R&D opens the Design Doc.
Design Doc §13 Task Breakdown filled → R&D runs /breakdown to convert each task row into a GitHub Issue, each labeled with the parent CU-id.
Every Issue includes the BeWith 6-section format (project_gh_issue_format). Effort and risk labels come from the Task Breakdown row.
PRs reference the Issue + the parent CU-id; process-guardian verifies the full DoD before closure.

Who lives where — and when NOT to create an Issue

The two trackers split by audience, and the mirror between them is conditional, not 1:1:

ClickUp = the product board. Product tasks + their sub-tasks — the unit PMs/sales/support/management see and report progress on in the daily. (May move to Jira later.)
GitHub Issues = the software breakdown R&D does on a product task — one Issue per PR-sized chunk, the engineering detail Product doesn't need to see.

Rules (the point is easy tracking + visible progress + no noise, not symmetry):

Create a GitHub Issue only when there is real software decomposition. A small ClickUp task that is itself one piece of work needs no Issue — work it directly (branch → PR referencing the CU-id). Forcing a 1:1 Issue per ClickUp task is duplication and noise.
A task too big to track as one → break it into smaller ClickUp sub-tasks (so the board shows movement and items come off the board), and open GitHub Issues only for the software pieces that compose them.
Product-visible building-blocks the team reports on in the daily live in ClickUp (as tasks or sub-tasks), opened by R&D; the engineering detail that doesn't interest Product stays in the Issues.

This is the complexity gate, applied to the whole pipeline: a small change skips PRD + Design Doc and goes straight to a branch/PR (or one Issue); a medium one fills only the relevant Design Doc sections; a feature runs the full chain. Same artifacts at variable depth — never a parallel /specs-style model. When an Issue does exist, state-sync keeps the bidirectional ClickUp↔Issue mirror; when one doesn't, ClickUp alone is the record. This system is experimental — we optimize it in use.

Enforcement (so the source of truth doesn't leak)

Two layers:

@bewith-dev/design-system/CLAUDE.md instructs every agent working in any consuming repo to assemble only from the library and tokens.
lint / CI in design-system blocks raw hex and ad-hoc duplicates of catalog components.

If a one-off color or a local copy of a library component slips in — stop. That belongs in the design system. Open an /add-component task and consume it from there.

Maintenance checklist (design-system)

These keep the SoT machine-readable. Maintained in @bewith-dev/design-system:

New/changed component → npm run catalog (refresh COMPONENTS.md) (ships with PR #326)
New/changed component → add/update its Storybook story
New shared color/spacing → add a token in palette.ts, never inline
PRD §7.2 references catalog component names + tokens, not screenshots
PRD §7.2.a itemizes every design-system delta with its type + command; non-reuse rows become design-system tasks that ship before the consuming-app build
Figma shared components have a Code Connect mapping to the catalog entry

TL;DR​

The pipeline at a glance​

Roles & responsibilities​

Independent human review at each gate (no self-approval)​

Lifecycle & statuses​

Stage 3b — the CTO-review ticket​

Path A — Figma (mature library, existing designs)​

Connecting it (once)​

Path B — Claude Design (greenfield, fast exploration)​

What a good PRD §7 looks like​

Design-system deltas ship first​

The task pipeline (ClickUp ↔ GitHub Issues)​

Who lives where — and when NOT to create an Issue​

Enforcement (so the source of truth doesn't leak)​

Maintenance checklist (design-system)​

See also​