publish-to-confluence

COG Confluence への公開スキル

呼び出すタイミング

• ユーザーがドキュメントを Confluence に公開したい場合
• ユーザーが「Confluence に公開」「Wiki にプッシュ」「Confluence に送信」「Confluence 公開」と言った場合
• ユーザーがチームと Confluence で共有したい Markdown ファイルを持っている場合
• PRD、リリースノート、その他 Wiki に掲載するドキュメントを生成した後

エージェントモードの確認

00-inbox/MY-PROFILE.md のフロントマターにある agent_mode を確認してください：

• agent_mode: team の場合 — このスキルで大きなメリットはありません（単一の順次操作です）
• agent_mode: solo の場合 — 標準的な実行

コマンド：/publish-to-confluence

事前確認

1. 00-inbox/MY-INTEGRATIONS.md を読み込む — Confluence が有効なインテグレーションに記載されている必要があります

   • Confluence が有効でない場合：ユーザーに知らせて停止します。

     Confluence は有効なインテグレーションに含まれていません。
     
     次のどちらにしますか？
     a) Confluence インテグレーションを設定する（MY-INTEGRATIONS.md に追加します）
     b) 手動アップロード用に、Confluence 対応形式でドキュメントをエクスポートする
     

   • Confluence が無効の場合：COG の規約に従い、何も知らせずにスキップします。有効な場合は、代替の公開先（HackMD、Notion）を提案してください。

2. 現在のタイムスタンプを取得する： Bash を使って date '+%Y-%m-%d %H:%M' を実行します

---

実行戦略

フェーズ 1：ソースドキュメントを特定する

公開するドキュメントを特定します。

オプション A：ユーザーがファイルパスを指定する

Read the specified file from the vault.

オプション B：ユーザーがドキュメントについて説明する

Search for matching files:
1. Glob for likely matches in 04-projects/, 05-knowledge/, 01-daily/
2. Present candidates and let user choose

オプション C：生成直後のドキュメント PRD、リリースノート、その他のドキュメントを生成した直後にこのスキルが呼び出された場合は、そのドキュメントを使用します。

フェーズ 2：公開先を設定する

まだ指定されていない場合は、ユーザーに確認します。

Where should this be published in Confluence?

Required:
- Space key: [CUSTOMIZE: YOUR-SPACE-KEY] (or let me search for spaces)
- Parent page: [Page title or ID under which to nest this page]

Optional:
- Page title: [defaults to the document's H1 heading]
- Labels: [Confluence labels to add]
- Publish mode: "create new" or "update existing"

ユーザーがスペースまたは親ページを把握していない場合：

Use WebFetch to search Confluence:
GET /wiki/rest/api/space?limit=50
- List available spaces for the user to choose

GET /wiki/rest/api/content?spaceKey=[SPACE]&type=page&limit=25
- List pages in the space for parent page selection

フェーズ 3：Markdown を Confluence 形式に変換する

Markdown ドキュメントを Confluence ストレージ形式（XHTML）に変換します。

変換ルール：

Markdown	Confluence ストレージ形式
# Heading	<h1>Heading</h1>
## Heading	<h2>Heading</h2>
**bold**	<strong>bold</strong>
*italic*	<em>italic</em>
- list item	<ul><li>list item</li></ul>
1. list item	<ol><li>list item</li></ol>
[text](url)	<a href="url">text</a>
`code`	<code>code</code>
コードブロック	<ac:structured-macro ac:name="code"><ac:plain-text-body><![CDATA[...]]></ac:plain-text-body></ac:structured-macro>
表	<table><tbody><tr><th>...</th></tr><tr><td>...</td></tr></tbody></table>
> blockquote	<blockquote><p>quote</p></blockquote>
---	<hr />
- [ ] task	<ac:task-list><ac:task><ac:task-status>incomplete</ac:task-status><ac:task-body>task</ac:task-body></ac:task></ac:task-list>
- [x] task	complete ステータスを指定した同形式
YAML フロントマター	完全に削除（Confluence には表示されません）

重要な変換上の注意：

• YAML フロントマターを削除します。Confluence ページには表示しません
• 表の構造を慎重に保持します
• 相対パスの Vault リンクはプレーンテキストに変換します（Confluence では機能しません）
• 入れ子になったリストを適切に処理します
• 絵文字はそのまま保持します

フェーズ 4：プレビューと承認のゲート

重要：ユーザーから明示的な承認を得ずに、絶対に公開しないでください。

ユーザーに概要を提示します。

Ready to publish to Confluence:

Document: [filename]
Title: [page title]
Space: [space key]
Parent Page: [parent page title]
Mode: [create new / update existing]
Labels: [labels]

Content preview (first 500 chars):
[preview text]

Estimated page size: [approximate word count]

Proceed with publishing? (yes/no)

続行する前に、明示的な「はい」の返答を待ってください。

フェーズ 5：公開

新しいページを作成する

Use WebFetch to POST to Confluence REST API:

POST [CUSTOMIZE: your-confluence-url]/wiki/rest/api/content

Headers:
  Content-Type: application/json
  Authorization: [from configured credentials]

Body:
{
  "type": "page",
  "title": "[page title]",
  "space": { "key": "[SPACE_KEY]" },
  "ancestors": [{ "id": "[PARENT_PAGE_ID]" }],
  "body": {
    "storage": {
      "value": "[converted XHTML content]",
      "representation": "storage"
    }
  },
  "metadata": {
    "labels": [
      { "prefix": "global", "name": "[label]" }
    ]
  }
}

既存のページを更新する

First, get the current page to obtain the version number:
GET [CUSTOMIZE: your-confluence-url]/wiki/rest/api/content/[PAGE_ID]?expand=version

Then update:
PUT [CUSTOMIZE: your-confluence-url]/wiki/rest/api/content/[PAGE_ID]

Body:
{
  "type": "page",
  "title": "[page title]",
  "version": { "number": [current_version + 1] },
  "body": {
    "storage": {
      "value": "[converted XHTML content]",
      "representation": "storage"
    }
  }
}

フェーズ 6：公開を確認して Vault を更新する

公開に成功した後：

1. ユーザーに確認します：

   Published successfully!
   
   Page: [Title]
   URL: [Confluence page URL]
   Space: [Space Key]
   Version: [version number]
   

2. ソース Vault ファイルを更新します（フロントマターに公開メタデータを追加）：

   confluence_url: "[page URL]"
   confluence_page_id: "[page ID]"
   confluence_space: "[space key]"
   published_at: "[timestamp]"
   confluence_version: [version number]
   

3. 今後参照できるように、公開内容を記録します。

---

再公開（更新フロー）

Vault ファイルのフロントマターに confluence_page_id がすでにある場合：

This document was previously published to Confluence:
  URL: [confluence_url]
  Last published: [published_at]

Would you like to:
a) Update the existing Confluence page (increment version)
b) Create a new page (separate copy)
c) Cancel

---

フォールバック動作

シナリオ	動作
Confluence がアクティブでない	処理を停止してユーザーに伝え、代替プラットフォームを提案します
Confluence API が失敗する	変換した XHTML をファイルに保存し、ユーザーが手動で貼り付けられるようにします
認証に失敗する	Confluence の認証情報を更新する必要がある可能性があることをユーザーに伝えます
ページがすでに存在する（タイトルが同じ）	既存ページを更新するか、別のタイトルで作成するか、キャンセルするかをユーザーに確認します
ドキュメントが非常に大きい	ページサイズについてユーザーに警告し、子ページへの分割を提案します
Markdown が複雑（未対応の要素がある）	可能な範囲で変換し、変換できなかった要素について警告します

エラー処理

• API 403（Forbidden）：ユーザーに対象スペースへの書き込み権限がない可能性があります
• API 404（Not Found）：スペースキーまたは親ページ ID が正しくない可能性があります
• API 409（Conflict）：別のユーザーがページを変更しました。最新バージョンを取得して再試行します
• 変換の失敗：変換できない要素はプレーンテキストにフォールバックします
• レート制限：バックオフして再試行します
• ネットワークエラー：変換した内容をローカルに保存し、作業が失われないようにします