Product Authoring

How a product author turns a loose idea into the canonical handoff artifacts — a PRD, a UI reference, and a design-system delta list — anchored to the live design system, with no screenshots and no invented components.

For an agent, the contract is code and tokens — not pixels. This is the product-author view of the pipeline that Product ↔ R&D Handoff describes from the R&D side. This page is the front of the pipeline (explore → normalize → ship a PRD); that page is the back (gatekeeper → /plan-feature → /breakdown → build).

The principle: free at the front, governed in the middle, gated at the back

Authoring has exactly two modes, and only one of them is defined:

Mode	Who drives	How it works	Governed?
Explore	The product author	Free. Any tool — Claude, Figma, an HTML mockup, ABC-TOM, their own tooling. The author chases the idea however they think best.	No. Loose by design.
Normalize	The normalizer (a Cowork project)	Reads the exploration and produces the PRD + UI reference + §7.2.a deltas, anchored to the live design system.	Yes. The only defined, repeatable step.

Exploration is deliberately unconstrained — that is where product judgment lives. The single governed, repeatable step is normalization: turning whatever was explored into the version-controlled handoff artifacts. Everything the rest of this page specifies is the Normalize half. The Explore half has no rules on purpose.

Where the product author works

Cowork on the org Claude account (not a personal account). The Claude Cowork app is org-managed, built for non-developers, and can read and write files.
Connectors: GitHub + ClickUp + Figma (Dev).
The plugin is NOT required in Cowork. The Claude Code plugin is the surface R&D runs locally. In Cowork, the standing project Instructions + the GitHub connector do the work — no plugin, no local clone.

Setup (once)

Configure the three connectors in Cowork (Settings → Connectors):

Connector	Required	Why	Permissions needed
GitHub	Yes	Read the design system; write the PRD + UI ref as a PR	Read on `bewith-dev/design-system`; read + create pull requests on `bewith-dev/bewith-docs` (GitHub App: Contents `write` + Pull requests `write`)
ClickUp	Yes	Link the PRD back to the feature's ticket	The relevant workspace/space; read tasks + write comments (+ update status). Confirm it is enabled — if not piloted yet, verify the connector first.
Figma (Dev)	Only if exploring in Figma	Read frames as structured data; enables Path A (Code Connect)	A Dev/Developer seat (on the `with` team)

No repo clone needed — the GitHub connector reads files directly and opens PRs.

Fallback if GitHub write/PR or ClickUp is unavailable: the normalizer saves both files to the project folder and tells the author exactly what to hand R&D instead. The handoff still happens; only the delivery channel changes.

The standing normalizer instructions

This block goes once into the Cowork project's Instructions field. There is one persistent project (e.g. BeWith — Product); each feature is a folder/task inside it, not a new project. The block is the contract the normalizer follows on every feature:

You are the Product–R&D normalizer for BeWith. The product author (currently Gali) explores
features freely (in Claude, in Figma, or in their own tooling). YOUR job is to turn
their exploration into the canonical handoff artifacts, anchored to the live design system.
Converse in whatever language the product author uses (Hebrew or English). ALWAYS write
every output artifact (the PRD, the UI ref, the diff report) in English. The PRD's
customer-facing copy table (7.4) still carries BOTH English and Hebrew, because the product
UI is bilingual — that is product copy, not the document's authoring language.

SOURCES OF TRUTH — always read these LIVE from GitHub. Never rely on memory, never invent:
- bewith-dev/design-system: COMPONENTS.md (component catalog), src/theme/palette.ts (tokens),
  CLAUDE.md, docs/standards/* (React/styling/a11y conventions).
- bewith-dev/bewith-docs: docs/templates/prd.md (the PRD shape — follow it exactly),
  .claude/agents/prd-writer.md (follow its method), docs/methodology/product-rd-handoff.md,
  docs/company/* (project-brief, voice-dna, icp-profile — copy and framing inherit from these).

WHEN THE PRODUCT AUTHOR GIVES YOU A FEATURE (a spec/mockup/remarks, or a ClickUp link + artifacts + remarks):
do not ask them what the deliverable is and do not ask them to pick components. Detect the intake
and produce three artifacts:

1) PRD — in the docs/templates/prd.md shape. WHAT and WHY only, never HOW (no endpoints, schemas,
   data models, architecture, or library choices). If the intake contains HOW, restate it as
   requirements: API details -> section 8.2 (API-accessible capabilities, what must be reachable
   and why, no routes); analytics -> 8.1 (business event name, when, why); activation -> 8.3.
   Full frontmatter: id, status: draft, author, created, updated, clickup_parent + clickup_url,
   affected_repos (include design-system if any delta is filed), design_reference (relative path
   to the UI ref). Keep her FR-IDs and P0/P1/P2 priorities. Resolve any Open Question that blocks
   a P0. Copy is provided as TEXT in English and Hebrew (RTL). No em-dashes in customer-facing copy
   (em-dashes are fine in PRD prose).

2) UI ref (the design_reference) — accept whatever the product author explored in: an HTML mockup,
   a Figma link, or Claude Design output. NONE is the default; all are first-class. Read it and produce
   the UI ref by the matching path:
   - Figma that uses the design-system's Figma library WITH Code Connect (Path A, most deterministic):
     read it via the Figma Dev MCP, capture the exact component-to-region mapping it returns; the UI ref
     is the Figma Dev Mode frame URL (recorded in design_reference).
   - HTML mockup, Claude Design output, or a freehand Figma not wired to the library (Path B): produce a
     single self-contained HTML file that renders the screen and ALL states (default, loading, empty,
     error, success, disabled, selected; RTL), with every region annotated data-ds-component="<catalog
     component>" and its palette tokens. Its raw CSS is illustrative only; the real screen composes from the catalog.
   In EVERY case, produce the section 7.2 component+token mapping and the diff/delta (below) inside the PRD,
   so the anchoring lives in the version-controlled PRD, not only in the source artifact. Development always
   composes from the catalog, never from the raw mockup or Figma.

3) Diff/delta report — map every UI region to catalog components + palette tokens. Anything the
   catalog does not cover becomes an EXPLICIT delta, typed reuse | variant | element | component |
   composite, with a rationale and the design-system command to open (/add-component, /add-variant,
   /add-composite). NEVER invent a component name or a hex color. Map any raw hex in her mockup to an
   existing palette.ts token. If the same need likely exists in another screen (e.g. the bank transfer
   report), flag it as "reuse if already shared, else promote".

GATES (enforce, do not skip):
- 7.2 names ONLY components that exist in COMPONENTS.md and tokens from palette.ts. If you cannot find a
  component, it is a delta, not an invention.
- The three product laws must be present and non-empty (or explicitly N/A with a reason): 8.1 Observability,
  8.2 API-First, 8.3 Self-Serve Activation.
- No P0-blocking Open Question may remain.

AT SHIP (when the product author says to ship / create the PRD / open the ticket):
- Save the PRD to bewith-docs at docs/prds/<slug>-<cu-id>.md and the UI ref next to it as
  docs/prds/<slug>-<cu-id>.design-ref.html, as a Pull Request on a branch prd/<slug>.
- Update the ClickUp ticket (clickup_parent) with links to the PRD and the UI ref, and note it is ready for R&D.
- If GitHub write/PR or ClickUp is unavailable, save both files to the project folder and tell the product author exactly
  what to hand to R&D instead.
- End with a short, scannable summary of what you produced and any deltas R&D must build. Do not write to
  memory directly; if something seems worth remembering, propose it as a one-line suggestion.

ITERATION (when the product author asks to change something): update the same feature's PRD and UI ref and push a new
commit to the same PR (or open a new PR if it was merged). Git keeps the version history.

BOUNDARY: you produce the WHAT artifacts. R&D owns the HOW — the Design Doc (via /plan-feature), and they
build the deltas per docs/standards/*. Do not design endpoints or architecture.

The block's "diff/delta report" is the now-formalized PRD §7.2.a Design-system deltas table (see below) — the structured, parseable form of the same delta list. Read "the section 7.2 mapping and the diff/delta" as §7.2 + §7.2.a.

Per-feature flow

Explore however you like — a spec doc, an HTML mockup, Claude Design output, a Figma link, or ABC-TOM. The intake the normalizer wants is three things: a spec, a mockup, and remarks. Add the feature's ClickUp link.
In the BeWith — Product project, open a new task/folder for the feature.
Drop the intake — either:
- a feature folder (e.g. withdrawals-report/) holding the spec + mockup + a remarks file; or
- a chat message: a ClickUp link + the artifacts (link or file) + the remarks.
Say "create the PRD and UI ref" (or "let's ship this feature"). Do not pick components or templates — the project does that.
The normalizer reads the design system live, produces the PRD + UI ref + §7.2.a deltas, and opens a PR + updates the ticket.
Review the deltas: each non-reuse row in §7.2.a is design-system work R&D must build first. Confirm it makes sense.

Minimum intake the normalizer needs: a ClickUp link + a mockup (HTML or Figma URL) + a spec/remarks.

Where the outputs are saved

Artifact	Location	Form
PRD	`bewith-dev/bewith-docs` → `docs/prds/<slug>-<cu-id>.md`	A Pull Request on branch `prd/<slug>`
UI reference	next to the PRD → `docs/prds/<slug>-<cu-id>.design-ref.html`	Same PR; the PRD's `design_reference` frontmatter points to it
ClickUp ticket	the feature's parent (`clickup_parent`)	Links to both files + a "ready for R&D" note

Iterating

Ask the normalizer to change something → it updates the same feature's PRD + UI ref and pushes a new commit to the same PR (or opens a new PR if the previous one merged). Git keeps the version history — no separate changelog to maintain.

The UI reference

The product author's exploration arrives as one of three first-class inputs — none is the default: an HTML mockup, a Figma link, or Claude Design output. The normalizer reads whatever was explored and produces the UI ref by the matching path:

Path A — Figma wired to the design-system library with Code Connect (most deterministic). Dev Mode returns real component code (<Button variant="primary">) rather than a generic <div>. The UI ref is the Figma Dev Mode frame URL, recorded in design_reference.
Path B — an HTML mockup, Claude Design output, or a freehand Figma not wired to the library. The normalizer produces a single self-contained HTML file rendering the screen and all states (default / loading / empty / error / success / disabled / selected; RTL), with every region annotated data-ds-component="<catalog component>" and its palette tokens. Its raw CSS is illustrative only.

In every case, §7.2 (UI Composition) and §7.2.a (Design-system deltas) live in the version-controlled PRD, not only in the source artifact — the anchoring is reviewable and diffable. Development always composes from the catalog, never from the raw mockup or Figma.

Exploring on the design-system basis (recommended, not mandatory)

Mockups are better — less drift, fewer deltas, a clearer picture of what already exists — when exploration starts from the design system:

Figma: seed the canvas with the design-system Figma library (not a freehand canvas).
Claude / Claude Design: seed the Cowork project with the catalog + tokens and ask it to compose from the real components.

This does not make exploration deterministic — that remains the normalizer's job, and drift is still caught there. It just gives the normalizer less to reconcile and surfaces fewer surprise deltas at ship time.

The delta taxonomy is §7.2.a

The list of design-system gaps is not prose — it is PRD §7.2.a Design-system deltas, a structured, parseable sub-table. The delta types use the catalog's own vocabulary, mapping 1:1 to the COMPONENTS.md sections (Elements / Components / Composites) and to the design-system commands:

Delta type	What it is	Design-system command
`reuse`	already in `COMPONENTS.md` — use as-is	none (note the import path in §7.2)
`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>`

The rule — enforced, not advised:

Never invent a component name or a hex color. Every gap is a row in §7.2.a, and every raw hex maps to an existing palette.ts token.

A component the feature needs is either in the catalog (reuse) or a tracked delta with a command. There is no third path where the consuming app quietly hand-rolls a one-off.

The seam — how §7.2.a flows downstream

§7.2.a is the deterministic bridge from "what the UI needs" to "what the shared design system must grow":

The product author's PRD carries §7.2.a.
/plan-feature parses it row by row and emits one design-system task per non-reuse row, recorded in the Design Doc as prerequisites that ship before the feature is built in organization-dashboard (or whichever consuming app §2 names).
The gatekeeper enforces it — the PRD goes back unless every component named in §7.2 is either in COMPONENTS.md or carries a §7.2.a delta row whose command matches its type. This is what makes "never invent" enforceable rather than advisory.

For the full R&D-side mechanics — the gatekeeper → /plan-feature → /breakdown → build chain, the dependency ordering that makes design-system tasks ship first, and the ClickUp ↔ GitHub task pipeline — see Product ↔ R&D Handoff. This page does not duplicate it.

The three product laws (a gate)

Every PRD must address the three product laws — present and non-empty, or explicitly N/A with a reason:

Law	PRD section	What it captures
Observability	§8.1	The business events to measure, when they fire, and why
API-First	§8.2	The business-logic actions that must be reachable programmatically (not UI-only)
Self-Serve Activation	§8.3	The questions the central activation agent asks the customer to enable the feature (skip only if there is no activation surface)

The normalizer fills these from the intake; the gatekeeper blocks a PRD that leaves a law silently empty.

Scaling: a template, not a one-off

The process is a template, and nothing here is bound to a single person — the instructions address "the product author" (the role), not a name.

Another product author, same product → joins the same BeWith — Product project (features are folders), or starts a new project pointed at the same coordinates. Same catalog, same docs/prds, same ClickUp space.
A different product (another app, a new product line) → swap three coordinates and open a fresh Cowork project pointed at them:
1. design-system — that product's design-system repo (its catalog + tokens).
2. docs target — that repo's docs/prds (or a product subfolder under bewith-docs).
3. ClickUp space — that product's space.

The normalizer doesn't care which product or person it serves. The more a design system is shared, the less the author has to specify — and the cheaper every future feature's handoff becomes.

The principle: free at the front, governed in the middle, gated at the back​

Where the product author works​

Setup (once)​

The standing normalizer instructions​

Per-feature flow​

Where the outputs are saved​

Iterating​

The UI reference​

Exploring on the design-system basis (recommended, not mandatory)​

The delta taxonomy is §7.2.a​

The seam — how §7.2.a flows downstream​

The three product laws (a gate)​

Scaling: a template, not a one-off​

See also​