oss-ready

OSS Ready

標準的なコミュニティ向けファイルと GitHub テンプレートを追加して、プロジェクトをプロフェッショナルなオープンソースリポジトリに変えます。

全体を通して、次の2つの用語を使用します。

• 追加編集：既存のファイルには、不足しているセクションまたは行だけを追加します。ユーザーのコンテンツを置き換えたり、言い換えたり、翻訳したり、削除したりしてはいけません。
• プレースホルダー：作成したファイル内、または既存のファイルに実行時に追加した行内にある PH='\[(YEAR|COPYRIGHT HOLDER|INSERT [A-Z ]+)\]|TODO|TBD|FIXME' の一致箇所です。

編集前のリポジトリ同期（必須）

前提条件：名前付きブランチと origin リモートが設定された git リポジトリであること。Step 0 の前に、references/repo-sync.md のブロックを1回実行してください。最初の失敗時点で停止します。

1. git rev-parse --git-dir が失敗した場合（git リポジトリではない場合）、停止します。
2. git symbolic-ref --quiet --short HEAD が失敗した場合（detached HEAD の場合）、stash または同期を行う前に停止します。
3. git remote get-url origin が失敗した場合、停止してユーザーに確認します。
4. git status --porcelain が1行でも出力した場合、git stash push -u で stash します。
5. git fetch origin && git pull --rebase origin "$branch" を実行します。
6. git stash pop --index で stash を復元します。

ゼロ以外の終了コードが返された場合は、BLOCKED と、ブロックが出力した復旧コマンドを含む最終レポートを表示します。変更を破棄してはいけません。失敗の原因が origin の欠落のみで、ユーザーが続行を承認した場合は、Step 0 に進み、Uncertainty: の下に Repo Sync skipped (no origin) を記載します。

ワークフロー

Step 0 の前に、references/edge-cases.md を確認してください。リポジトリに該当するケースがある場合は、まずそこに記載されたとおりに対応します。

Step 0：フィーチャーブランチの作成

1. 現在のブランチを確認します：git branch --show-current。
2. デフォルトブランチを確認します：origin/ の接頭辞を付けずに git symbolic-ref --short refs/remotes/origin/HEAD を実行します。失敗した場合は main を使用します。ただし、master のみが存在する場合は master を使用します。
3. 現在のブランチがデフォルトブランチではなく、名前に oss が含まれている場合は、そのブランチを維持して Step 1 に進みます。
4. git branch -a --format='%(refname:short)' の出力で feature/ ブランチの数が feat/ ブランチの数を上回る場合は、接頭辞に feature/ を選びます。それ以外の場合は feat/ を選びます。
5. <prefix>oss-ready が存在する場合は、再利用するか別の名前を指定するか、ユーザーに確認します。既存のブランチをリセットしてはいけません。
6. git switch -c <prefix>oss-ready を実行します。再利用する場合は git switch <name> を実行します。失敗した場合は BLOCKED で停止します。

Step 1：プロジェクトの分析

references/file-specs.md の Analysis values に従い、技術スタック、目的、既存ファイル、ライセンス、リポジトリ URL、README の言語、公開範囲、入力値を記録します。セキュリティ連絡先と行動規範の連絡先を1つの質問で確認します。技術スタックを特定できない場合は、どの技術スタックを想定するかユーザーに確認します。

Step 2：コアファイルの作成／更新

Step 1 の値を使って README.md と CONTRIBUTING.md を作成します。LICENSE が存在しない場合、またはユーザーが別のライセンスを指定していない場合は、assets/LICENSE-MIT をコピーします。Contributor Covenant 2.0 の CODE_OF_CONDUCT.md と SECURITY.md を assets/ からコピーします。各プレースホルダーを Step 1 の値に置き換えます。セクション一覧とファイルごとのルールについては、references/file-specs.md を参照してください。

使用例はすべて、リポジトリ内のコード、スクリプト、または --help の出力から取得します。コマンドや連絡先を決して作り出してはいけません。コードに根拠がないセクションは省略し、Manual review の下に記載します。

Step 3：GitHub テンプレートの作成

assets/.github/ から、存在しないファイルをそれぞれコピーします：ISSUE_TEMPLATE/bug_report.md、ISSUE_TEMPLATE/feature_request.md、PULL_REQUEST_TEMPLATE.md。.github/ 内の既存ファイルとワークフローはすべて変更せず、そのまま維持します。

Step 4：ドキュメント構造の作成

存在しないファイルをそれぞれ作成します。省略ルールと内容については、references/file-specs.md の docs/ を参照してください。

docs/
├── ARCHITECTURE.md    # System design, components
├── DEVELOPMENT.md     # Dev setup, debugging
├── DEPLOYMENT.md      # Production deployment
└── CHANGELOG.md       # Version history (skip when a root CHANGELOG.md exists)

Step 5：プロジェクトメタデータの更新

ルートマニフェストに license、description、repository のうち不足しているフィールドをそれぞれ追加します。値が設定済みのフィールドは上書きしてはいけません。編集後にファイルを解析します。技術スタックごとのフィールドと解析コマンドについては、references/file-specs.md の Project metadata を参照してください。

Step 6: .gitignore を確認する

references/file-specs.md の .gitignore に記載されているスタック用のパターンのうち、不足しているものをそれぞれ追記します。grep -qxF '<pattern>' .gitignore で各パターンを確認します。行は削除しないでください。

Step 7: 検証して報告する

1. すべての受け入れ基準を確認します。それぞれについて、理由とともに pass、fail、not applicable のいずれかを記録します。
2. 上記の Placeholder で定義されているとおりに PH を設定します。作成した各ファイルに対して、プレースホルダーの grep を実行します：grep -nE "$PH" <file>。
3. 更新した各ファイルに追加した行に対して実行します：git diff -U0 -- <file> | grep -E '^\+' | grep -E "$PH"。
4. git status --porcelain を実行します。 D または D で始まる行がないことを確認します。
5. 最終レポートを出力します。

コミットやプッシュはしないでください。ユーザーがブランチを確認してコミットします。

ステップ完了レポート

ステップ 1～7 の各ステップの後に、次の形式でレポートを出力します（例：references/final-report.md）。

◆ [Step Name] ([step N of 7] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          × fail — [reason]
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

各チェックには、そのステップで検証する内容に基づいた名前を付けます。ステップ 0 ではレポートを出力しません。ステップ 0 または 1 が失敗した場合は、BLOCKED を出力して停止します。ステップ 2～6 のいずれかで FAIL または PARTIAL が報告された場合も処理を続けますが、実行結果は PARTIAL となります。ステップ 7 は、ステップ 2 が開始された場合に実行します。

最終レポート

最後のステップレポートの後、チャットに最終レポートを 1 件出力します。依頼がない限り、ファイルには書き込みません。次の 4 部構成とし、順番を守ってください。

1. Result: ステータス語、リポジトリとブランチ、PARTIAL または BLOCKED となった理由。
2. Evidence: 作成・更新したファイルと、実行した各ステップ 7 のチェック結果。
3. Uncertainty: 残っているプレースホルダー、未実行のチェックとその理由、未テストの動作。
4. Decision: 必要な承認、または No approval needed. に続けて、ユーザーが行う必要のある残りの作業。

最初に一致したステータス規則を適用してください。

1. BLOCKED：ステップ 7 より前に実行が停止し、対象リポジトリ内のファイルが一切作成・変更されていない。
2. PARTIAL：該当するチェックに失敗または未実行のものがある、プレースホルダーが残っている、ステップで FAIL または PARTIAL が報告された、あるいはステップ 7 の完了前に実行が停止した。
3. COMPLETE：該当するすべてのチェックに合格し、プレースホルダーの grep で一致がなく、ステップ 1～7 のすべてで PASS が報告された。

not applicable は、references/final-report.md に記載された理由と、結果表、例、読者向けチェックがある場合に限り使用できます。それ以外のチェックの省略は、未実行として扱います。

受け入れ基準

ステップ 7 では、各チェックに test -f、grep、git、または目視確認を使用します。

• LICENSE が存在する。新規作成した MIT ライセンスファイルは grep -c "MIT License" LICENSE（または指定されたライセンスのタイトル）に合格する。既存ファイルは変更されていない：git diff --quiet -- LICENSE。
• README.md が 40 行以上で、Installation、Usage、License の各セクションがある。英語の場合、grep -ciE "^#+ .*(install|usage|license)" README.md の結果が 3 以上であること。別の言語の場合は、見出しを目視で確認する。
• CONTRIBUTING.md が課題トラッカーとブランチ作成／PR のワークフローに言及している：grep -iE "issue|pull request|branch" CONTRIBUTING.md。
• CODE_OF_CONDUCT.md が Contributor Covenant に言及している：grep -i "contributor covenant" CODE_OF_CONDUCT.md。
• SECURITY.md に脆弱性報告用の連絡先が記載されている：grep -E "@|https?://" SECURITY.md。
• .github/ISSUE_TEMPLATE/bug_report.md と feature_request.md が存在し、YAML フロントマター（name:、about:）を含んでいる。
• .github/PULL_REQUEST_TEMPLATE.md にチェックリスト（- [ ]）が含まれている。
• 実行中に作成した docs/ 内の各ファイルが # 見出しで始まっている：head -1 <file>。
• .gitignore にスタック用のステップ 6 の各パターンが含まれている。
• マニフェスト（package.json、pyproject.toml、Cargo.toml）に license、description、repository が宣言されており、引き続き解析可能である。
• プレースホルダーの grep で一致が見つからない。
• 以前にコミットされたファイルが削除されていない（ステップ 7 の項目 4）。
• 最終レポートが Result: とステータス語で始まり、残りの 3 部を含み、references/final-report.md の読者向けチェックに合格している。

期待される出力

README.md が一部作成されている TypeScript CLI で一連の作業を完了した場合、最後は次のようになります。

Result: COMPLETE — acme/tsgrep on feat/oss-ready
Evidence:
  Created: LICENSE (MIT, 2026 Jane Doe), CONTRIBUTING.md,
           CODE_OF_CONDUCT.md ([email protected]), SECURITY.md ([email protected]),
           .github/ISSUE_TEMPLATE/bug_report.md, feature_request.md,
           .github/PULL_REQUEST_TEMPLATE.md, docs/ (4 files)
  Updated: README.md (+ Quick Start, Usage, License badge),
           package.json (+ license, repository), .gitignore (+ dist/, .env)
  Acceptance criteria: 13/13 pass. Placeholder grep: no matches. No deleted files.
Uncertainty: README commands copied from package.json scripts, not executed.
Decision: No approval needed.
  Remaining action: confirm both contact addresses are monitored.
  Remaining action: review and commit feat/oss-ready.

出力する前に、記載された各ファイルの存在を確認してください（test -f）。

エッジケース

検出方法とステータスへの影響を含む完全な一覧は、references/edge-cases.md を参照してください。要点は次のとおりです。

• 既存の MIT 以外の LICENSE、.github/ 内のファイル、または CODE_OF_CONDUCT.md や SECURITY.md 内のユーザーコンテンツは上書きしないでください。
• リポジトリがプライベートまたは内部向けの場合、origin がない場合、またはスタックを検出できない場合は、先に確認してください。
• ユーザーがサブパッケージを指定しない限り、モノレポではルートのマニフェストのみを更新してください。
• HEAD が切り離されている場合、Git リポジトリの外にいる場合、または stash、同期、復元に失敗した場合は、停止してください。変更を破棄してはいけません。
• README の言語とルートの CHANGELOG.md を維持してください。

アセットと参考資料

• assets/：LICENSE-MIT、CODE_OF_CONDUCT.md（Contributor Covenant 2.0）、SECURITY.md、および .github/ の issue と PR のテンプレート
• references/repo-sync.md：Repo Sync ブロック
• references/file-specs.md：分析値、ファイルごとの内容、入力値、メタデータ、.gitignore
• references/final-report.md：ステータスのルール、結果の表、例、読者による確認事項
• references/edge-cases.md：各エッジケースの検出、対応、ステータス