paperclip-admin

Paperclip 管理

小規模な Paperclip の運用者リクエストを、最も限定的で安全なワークフローに振り分けます。

主に確認、戦略の記録、再帰的な計画、AFK 実行準備状況のトリアージ、実行状況の監視を目的としない、その場限りの Paperclip 作業には、このスキルを使用してください。リクエストがこれらのワークフローのいずれかに発展した場合は、専用スキルに切り替え、その理由を伝えてください。

参照資料

まず、次の資料を読んでください。

• references/CONTEXT.md
• references/docs/paperclip-operator/control-plane.md
• references/docs/paperclip-operator/workflow.md
• references/docs/paperclip-operator/cli-contract.md
• references/docs/paperclip-operator/integration-matrix.md

これらのプロジェクトドキュメントが見つからない場合は、まず paperclip-setup を実行して、同梱テンプレートから生成してください。

リクエストの振り分け

• エージェント、課題、承認、アクティビティ、コスト、ブロック中の作業に関する広範な読み取り専用のヘルスレポートには、paperclip-monitor を使用してください。
• 運用者が望む結果が曖昧で、コントロールプレーンの記録を変更する前に内容を明確にする必要がある場合は、paperclip-clarify を使用してください。
• 運用者が新しい Goal、Project、Parent Issue、または plan ドキュメントを求めている場合は、paperclip-record-strategy を使用してください。
• 戦略アーティファクトまたは親課題を子課題に分割する場合は、paperclip-plan-work を使用してください。
• 課題が AFK 実行の準備ができているかどうかを判断する場合は、paperclip-triage を使用してください。
• 新しい Paperclip エージェントの作成または採用には、paperclip-create-agent を使用してください。
• Paperclip の llm-wiki コンテンツの作成、更新、名前変更、アーカイブ、削除、公開、同期、またはその他の変更がリクエストされている場合は、paperclip-wiki-manage を使用してください。
• 範囲を限定した読み取り、軽微な編集、既存エージェントの管理、会社のスキルライブラリの操作、準備済みの割り当ての引き継ぎ、レビュアーゲートの微調整、予算やステータスの確認、単発の保守作業には、paperclip-admin を使用してください。

運用ループ

1. 有効な会社とプロファイルを特定します。
2. 変更を加える前に、現在の Paperclip の状態を確認します。
3. リクエストが読み取り専用か、変更を伴うものかを判断します。
4. 読み取り専用のリクエストには、関連する記録と不確実な点を直接回答します。
5. 変更を伴う場合は、提案する変更内容を正確に提示し、承認を待ちます。
6. 承認された変更のみを適用します。
7. 変更した記録を読み直し、想定したフィールドを確認します。
8. 変更内容、記録 ID、未対応の事項があれば報告します。

一般的な読み取り

読み取りに対応している場合は、JSON 出力を指定して paperclipai を優先してください。CLI の出力が不十分または利用できない場合は、MCP の読み取りを使用してください。

paperclipai context show --json
paperclipai company list --json
paperclipai agent list -C <company-id> --json
paperclipai skills list -C <company-id> --json
paperclipai issue list -C <company-id> --json
paperclipai approval list -C <company-id> --json
paperclipai activity list -C <company-id> --json

エージェント管理

新しい Paperclip エージェントの作成は paperclip-create-agent で行います。このスキルを使うのは、既存のエージェントを調査する場合、または作成済みエージェントに承認済みの軽微な変更を加える場合に限ります。

既存エージェントの変更を提案する前に、次のことを行います。

1. 既存のエージェントと会社のスキルを一覧表示します。
2. 変更対象となるエージェントの現在の役割、マネージャー、アダプター／ランタイム、予算、ハートビートポリシー、関連付けられているスキルを特定します。
3. 依頼された変更ではなく、新たなエージェントの採用が適切かどうかを確認します。
4. 参照されているスキルが会社のスキルライブラリに存在することを確認するか、先にインストールすることを提案します。
5. 提案する変更を提示し、承認を得ます。

承認後は、利用可能な手段の中から最適なものを使います。

• paperclipai：必要なエージェントコマンドが利用でき、ネイティブフィールドを検証できる場合。
• MCP：エージェントの作成／更新ツールが公開されている場合、または状況把握に MCP での読み取りが必要な場合。
• paperclipApiRequest：CLI と専用 MCP ツールで必要なネイティブフィールドを扱えない場合。
• REST API を直接使用：CLI と MCP が利用できない、または動作しない場合。
• Paperclip UI：エージェントを安全に作成または更新できる呼び出し可能な手段がない場合の最終手段。

更新後、エージェントを再度読み込み、名前、役割、マネージャー、アダプター、スキル、予算、ハートビートポリシーを検証します。

管理対象の指示バンドルを読み書きする場合は、paperclipai agent --help を確認し、利用できる場合はネイティブの instructions-bundle、instructions-bundle:update、instructions-file:get、instructions-file:put、instructions-file:delete コマンドを優先します。専用 MCP には現在、instructions-bundle ツールがありません。インストール済みの CLI に必要なコマンドがない場合に限り、paperclipApiRequest または REST API を直接使用します。

• GET /api/agents/{agentId}/instructions-bundle
• PATCH /api/agents/{agentId}/instructions-bundle
• GET /api/agents/{agentId}/instructions-bundle/file?path=AGENTS.md
• PUT /api/agents/{agentId}/instructions-bundle/file
• DELETE /api/agents/{agentId}/instructions-bundle/file?path=...

指示を書き込む前に、現在のファイルを読み込み、正確な差分または変更がないことの検証計画を提示して、承認を得ます。書き込み後は再度読み込み、内容、バイトサイズ、バンドルモード、エントリーファイル、変更したファイルパスが正確であることを検証します。承認された変更に含まれていない限り、末尾の改行を追加または削除しないよう注意してください。

軽微な変更

次のような小規模な変更が承認された場合は、このスキルを使います。

• イシューのタイトル、説明、優先度、ラベル、担当者、またはライフサイクル状態の編集
• executionPolicy.stages[].participants によるイシューレビューゲートの設定または解除
• イシューへのコメント
• エージェントへの会社のスキルの関連付けまたは解除
• 明示的な承認を得たうえでの、管理対象エージェント指示バンドルの読み取りまたは更新
• エージェントの予算、または一時停止／再開設定の調整
• 調査中に見つかった、小規模な Paperclip レコードの不整合の解消
• オペレーターが希望するイシューの内容を正確に把握している場合の、単純なイシューの作成

広範な作業を暗黙のうちに todo に変更したり、広範なイシューを割り当てたり、広範なイシューにレビューゲートを設定したり、作業をチェックアウトしたり、ハートビートを手動で実行したり、ボードゲートを承認したり、Wiki コンテンツを変更したりしないでください。変更によって作業を開始可能にする場合、または llm-wiki のコンテンツを変更する場合は、トリアージ、委任、または Wiki 管理の範囲に及ぶことを伝え、明示的に確認してください。

レビュアーゲート

オペレーターから課題のレビュアー設定を依頼された場合は、Paperclip のネイティブな課題実行ポリシーを使用します。

• type: "review" のステージに executionPolicy.stages[].participants を設定します
• レビューステージに approvalsNeeded を含めます
• レビュアーのコメントが必須の場合は、commentRequired: true を含めます
• 対象環境で UI のレビュアーフィールドに対応していることを確認できていない限り、reviewRequest は書き込みません
• 通常の実行ポリシーのレビュアーはエージェントのみにします
• 人による最終承認が必要な場合は、その要件を引き継ぎに記載し、エージェントレビュアーにべき等な request_confirmation の作成を求めます。オペレーターをユーザー承認ステージの参加者に追加しないでください

書き込み後、課題を再読み込みし、レビュアーの参加者が設定されていることを確認します。選択したレビュアーエージェントの status: "error" の場合は、割り当ては正しく行われていますが、実行時のレビューにはエージェントのエラー解消が必要になる可能性があることを伝えます。

割り当て準備プロトコル

割り当ては、受動的なフィールド編集ではなく、イベントを発生させるディスパッチとして扱います。

1. 未割り当ての状態で準備します。 issue、ブロッカー、コメント、アクティビティ、issue live-runs、issue active-run、直近のissue runs、復旧アクション、実行者の設定、プロジェクトのワークスペース、レビュー方針を確認します。オペレーターから明示的な上書きの依頼がない限り、実行者の既存またはデフォルトの環境を維持します。割り当てる前に、引き継ぎ情報を漏れなく追加または更新し、エージェントレビュアーのゲートを設定します。人間による最終承認が必要な場合は、判断基準を明記し、レビュアーにrequest_confirmationを作成させます。ユーザー承認ステージは設定しないでください。issueを読み返し、ブリーフ、ステータス、ブロッカー、アサイニーが未設定であること、ワークスペースと環境の状態、executionPolicyを確認します。issueに必要な情報がそろい、検証済みで、未割り当てであり、実行中またはキュー待ちの実行も未解決の復旧アクションもない状態になれば完了です。
2. ディスパッチは一度だけ行います。 明示的な承認を得たうえで、実行者を割り当て、必要に応じてstatus: todoを設定することを、実行を開始できる最後の変更として行います。利用可能な操作であれば、1回の更新にまとめます。割り当てが起動のトリガーです。ハートビート、再開、エージェントへのメンション、チェックアウトを行ったり、割り当てを再度変更したりしないでください。アクティビティに起動のキュー投入が記録されるか、対象の実行者による実行が開始されれば完了です。
3. 読み取り専用で観察します。 Paperclipがwake queued、キュー待ちまたは実行中の実行、あるいはworkspace readyを報告したら、処理が開始されたものとして扱います。アクティビティと実行状態の読み取りだけを行います。実行がキュー待ちまたは実行中の間は、ステータス、アサイニー、コメント、ワークスペース、環境、実行ポリシー、エージェント設定を変更しないでください。コメントは作業の注入であり、別のキュー待ちインタラクションを発生させる場合があります。
4. エージェントレビューはネイティブの経路に任せます。 実行者が証拠を記録してissueをdoneに移行します。Paperclipはこの移行をインターセプトし、issueをin_reviewに移し、executionStateを更新して、選択されたエージェントレビュアーに割り当てて起動します。レビューのルーティングを調査する場合は、executionState.currentStageTypeとcurrentParticipantを確認してください。Paperclipがレビューのディスパッチをスキップした、または失敗したと明示的に報告しない限り、レビュアーを手動で割り当てたり、メンション、再開、起動したりしないでください。
5. 人間による承認はインタラクション経由で行います。 引き継ぎで人間による最終承認が必要な場合、レビュアーは証拠、残存リスク、承認または却下した場合の影響を含む、冪等なrequest_confirmationを1つ作成して待機します。インタラクションが保留中で、確認可能な状態であることを検証してください。承認または却下を受けるとレビュアーが再開し、決定を記録して、ネイティブの承認または変更リクエストの経路を使用します。オペレーターをレビュアーまたは承認者に追加したり、正式なApprovalを作成したり、オペレーターに代わってCLIで最終処理を行ったりしないでください。
6. 静止状態になってからのみ修正します。 承認済みの重要な修正を行う場合は、一度だけ中断またはキャンセルし、すべての実行中の処理、インタラクションの再開試行、プロセス復旧、コメントの再試行、関連する復旧アクションがすべて収束するまで待ちます。その後でのみ、割り当てを解除し、issueまたは設定を修正し、修正後の状態を検証して、再度一度だけ割り当てます。中断後、すぐに割り当てを解除して再割り当てすることは決してしないでください。

厳守事項：Paperclipがwake queued、キュー待ちまたは実行中の実行、あるいはworkspace readyを報告した後は、Paperclipがディスパッチのスキップまたは失敗を明示的に報告しない限り、読み取り専用の観察に切り替えてください。

変更ルール

自由に読み取ってかまいません。Paperclip上での作成、更新、削除、割り当て、チェックアウト、承認、却下、インストール、添付を行う前に確認を求めてください。割り当てだけでディスパッチは完了します。ハートビートや再開を手動で呼び出したり、別の起動を発生させたりしないでください。起動がキューに入った後、または実行中になった後は、完了するか、明示的に承認された修正が静止状態に達するまで、読み取り専用の状態を維持してください。

破壊的な変更には、特に明示的な承認が必要です。削除、キャンセル、予算削減、認証情報またはランタイムの変更、承認の却下、エージェントの無効化または終了が該当します。