od-contribute

od-contribute — OpenDesign の初回コントリビューションフロー

nexu-io/open-design 専用です。イシューではなく、コントリビューションの種類ごとに分岐します。開発ループを、種類ごとに特化したノーコードのバリデーターに置き換えます。コーディング経験がまったくないプロダクトユーザーでも、実際の PR を作成できるように設計されています。

言語

ユーザー向けのすべてのメッセージ（AskUserQuestion のラベルや説明、ステータス更新、エラーの説明）で、ユーザーの言語に合わせてください。最初のメッセージから言語を判定し、判断できない場合は英語を使用してください。

生成される成果物（PR タイトル、コミットメッセージ、PR／イシュー本文ファイル、ブランチ名）は、ユーザーのチャット言語にかかわらず、必ず英語にしてください。 GitHub の慣例、メンテナーによるレビュー、検索では、すべて英語が前提となっています。templates/ 配下のテンプレートはすでに英語なので、レンダリング時も英語のままにしてください。

スクリプトは scripts/ 配下にあります。任意のスクリプトから共通ヘルパーを読み込んでください。

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

以下でいう SKILL_DIR は、この SKILL.md を含むディレクトリです。

---

ステップ 1 — 前提条件の確認（必ず最初に実行）

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

• 終了コード 0：標準出力から GH_USER=<login> を取得します。デフォルトの TARGET_FORK="${GH_USER}/open-design" を設定します。
• 終了コード 2：表示されたインストール／認証に関するヒントをそのまま提示し、停止します。トークンによる回避策は試さないでください。

gh repo view "$TARGET_FORK" が失敗した場合は、gh repo fork nexu-io/open-design --clone=false で今すぐフォークするかどうかを、ユーザーに（AskUserQuestion を 1 回使って）尋ねてください。デフォルトは「はい」です。

ステップ 2 — コントリビューションの種類を選択

AskUserQuestion を 1 回使用します（ヘッダー：「Contribution」、multiSelect: false）。選択肢は 4 つです。選択肢のラベルと説明はユーザーのチャット言語に翻訳してください。ブランチの振り分けは変更しません。

1. 🎨 OD で作ったものを公開する — コントリビュートしたい Skill、Design System、HyperFrame、またはテンプレート → ブランチ 3a
2. 🌍 OD のドキュメントを翻訳する — README／QUICKSTART／CONTRIBUTING を新しい言語に翻訳する → ブランチ 3b
3. 📝 ドキュメントを修正する／ブログを書く／誤字を直す — 誤字の修正、リンク切れの修正、ユースケースの紹介記事 → ブランチ 3c
4. 🐛 バグを報告する — 問題が発生したので、質の高いイシューにまとめる作業に協力する → ブランチ 3d（イシューの手順。PR は作成しません）

以下の各ブランチはそれぞれ単独で完結します。ステップ 7〜8（プレビュー＋プッシュ）は、ブランチ 3a／3b／3c で共通です。ブランチ 3d では、これらをすべてスキップします。

---

ステップ 3a — OD プロダクトの投稿（Skill／Design System）

3a.1 ユーザーに尋ねます：「公開したい成果物のローカルパスを教えてください。」（自由入力 1 件。ユーザーのチャット言語に翻訳します。）よくある指定は、フォルダパス（Skill）または単一の DESIGN.md ファイル（Design System）です。

3a.2 種類を判定します。

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

判定できない場合は、ユーザーに確認を求めてください。

3a.3 セットアップを実行します。

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

<slug> には、Skill の name フロントマターの値、またはブランド名を od::slugify したものを指定します。標準出力から WORKDIR を取得してください。

3a.4 成果物をワークスペース内の適切な保存先ディレクトリにコピーします。

• Skill → $WORKDIR/skills/<slug>/
• Design System → $WORKDIR/design-systems/<brand-slug>/DESIGN.md（同じフォルダ内にある関連アセットもコピーします）

3a.5 検証します。

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"

検証に失敗した場合は、FAIL の行をそのまま提示し、ユーザーに修正を依頼してから再試行します。検証に失敗した成果物は絶対にプッシュしないでください。

3a.6 AskUserQuestion を使って、短い質問を 3 つ尋ねます（ラベルはユーザーのチャット言語に翻訳します）。

• 「PR でクレジットするお名前を教えてください。」— 自由入力
• 「この Skill／Design System の魅力を一言で教えてください。」— 自由入力
• 「スクリーンショットのパスを教えてください（任意）。」— 自由入力

3a.7 templates/PR-BODY-skill.md（または PR-BODY-design-system.md）に以下を差し込んでレンダリングします。

• {{SKILL_NAME}}、{{SKILL_SLUG}}（または {{BRAND_NAME}}、{{BRAND_SLUG}}）
• {{PITCH}}（一言の紹介文）
• {{MOTIVATION}}（自由入力。エージェントは Skill の本文をもとに下書きを提案できますが、ユーザーの確認が必要です）
• {{TRY_PROMPT}}（試してみることを推奨するプロンプト。エージェントがデフォルト案を提案し、ユーザーが確認します）
• {{SCREENSHOT_BLOCK}}（スクリーンショットのパスが指定されていれば Markdown の画像ブロック、指定されていなければ空欄）
• $OD_DISCORD_INVITE の値を使った {{DISCORD_INVITE}}

$WORKDIR/.od-contrib/PR-BODY.md に書き込みます。

→ ステップ 7 に進みます。

---

Step 3b — i18n 翻訳

3b.1 ワークスペースをセットアップします（slug = 分かっている場合は translate-<doc>-<lang>、不明な場合は translate）：

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

3b.2 不足箇所を検出します：

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

各行は JSON です。次の順に優先順位を付けます：

• まず status: "missing"（言語が欠けている場合は、最も大きな効果が見込めます）
• 次に status: "stale" を english_commits_since_translation の降順で並べます
• README ファミリー、QUICKSTART、CONTRIBUTING の順にします

3b.3 不足箇所の上位 3～4 件を選び、AskUserQuestion で提示します（ヘッダー：「翻訳対象」）。各選択肢のラベルは次のようにします：README → 한국어 (Korean) / QUICKSTART (zh-CN) refresh — 12 commits behind。ヘッダーのテキストはユーザーのチャット言語に翻訳しますが、選択肢のラベルは内容が分かるようにし（言語名はそれぞれの言語の文字表記にします）。

3b.4 ユーザーが選択したら、ブランチ名を具体的なものに変更します：

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

（または、ユーザーが事前に確認済みの場合は、手順 3b.1 で slug を設定します。）

3b.5 翻訳します。英語のソースを読みます。構造を維持して翻訳します：

• コードブロック：翻訳しません
• ブランド名／製品名：翻訳しません
• インラインコード内のファイル名：翻訳しません
• 画像／リンクのターゲット：変更しません。リンク先ドキュメントのローカライズ版が存在する場合は、リンク先をローカライズされたファイルに差し替えます
• 見出し：翻訳し、見出しレベルは同じに保ちます
• 表：セル内のテキストのみ翻訳し、配置／パイプはそのままにします

結果を $WORKDIR/<TRANSLATED_PATH>（例：QUICKSTART.es.md）に書き込みます。目視確認のため、英語のソースとの差分を unified diff 形式でユーザーに表示します（行数の差が ±15% 以内であれば、適切な目安です）。

3b.6 翻訳ファイルを英語のソースと照合して検証します。--reference フラグを指定すると、ソースですでに壊れていた相対参照を検証時に無視できます。OD のドキュメントでは、ウェブサイトのルートスラッグ（例：skills/blog-post/）など、ディスク上にファイルがない参照が頻繁に使われています。構造を維持した翻訳が、既存の無効な参照のために失敗しないようにします。

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

失敗した場合は、出力をそのまま提示し、修正して再試行します。

3b.7 templates/PR-BODY-i18n.md を {{DOC_NAME}}、{{LANG_DISPLAY_NAME}}、{{LANG_CODE}}、{{TRANSLATED_PATH}}、{{ENGLISH_PATH}}、{{STATUS}}、{{TRANSLATION_NOTES}}（エージェントが記述する 1 段落。扱いが難しかった点、翻訳せずに残した用語など）、{{DISCORD_INVITE}} でレンダリングします。

→ Step 7。

---

Step 3c — ドキュメント／ブログ／誤字

3c.1 ワークスペースをセットアップします（slug は docs）：

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

3c.2 ユーザーに質問します（AskUserQuestion を 1 回）：

1. 小さな修正を自動検出する（discover-doc-gaps を実行し、項目を選択する）
2. 修正したい箇所が決まっている（自由記述）
3. ブログ／事例紹介を書きたい（自由記述 — ユースケースは何ですか？）

3c.3（自動検出の分岐） 次を実行します：

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

kind（typo / deadlink / todo）ごとに分類します。候補を最大 6 件まで AskUserQuestion でユーザーに提示します。選択された項目をコードで修正します（typo：単語を置き換える、deadlink：新しい URL をユーザーに尋ねる、todo：正式なタスクなので、不足している文章を書くようユーザーに依頼する）。

3c.4（具体的な修正の分岐） ファイルを読み、ユーザーが説明した変更を適用します。差分を示して確認します。

3c.5（ブログの分岐） まず、OD にブログディレクトリがあるか確認します：

ls "$WORKDIR/docs" 2>/dev/null

docs/blog/ などが存在する場合は、新しい投稿をそこに配置します。存在しない場合は、ユーザーに配置場所を尋ねます。デフォルトは docs/<slug>.md です。アウトラインを作成し、ユーザー固有の情報（ユースケース、スクリーンショット、使用したプロンプト、レンダリング結果）をユーザーが記入した後、エージェントが最終的な Markdown にまとめます。

3c.6 変更または追加したすべてのファイルを検証します。リポジトリにすでに存在するファイル（誤字修正、無効なリンクの修正、ドキュメントの編集）については、HEAD のバージョンを指す --reference を渡し、ユーザーが新たに導入した相対参照のみを対象に失敗させます。既存のルートスラッグは対象外です。

# For modifications to existing files:
git -C "$WORKDIR" show "HEAD:<path>" > "/tmp/od-contrib-orig-<basename>" 2>/dev/null
bash "$SKILL_DIR/scripts/validate-markdown.sh" \
  "$WORKDIR/<changed-path>" \
  --reference "/tmp/od-contrib-orig-<basename>"

# For brand-new files (e.g. a blog post the user is creating from scratch),
# omit --reference. The validator will skip the relative-ref check entirely
# (since it can't tell route slugs from real paths in isolation).

3c.7 templates/PR-BODY-docs.md を {{ONE_LINE_SUMMARY}}、{{DETAILS}}、{{FILES_LIST}}、{{DISCORD_INVITE}} でレンダリングします。

→ Step 7。

---

ステップ 3d — バグ報告（イシューパス、PR なし）

3d.1 実行時に OD の実際のスキーマを読み込み、一致させます。

gh api "repos/${TARGET_REPO}/contents/.github/ISSUE_TEMPLATE/bug-report.yml" --jq .content | base64 -d > /tmp/od-bug-report.yml

スキーマがテンプレート（templates/ISSUE-BODY-bug.md）から変わっている場合は、それに合わせて本文を再生成します。

3d.2 重要なフィールドごとに 1 つの構造化された質問を提示し、AskUserQuestion を使ってユーザーに尋ねます。YAML のフィールド名ではなく、平易な言葉を使います。

バグ報告のフィールド	ユーザーへの質問
description	「何が起きましたか？ 1 文で構いません。」
steps	「どのように再現できますか？ 手順を追って説明してください。」
expected	「何が起きることを期待していましたか？」
version	「実行している OD のバージョンは何ですか？（About メニュー、または od --version）」
platform	ドロップダウン：macOS（Apple Silicon）／macOS（Intel）／Windows／Linux／その他
logs	「貼り付けられるエラーログはありますか？ なければスキップしてください。」
screenshots	「スクリーンショットのパスを教えてください。なければスキップしてください。」

実行時に、上記のすべての質問をユーザーのチャット言語に翻訳します。

3d.3 取得できる情報は自動収集します（これらはユーザーに尋ねる必要はありません）。

• uname から OS ファミリーを取得
• 該当する場合は node -v から Node のバージョンを取得

3d.4 重複を確認します。説明から 3～5 個のキーワードを抽出し、次を実行します。

gh search issues "<keywords>" --repo "$TARGET_REPO" --state open --limit 5 --json number,title,url

一致するものがあれば、ユーザーの言語に翻訳したうえで AskUserQuestion を使って提示します。「関連がありそうな既存のイシューが見つかりました。どれにしますか？（a）既存のイシューにコメントする、（b）新しいイシューを作成する、（c）キャンセルする」

3d.5 新しいイシューを作成する場合は、templates/ISSUE-BODY-bug.md をレンダリングして送信します。

bash "$SKILL_DIR/scripts/create-issue.sh" \
  --title "$TITLE" \
  --body-file "$WORKDIR_OR_TMP/.od-contrib/ISSUE-BODY.md" \
  --dedupe-keywords "<keywords>"

3d.6 イシューの URL を単独の行に出力します。このブランチからブランチをプッシュしたり、PR を作成したりしないでください。

---

ステップ 7 — プレビューと確認（PR ブランチのみ共通）

ユーザーに分かりやすい概要を表示します。

About to commit:
  Branch:  od-contrib/<type>/<slug>-<date>
  Files:
    + skills/foo/SKILL.md            (1.2 KB)
    + skills/foo/preview.png         (54 KB)
  Push to:  <fork or upstream>
  Open PR:  nexu-io/open-design:main ← <fork>:<branch>

続いて git -C "$WORKDIR" diff --stat と、レンダリングされた PR 本文の先頭 40 行（head -40）を表示し、見た目を確認します。

AskUserQuestion による確認が必須です（ユーザーの言語に翻訳してください）。質問は 「この PR をプッシュしますか？」 とし、次の 3 つの選択肢を提示します。

• 公開する — ステップ 8 に進む
• 修正する — 該当するステップ 3 のサブステップに戻る
• キャンセル — ワークスペースをディスク上に残し、後で戻れるようにパスをユーザーに伝えて終了する

「公開する」と明示的に確認されない限り、決してプッシュしないでください。

ステップ 8 — プッシュして PR を作成

bash "$SKILL_DIR/scripts/create-pr.sh" \
  --workdir "$WORKDIR" \
  --type "<skill|design-system|i18n|docs>" \
  --title "<PR title from references/newcomer-tone.md>" \
  --body-file "$WORKDIR/.od-contrib/PR-BODY.md"

PR の URL を単独の行に出力します。完了です。

---

安全対策（必須）

• main／master／develop には決してプッシュしないでください。プッシュスクリプトが拒否します。
• --force でプッシュしないでください。絶対に使用しないでください。
• ワークスペース内のすべての作業は $OD_WORK_ROOT（デフォルトは $HOME/od-contrib-work）配下で行います。od::assert_in_workroot がこれを強制します。
• バグ報告のパスでは、gh issue create の前に必ず重複検索を実行します。
• ユーザーのメモリーを尊重し、コントリビューターを検索する際は GitHub ユーザー xxiaoxiong を除外します（[[feedback_no_outreach_xxiaoxiong]]）。

このスキルを使用しない場合

• ユーザーがデーモン／Web のバグ修正、またはコード変更を伴う機能追加を希望している場合 → 代わりに auto-github-contributor を使用します（TDD ループがあります）。コンテンツのパスでは不要なため、このスキルでは lint／typecheck／テストを実行しません。
• ユーザーが Skill／Design System を一から生成したい場合 → それは OpenDesign 自体の役割です。まず OD を実行して成果物を取得し、その後ここに戻って公開します。