Od Contribute

od-contribute — first-contribution flow for OpenDesign

Locked to nexu-io/open-design. Branches by contribution type, not by issue. Replaces the dev-loop with type-specific no-code validators. Designed so a product user with zero coding background can ship a real PR.

Language

Mirror the user's language in every user-facing message — AskUserQuestion labels and descriptions, status updates, error explanations. Detect from their first message; when uncertain, default to English.

Generated artifacts (PR titles, commit messages, PR/issue body files, branch names) MUST be English regardless of the user's chat language. GitHub conventions, maintainer review, and search all assume English. The templates under templates/ are already English — keep them that way when rendering.

Scripts live under scripts/. Source the shared helpers from any script:

source "$(dirname "$0")/config.sh"

SKILL_DIR below = the directory that contains this SKILL.md.

Step 1 — Prereq check (always first)

bash "$SKILL_DIR/scripts/check-prereqs.sh"

• Exit 0: capture GH_USER=<login> from stdout. Default TARGET_FORK="${GH_USER}/open-design".
• Exit 2: surface the printed install / auth hint verbatim and stop. Do not attempt token workarounds.

If gh repo view "$TARGET_FORK" fails, ask the user (one AskUserQuestion) whether to fork now via gh repo fork nexu-io/open-design --clone=false. Default to yes.

Step 2 — Pick contribution type

Single AskUserQuestion (header: "Contribution", multiSelect: false), four options. Translate option labels/descriptions into the user's chat language; the branch routing is unchanged.

1. 🎨 Ship something I made with OD — _a Skill, Design System, HyperFrame, or template I want to contribute upstream_ → branch 3a
2. 🌍 Translate OD docs — _README / QUICKSTART / CONTRIBUTING into a new language_ → branch 3b
3. 📝 Fix docs / write a blog / fix a typo — _typo fix, dead link, use-case writeup_ → branch 3c
4. 🐛 Report a bug — _something broke; I'll help turn it into a high-quality issue_ → branch 3d (issue path, no PR)

Each branch below is self-contained. Steps 7–8 (preview + push) are shared across branches 3a/3b/3c. Branch 3d skips them entirely.

Step 3a — OD product submission (Skill / Design System)

3a.1 Ask user: "What's the local path to the artifact you want to ship?" (single free-text, translated into the user's chat language). Common: a folder path (Skill) or a single DESIGN.md file (Design System).

3a.2 Sniff type:

# Skill: folder containing SKILL.md with frontmatter.
# Design System: file matching DESIGN.md anatomy.

If ambiguous, ask the user to confirm.

3a.3 Run setup:

bash "$SKILL_DIR/scripts/setup-workspace.sh" skill <slug>
# or
bash "$SKILL_DIR/scripts/setup-workspace.sh" design-system <slug>

<slug> is od::slugify of the Skill name frontmatter field or of the brand name. Capture WORKDIR from stdout.

3a.4 Copy artifact into workspace at the right target dir:

• Skill → $WORKDIR/skills/<slug>/
• Design System → $WORKDIR/design-systems/<brand-slug>/DESIGN.md (+ any sibling assets in the same folder)

3a.5 Validate:

bash "$SKILL_DIR/scripts/validate-skill-submission.sh" "$WORKDIR/skills/<slug>"
# or, with 1-2 reference DESIGN.md files passed in:
bash "$SKILL_DIR/scripts/validate-design-system.sh" \
  "$WORKDIR/design-systems/<slug>/DESIGN.md" \
  --reference "$WORKDIR/design-systems/airbnb/DESIGN.md" \
  --reference "$WORKDIR/design-systems/apple/DESIGN.md"

If validation fails, surface the FAIL lines verbatim, ask the user to fix, retry. Never push a failing artifact.

3a.6 Ask 3 short questions via AskUserQuestion (translate the labels into the user's chat language):

• "What name should we credit you under in the PR?" — free-text
• "One-line pitch for this Skill / Design System?" — free-text
• "Path to a screenshot (optional)?" — free-text

3a.7 Render templates/PR-BODY-skill.md (or PR-BODY-design-system.md) with substitutions:

• {{SKILL_NAME}}, {{SKILL_SLUG}} (or {{BRAND_NAME}}, {{BRAND_SLUG}})
• {{PITCH}} (the one-line)
• {{MOTIVATION}} (free-text — agent can offer to draft this from the skill body, but user confirms)
• {{TRY_PROMPT}} (a prompt they recommend trying — agent suggests a default, user confirms)
• {{SCREENSHOT_BLOCK}} (Markdown image block if a screenshot path was given, else empty)
• {{DISCORD_INVITE}} from $OD_DISCORD_INVITE

Write to $WORKDIR/.od-contrib/PR-BODY.md.

→ Jump to Step 7.

Step 3b — i18n translation

3b.1 Setup workspace (slug = translate-<doc>-<lang> if known, else translate):

bash "$SKILL_DIR/scripts/setup-workspace.sh" i18n translate
# capture WORKDIR

3b.2 Discover gaps:

bash "$SKILL_DIR/scripts/discover-i18n-gaps.sh" "$WORKDIR" > /tmp/od-i18n-gaps.json

Each line is JSON. Rank by:

• status: "missing" first (missing language is highest leverage)
• then status: "stale" ordered by english_commits_since_translation desc
• README family before QUICKSTART before CONTRIBUTING

3b.3 Take the top 3–4 gaps and present via AskUserQuestion (header: "Translation target"). Each option label like: README → 한국어 (Korean) / QUICKSTART (zh-CN) refresh — 12 commits behind. Translate the header text into the user's chat language but keep the option labels descriptive (the language names belong in their native script).

3b.4 Once user picks, rename branch to be specific:

git -C "$WORKDIR" branch -m "od-contrib/i18n/<doc>-<lang>-<date>"

(or pre-set the slug in step 3b.1 if the user confirmed earlier.)

3b.5 Translate. Read the English source. Translate structure-preserving:

• Code blocks: leave untranslated
• Brand / product names: leave untranslated
• Filenames in inline code: leave untranslated
• Image / link targets: leave untranslated; if a localized version of a linked doc exists, swap the link to the localized file
• Headings: translate, keep the heading depth identical
• Tables: translate cell text only, keep alignment / pipes

Write the result to $WORKDIR/<TRANSLATED_PATH> (e.g. QUICKSTART.es.md). Show user a unified diff vs. the English source for visual sanity-check (line-count delta within ±15% is a healthy signal).

3b.6 Validate the translated file against the English source. The --reference flag tells the validator to ignore relative refs that were already broken in the source — OD docs frequently link to website route slugs (e.g. skills/blog-post/) that aren't files on disk; we don't want a structure-preserving translation to fail because of pre-existing dead refs.

bash "$SKILL_DIR/scripts/validate-markdown.sh" \
  "$WORKDIR/<TRANSLATED_PATH>" \
  --reference "$WORKDIR/<ENGLISH_PATH>"

If FAIL → surface verbatim, fix, retry.

3b.7 Render templates/PR-BODY-i18n.md with {{DOC_NAME}}, {{LANG_DISPLAY_NAME}}, {{LANG_CODE}}, {{TRANSLATED_PATH}}, {{ENGLISH_PATH}}, {{STATUS}}, {{TRANSLATION_NOTES}} (one paragraph from the agent: anything tricky, untranslated terms it kept, etc.), {{DISCORD_INVITE}}.

→ Step 7.

Step 3c — Docs / blog / typo

3c.1 Setup workspace (slug docs):

bash "$SKILL_DIR/scripts/setup-workspace.sh" docs <slug>

3c.2 Ask user (one AskUserQuestion):

1. Auto-discover small fixes (run discover-doc-gaps, pick something)
2. I have a specific fix in mind (free-text)
3. I want to write a blog / case study (free-text — what's the use case?)

3c.3 (Auto-discover branch) Run:

bash "$SKILL_DIR/scripts/discover-doc-gaps.sh" "$WORKDIR" > /tmp/od-doc-gaps.json