incu-way-init

リポジトリ初期化プロセス

リポジトリを incu-way にオンボーディングするための、ゲート駆動型ワークフローです。他のスキルが前提とする基盤を整えます。内容には、記入済みの CLAUDE.md、PRD.md、docs/ ツリー、develop／main のブランチモデル、.ways/ ディレクトリが含まれます。既存のアプリケーション（ブラウンフィールド。一般的なケース）の場合は、アーキテクチャと機能に関するドキュメントの作成も進め、人間と incu-way のフローがリポジトリの内容を実際に理解できるようにします。

これはブートストラップフローであり、作業項目フローではありません。.ways/state.json は作成しません（このモデルは feature／bug／security の作業向けです。ways/v1alpha1 の状態コントラクトを参照してください。これは常時有効な state-contract ルールとして提供されています）。その代わり、このスキルは .ways/ ディレクトリを作成します。作業項目フローでは、後からこのディレクトリにデータを追加します。

---

リポジトリの適格性チェック（ほかの作業に先立って実施）

Phase 0 の前に、現在のリポジトリが ~/.ways/config.yaml の blacklist に含まれているか確認してください（形式は incu-base の global-config ルールに準拠し、常時インストールされています）。一致する場合、このリポジトリは incu-way のブラックリストに登録されていることをユーザーに伝え、今回に限り例外として続行するか、停止するかを尋ねてください。回答があるまで、どの Phase も実行しないでください。ファイルが存在しない場合、または一致しない場合は、通常どおり続行します。

---

Phase 0 — 状況把握とモードの判定

目標： リポジトリがグリーンフィールドかブラウンフィールドか、また incu-way がすでに（一部でも）セットアップされているかを判断します。まだ何も書き込まないでください。

判定チェックリスト

リポジトリのルートを読み取り専用で調査します。

git -C . rev-parse --is-inside-work-tree 2>/dev/null   # is this a git repo at all?
git log --oneline -1 2>/dev/null                        # any commits yet?
git branch -a                                           # does develop/main exist?
ls -A                                                    # what is at the root?

次に、以下の情報を確認します。

1. アプリケーションコードの有無： 実際のコードを含むソースディレクトリ（src/、app/、lib/、pkg/ など）。
2. 依存関係／ビルドマニフェストの有無： package.json、pnpm-lock.yaml、pom.xml、build.gradle、go.mod、requirements.txt／pyproject.toml、Cargo.toml、*.csproj、Gemfile など。
3. Git 履歴の有無： コミットがゼロ／空のツリーか、実際の履歴があるか。
4. incu-way の導入状況： incu-way のフローに言及する CLAUDE.md、.ways/ ディレクトリ、または docs/architecture/ があるか。
5. ブランチモデル： main と develop がすでに存在するか。

リポジトリの分類

• グリーンフィールド — 空、またはほぼ空（アプリケーションコードはまだなく、README やライセンスだけがある場合もあります）。作業の目的は、意図を記録することです。つまり、プロダクトビジョンと、チームが構築を予定しているアーキテクチャです。
• ブラウンフィールド — コードと履歴のある既存のアプリケーション（これをデフォルトとします）。作業の目的は、既存の内容をリバースエンジニアリングして理解することです。アーキテクチャを文書化し、必要に応じて、すでに存在する機能の動作も記録します。
• 初期化済み — incu-way の構造が存在します。リフレッシュモードに切り替え、欠けている部分を補完し、古くなったセクションを更新します。また、ブラウンフィールドの場合はドキュメント作成の工程を再実行します。

Phase 0 の終了条件

Gate 1 の前に、Claude は以下を説明できる必要があります。

• リポジトリがグリーンフィールド、ブラウンフィールド、初期化済みのいずれであるか
• 検出された技術スタック（言語、フレームワーク、パッケージマネージャー、テストランナー、ビルドツール）。ブラウンフィールドの場合は推測ではなく、マニフェストとディレクトリ構成から判断します
• main と develop が存在するか（および Git が初期化されているか）
• すでに存在する incu-way の要素と、欠けている要素
• 提案する初期化計画（作成するファイル、ブランチ戦略、ドキュメントの詳細度）

技術スタックやプロダクトの目的を推測しないでください。マニフェストから判断できない場合や、リポジトリの目的が不明確な場合は、推測で補わず、Gate 1 で確認する未解決の質問として記載してください。

---

Gate 1 — モードと範囲の確認

判定結果と提案する計画を提示し、ユーザーに確認します。

短い概要を提示します。

## Initialization plan

- **Mode:** greenfield | brownfield | refresh
- **Detected stack:** {languages / frameworks / package manager / test runner}
- **Branch model:** {exists: main, develop} | {will create: main, develop}
- **Will create / update:**
  - CLAUDE.md (from template, filled with the detected stack)
  - PRD.md (root) — {product vision (greenfield) | reverse-engineered overview (brownfield)}
  - docs/ tree: prds/, bugs/, security/, architecture/
  - .ways/ (work-item state.json lives here later)
- **Documentation depth (brownfield):** {structural only | architecture | architecture + functional}
- **Open questions:** {anything ambiguous about stack or product intent}

• 次のように尋ねます。「これが初期化計画です。作成を始める前に、モードとドキュメントの詳細度を確認してください。」
• 停止します。ユーザーがモードと範囲を確認するまで、先に進まないでください。

リポジトリの判定だけで、ひな形の作成が承認されたと見なさないでください。Gate 1 では、モードとドキュメントの詳細度を決定します。

---

分離環境の設定（Gate 1 の直後）

ファイルを書き始める前に、ブランチモデルを決め、初期化作業をどのように分離するかユーザーに尋ねます。

現在のチェックアウトで新しいブランチを使って作業しますか。それとも、別の git worktree を作成しますか？

ユーザーの回答をそのまま使用します。 質問したらそこで止め、ユーザーが選択するまでブランチや worktree を作成しないでください。

現在のチェックアウトにコミットされていない変更がある場合は、ブランチを切り替えたり worktree を作成したりする前に、いったん止めて確認してください。

git がまだないグリーンフィールド

ユーザーが git の初期化後に別の worktree を明示的に希望しない限り、現在のチェックアウトでブランチを使用します。このリポジトリにはまだコミットがないため、コミットなしでは main／develop は存在できません。まず、次のように尋ねてください。「このリポジトリにはまだコミットがありません。main を作成するために空の初回コミットを作成してもよいですか？」 ユーザーが確認した後に限り、次を実行します。

git init
git checkout -b main
git commit --allow-empty -m "chore: initial commit"
git checkout -b develop
git checkout -b chore/incu-way-init

ブラウンフィールド（git がすでにある）

develop がない場合は、main から作成する必要があります（これはリポジトリ全体に関わる判断です。まだ確認していない場合は Gate 1 で確認してください）。また、リモートに存在するよう push する必要があります。まず、次のように尋ねてください。「develop はまだありません。main から作成して push してもよいですか？」 ユーザーが確認した後に限り、次を実行します。

git checkout main && git checkout -b develop && git push -u origin develop   # only if develop is missing

オプション A — 現在のチェックアウトでブランチを使用

# Run from the repo root
git switch develop
git pull --ff-only
git switch -c chore/incu-way-init

以降のすべての作業（CLAUDE.md、ドキュメント、.ways/ のスキャフォールド、コミット）は、現在のチェックアウトにあるこのブランチで行います。develop または main に直接書き込まないでください。

オプション B — 別の worktree

worktree は .worktrees/ の下にのみ作成します。ユーザーにパスを尋ねないでください。

# Run from the repo root
git fetch origin develop
mkdir -p .worktrees
git worktree add .worktrees/incu-way-init -b chore/incu-way-init origin/develop

以降のすべての作業（CLAUDE.md、ドキュメント、.ways/ のスキャフォールド、コミット）は、この worktree 内だけで行います。develop または main に直接書き込まないでください。

---

フェーズ 2 — incu-way の構成をスキャフォールドする

目標： incu-way のフローが前提とするファイルとディレクトリを作成し、リポジトリから答えが分かる場合はプレースホルダーではなく、検出した実際の情報を記入します。

2.1 — CLAUDE.md

このスキルに同梱されている claude.template.md（この SKILL.md の隣にあり、ways add 時にスキルとともにコピーされます）をリポジトリのルートに CLAUDE.md としてコピーし、フェーズ 0 で検出した情報を使ってすべての [TODO: ...] を埋めます。

• プロジェクトについて — ブラウンフィールドの場合は README、マニフェスト、コードから導きます。グリーンフィールドの場合は Gate 1 で記録したユーザーのビジョンから導きます。
• スタック — 言語、フレームワーク、DB、テスト、パッケージマネージャー（検出したもの）。
• フォルダー構成 — 実際のトップレベル構成と、それぞれの用途を一行で示します。
• コード規約 — ブラウンフィールドの場合は既存の設定（.eslintrc、.editorconfig、tsconfig.json、リンター、フォーマッター）から推定します。グリーンフィールドの場合はテンプレートの既定値を使います。
• 便利なコマンド — マニフェストのスクリプト（package.json の scripts、Makefile、pom.xml など）から読み取ります。存在しないコマンドを作らないでください。
• Security、Worktree、Development workflow、Bug workflow の必須セクションは、テンプレートの定義どおりに維持してください。

導き出せない情報は、明示的な [TODO: ...] のまま残し、Gate 2 で列挙してください。作り上げてはいけません。

2.2 — PRD.md（ルート）

incu-way のフローでは、フェーズ 0 で最初に PRD.md を読み込みます。これを作成してください。

• グリーンフィールド： Gate 1 で合意したプロダクトビジョン（課題、対象ユーザー、目標、対象外事項、想定する高レベルのアーキテクチャ）を記録します。
• ブラウンフィールド： リバースエンジニアリングしたプロダクト概要を作成します。現在のアプリケーションが何をするのか、誰を対象としているのか、主な機能は何かを、コードから追跡できる形で記述します。incu-way-docs が対象範囲に含まれる場合（フェーズ 3 を参照）、docs/architecture/ と機能ドキュメントへの簡潔な案内として、意図的に薄い内容にできます。

2.3 — docs/ ツリーと .ways/

各フローが書き込むディレクトリ構造を作成します。

docs/
  prds/          # incu-way-development writes here
  bugs/          # incu-way-bugs writes here
  security/      # snyk-remediation writes here
  architecture/  # incu-way-docs writes here (brownfield)
.ways/       # work-item state.json lands here later (add a .gitkeep)

空のディレクトリには .gitkeep を追加して、コミットされるようにします。ここでは .ways/state.json を作成しないでください。これは作業項目のフローに属します。

.ways/ は way の状態（ways/v1alpha1）の標準ルートです。プロジェクトでも ways CLI を使用する場合、そのツールは .ways/cache/ の下にキャッシュを保持します。 詳しくは、以下のリポジトリの衛生管理を参照してください。

2.4 — リポジトリの衛生管理

.gitignore に次の項目が含まれていることを必ず確認してください（不足している項目を追加し、 すでにある行は重複させないでください）。

.claude/
.agents/

.claude/ と .agents/ には、skills.sh／hooks.sh による配置出力（および .claude/ の場合は Claude Code 独自のローカル設定）が格納されます。すべて ways.lock／skills-lock.json／steering-lock.json から ways install で再生成されるため、 node_modules と同様に破棄可能です。絶対にコミットせず、無視するかどうかを尋ねる必要もありません。

このプロジェクトに該当する場合のみ、次の対応を行います。

• .worktrees/ がリポジトリ内にあり、まだ無視されていない場合は、.gitignore に追加します。
• .ways/ の gitignore ルール。 .ways/state.json は追跡対象のままにする必要があります （ブランチからの再開とボードは、incu-way-prepare-pr 経由でコミットされることを前提としています）。 ways CLI を使用している場合は、.ways/ 全体ではなく、キャッシュのみを無視します。 .gitignore に .ways/cache/ を追加してください。.ways/ 全体を無条件に無視してはいけません。
• フローで参照される SonarQube スキャンをプロジェクトで使用する場合は、run-sonar.sh の場所、 またはまだ TODO であることを記載します。スクリプトを捏造してはいけません。

スキャフォールドの準備ができたことをユーザーに伝え、コミットするために incu-way-prepare-pr を実行するよう提案します。自分でコミットしてはいけません。

Suggested message: chore(incu-way-init): scaffold CLAUDE.md, docs/ tree and .ways/

---

フェーズ 3 — アプリケーションのドキュメント作成

目標： 人間と incu-way フローがアプリケーションを理解できるよう、アーキテクチャの ドキュメント（必要に応じて機能ドキュメントも）を作成します。

ブラウンフィールド — incu-way-docs を実行する

Gate 1 で合意したドキュメントの深さがアーキテクチャまたはアーキテクチャ + 機能の場合は、incu-way-docs スキルに引き継ぎ、現在の初期化ブランチ／ワークツリー に書き込むよう指示します（別の PR は作成せず、出力はこの初期化 PR に含めます）。 incu-way-docs は、アプリケーションの規模に応じて次を作成します。

• docs/architecture/ — 概要、コンポーネント、データモデル、統合、デプロイ／運用
• 機能／ドメインのドキュメントと用語集（アプリケーションがユーザー向け、またはドメインの要素が多い場合）
• Mermaid 図（検証済み）

合意した深さが構造のみの場合は、詳細な作業を省略します。現時点では CLAUDE.md のフォルダー構造と PRD.md の概要で十分です。詳細なドキュメント作成は後回しとし、 後から incu-way-docs で作成できることを PRD.md に記載します。

グリーンフィールド — 想定するアーキテクチャを記録する

リバースエンジニアリングするコードはありません。その代わり、docs/architecture/overview.md に意図を記録します。予定するアーキテクチャ、主要コンポーネント、重要な技術選定とその理由を （ADR 形式で）記載します。内容は簡潔にまとめます。コードが incu-way-development を通じて 書かれるにつれて、内容も発展していきます。

---

Gate 2 — 初期化内容を確認する

スキャフォールド作成後（対象範囲に含まれる場合はドキュメント作成後）：

• 作成／更新した内容を要約し、CLAUDE.md に残っているすべての [TODO: ...] と未解決の質問を列挙します。
• 次のように伝えます。「chore/incu-way-init で初期化が完了しました。CLAUDE.md、PRD.md、docs/ ツリー、.ways/ の準備ができています{。アーキテクチャ／機能ドキュメントも作成済みです}。PR を作成する前に確認してください。」
• 停止します。ユーザーの承認を得るまで PR を作成してはいけません。

---

フェーズ 4 — プルリクエストでマージする

目標： レビュー済みの PR を通じて、初期化内容を develop（その後 main）に反映します。 直接マージしてはいけません。

PR

Gate 2 の承認後、incu-way-prepare-pr の実行を提案して、chore/incu-way-init をプッシュし（リポジトリにリモートや履歴がまだなかった場合は、main／develop の初回プッシュも含みます）、PR を作成します。自分でプッシュしたり、gh pr create を実行したりしないでください。

incu-way-prepare-pr で使用する PR のタイトル／本文の案：

Title: chore: initialize incu-way

PR 本文には以下を含める必要があります：

• モード： greenfield／brownfield／refresh。
• 作成／更新対象： CLAUDE.md、PRD.md、docs/ ツリー、.ways/、および（該当する場合）リンク付きのアーキテクチャ／機能ドキュメント。
• 未解決項目： 残っている [TODO: ...] と、チームへの未解決の質問。

PR を作成したら、PR の URL をユーザーに共有します。ここで停止してください。ユーザーの承認を得るまでマージしないでください。

チームが main にもゲートを設けている場合は、最初の PR がマージされた後、開発フローと同様に、後続の PR develop → main を作成します。

---

クイックリファレンス — ゲート

ゲート	トリガー	伝える内容	待機条件
1	モードと計画を検出	「これは初期化計画です。モードとドキュメントの詳しさを確認してください。」	ユーザーが確認するまで
2	スキャフォールド（＋ドキュメント）の準備完了	「chore/incu-way-init で初期化が完了しました。PR を作成する前にレビューしてください。」	ユーザーが承認するまで
3	レビュー完了	PR chore/incu-way-init → develop のために incu-way-prepare-pr を提案し、ユーザーが実行したら URL を共有する	ユーザーが PR を承認するまで

---

してはいけないこと

フェーズごとの上記ルールが優先されます。ほかに明記されていない点は次のとおりです。

• greenfield／brownfield のブートストラップコマンドは、コミットを自動で行わないルールの唯一の例外ですが、それでも事前に確認が必要です。それ以外（スキャフォールドのコミット、PR）は、すべて incu-way-prepare-pr を通じてのみ行います。