handover-author

プロジェクト引き継ぎ - オーサリング

コンテンツ作成者とコンテンツ管理者向けの完全なオーサリングガイドを生成します。プロジェクトを分析し、実行可能なドキュメントを作成します。

---

ステップ 0：プロジェクトのルートに移動（条件付き）

.claude-plugin/project-config.json で allGuides が設定されている場合はスキップします（オーケストレーターによる検証は完了しています）。

ALL_GUIDES=$(cat .claude-plugin/project-config.json 2>/dev/null | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  try { console.log(JSON.parse(d).allGuides ? 'true' : ''); } catch(e) { console.log(''); }
")
if [ -z "$ALL_GUIDES" ]; then
  cd "$(git rev-parse --show-toplevel)"
  ls scripts/aem.js
fi

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

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

---

実行チェックリスト

- [ ] Phase 0: Get org name and authenticate
- [ ] Phase 1: Gather project information from Config Service API
- [ ] Phase 2: Analyze content structure
- [ ] Phase 3: Document blocks and templates
- [ ] Phase 4: Document configuration sheets
- [ ] Phase 5: Generate PDF

---

フェーズ 0：組織名の取得と認証

0.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) {}
"

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

組織名が見つからない場合は、ユーザーに尋ねます。

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

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

0.3 組織名を保存する

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

if [ -f .claude-plugin/project-config.json ]; then
  cat .claude-plugin/project-config.json | sed 's/"org"[[:space:]]*:[[:space:]]*"[^"]*"/"org": "{ORG_NAME}"/' > /tmp/project-config.json && mv /tmp/project-config.json .claude-plugin/project-config.json
else
  echo '{"org": "{ORG_NAME}"}' > .claude-plugin/project-config.json
fi

{ORG_NAME} を実際の組織名に置き換えます。

0.4 認証トークンを確認する

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 [ -z "$AUTH_TOKEN" ]; then
  echo "AUTH_REQUIRED"
fi

AUTH_REQUIRED の場合は、先に進む前に認証スキルを呼び出します。

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

---

フェーズ 1：プロジェクト情報を収集する

1.1 Config Service API からサイトを取得する

サイト情報の信頼できる唯一の情報源は Config Service API です。fstab.yaml、README、または git のリモート URL は使用しないでください。

ORG=$(cat .claude-plugin/project-config.json | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  console.log(JSON.parse(d).org || '');
")
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) {}
")

curl -s -H "x-auth-token: ${AUTH_TOKEN}" -H "Accept: application/json" \
  "https://admin.hlx.page/config/${ORG}/sites.json" > .claude-plugin/sites-config.json

node -e "
  const d = require('fs').readFileSync('.claude-plugin/sites-config.json', 'utf8');
  const j = JSON.parse(d);
  if (!j.sites || !j.sites.length) {
    console.error('No sites returned — verify org name and re-authenticate if needed');
    process.exit(1);
  }
  console.log('Found ' + j.sites.length + ' site(s): ' + j.sites.map(s => s.name).join(', '));
"

検証に失敗した場合は、組織名が正しいことを確認し、再認証してから再試行します。

コンテンツの詳細を取得するため、サイトごとの設定を取得します。

curl -s -H "x-auth-token: ${AUTH_TOKEN}" \
  "https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"

次の情報を抽出します。

• code.owner / code.repo — GitHub リポジトリ
• content.source.url — コンテンツのマウントパス（例：https://content.da.live/org/site/）
• content.source.type — コンテンツソースの種類（markup、onedrive、google）

コンテンツソースから DA とブロックライブラリの URL を作成します。

• DA URL：https://da.live/#/{org}/{site}/
• ブロックライブラリ：https://da.live/#/{org}/{site}/.da/library

複数のサイトがある場合はリポジトリなしのセットアップです。単一のサイトの場合は標準的なセットアップです。

1.2 多言語サポートを確認する

ls -la /en /fr /de /es /it 2>/dev/null || echo "Check DA for language folders"

プロジェクトが多言語対応かどうか、また対応している言語を記録します。

---

フェーズ 2：コンテンツ構造を分析する

フェーズ 1 で取得したサイト設定を読み込みます。

cat .claude-plugin/sites-config.json

2.1 ナビゲーションとフッターを分析する

ls nav.md footer.md 2>/dev/null || echo "Nav/footer likely in DA"

次の情報を記録します：ナビゲーションとフッターの場所（DA パスまたはローカルファイル）、メニュー構成、モバイルでの動作。

2.2 ページテンプレートを特定する

ls -la templates/ 2>/dev/null && ls templates/

各テンプレートについて、名前、目的、適用方法（メタデータの設定）を記録します。

2.3 セクションスタイル

grep -E "\.section\." styles/styles.css 2>/dev/null | head -15

ガイドの「利用可能なセクションスタイル」表に記載するため、利用可能なセクションスタイル（例：dark、highlight、narrow）を記録します。

---

フェーズ 3：ブロックとテンプレートをドキュメント化する

3.1 ブロックを一覧表示して分析する

ls blocks/

ブロックの分析は、出力せずに実行します。各ブロックについて、目的、バリアント（CSS の .blockname.variant から取得）、作成者が使用すべき場面を特定します。作成者が利用可能なブロックを把握できるよう、すべてのブロックを記載します。

3.2 テンプレートをドキュメント化する

フェーズ 2.2 で見つかった各テンプレートについて、名前、目的、必須のメタデータフィールド、適用方法（Metadata ブロックの template: name）を記載します。

3.3 DA とブロックライブラリのパス

Config Service のサイト設定からコンテンツパスを取得します。ブロックライブラリの URL は https://da.live/#/{content-owner}/{content-path}/.da/library です。パスはプロジェクトによって異なります。

---

フェーズ 4：設定シートをドキュメント化する

4.1 プレースホルダー

ls placeholders.json 2>/dev/null

DA 内の場所、言語シート、作成者が更新する必要のある主な文字列を記載します。

4.2 リダイレクト

ls redirects.json 2>/dev/null

DA 内の場所、形式（ソース → 移動先の列）、使用する場面を記載します。

4.3 一括メタデータ

ls metadata.json 2>/dev/null

DA 内の場所、URL パターン、一括設定するメタデータプロパティを記載します。

4.4 その他の設定シート

ls -la *.xlsx *.json 2>/dev/null | grep -v package

---

フェーズ 5：作成者向けガイドを生成する

5.1 出力ファイル

project-guides/AUTHOR-GUIDE.md に保存します（最初に mkdir -p project-guides を実行してください）。

---
title: "[Project Name] - Author Guide"
date: "[Full Date — e.g., February 17, 2026]"
---

# [Project Name] - Author Guide

## Quick Reference

| Resource | URL |
|----------|-----|
| Document Authoring | https://da.live/#/{content-owner}/{content-path}/ |
| Preview (per site) | https://main--{site}--{org}.aem.page/ |
| Live (per site) | https://main--{site}--{org}.aem.live/ |
| Block Library | https://da.live/#/{content-owner}/{content-path}/.da/library |
| Bulk Operations | https://da.live/apps/bulk |

(**Content path** comes from the Config Service site config — e.g., `content.da.live/org/site/` → use `org/site` for the path after `#/`. This varies by project.)

### Sites

| Site | Content Source (DA) | Preview | Live |
|------|---------------------|---------|------|
| {site1} | [from site config] | https://main--{site1}--{org}.aem.page/ | https://main--{site1}--{org}.aem.live/ |

## Getting Started

### Access Requirements
- [ ] DA access (request from admin)
- [ ] Preview/publish permissions

### Your First Page
1. Go to DA: [link]
2. Navigate to the correct folder
3. Create new document
4. Use blocks from Library sidebar
5. Add Metadata block at bottom
6. Preview → Publish

## Content Organization

### Site Structure
[Describe the folder structure in DA]

### Languages
[List supported languages if multi-lingual]

## Block Library

The Block Library is the sidebar in Document Authoring where you browse and insert blocks and templates.

| What | Details |
|------|---------|
| **Open in DA** | Use the Library icon in the DA editor sidebar, or go directly to: `https://da.live/#/{content-owner}/{content-path}/.da/library` |
| **How to use** | Click a block or template in the library to insert it at the cursor position |

## Available Blocks

| Block | Purpose | Variants | Usage |
|-------|---------|----------|-------|
| [name] | [what it's for] | [variant1, variant2] | [when to use] |

[Generate table rows for all blocks]

## Page Templates

| Template | Purpose | Required Metadata | How to Apply |
|----------|---------|-------------------|--------------|
| [name] | [what type of pages] | [key fields] | `template: [name]` in Metadata |

[Generate table rows for all templates]

## Configuration Sheets

| Sheet | Location | Purpose | When to Update |
|-------|----------|---------|----------------|
| Placeholders | `/placeholders` | Reusable text strings, translations | Changing labels, button text |
| Redirects | `/redirects` | Forward old URLs to new URLs | After deleting/moving pages |
| Bulk Metadata | `/metadata` | Apply metadata to multiple pages | Setting defaults by folder |

## Publishing Workflow

| Environment | Domain | Purpose |
|-------------|--------|---------|
| Preview | `.aem.page` | Test changes before going live |
| Live | `.aem.live` | Production site |

**Workflow:** Edit in DA → Preview → Publish → Live immediately

**Bulk:** https://da.live/apps/bulk

## Common Tasks

| Task | Steps |
|------|-------|
| **Create a Page** | Navigate to folder → New → Document → Add content → Add Metadata → Preview → Publish |
| **Edit a Page** | Open in DA → Make changes → Preview → Publish |
| **Delete a Page** | Add redirect first → Delete document → Publish redirects |
| **Update Navigation** | Edit `/nav` document → Preview → Publish |
| **Update Footer** | Edit `/footer` document → Preview → Publish |

## Sections and Section Metadata

Sections group content together. Create sections with horizontal rules (`---`).

Add styles with a Section Metadata block at the end of the section:

| Section Metadata | |
|------------------|-|
| style | [style-name] |

**Available Section Styles:**

| Style | Effect |
|-------|--------|
| [List project-specific styles] | |

## Page Metadata

| Property | Required | Purpose | Example |
|----------|----------|---------|---------|
| `title` | Yes | Page title for SEO | "About Us" |
| `description` | Yes | SEO description | "Learn about..." |
| `image` | No | Social sharing image | /images/og.jpg |
| `template` | No | Apply page template | project-article |
| [Add project-specific fields] | | | |

## Images and Media

| Method | How |
|--------|-----|
| Drag & drop | Drag images directly into DA editor |
| AEM Assets | Use Assets sidebar in DA |

Best practices: descriptive filenames, always add alt text, images auto-optimized.

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Page not updating after publish | Wait 1-2 min for cache, hard refresh (Cmd+Shift+R) |
| Block not displaying correctly | Check structure matches expected format, verify variant spelling |
| Images not showing | Verify image uploaded to DA, check path is correct |
| Wrong template styling | Check `template` value in Metadata matches template name exactly |

## Resources

| Resource | URL |
|----------|-----|
| DA Documentation | https://docs.da.live/ |
| Authoring Guide | https://www.aem.live/docs/authoring |
| Placeholders Docs | https://www.aem.live/docs/placeholders |
| Redirects Docs | https://www.aem.live/docs/redirects |

## Support Contacts

[Add project-specific contacts]

5.2 プロフェッショナルな PDF に変換

YAML フロントマター（タイトル、完全な日付形式の日付。例：「February 17, 2026」）を付けて、完成した Markdown を project-guides/AUTHOR-GUIDE.md に保存します。その後、すぐに PDF 変換を実行してください。

Skill({ skill: "aem-project-management:whitepaper", args: "project-guides/AUTHOR-GUIDE.md project-guides/AUTHOR-GUIDE.pdf" })

ホワイトペーパーのスキルがソースファイルを自動的にクリーンアップします。最終出力：project-guides/AUTHOR-GUIDE.pdf。

ユーザーに「Author guide complete: project-guides/AUTHOR-GUIDE.pdf」と伝えてください。

---

成功基準

カテゴリ	確認項目
データソース	Config Service API が呼び出されている（https://admin.hlx.page/config/{ORG}/sites.json）
データソース	サイト一覧が API のレスポンスに基づいており、fstab.yaml やコードベースの分析に基づいていない
データソース	DA／Block Library の URL が、code.owner/repo から推測したものではなく、Config Service のコンテンツソースから導出されている
コンテンツ	すべてのプロジェクト URL を含むクイックリファレンステーブル
コンテンツ	すべてのブロックが表形式で記載されている
コンテンツ	すべてのテンプレートが必須メタデータとともに記載されている
コンテンツ	設定シートが記載されている
コンテンツ	公開ワークフローが説明されている
コンテンツ	よくあるタスクが記載されている
コンテンツ	セクション／ページのメタデータオプションが一覧になっている
コンテンツ	トラブルシューティングが含まれている
出力	PDF が project-guides/AUTHOR-GUIDE.pdf に生成されている
出力	すべてのソースファイルがクリーンアップされ、PDF のみが残っている

---

コミュニケーション： 出力およびドキュメントでは、「EDS」という略称を決して使用しないでください。常に「Edge Delivery Services」または「AEM Edge Delivery Services」と表記してください。