handover

プロジェクト引き継ぎドキュメント

Edge Delivery Services プロジェクト向けの包括的な引き継ぎドキュメントを生成します。さまざまな対象者向けのガイド作成を調整します。

利用可能なドキュメントの種類

ガイド	対象者	スキル
オーサリングガイド	コンテンツ作成者およびコンテンツマネージャー	handover-author
開発者ガイド	開発者および技術チーム	handover-developer
管理者ガイド	サイト管理者および運用担当者	handover-admin

---

実行フロー

Step 0: プロジェクトのルートに移動する（必須）

cd "$(git rev-parse --show-toplevel)"
ls scripts/aem.js

scripts/aem.js が存在しない場合、このスキルには AEM Edge Delivery Services プロジェクトが必要であることをユーザーに伝え、停止します。

以降のすべての手順はプロジェクトのルートから実行します。ガイドは project-guides/ に作成されます。

---

Step 0.5: 古い設定をクリーンアップする

rm -f .claude-plugin/project-config.json

---

Step 1: ドキュメントの種類をユーザーに尋ねる

AskUserQuestion を使用し、次の4つの選択肢をそのまま提示します。

AskUserQuestion({
  "questions": [{
    "question": "Which type of handover documentation would you like me to generate?",
    "header": "Guide Type",
    "options": [
      {"label": "All (Recommended)", "description": "Generate all three guides: Authoring, Developer, and Admin"},
      {"label": "Authoring Guide", "description": "For content authors and managers - blocks, templates, publishing"},
      {"label": "Developer Guide", "description": "For developers - codebase, implementations, design tokens"},
      {"label": "Admin Guide", "description": "For site administrators - permissions, API operations, cache"}
    ],
    "multiSelect": false
  }]
})

Step 1.5: 組織名を取得する

ユーザーがガイドの種類を選択した後、サブスキルを呼び出す前に組織名を確認します。

1.5.1 保存済みの組織名を確認する

cat .claude-plugin/project-config.json 2>/dev/null | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  try { const o = JSON.parse(d).org; if(o) console.log('org: ' + o); } catch(e) {}
"

1.5.2 Git からサイト名を解決する

SITE=$(basename -s .git $(git remote get-url origin 2>/dev/null) 2>/dev/null)
echo "site=${SITE:-NOT SET}"

1.5.3 組織名を尋ねる（保存されていない場合）

組織名が保存されていない場合は、ユーザーに尋ねます。

「Config Service の組織名を教えてください。これは Edge Delivery Services の URL における {org} の部分です（例：https://main--site--{org}.aem.page）。組織名は GitHub の組織名と異なる場合があります。

組織名またはプレビュー／ライブ URL のいずれかを入力してください。」

選択肢付きの AskUserQuestion ではなく、通常のテキストで質問します。組織名は必須です。

ユーザーが URL を入力した場合は、そこから組織名を解析します。

URL="$USER_INPUT"
if echo "$URL" | grep -q '\.aem\.page\|\.aem\.live'; then
  HOST_PART=$(echo "$URL" | cut -d'/' -f3 | cut -d'.' -f1)
  ORG=$(echo "$HOST_PART" | awk -F'--' '{print $NF}')
  echo "Parsed from URL: org=$ORG"
fi

1.5.4 組織名を保存する

mkdir -p .claude-plugin
grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore

# Include allGuides flag only when "All (Recommended)" was selected
echo '{"org": "{ORG_NAME}"}' > .claude-plugin/project-config.json
# OR for "All (Recommended)":
echo '{"org": "{ORG_NAME}", "allGuides": true}' > .claude-plugin/project-config.json

{ORG_NAME} を実際の組織名に置き換えます。ユーザーが「All (Recommended)」を選択した場合に限り、"allGuides": true を含めます。これにより、サブスキルは手順0の検証をスキップします。

Step 1.6: 認証する

有効な認証トークンがあるか確認します。

AUTH_TOKEN=$(node -e "
  const fs = require('fs');
  try {
    const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
    if (t.authToken && t.authTokenExpiry > Math.floor(Date.now()/1000) + 60) {
      process.stdout.write(t.authToken);
    }
  } catch (e) {}
")

if [ -n "$AUTH_TOKEN" ]; then
  echo "Token valid"
else
  echo "Token missing or expired."
fi

有効なトークンがない場合は、認証スキルを呼び出します。

Skill({ skill: "aem-project-management:auth" })

ここで認証することで、並行して実行されるすべてのサブスキルが、個別にログインを求めることなく保存済みトークンを使用できます。

Step 1.7: 組織名を検証する

認証後、組織名を検証します。

AUTH_TOKEN=$(node -e "
  const fs = require('fs');
  try {
    const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
    process.stdout.write(t.authToken || '');
  } catch (e) {}
")
ORG=$(cat .claude-plugin/project-config.json | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  process.stdout.write(JSON.parse(d).org || '');
")
curl -s -w "\nHTTP: %{http_code}" -H "x-auth-token: ${AUTH_TOKEN}" \
  "https://admin.hlx.page/config/${ORG}/sites.json"

HTTP 200 の場合：組織名は有効です。Step 2 に進みます。

HTTP 200 以外の場合：組織名が正しくないようであることをユーザーに伝え、正しい組織名を尋ねます。.claude-plugin/project-config.json を更新し、HTTP 200 が返るまで再試行します。

Step 2: 適切なスキルを呼び出す

選択	アクション
All	3つのスキルすべてを並行して呼び出す（Step 3 を参照）
Authoring Guide	Skill({ skill: "aem-project-management:handover-author" })
Developer Guide	Skill({ skill: "aem-project-management:handover-developer" })
Admin Guide	Skill({ skill: "aem-project-management:handover-admin" })

ガイドを1つだけ選択した場合は、メインの会話からスキルを直接呼び出します（Agent 経由ではありません）。これにより、権限の確認がユーザーに表示されます。

Step 3: 「All」を選択した場合 — 並行実行

開始前に、ただちにユーザーへ状況を伝えます。

"Starting parallel generation of all 3 handover guides:
  Authoring Guide - analyzing blocks, templates, configurations...
  Developer Guide - analyzing code, patterns, architecture...
  Admin Guide - analyzing deployment, security, operations..."

3つのエージェントを1つのメッセージで同時に起動します（フォアグラウンドモード）。run_in_background: true は使用しないでください。各エージェントには、サブスキルの SKILL.md を読み、その指示に直接従うよう伝えます。Skill ツールを呼び出すよう指示してはいけません。

Agent({
  description: "Generate authoring guide",
  prompt: "You are generating an authoring guide for an AEM Edge Delivery Services project at {PROJECT_ROOT}. Read the skill instructions at {PLUGIN_ROOT}/skills/handover-author/SKILL.md and follow them to generate the guide. The project config is at .claude-plugin/project-config.json (org, allGuides are already set — skip Phase 0 and authentication). Auth token is at ~/.aem/ims-token.json. Start from Phase 1. For PDF conversion, read {PLUGIN_ROOT}/skills/whitepaper/SKILL.md and follow its instructions. Do NOT use the Skill tool — execute all steps directly with Bash, Read, and Write tools."
})

Agent({
  description: "Generate developer guide",
  prompt: "You are generating a developer guide for an AEM Edge Delivery Services project at {PROJECT_ROOT}. Read the skill instructions at {PLUGIN_ROOT}/skills/handover-developer/SKILL.md and follow them to generate the guide. The project config is at .claude-plugin/project-config.json (org, allGuides are already set — skip Phase 0 and authentication). Auth token is at ~/.aem/ims-token.json. Start from Phase 1. For PDF conversion, read {PLUGIN_ROOT}/skills/whitepaper/SKILL.md and follow its instructions. Do NOT use the Skill tool — execute all steps directly with Bash, Read, and Write tools."
})

Agent({
  description: "Generate admin guide",
  prompt: "You are generating an admin guide for an AEM Edge Delivery Services project at {PROJECT_ROOT}. Read the skill instructions at {PLUGIN_ROOT}/skills/handover-admin/SKILL.md and follow them to generate the guide. The project config is at .claude-plugin/project-config.json (org, allGuides are already set — skip Phase 0 and authentication). Auth token is at ~/.aem/ims-token.json. Start from Phase 1. For PDF conversion, read {PLUGIN_ROOT}/skills/whitepaper/SKILL.md and follow its instructions. Do NOT use the Skill tool — execute all steps directly with Bash, Read, and Write tools."
})

{PROJECT_ROOT} を実際のプロジェクトルートのパス（git rev-parse --show-toplevel の出力）に置き換えます。

次の方法で {PLUGIN_ROOT} を特定します。

PLUGIN_ROOT=$([ -d ".claude/plugins/aem-project-management" ] && echo ".claude/plugins/aem-project-management" || echo "$CLAUDE_PLUGIN_ROOT")

3つすべてが完了したら、最終的な概要を報告します。

"Handover documentation complete:

project-guides/
├── AUTHOR-GUIDE.pdf
├── DEVELOPER-GUIDE.pdf
└── ADMIN-GUIDE.pdf

All PDFs generated. Source files cleaned up."

---

出力ファイル

選択項目	出力ファイル
すべて	project-guides/AUTHOR-GUIDE.pdf、project-guides/DEVELOPER-GUIDE.pdf、project-guides/ADMIN-GUIDE.pdf
オーサリングガイド	project-guides/AUTHOR-GUIDE.pdf
開発者ガイド	project-guides/DEVELOPER-GUIDE.pdf
管理者ガイド	project-guides/ADMIN-GUIDE.pdf

各サブスキルは、ガイドの完成直後に PDF を生成します。PDF の生成後、すべてのソースファイル（.md、.html、.plain.html）は削除されます。

---

関連スキル

• aem-project-management:handover-author — 作成者／コンテンツマネージャー向けガイド
• aem-project-management:handover-developer — 開発者向け技術ガイド
• aem-project-management:handover-admin — 管理者向け運用ガイド
• aem-project-management:whitepaper — PDF の生成（各サブスキルから呼び出されます）