Reference Guide

Design + Build Workflow

Cowork plans, designs, and decides; Claude Code builds. The six-phase pattern and the one anti-pattern that wrecks it.

← Back to Reference Hub

Best for: Turning a vague idea into a written brief with constraints, audience, and success criteria.

  • Skills: doc-coauthoring, user-research-synthesis, competitive-analysis, account-research
  • Connectors: Drive, Notion, Linear, Slack — for context Cowork can pull rather than you pasting
  • Output: a written brief in a working folder — audience, problem, success criteria, constraints
  • Time investment: 30 minutes to a few hours, depending on stakes
  • Anti-pattern: skipping straight to Phase 4 because "we know what we're building"

Limitations: Don't over-engineer the brief. The goal is to make Phase 2 (design) and Phase 4 (build) faster — not to produce a perfect spec. If the brief takes more than half a day, you're solving the wrong problem.

Strategy

Best for: Pinning down the UX, the data model, the key flows, and the visual direction.

  • Skills: client-feature-roadmap, canvas-design, brand-guidelines, theme-factory, web-artifacts-builder
  • Artifacts: interactive React/HTML mockups, feature boards, comparison matrices
  • Connectors: Figma (if available), Canva for visual assets
  • Output: artifacts the user clicks through and reacts to — not a deck of static images
  • Anti-pattern: producing a static PDF and asking "what do you think?" — interactive artifacts get sharper feedback

Limitations: Mockups are a planning tool, not a deliverable. The artifact's job is to surface decisions, not to be production code. Don't over-style — the build pass will redo the visual layer anyway.

Design

Best for: Translating the brief + design into an unambiguous build instruction.

  • Skill to load: cowork-cc-handoff — the canonical pattern for Cowork → Claude Code dispatch
  • Output: a Markdown prompt body, plus a launch line (cd ~/project; claude --dangerously-skip-permissions)
  • Format: two separate copy-blocks (launch line, prompt body) — easier for the user to paste
  • Include in the prompt: stack, file structure, env vars, the data model, what "done" looks like
  • Anti-pattern: Cowork relays user messages to Claude Code by hand for hours — write the prompt once and let CC drive

Limitations: The prompt should be long enough to remove ambiguity, short enough that the user can review it before pasting. If you find yourself writing 600 lines, you're probably scoping a Phase 4a + 4b — split it.

Handoff

Best for: Scaffolding the project, writing the code, wiring the integrations, getting to a runnable state.

  • Surface: Claude Code CLI in a fresh project directory
  • Skills to lean on: neon-rls-scaffold, supabase-project-setup, google-oauth, vercel-deploy, demo-mode
  • Pattern: Plan Mode for each non-trivial sub-task; subagents for parallel exploration
  • Output: a working app that can be deployed and reviewed
  • Hooks: lint/test gates if the build will be unattended; format-on-write for cleanliness

Limitations: Don't let Cowork act as a paste-relay between you and Claude Code for hours — if the build hits a real decision point, route the decision through Cowork (strategy layer), not through manual re-prompting. The cowork-cc-handoff skill exists to prevent this failure mode.

Execution

Best for: Catching what the build agent missed before the user does.

  • Claude Code: code-reviewer subagent + lint/test hooks (PostToolUse)
  • Cowork: native screen awareness — walk the running app, capture screenshots, narrate observations
  • Both: cross-check the original brief against what was built
  • Output: a list of fixes prioritized by user impact
  • Anti-pattern: trusting the same Claude Code session to review what it just wrote

Limitations: Reviews are bounded by what the agents can see. A subagent reviewing code can't catch a misaligned UX expectation; Cowork walking the running app can't catch an unsafe SQL query. Cover both axes.

Quality gate

Best for: Getting the app in front of users and watching what happens.

  • Claude Code: vercel-deploy skill, supabase-project-setup, env var management
  • Cowork: /schedule for daily error digests, artifacts for live metrics, connectors to your error tracker
  • Output: a deployed app and a recurring routine that surfaces what happens next
  • Pattern: every shipped app earns one Cowork routine — error digest, usage tracker, or feedback summary

Limitations: The first deploy almost never works on the first try. Plan for an env-var loop and a build-log read pass. Don't skip the post-deploy verification — a green deploy doesn't mean the app works.

Operate

The "Cowork-as-paste-relay" anti-pattern

The most common failure mode: Cowork reads Claude Code's output, summarizes to the user, user dictates the next step, Cowork pastes it back to CC. Hours pass; nothing ships. This happens when the Phase-3 prompt was vague — the build agent keeps hitting decisions it can't resolve. The fix is *not* to keep relaying. The fix is to stop, go back to Phase 3, and write a prompt that resolves the decisions up front. A good Phase-3 prompt makes Phase 4 a long autonomous run, not a back-and-forth.