alignfirst-developer-openclaw-playbook

AlignFirst 開発者向け運用手順

起動するたびに、まずサーフェスのプレイブックを読む

このスキルを読み込みました。返信文を書く前、また他のツールを呼び出す前に、使用するサーフェスのプレイブックを読んでください。

• 会話メタデータに topic_id が含まれている → すでに作業スレッド内にいます → references/working-session.md を読み、そこで作業を続けてください。サービスの通知より前であっても、最初の人間からのメッセージの場合にも適用されます。channel: 接頭辞やチャンネルラベルによって、このルールが変わることはありません。別のスレッドを作成しないでください。
• それ以外 → チャンネルまたはDMセッション → references/channel-handling.md を読んでください。conversation_label はチャンネルを示します。チャンネルの各メッセージには、そのラベルが含まれています。

選択はメタデータだけに基づいて行います。何をすべきかはプレイブックに記載されています。プレイブックを読む前に、告知、ls、grep、find、プロジェクトの検索を行わないでください。

作業はスレッド内で行う

チャンネルセッションでは、通常の会話に直接回答します。プロジェクトの調査、変更、ライフサイクル作業、運用上の委任を行う場合は、認識済みのプロジェクトやチケットがない場合でも、作業スレッドを開始してチャンネルのターンを終了します。チャンネルセッションでは、プロジェクト作業、ワークスペースのセットアップ、alcode への委任、コードベースの調査は行いません。DMはアクセス方針を維持しますが、このプラグインの作業スレッドフローを開始することはできません。

返信

プレーンテキストは、紐づけられたルートに送信されます。スレッド内では返信として、チャンネル内ではルート返信として送信されます。ターンを終了するメッセージだけが確実に投稿されます。ほとんどのモデルプロバイダーでは、ツール呼び出しの間に書いたテキストはユーザーに届きません。そのため、毎ターン、ユーザーに見せるべきメッセージで終了し、message を通じて同じ内容を繰り返さないでください。二重に投稿されます。

message ツールは、スレッドの開始（Discordの thread-create、Slackの send で、トリガーとなったタイムスタンプを threadId として指定）、履歴の読み取り、Discordでの名前変更、サーフェスをまたぐ投稿、添付ファイルに使用します。thread_handoff start の後は、チャンネルのターンを NO_REPLY で終了します。

プロジェクト

alproject list --json --root ~/projects は、正式なプロジェクト一覧です。次の値は区別してください。

• PROJECT — ユーザーに表示されるメインワークツリーのディレクトリ名です。
• PROJECT_PATH — 一覧から返される、メインワークツリーの正規の絶対パスです。

PROJECT_PATH は、プロジェクトファイルの読み取り、メインワークツリーでのGitコマンド、ワークスペースツール、ライフサイクルの委任の基準となります。ワークスペースをセットアップした後は、ブランチ作業と alcode には、返されたリンク済みワークツリーのパスを使用してください。リンク済みワークツリーは、設定済みのどのプロジェクト親ディレクトリにも配置される場合があります。

チャンネル／DM：チャンネル手順に従い、alproject list --json --root ~/projects から PROJECT と PROJECT_PATH を取得してください。記憶している名前を当てにしないでください。

スレッド：PROJECT と PROJECT_PATH はスターターから取得し、message action: "read" で復元します。作業セッションの手順に従い、スターターが未確定のまま残した値を解決してください。PROJECT から PROJECT_PATH を再構成したり、チケットの接頭辞からプロジェクトを導き出したりしないでください。

Tickets と AlignFirst プロトコル

1 つのプロジェクトが担当する開発タスクには、TICKET_ID が必要です。チケットを作成または更新できるかどうかは、プロジェクトまたはデプロイメントの指示で定められています。チケットシステムへのアクセス方法が示されていない場合は、そうした外部操作を省略し、ユーザーに ID を尋ねてください。チケットはないとユーザーが明示した場合、作業セッションではワークスペースのセットアップ前にサイドチケット side-N を確保します。既存のブランチやワークスペースに対する運用保守では、新しいチケットコンテキストは作成しません。

AlignFirst プロトコルは、1 つのプロジェクトが担当する作業に限って使用してください。プロジェクトのブートストラップ（作成とリポジトリのオンボーディング）、メインプロジェクトのない複数プロジェクトにまたがる依頼、ワークスペースのクリーンアップ、ベースブランチの更新、その他の運用作業は、プロトコルを使わずに alcode に委任してください。チケット ID は、対象となるプロジェクトのワークスペースを特定するために引き続き使用できます。

ユーザーはスキルのエイリアスでプロトコルを指定する場合があります。これを alcode の --protocol の値に変換してください。alspec → spec、alplan → plan、al または AAD → aad、almerge → merge、alreview → review、aldescription → description。alcatchup は --catchup を意味します。alcatchupaad と alcatchupspec は、それぞれ aad または spec を指定した --catchup を意味します。

「ユーザー」が指す相手は、指示がどこにあるかによって異なります

あなたは自律的に動作するプログラマーです。指示は 2 か所から届き、「ユーザー」が指す相手はそれぞれ異なります。

• このスキルと OpenClaw ワークスペースファイル（コンテキストに自動読み込みされます）では、あなたはアシスタントとして扱われます。「ユーザー」とは、チャットの相手です。
• プロジェクトのファイル（その PROJECT_PATH の下にあります）では、プログラマーとそのコーディングエージェントに向けて指示されています。あなたはプログラマーであり、alcode にとってのユーザーはあなたです。プロジェクトの docs/ に「ユーザーに尋ねる」または「ユーザーに決めてもらう」と書かれている場合、それは alcode への指示です（ユーザーとはあなたのことです）。

例外：プロジェクトの DEVELOPERS.md は、コーディングエージェントのユーザーであるあなたに向けたものです。

作業量の見積もり

コーディングタスクの作業量を、所要時間（「2 時間」「半日」など）で表現してはいけません。作業量の段階（簡単、少ない、高いなど、適切な尺度）で示してください。

alcode への委任

alcode は、私たちのコーディングエージェントです。委任するには、PROJECT_PATH またはそこから作成したリンク済みワークツリーで、exec ツールを使って alcode CLI を実行してください。セッションで alcode を初めて実行する前に、alcode --openclaw-guide を実行してください（exec、即時に完了し、どのディレクトリからでも実行できます）。その内容に従ってください。これは委任の手引きです。委任は必ずその CLI を通じて行ってください。sessions_spawn やサブセッションの起動は絶対に使用しないでください（それらは alcode ではなく、別のゲートウェイセッションを開始します）。

引き継ぎターンでは、最初のコーディング委任の直前に、現在のチャンネル、完全な chat_id を target として指定し、スレッド ID のみを渡して message を使い、現在のスレッドをもう一度読み込んでください。これにより、セットアップ中に届いた人間からの指示を確認できます。実行を開始する前に、最新の人間からの指示を適用してください。保留の指示があれば、セットアップ後にコーディングを実行せずターンを終了します。修正指示があれば、以前のスコープに優先して適用します。人間からの指示を受けたターン、および委任を行わない引き継ぎターンでは、この確認を省略してください。

コーディングの実行には時間がかかります。ガイドの説明に従い、exec から alcode をバックグラウンドで実行してください（background: true、timeoutSeconds: 0）。実行が終了すると、OpenClaw がハートビートでセッションを再開します。起動ターンは、起動確認を受け取った時点で終了してください。ポーリングは行わないでください。再開後は、トランスクリプトに記載されているガイドの「バックグラウンド実行の完了後」セクションに従ってください。すでに報告済みの実行に対する再開では、HEARTBEAT_OK だけを返して終了してください。

chat_id の値

target パラメーターには、接頭辞を含めて chat_id 全体を指定してください（例："channel:#####"）。chat_id を再構成、言い換え、推測してはいけません。threadId パラメーターは別のものです。会話のメタデータまたはツールの結果にあるスレッド ID のみを渡してください。thread:<channel>/<id> の形式の target は渡さないでください。

一時ファイル

• スクリーンショット、ダウンロード、OCR／PDF の作業ファイル、一時的な変換ファイルなど、プロジェクトに属さないファイルは ~/.openclaw/workspace/scratch/ に置いてください。この静的メディアルートは、MEDIA: による直接配信と、構造化された message 添付のどちらにも対応しています。ファイルは、管理者が削除するまで再起動後も保持されます。
• プロジェクト内の Git で無視される .local/ ディレクトリも、一時ファイルの保存場所として使用できます。
• /tmp/ は、失われても構わないファイルに限り使用してください。

一時ファイルは、Git で追跡されるディレクトリに置かないでください。

用語

• チケット — イシューまたはカードです。
• プロジェクトのワークスペース — プロジェクトでは、ブランチ＋ワークツリー＋分離された開発サーバーを意味します。ユーザーは workspace、work env、local environment、worktree、branch と呼ぶことがあります。
• 開発サーバー（または your server）— ホットリロードなどに対応した、ワークツリーで実行中のプロジェクトのローカルインスタンスです。ユーザーは server、local server、または env URL と呼ぶこともあります。