scrolls-setup

docs/.scrolls/ のセットアップ

docs/.scrolls/ は、プロジェクトの作業メモリとしてセッションをまたいで機能する、小規模な Markdown ファイル群です。プロジェクトの機能、現在の状態、判明している不足点とその理由、次に行うこと、避けるべき落とし穴を記録します。SCROLLS.md によって、以降のすべてのセッションで最初に docs/.scrolls/STARTER.md を確認するため、毎回ゼロから情報を調べ直すのではなく、状況を引き継げます。また、SCROLLS.md を指す簡潔な CLAUDE.md と、代わりにそのファイルを読み込むハーネス向けに CLAUDE.md を指す対応する AGENTS.md も用意します。このスキルは、まだこの仕組みがないプロジェクト向けに、その土台を作成します。

このスキルの assets/templates/ ディレクトリにはテンプレートの原本が格納されています。そこからコピーしてください。原本ファイルを直接編集しないでください。

クロスプラットフォーム

ほかの4つの scrolls スキルとは異なり、このスキルには選択が必要な同梱の .sh／.ps1 スクリプトはありません。移植が必要なものはありません。ファイルの作成には、シェルコマンドを直接実行するのではなく、Read／Write／Edit ツールを使います。また、このスキルが依存する外部コマンドは1つだけ（git rev-parse --show-toplevel）で、bash と PowerShell のどちらから実行しても同じように動作します。どちらも、このファイル全体で使われる同じ $(...) コマンド置換構文に対応しています。macOS、Linux、Windows のいずれでも、環境ごとの分岐なしで同じように動作します。

オプション

ユーザーは /scrolls-setup の後に、以下をプレーンテキストで任意の順序で指定できます。ここには実際の argv パーサーがないため、呼び出しテキストを自分で読み取り、指定内容を抽出してください。

• -p <path>／--path=<path>／--path <path> — カスタムの docs フォルダーを指定します。絶対パス（/ で始まるパス）でない場合は、現在の作業ディレクトリからの相対パスです。モノレポや標準外のディレクトリ構成で使用します。たとえば、--path=packages/api/docs と指定すると、scrolls は packages/api/docs/.scrolls に配置されます。これは、ベースディレクトリではなく docs フォルダーを直接指定する唯一のオプションです。深い階層に配置する場合の注意点については、ステップ4の SCROLLS.md／CLAUDE.md の配置に関する注記を参照してください。
• -t／--reporoot — 実際にどのサブディレクトリから呼び出したかにかかわらず、すべてを git リポジトリのトップレベル（$(git rev-parse --show-toplevel)）に固定します。現在のディレクトリが git リポジトリ内にない場合は、明確なメッセージを表示して失敗します。リポジトリのルートを特定できないためです。
• -l／--local — すべてを現在の作業ディレクトリに明示的に固定します。-p／-t／-l のいずれも指定されない場合、デフォルトでこの動作になります。このフラグは、たとえばステップ1の不一致チェックを省略するために、意図的にそのように指定したい場合に使います。
• -r／--recurse — 作成を始める前に、BASE_DIR 以下を再帰的にスキャンし、近くに既存の scrolls フォルダーがないか確認します（/scrolls-hide／/scrolls-unhide が使う、同じ範囲に制限され、除外処理を行い、STARTER.md を条件とする検索です）。これにより、誤って重複を作成するのを防ぎます。続行した場合に新しい scrolls フォルダーが配置される場所は変わりません。ステップ1を参照してください。
• -u／--unhide — scrolls フォルダーの名前をデフォルトの .scrolls ではなく scrolls にします。これにより、ドットファイルとして非表示になりません。デフォルト（非表示）にする場合は省略してください。

-p、-t、-l は、いずれも同じ質問（「docs フォルダーをどこに配置するか」）に答えるための異なる方法です。指定するのは最大1つです。複数指定されている場合は、どれを意図したのか確認してください。-r は独立したオプションで、これらのいずれか（または何も指定しない場合）と自由に組み合わせられます。

手順

1. BASE_DIR を解決し、既存の作業を上書きしない

docs フォルダー、SCROLLS.md、CLAUDE.md、AGENTS.md を格納するディレクトリである BASE_DIR を計算します。

• -t／--reporoot が指定されている場合：BASE_DIR = $(git rev-parse --show-toplevel)。このコマンドが失敗した場合（Git リポジトリ内ではない場合）は、処理を中止してユーザーに伝えてください。ここには固定するリポジトリのルートがないため、代わりに --path を使うよう提案してください。
• -l／--local または -p／--path が指定されている場合：以下の DOCS_BASE の計算に進みます。-l は BASE_DIR = $(pwd) を使い、-p は BASE_DIR を完全に迂回します（DOCS_BASE の注記を参照）。
• 何も指定されていない場合（一般的なケース）：BASE_DIR = $(pwd)。ただし、まず現在のディレクトリが Git リポジトリ内にある場合は git rev-parse --show-toplevel を実行し、その結果と $(pwd) を比較します。両者が同じ場合、または Git リポジトリではない場合は、注意喚起する必要はありません。異なる場合は、ここから実行するとスクロールが $(pwd)/docs/.scrolls に作成され、リポジトリのルート（<repo-root>）にすでに存在する可能性のあるものとは別になることを明確に伝え、現在のディレクトリ（デフォルト。どちらでも特に希望がなければこちらで続行します）とリポジトリのルート（-t で再実行するのと同じ）のどちらにするか尋ねてください。これを確認し続けて処理を止めないでください。迷う場合は、ドキュメントに記載されたデフォルトである現在のディレクトリを優先します。

-r／--recurse が指定されている場合は、ファイルシステムに触れる前に、次のスキャンを実行します。BASE_DIR 以下を再帰的に検索し、STARTER.md を含む .scrolls または scrolls という名前のディレクトリを探します（-p が指定されている場合はスキップします。カスタムの --path は明示的に指定された場所であり、再検討するものではありません）。/scrolls-hide／/scrolls-unhide が除外するものと同じ、容量の大きいディレクトリやベンダーディレクトリ（node_modules、.git、vendor、dist、build、.venv、venv、__pycache__、target、.next、.cache）を除外し、妥当な深さ（他のスクロールスキルでは 8）に制限します。この検索で、これから作成する SCROLLS_PATH と完全に一致する場所を除く既存のスクロールフォルダーが BASE_DIR 以下に見つかった場合、その場所をユーザーに伝え、ここに新しい別個のフォルダーを作成するのではなく、そちらを対象に /scrolls-update を実行するつもりだったか尋ねてください。ユーザーがその意図を確認した場合にのみ作成を続行します（たとえば、サブプロジェクト用に意図的に別のスクロールシステムを作る場合など）。

次に、以下を実行します。

DOCS_BASE    = the --path value if -p was given, else "${BASE_DIR}/docs"
SCROLLS_DIR  = "scrolls" if --unhide/-u was passed, else ".scrolls"
SCROLLS_PATH = "${DOCS_BASE}/${SCROLLS_DIR}"

SCROLLS_PATH は、以下およびテンプレート内に記載されているすべての docs/.scrolls に置き換わります。このスキルの残りの部分では、これを総称して「スクロールのパス」と呼びます。ユーザーが既存の隠し .scrolls を後で表示状態に変換したい場合、それは別途実行する専用の操作です。このスキルを再実行するのではなく、/scrolls-unhide を案内してください。

SCROLLS_PATH にすでにファイルが存在する場合は、処理を中止し、不足しているファイルだけを補うか、そのままにしておくかをユーザーに尋ねてください。HANDOFF.md／PLAN.md などに実際に蓄積された状態が含まれている可能性があるため、既存のスクロールファイルをユーザーに知らせずに上書きしてはいけません。同じ注意は SCROLLS.md、CLAUDE.md、AGENTS.md にも当てはまります。既存の内容を消去してはいけません。--unhide が指定されているのに、その場所に .scrolls フォルダーがすでに存在する場合（またはその逆の場合）は、2 つ目の並列するスクロールフォルダーを作成しないでください。ユーザーに伝え、代わりに /scrolls-unhide を案内してください。

2. プロジェクトの概要を把握する

ユーザーに長々と質問するのは避け、最小限のセットアップですばやく進めます。数秒で分かることを推測します。

• プロジェクト名：package.json の name、pyproject.toml の [project].name、Cargo.toml を確認し、それでも分からない場合はディレクトリのベース名を使います。
• 一行のキャッチコピー：同じマニフェストの description フィールド、または既存の README.md の最初の行から取得します。省略してもかまいません。雰囲気を伝えるための任意のテキストであり、不可欠なものではありません。
• 概要：プロジェクトの実際の構成を短い段落で説明します。主なエントリーポイント、特に重要なファイルやディレクトリを1つか2つ、主要な言語や技術スタックを取り上げます。リポジトリのルートとマニフェストファイルを手早く確認し、詳細な監査は行いません。プロジェクトにコードがなく、本当に空の状態であれば、構成を創作せず、その旨を率直に伝えます。

複数の package.json があるモノレポなど、情報が曖昧な場合は、確認の質問を1つだけしてもかまいません。ただし、リポジトリから分かることについて質問で作業を止めず、まずは実行することを基本とします。

3. 7つのファイルを作成する

assets/templates/ の各ファイルをディスク上の SCROLLS_PATH にコピーし、ステップ2で収集した内容と上記で算出した内容を使って、{{PROJECT_NAME}}、{{PROJECT_TAGLINE}}、{{QUICK_ORIENTATION}}、{{SCROLLS_PATH}} のプレースホルダーを置き換えます。-t／-l／デフォルトから取得した SCROLLS_PATH は、絶対ファイルシステムパスです（いずれも常に絶対パスである BASE_DIR を経由して解決されます）。実際のファイル書き込みにはこれで問題ありませんが、テンプレート内の {{SCROLLS_PATH}} に代入するテキストは、同じ文字列ではありません。

• -t／-l／デフォルト（BASE_DIR 由来）：短縮形の docs/${SCROLLS_DIR}（例：docs/.scrolls）を代入します。絶対パスの SCROLLS_PATH は絶対に使わないでください。これによりファイルの移植性が保たれます。SCROLLS.md も（ステップ4で）常に BASE_DIR に配置されるため、BASE_DIR が $(pwd) か git ルートかにかかわらず、また後でどのマシンやクローンから参照されても、BASE_DIR からの相対パスが正しく機能します。ここに絶対パスを埋め込むと、リポジトリを別の場所にクローンした時点で壊れてしまいます。
• -p／--path：指定された DOCS_BASE ベースの完全な SCROLLS_PATH を、変更せずに代入します（例：packages/api/docs/.scrolls）。このパスはすでに相対パスであり、このケースで SCROLLS.md がどこに配置されるかは判断に依存するため（ステップ4を参照）、短縮形を推測せず、既存の動作を維持してください。

テンプレート	→	用途
STARTER.md	SCROLLS_PATH/STARTER.md	読む順序と更新タイミングの表。各セッションが最初に読む入口です。
SPEC.md	SCROLLS_PATH/SPEC.md	機能一覧。機能のリリースに合わせて記入します。
HANDOFF.md	SCROLLS_PATH/HANDOFF.md	現在の状態のスナップショット。各セッションで上書きし、追記はしません。
GAP_ANALYSIS.md	SCROLLS_PATH/GAP_ANALYSIS.md	未対応または部分的に対応していることが分かっている項目。
GAP_CONTEXT.md	SCROLLS_PATH/GAP_CONTEXT.md	各ギャップが存在する理由（意図的な省略、見落とし、ブロッカー）。
PLAN.md	SCROLLS_PATH/PLAN.md	優先順位を付け、チケット化したバックログ。
WISDOM.md	SCROLLS_PATH/WISDOM.md	制約／落とし穴／避けるべきこと／知見の各セクション。

これは最小限のセットです。STARTER.md で順に確認する6つのファイルと、STARTER.md 自体だけです。セキュリティレビュー、アーキテクチャ決定記録、サブシステムの詳細解説など、余分なスクロールファイルを最初から作らないでください。こうしたファイルは、後に該当する作業を担当する人が、STARTER.md の最後のセクションで説明されているパターンに従って、必要に応じて追加します。使える内容が見つからなかった場合は、{{PROJECT_TAGLINE}} を空欄にします（プレースホルダーを完全に削除し、{{...}} という文字列を残さないでください）。タグラインがなくても、You're picking up work on **Foo**. と表示され、タグラインの節がない形で問題なく読めます。

{{SCROLLS_PATH}} を含むテンプレートは STARTER.md と SCROLLS_MD_BLOCK.md のみです。上記のルールに従って（-t／-l／デフォルトでは短縮形、-p では完全な SCROLLS_PATH）、プレースホルダー文字列ではなく実際のパスに置き換え、両方のファイルで同じ値を使ってください。CLAUDE_MD_BLOCK.md と AGENTS_MD_BLOCK.md は置き換え不要です。ステップ4を参照してください。

テンプレートは、意図的にほぼ空の状態にしてあります（「（まだ記録なし）」のようなプレースホルダー項目など）。推測した機能一覧で SPEC.md を埋めたり、架空のチケットで PLAN.md を埋めたりしたい気持ちは抑えてください。最小限のひな型の役割は、形を保つことです。内容は実際のセッションを通じて蓄積されていきます。唯一の例外は STARTER.md の「Quick orientation」セクションです。すべてのセッションがすぐに頼る唯一の静的なコンテキストなので、正しく記載する価値があります。

4. SCROLLS.md、CLAUDE.md、AGENTS.md から STARTER.md を参照するようにする

このステップは、ステップ 1 で scrolls フォルダー内の 7 つのファイルについて何が決定されたかにかかわらず、常に実行されます。すでに docs/.scrolls/ に 7 つのファイルがすべて揃っていて、そこには手を加えなかったプロジェクトでも、ここで SCROLLS.md／CLAUDE.md／AGENTS.md を確認し、不足分を補ってください。このようにすることで、このスキルは冪等になり、既存プロジェクトに対してこのポインターのつながりを整える目的だけで安全に再実行できます。2 回実行しても（または SCROLLS.md／AGENTS.md が存在しなかった、このスキルの古いバージョンでセットアップされたプロジェクトに対して実行しても）、重複や上書きは発生しません。以下の 3 つの確認はそれぞれ、「存在しない場合のみ作成」「まだ参照がない場合のみ挿入」「すでに正しい場合はそのまま」です。

assets/templates/SCROLLS_MD_BLOCK.md を読み込み、STARTER.md と同じ方法で {{SCROLLS_PATH}} を置き換えてください。これを SCROLLS.md として設置します。

• -t／-l／デフォルト（BASE_DIR から導出）：SCROLLS.md（および以下の CLAUDE.md、AGENTS.md）は BASE_DIR、つまり新たに docs が置かれたディレクトリに配置します。ここは確定しており、曖昧さはありません。BASE_DIR は、ステップ 1 で -t／-l／不一致の確認によって解決済みの値なので、ここで改めて「プロジェクトルート」を判断する必要はありません。
• -p／--path：配置場所は実際に判断が必要です。カスタムの --path は、独立したモノレポのパッケージ（独自の SCROLLS.md と短いローカル参照を持つもので、先にそのパッケージに cd してから -l を実行した場合に近いもの）を指している場合もあれば、リポジトリ全体を参照するポインターファイル一式の下に置くべき、より大きなリポジトリの一部を指している場合もあります。プロジェクトの他のツールがすでに想定している場所を使ってください。本当に判断がつかない場合は、推測せずに尋ねてください。ここは誤った推測の代償が大きい唯一のケースです（チェックイン済みドキュメントに壊れた参照が埋め込まれてしまいます）。

配置場所が決まったら、以下の手順に従います。

• その場所に SCROLLS.md がまだない場合：その内容をそのまま記載したファイルを作成します。
• SCROLLS.md はあるものの、scrolls のパスへの参照がない場合：ファイルの上部付近に、前後を空行で区切って挿入します。ファイルが独自のトップレベル見出しで始まっている場合は、ブロックの見出しを 2 つ目のトップレベル見出し # Scrolls — Project Memory にするのではなく、サブセクションとして追加します。既存の見出し構成に合わせ、無理に変更しないでください。
• SCROLLS.md がすでに SCROLLS_PATH/STARTER.md（または、ここで該当する場合は短縮形）を参照している場合：そのままにし、ブロックを重複して追加せず、その旨をユーザーに伝えます。

次に、同じディレクトリにある CLAUDE.md についても同じように処理します。内容は assets/templates/CLAUDE_MD_BLOCK.md のそのままの内容です。これは固定の 2 行のポインター（## Access Scrolls Agentic Memory／See @SCROLLS.md.）であり、SCROLLS.md の内容そのものではありません。また、{{SCROLLS_PATH}} の置換も不要です。参照するのは常に SCROLLS.md だけであり、どのフラグを使った場合でも、SCROLLS.md は必ず同じディレクトリに置かれるためです。

• その場所に CLAUDE.md がまだない場合：そのブロックをそのまま記載したファイルを作成します。

• CLAUDE.md はあるものの、すでに SCROLLS.md を参照していない場合：他の指示より先にブロックを読み込めるよう、ファイルの上部付近に、前後を空行で区切って挿入します。このファイル分割が導入される前から、ファイルが SCROLLS_PATH/STARTER.md を直接参照している場合も同様です。これは実際によくあるケース（このスキルの 1.2.0 より前のバージョンでセットアップされたプロジェクト）であり、まさにこの処理で対応するものです。既存の記述内容にかかわらず、CLAUDE.md が SCROLLS.md を参照するよう、スタブを追加します。これは追加のみの処理です。古い直接参照と新しいスタブが同じファイル内に残ることになっても、既存の記述を削除したり書き換えたりしないでください。

• CLAUDE.md がすでに SCROLLS.md を参照している場合：そのままにし、ブロックを重複して追加せず、その旨をユーザーに伝えます。 次に、同じディレクトリで AGENTS.md についても同様に対応します。これは、CLAUDE.md の代わりに読み込む、他のいくつかのエージェントハーネス（Codex CLI など、agents.md の規約に従うもの）が採用している規約です。内容は assets/templates/AGENTS_MD_BLOCK.md のとおりです。SCROLLS.md の内容ではなく、1 行のポインター（See @CLAUDE.md）です。

• まだ AGENTS.md がない場合：その行だけを含むファイルを作成します。

• AGENTS.md はあるものの、CLAUDE.md への参照がまだない場合：上記と同じように、周囲の内容との間に空行を入れて、その行をファイルの上部付近に挿入します。すでにファイルにある内容には、それ以外手を加えません。

• AGENTS.md がすでに CLAUDE.md を参照している場合（または、すでに SCROLLS.md／SCROLLS_PATH/STARTER.md を直接指している場合）：そのままにして、重複して記載せずにユーザーへ伝えます。

5. 結果を報告する

新たに作成したものと、すでに存在していて変更せずに残したものを要約します。SCROLLS.md、CLAUDE.md、AGENTS.md のそれぞれを作成、更新、またはそのままにしたかどうかを含め、次にユーザーが特に注目すべき点を2つか3つ挙げます。たとえば、推測で補った場合は STARTER.md の概要説明を埋めること、何かをリリースしたら最初の正式な SPEC.md の項目を作成することなどです。

開発

レイアウトとバージョン管理に関する注意事項は meta/MAINTAINERS.md を参照してください。ユーザーの /scrolls-setup リクエストを実行する際には読み込まないでください。そのリクエストへの対応中は、meta/MAINTAINERS.md に基づいて作業しないでください。