SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsmoai-domain-design-handoff

moai-domain-design-handoff

Design & creation

View repository

Updated 10-16 01:17

About this skill

Design Handoff Domain Specialist

Assembles the 5-file Claude Design handoff package for the brain workflow's Phase 7. The package is designed for paste-and-go use in the external claude.com Design product.

Quick Reference

The handoff package lives at .moai/brain/IDEA-NNN/claude-design-handoff/:

File Purpose Paste target
prompt.md Master prompt — paste directly into claude.com Design Yes (primary)
context.md Extended context for reference during design session Optional supplement
references.md Visual reference URLs and design inspiration sources Referenced in prompt
acceptance.md Design acceptance criteria (WCAG, responsive, brand) Referenced in prompt
checklist.md Pre-paste self-check before using in claude.com Design Human review tool

Key guarantees:

  • [HARD] prompt.md contains NO MoAI-specific tokens (no SPEC-, .moai/, manager-, IDEA-)
  • [HARD] Brand voice integrated when .moai/project/brand/brand-voice.md exists
  • [HARD] Brand-absent fallback: Brand Voice (default — please customize) placeholder section
  • [HARD] Phase 7 exits with AskUserQuestion offering 3 options (a/b/c per the relevant requirement)
  • [HARD] All 5 files produced regardless of brand context availability

Phase 7: Handoff Package Assembly

Input

  • ideation.md (Lean Canvas + Evaluation Report from Phases 4 and 5)
  • proposal.md (product summary and SPEC decomposition from Phase 6)
  • Optional: .moai/project/brand/brand-voice.md (brand context)
  • Optional: .moai/project/brand/visual-identity.md (design tokens, colors)

Step 0: Brand Context Detection

Before writing any file, check brand context:

IF .moai/project/brand/brand-voice.md exists AND is non-empty:
  Load brand voice → use in Brand Voice section of prompt.md
  SET brand_present = true
ELSE:
  Use default brand voice placeholder
  SET brand_present = false
  Note: will include AskUserQuestion offer to run brand interview

Step 1: Assemble prompt.md

prompt.md MUST follow this exact 5-section structure:

  1. Goal — 2-3 sentences describing what needs to be designed, target users, top 3 value propositions from Lean Canvas UVP
  2. References — 3-5 URLs to existing products with style notes, plus key aesthetic direction
  3. Brand Voice — Two branches (brand_present vs brand_absent), see decision below
  4. Acceptance Criteria — Concise non-negotiable requirements list (5-8 items)
  5. Out of Scope — Explicit exclusions (3-5 items)

Section 3 — Brand Voice Decision Tree

  • Branch A (brand_present = true): Extract personality + voice guidelines + color palette + typography from brand-voice.md and visual-identity.md
  • Branch B (brand_present = false): Emit ## 3. Brand Voice (default — please customize) header with explicit placeholder + instructions to either edit or run brand interview

See 5-section prompt template + brand branches detail for verbatim section templates.

Prohibited Content in prompt.md

[HARD] The following MUST NOT appear anywhere in prompt.md:

  • References to SPEC- identifiers (e.g., SPEC-AUTH-001)
  • References to .moai/ paths (e.g., .moai/brain/, .moai/project/)
  • References to agent names (e.g., manager-brain, manager-spec)
  • References to IDEA-NNN identifiers
  • References to MoAI-specific commands (e.g., /moai plan, /moai run)
  • Internal implementation details (file structures, Go code, database schemas)

The prompt must read as if written by a human product designer with no knowledge of MoAI's internal structure.

Steps 2-5: Supporting Files

Step File Purpose
2 references.md Competitor analysis + visual inspiration + UX pattern references (3-5 URLs from research.md Sources). Falls back to instructional note when URLs are scarce.
3 acceptance.md Accessibility (WCAG 2.1 AA), Responsiveness (375/768/1280px), Brand Alignment, Content Completeness, Technical Constraints
4 context.md Extended context — NOT for pasting into Claude Design. Full Lean Canvas summary, SPEC roadmap, research findings, brand context
5 checklist.md Human self-check before pasting prompt.md: content review, MoAI-internal cleanup (auto-verified), scope verification, session readiness

See supporting files templates for verbatim references.md, acceptance.md, context.md, and checklist.md templates.

Phase 7 Exit: AskUserQuestion

After all 5 files are written, the workflow MUST invoke AskUserQuestion (with ToolSearch preload) presenting 3 options:

ToolSearch(query: "select:AskUserQuestion")
AskUserQuestion({
  questions: [{
    question: "핸드오프 패키지가 준비되었습니다. 다음 단계를 선택하세요.",
    header: "Brain Workflow 완료",
    options: [
      {
        label: "/moai project 실행 (권장)",
        description: "IDEA-NNN/proposal.md 기반으로 product.md, structure.md, tech.md 프로젝트 문서 생성. 이후 /moai plan으로 첫 SPEC 작성 가능."
      },
      {
        label: "수동 검토",
        description: "핸드오프 파일을 직접 검토하고 필요한 경우 편집. .moai/brain/IDEA-NNN/ 디렉토리를 확인하세요. 준비가 되면 /moai project --from-brain IDEA-NNN을 실행하세요."
      },
      {
        label: "핸드오프 패키지 재생성",
        description: "prompt.md 또는 다른 파일에 수정이 필요한 경우 어떤 부분을 변경할지 알려주세요. 해당 파일만 재생성합니다."
      }
    ]
  }]
})

For non-Korean conversation_language, translate option labels and descriptions accordingly.

Works Well With

  • moai-domain-ideation: Consumes ideation.md and proposal.md as primary inputs
  • moai-domain-research: Pulls reference URLs from research.md Sources section
  • moai-workflow-design: Downstream consumer of claude-design-handoff/ directory after user completes external Claude Design session (Path A handler)
  • moai-workflow-brain: Orchestrates Phase 7 execution with IDEA-NNN directory management

Common Rationalizations

Rationalization Reality
"Including SPEC-AUTH-001 in prompt.md helps the designer understand scope" prompt.md is for claude.com Design, not MoAI. SPEC IDs are internal. Use the Out of Scope section to describe scope boundaries in plain English.
"I should skip checklist.md — it's obvious" Checklist.md prevents the most common error: pasting a prompt with placeholder Brand Voice. It takes 30 seconds to complete and saves a bad design session.
"references.md is optional if research had no URLs" references.md is always produced. When URLs are scarce, include a note asking the user to add their own. An empty references file is worse than one with instructions.
"If brand is absent, skip the Brand Voice section" Brand Voice section is always present. Brand-absent path produces an explicit placeholder with instructions — clearer than a missing section.

Verification

  • All 5 files produced: prompt.md, context.md, references.md, acceptance.md, checklist.md
  • prompt.md has exactly 5 sections (Goal, References, Brand Voice, Acceptance, Out of Scope)
  • prompt.md contains no SPEC- identifiers
  • prompt.md contains no .moai/ path references
  • prompt.md contains no manager- or /moai references
  • Brand-absent path includes "Brand Voice (default — please customize)" header in prompt.md
  • context.md includes note that it is NOT for pasting into Claude Design
  • Phase 7 exit AskUserQuestion called with exactly 3 options