レイアウト移行
概要
アップストリームの agent-skills は作業ファイルをプロジェクトルートに保持します。チームはそれらを .claude-work/ に保持します（チームオーバーライドのパス表を参照）。このスキルは、進行中のプロジェクトを1つのコミットでチームレイアウトに移行します。各ファイルは git の履歴を保持します。タスクのチェックボックスもファイルと一緒に移動するため、中断したところから作業を続行できます。
引数はプランとタスクファイルの <id> です。例: /agent-skills-jksim:migrate-layout fl-debug
使用タイミング
- プロジェクトのルートに
SPEC.md、tasks/plan.md、tasks/todo.md、CONSTRAINTS.mdが存在する場合。 - プロジェクトにルート作業ファイルと
.claude-work/の両方が存在する場合。
新しいプロジェクトでは使用しないでください。仕様作成段階は最初から .claude-work/ に書き込みます。
手順
1. 開始状態の確認
以下のいずれかが該当する場合は停止し、ユーザーに通知します:
- フォルダが git リポジトリではない。
git status --porcelain --untracked-files=noが追跡ファイルの変更を示している。ユーザーにコミットまたはスタッシュを依頼してください。未追跡ファイルはそのままで構いません。ステップ8ではgit add -uでステージングするため、それらは追加されません。git check-ignore -q .claude-work/spec/SPEC.mdが成功する。ファイルパスを確認してください:.claude-work/のようなパターンは、フォルダが存在する前に一致しません。コンシューマープロジェクトは.claude-work/をコミットします。
2. 古いファイルの検索
プロジェクトルートからの相対パスで、以下のパスのみを対象とします:
| 古いパス | チームパス |
|---|---|
SPEC.md、docs/SPEC.md | .claude-work/spec/SPEC.md |
SPEC-<module>.md | .claude-work/spec/SPEC-<module>.md |
CAPABILITY-MAP.md | .claude-work/spec/CAPABILITY-MAP.md |
tasks/plan.md | .claude-work/tasks/plan-<id>.md |
tasks/todo.md | .claude-work/tasks/todo-<id>.md |
CONSTRAINTS.md | .claude-work/docs/CONSTRAINTS.md |
docs/ideas/<name>.md | .claude-work/docs/ideas/<name>.md |
docs/intent/<topic>.md | .claude-work/docs/intent/<topic>.md |
docs/decisions/ | そのまま残す。確認を取る（ステップ4を参照） |
spec/ には触れないでください。RSpec や他のテストレイアウトが使用します。
git が追跡しているファイルのみを使用します（git ls-files）。git mv は他のファイルでは失敗します。未追跡または無視されている古いファイルがあれば名前を挙げてユーザーに確認してください。
古いファイルが存在しない場合は、移行するものがないことをユーザーに伝えて停止します。
3. <id> の取得
引数を使用します。引数がない場合は、プロジェクト名から短いケバブケースの id を提案し、ユーザーに確認してください。tasks/plan.md または tasks/todo.md がない場合はこのステップをスキップします。
4. 計画の表示と承認待ち
古いパスと新しいパスの表を1つ表示します。次に、各競合をリストアップして対処方法を尋ねます:
- ターゲットが存在する: すでにチームパスにファイルが存在します。そのファイルは移動しないでください。どうするか尋ねてください。
- 2つのスペック:
SPEC.mdとdocs/SPEC.mdの両方が存在します。どちらがスペックかを尋ねてください。 tasks/内のその他のファイル:plan.mdとtodo.mdのみを移動します。その他のファイルを指定してください。docs/decisions/が存在する: デフォルトはそのまま残すことです。プロジェクトは独自の ADR フォルダを保持します。ユーザーが明示的に希望した場合のみ、.claude-work/docs/adr/に移動します。
ユーザーが表を承認するまで何も移動しないでください。
5. git mv で移動
各ファイルに対して git mv <古いパス> <新しいパス> を実行します。ターゲットフォルダを最初に作成します（mkdir -p）。コピーして削除しないでください: git mv は履歴を保持します。tasks/ が空になった場合は rmdir tasks を実行します。
6. ライブ参照の修正
プロジェクト内で古いパスを検索します: git grep -n -E 'SPEC(-[A-Za-z0-9_-]+)?\.md|CAPABILITY-MAP\.md|CONSTRAINTS\.md|tasks/(plan|todo)\.md|docs/(ideas|intent|decisions)/'
また、ファイル名のみ（フォルダなし）も検索します。移動したファイルがパートナーをフォルダなしで参照する可能性があるためです: git grep -n -E '(^|[^-/A-Za-z0-9_])(plan|todo)\.md'。例: プラン内の "detail in todo.md" は "detail in todo-.md" になります。
ライブ参照は、読み手やエージェントにファイルの現在位置を示します。以下のように変更します:
CLAUDE.md: "SPEC.md: approved spec" は ".claude-work/spec/SPEC.md: approved spec" になります。README.md:[SPEC.md](SPEC.md)は[SPEC.md](.claude-work/spec/SPEC.md)になります。- 移動したファイル内の相対リンク: 古い
tasks/plan.md内の../SPEC.mdは.claude-work/tasks/plan-<id>.md内の../spec/SPEC.mdになります。 CLAUDE.md内の制約ポインター行。- 各移動ファイル内のその他の相対リンク。移動したファイルは新しい深さにあるため、移動しなかったファイルへのリンクも壊れます。例: ルートの
SPEC-foo.md内の[x](src/a.kt)は.claude-work/spec/SPEC-foo.md内の[x](../../src/a.kt)になります。
記録は過去の出来事を表します。そのまま残します:
- 完了したタスクのエントリー: "Files: README.md, SPEC.md"
- 変更ログ、レビューノート、コミットメッセージ。
確信が持てない場合は、テキストをそのままにしてステップ7でリストアップします。
7. 結果の表示
git status、変更された参照の差分、および変更しなかった古いパスの参照（理由付き）のリストを表示します。
8. 1つのコミット
git mv はすでに移動をステージングしています。編集した参照を git add -u でステージングします。git add -A は使用しないでください: 無関係なファイルを追加する可能性があります。メッセージ Move working files to .claude-work でコミットします。プッシュはしないでください。
フックがコミットを拒否した場合は、停止して報告します。--no-verify は使用しないでください。
9. 次のステップの報告
どのファイルが移動し、どれが残ったかをユーザーに伝えます。.claude-work/docs/VOCABULARY.md が存在しない場合は、次の仕様作成段階で作成される（ルール2）ことを伝えます。今は作成しないでください。
よくある言い訳
| 言い訳 | 現実 |
|---|---|
"コピーの方が git mv より簡単だ。" | コピーはファイル履歴を失います。レビュアーと git log --follow は履歴を必要とします。 |
"SPEC.md への言及をすべて更新する。" | 記録は過去を表します。変更すると歴史を書き換えることになります。 |
| "ツリーが少し汚れているだけだ。" | 未コミットの作業は移行コミットに含まれてしまいます。最初にユーザーに確認してください。 |
| "計画は明らかなので、承認をスキップする。" | ユーザーが <id> と各競合を決定します。待ってください。 |
レッドフラグ
git log --followが移行コミットより前の履歴を表示しない。- 完了したタスクエントリーや変更ログが、当時存在しなかったチームパスを参照している。
spec/またはdocs/decisions/がユーザーの承認なしに移動した。- コミットが1つより多い、またはプッシュがある。
検証
- 各古いファイルがチームパスに配置されている。ユーザーが保持を選択したものを除き、ルートに古いファイルは残っていない。
-
git log --follow <新しいパス>が古い履歴を表示する。 - ライブ参照がチームパスを指している。記録は変更されていない。
- タスクのチェックボックスが変更されていない。
- コミットは1つ（
Move working files to .claude-work）。git statusはクリーン。プッシュされていない。