squad

共有コンテキスト：プロジェクトの設定と認証、パイプラインのレベル、ステータス遷移、API エンドポイント、エラー処理、エージェントのコンテキストフローについては、shared.md を読んでください。 安全性の原則：principles.md を読んでください — 必須です。任意ではありません。

コマンド

/squad または /squad list — ボードを表示

BOARD=$(api GET /board?summary=true)

出力：ID、ステータス、優先度、タイトルを含む Markdown テーブル。

エピック：ボードの応答には epics 集計データ（それぞれに children_progress と導出された epic_status を含む）が含まれます。この集計データと埋め込みの parent／children 関係を使って、子タスクを各エピックの下にグループ化してください。タグの解析からグループ化してはいけません（shared.md → タスクの関係とエピックを参照）。各エピックの children_progress（例：2/5 done）を表示してください。

/squad context — セッションの引き継ぎ

新しいセッションの開始時に、最初に実行してください。 ボードを取得し、パイプラインの状態を出力します： 実装中／計画レビュー／実装レビュー／テスト中／最近完了／次のタスク

BOARD=$(api GET /board?summary=true)

/squad add <title> — タスクを追加

1. ユーザーに優先度、レベル（L1/L2/L3）、説明、タグを尋ねます（AskUserQuestion を使用）
2. jq で安全に JSON を構築し（shared.md → JSON の安全性を参照）、API に POST して新しいタスク ID を取得します。 tags は必ず JSON 配列にしてください — これはボードが表示する標準の保存形式です。ユーザーの カンマ区切りの入力を配列に分割します。例：--arg tags "$TAGS" を指定し、jq の本文で tags: ($tags | split(",") | map(gsub("^ +| +$";""))) とします（タグがない場合はフィールドを省略するか、[] を渡してください。"" は使用しないでください）。
3. 画像：ユーザーが画像のファイルパスを指定した場合（例：/squad add "Login bug" --image ./bug.png、または「./shot.png を添付」）、添付 API を使って、それぞれ新しいタスクにアップロードします（shared.md →「画像の添付ファイルをアップロード」を参照）。タスク ID と、返された添付ファイルの url を出力します。画像が貼り付けられていてパスがない場合は、まずファイルに保存するようユーザーに依頼してください（アップロード時にローカルファイルを読み取ります）。

/squad move <ID> <status> — タスクを移動

必ず shared.md → Move Protocol の順序に従ってください。 ステップ 1（現在のステータスとレベルを確認）→ ステップ 2（マトリクスを確認）→ ステップ 3（移動を実行）。 400 が返された場合：応答の .allowed[0] を使って一度だけ自己修正し、2 回失敗したらユーザーに知らせてください。

/squad edit <ID> — タスクを編集

変更するフィールドをユーザーに尋ねてから、API 経由で PATCH します。既存のタスクに画像を添付するには、添付 API を使ってローカル画像ファイルをアップロードします（shared.md →「画像の添付ファイルをアップロード」を参照）。

/squad complete <ID> [note] — タスクを完了（管理上の完了）

終端以外のステータスからタスクを完了にします。これは対話を必要としません — AskUserQuestion も確認プロンプトも不要です。完了は履歴を保持し、取り消し可能なので、そのまま実行してください。

NOTE="$*"   # everything after the ID; may be empty
# omit/empty note → send {} ; otherwise send {"completion_note": "<note>"}
if [ -n "$NOTE" ]; then
  api POST /task/$ID/complete --json "$(jq -n --arg n "$NOTE" '{completion_note:$n}')"
else
  api POST /task/$ID/complete --json '{}'
fi
# → {"success":true,"status":"done","version":<int>}

Complete は /squad cancel と対になる機能です。complete は完了、cancel は実施しないことを意味します。どちらも履歴を保持し（計画、メモ、コメント、件数、結果を保持）、/squad reopen で取り消し可能です。取り消し不能な /squad remove（完全な DELETE）とは異なります。すでに完了済みのタスクを再度完了しても安全な no-op です。対象がキャンセル済みの場合は 409 が返されます — 先に再オープンしてください。カードには completed_via:"admin"（ゲート付きパイプラインの finalize の場合は "pipeline"）と、省略可能な completion_note が記録されます。

/squad cancel <ID> [reason] — タスクをキャンセル（作業を放棄する際の推奨動詞）

どのステータスからでもタスクをキャンセルできます。これは対話を必要としません — AskUserQuestion も確認プロンプトも不要です。キャンセルは履歴を保持し、取り消し可能なので、そのまま実行してください。

REASON="$*"   # everything after the ID; may be empty
# omit/empty reason → send {} ; otherwise send {"cancel_reason": "<reason>"}
if [ -n "$REASON" ]; then
  api POST /task/$ID/cancel --json "$(jq -n --arg r "$REASON" '{cancel_reason:$r}')"
else
  api POST /task/$ID/cancel --json '{}'
fi
# → {"success":true,"status":"cancelled","version":<int>}

作業を放棄する場合は、推奨される方法としてキャンセルを使用してください。キャンセルは履歴を保持し（計画、メモ、コメント、件数、結果を保持）、/squad reopen で取り消し可能です。すでにキャンセル済みのタスクを再度キャンセルしても安全な no-op です。実施しない作業、不要になった作業、優先度が下がった作業には、/squad remove の代わりに使用してください。

/squad reopen <ID> — タスクを再開（キャンセル解除／完了解除のパス）

終端状態のタスク（cancelled または done）を todo に戻します。キャンセル解除と 完了解除の両方に使うパスです。再開するとライフサイクルのタイムスタンプ、current_agent、cancel_reason、 completion_note、completed_via がクリアされ、これまでの作業は保持されます。

api POST /task/$ID/reopen --json '{"reason": "<why reopening>"}'
# → {"success":true,"status":"todo","version":<int>}

終端状態ではないタスク（cancelled／done 以外）を再開しようとすると 409 が返され、何も変更されません。

/squad remove <ID> — タスクを削除

api DELETE /task/$ID

remove は完全な DELETE であり、取り消せません（カードとその添付ファイルは削除されます）。一度も着手していない誤りや重複に限って使用してください。対応しない作業や、別の作業に置き換えられた作業には、/squad cancel を推奨します（履歴が保持され、元に戻せます）。

/squad stats — 統計情報

カラムごとの件数はボードのサマリーから取得します。アクターごとのトークン数／イベント数は、1 回の GET /api/activity/stats 呼び出しから取得します（サーバー側で GROUP BY actor を実行し、タスクごとのループやトークン取得のためのボード呼び出しは行いません）。

export BOARD=$(api GET /board?summary=true)
export STATS=$(api GET /activity/stats)
python3 << 'PY'
import json, os

board = json.loads(os.environ['BOARD'])
stats = json.loads(os.environ['STATS'])
columns = ['todo', 'plan', 'plan_review', 'impl', 'impl_review', 'test', 'done', 'cancelled']

# Column counts (summary is keyed by status, each an array of cards)
counts = {col: len(board.get(col, [])) for col in columns}
counts['total'] = sum(counts.values())
print("## Column Counts\n")
print("| Status | Count |")
print("|--------|-------|")
for col in columns:
    print(f"| {col} | {counts[col]} |")
print(f"| **total** | **{counts['total']}** |")

# Per-actor token/event stats — tolerant reader: pull only the fields we use,
# treat a null/missing per-actor `tokens` as unknown (render —, never coerce to 0,
# never do arithmetic over a null), and ignore any unknown/extra fields the server adds.
rows = stats.get('stats', [])
totals = stats.get('totals', {})
print("\n## Agent Token Usage\n")
if not rows:
    print("No token data")
else:
    print("| Actor | Events | Tokens | Coverage |")
    print("|-------|--------|--------|----------|")
    for r in sorted(rows, key=lambda r: r.get('actor', '')):
        events = r.get('events', 0)
        tok = r.get('tokens')
        reported = r.get('reported')
        tok_cell = "—" if tok is None else f"{tok:,}"
        if reported is None:
            cov_cell = "—"
        elif reported < events:
            cov_cell = f"{reported}/{events} (partial)"
        else:
            cov_cell = f"{reported}/{events}"
        print(f"| {r.get('actor', 'unknown')} | {events} | {tok_cell} | {cov_cell} |")
    tot_tok = totals.get('tokens')
    tot_tok_cell = "—" if tot_tok is None else f"{tot_tok:,}"
    print(f"| **Total** | **{totals.get('events', 0)}** | **{tot_tok_cell}** | |")
PY

/squad project — 現在のプロジェクトコンテキスト（AI コンテキストの読み込み）

projects テーブルから現在のプロジェクトのコンテキストを取得します。セッションの開始時に使用すると、プロジェクトの目的、技術スタック、概要、関連情報、タスク数を 1 回の呼び出しで読み込めます。

PROJECT_DATA=$(api GET /projects/$PROJECT)

出力：次の情報を含む、フォーマット済みのプロジェクトコンテキストです。

• 目的（このプロジェクトが存在する理由）
• 技術スタック（使用するテクノロジー）
• 概要（現在の状況、方向性、最近の決定事項をまとめたもの）
• カテゴリとステータス
• ステータス別のタスク数
• 関連プロジェクトへのリンク

プロジェクトが登録されていない場合は、/squad-init を実行して登録するよう提案します。

/squad project all — プロジェクト全体のマップ

すべてのプロジェクトをカテゴリ別にまとめて取得します。プロジェクト全体の状況を把握するのに役立ちます。

ALL_PROJECTS=$(api GET /projects)

出力：プロジェクトをカテゴリ（例：個人、ツール、スキル）ごとにまとめ、名前と目的を表示します。

/squad project brief — プロジェクト概要の表示／更新

概要は、エージェントが少ないトークン数で利用できる、圧縮されたコンテキストの要約（200～500 文字）です。

現在の概要を表示：

api GET /projects/$PROJECT | jq -r '.brief // "No brief set"'

概要を直接設定：

api PATCH /projects/$PROJECT --json '{"brief": "..."}'

AI 支援による更新（/squad project brief update）：

1. 現在のプロジェクト情報と最近完了したタスクを取得します（GET /api/board?project=$PROJECT&summary=true）
2. 現在の状況、最近の完了事項、進行中の方向性を分析します
3. 現在あるもの、今後の方向性、最近の重要な決定事項を含む簡潔な概要（200～500 文字）を作成します
4. ユーザーに提示して確認を得た後、PATCH で保存します

/squad project update <field> <value> — プロジェクトのメタデータを編集

PATCH を使って、任意のプロジェクトフィールドを更新します。

# Update purpose
api PATCH /projects/$PROJECT --json '{"purpose": "new purpose"}'

# Archive project
api PATCH /projects/$PROJECT --json '{"status": "archived"}'

対応フィールド：name、purpose、stack、brief、status、category、repo_url。

/squad project link — プロジェクト間の関連を管理

# Add relationship
api POST /projects/$PROJECT/links --json '{"target_id": "other-project", "relation": "depends_on"}'

# Remove relationship
api DELETE /projects/$PROJECT/links --json '{"target_id": "other-project", "relation": "depends_on"}'

関連タイプ：extends、serves、depends_on、shares_data。

/squad observe status|dry-run — 観察への同意（読み取り専用）

観察への同意のゲートを確認します。読み取り専用です。同意／拒否の操作はウェブアプリ（Settings → Observation & Consent）で行います。このスキルが同意を付与または取り消すことはありません。shared.md → Observation & Consent を参照してください。

observe() { python3 ../squad/scripts/observe.py "$@"; }

# status — effective on/off, the source that decided it (env override / server
# consent / default), the policy_version on record, and the web-app manage pointer.
observe status            # human-readable;  add --json for the decision object

# dry-run — print the ABSTRACTED user_steering payload that WOULD be recorded to
# stdout (pipeable to jq) + a `# DRY RUN` banner to stderr. Writes/sends NOTHING,
# in any consent state — inspect before opting in.
observe dry-run | jq .

ここには grant／withdraw はありません。ウェブアプリで同意または拒否を設定してください。

セットアップとウェブボード

まず /squad-init を実行して、このプロジェクトを登録します。リポジトリのルートに .squadrc（SQUAD_PROJECT=… と、任意の組織セレクター SQUAD_ORG=<label>）が作成され、チーム全体のエージェントが同じボードプロジェクトを対象にするよう、コミットされます。トークンをプロジェクトファイルに保存することはありません。トークンは Personal Access Token として、環境変数 SQUAD_AUTH_TOKEN、次に ~/.squad/auth の値のみの SQUAD_AUTH_TOKEN= の順で解決されます（shared.md を参照）。

デプロイ済みのボードを https://squad.steloit.com/?project=<PROJECT>（または設定済みの SQUAD_BASE_URL）で開きます。 機能：7 カラムのパイプライン、ドラッグ＆ドロップ（有効な遷移のみ）、カードのライフサイクルモーダル、エージェントログビューアー、10 秒ごとの自動更新。