swt workflow

swt は Superset workspace で GitHub Issue/PR 起点の作業を始めるための CLI です。このページは日常的な workflow として使う swt issue、swt pr、swt task template、swt task run、swt clean を扱います。

Superset workspace の transport、MCP/CDP、Codex App worktree 同期、record cleanup、archived cleanup は Superset/Codex 連携 に分けます。

このページの範囲

  • GitHub Issue/PR から worktree を作成する入力形式と branch 名生成
  • --agent、--danger、--base、--pr によるタスクファイルとエージェント起動
  • .superset/task-prompt-template.md の探索順、プレースホルダー、PR 作成戦略
  • .superset/task-{slug}.md から作業を再開する swt task run
  • Superset から消えたが disk に残った worktree を掃除する swt clean

扱わないもの:

  • swt codex sync-* / unlink-workspace / cleanup-archived-workspaces の詳細
  • Superset v2/MCP/CDP の mode/transport と手動検証
  • 汎用 git worktree wrapper としての gwt

README 代表導線

README に残す候補 リンク先 理由
swt issue 123 #github-issue-から-worktree-を作成する Issue 起点の主要 workflow を示すため。
swt pr 456 #github-pr-から-worktree-を作成する PR 起点の主要 workflow を示すため。
swt issue 123 --agent --pr draft #pr-作成戦略 worktree 作成からエージェント起動、Draft PR 指示までの代表例になるため。
swt task run #タスクファイルからエージェントを起動する 作成済みタスクから作業再開できることを示すため。
swt clean --list #孤立-worktree-をクリーンアップする 破壊的操作の前に確認する導線として残すため。

前提条件

swt は Superset sh / Mac 前提の workflow 用 CLI です。Windows で汎用の git worktree wrapper だけが必要な場合は、swt ではなく gwt の install 手順 を使ってください。

swt issue と swt pr は GitHub CLI を使います。事前に gh をインストールし、対象 repository を読める account で認証してください。

gh auth status

引数なしで Issue/PR や task を選ぶ場合は fzf を使います。fzf がなくても、Issue 番号、PR 番号、task slug を直接指定すれば利用できます。

swt issue 123
swt pr 456
swt task run 123-fix-login

--agent や swt task run を使う場合は、起動したい AI エージェント CLI が必要です。現在の swt は claude、codex、gemini、opencode、pi、copilot、cursor-agent を agent 名として扱えます。

日本語など ASCII 以外を含む Issue title から branch 名を作る場合、swt issue は codex、copilot、claude の順に英訳を試します。翻訳対象の Issue title は外部入力のため、Codex はローカルツール系 feature を無効化して起動します。いずれも使えない場合や翻訳に失敗した場合でも worktree 作成は継続し、title 情報が落ちる場合は警告を出します。

GitHub Issue から worktree を作成する

swt issue は GitHub Issue を取得し、Issue 番号と title から branch 名を作って worktree を作成します。

swt issue              # fzf で Issue を選ぶ
swt issue 123          # Issue 番号を直接指定
swt issue '#123'       # #付き番号を指定
swt issue https://github.com/org/repo/issues/123
swt issue 123 --path /path/to/worktree
swt issue 123 --base develop

Issue の入力形式は番号、# 付き番号、GitHub Issue URL です。URL を指定した場合、現在の repository と違う owner/repo の URL は拒否します。

branch 名は {issue番号}-{title由来のslug} です。title が ASCII 以外を含む場合は、英訳した title から slug を作ります。翻訳に失敗して slug 化できない場合は、番号だけの branch 名になることがあります。

--base は新規 branch の起点です。swt issue のデフォルトは main です。

swt issue 123 --base release/1.2

worktree 作成後は .superset/task-{slug}.md を生成し、Issue 本文、PR 作成戦略、base branch を task に埋め込みます。Superset workspace 登録の transport と fallback は Superset/Codex 連携 を参照してください。

GitHub PR から worktree を作成する

swt pr は GitHub PR を取得し、PR の head branch を作業用 branch として worktree を作成します。

swt pr              # fzf で PR を選ぶ
swt pr 456          # PR 番号を直接指定
swt pr '#456'       # #付き番号を指定
swt pr https://github.com/org/repo/pull/456
swt pr 456 --path /path/to/worktree
swt pr 456 --base develop

PR の入力形式は番号、# 付き番号、GitHub PR URL です。URL を指定した場合、現在の repository と違う owner/repo の URL は拒否します。

同一 repository の PR は headRefName を branch 名として使います。fork PR は衝突を避けるため、PR 番号を prefix した branch 名を使います。

PR の head ref は fetch され、ローカル branch がなければ作成されます。すでにローカル branch がある場合は、未pushコミットがなければ PR の開始点に同期します。未pushコミットがある場合は、ローカル作業を保護するためエラーになります。

swt pr の --base は git worktree add の起点ではなく、task ファイルに書き込む Base Branch の値です。省略時は GitHub PR の baseRefName を引き継ぎます。PR から追加作業をして新しい PR を作る場合でも、元 PR の base branch が task に残ります。

branch 名と base branch

コマンド branch 名 base branch の扱い
swt issue Issue 番号 + title slug --base の値。省略時は main。
swt pr PR head branch。fork PR は PR 番号 prefix 付き --base の値を task に記録。省略時は PR の baseRefName。

この表は swt が作る local branch / task の branch 名を示します。Superset workspace 作成を MCP 経由にした場合、Superset 側の branch prefix 設定が workspace 表示や作成結果に反映されることがあります。transport ごとの違いは Superset/Codex 連携 を参照してください。

swt issue / swt pr の fzf 候補では、すでに local の git worktree として存在する branch に対応する Issue/PR を除外します。同じ branch を再度選んで git worktree add が失敗するケースを避けるためです。

タスクファイルとテンプレート

worktree 作成後、swt は .superset/task-{slug}.md を生成します。task ファイルは作業内容の再開と agent 起動に使います。

テンプレートは次の順で探索します。

  1. 新しい worktree の .superset/task-prompt-template.md
  2. swt 実行元 repository の .superset/task-prompt-template.md
  3. ~/.superset/task-prompt-template.md
  4. 組み込みデフォルトテンプレート

実行元 repository も見るため、まだ commit していない project local template でも新しい worktree に反映できます。ファイルが存在しない場合だけ次の候補へ進み、権限不足など読み込み error はそのまま失敗として扱います。

組み込みテンプレートを元にする場合は、次のコマンドで出力します。

swt task template > .superset/task-prompt-template.md

テンプレートでは次の placeholder を使えます。

Placeholder 内容
{{id}} Issue/PR 番号
{{slug}} task ファイル名に使う slug
{{title}} Issue/PR title
{{description}} Issue/PR body
{{priority}} task priority
{{statusName}} task status
{{labels}} label 一覧
{{prStrategy}} draft、create、none の PR 作成戦略
{{baseBranch}} PR 作成時に使う base branch

古い custom template に {{prStrategy}} がない場合でも、render 時に末尾へ PR Strategy: <value> を追加します。既存 template をすぐ直せない場合でも、agent が PR 作成方針を読めるようにするためです。

タスクファイルからエージェントを起動する

swt task run は現在の git worktree root を解決し、.superset/task-{slug}.md を読み込んで AI エージェントを起動します。

swt task run                    # 複数 task があれば fzf で選ぶ
swt task run 123-fix-login      # slug を直接指定
swt task run --agent claude
swt task run 123-fix-login --agent gemini

slug を省略した場合、.superset/task-*.md を探します。1 件だけならその task を直接使い、複数あれば fzf で選びます。slug に /、\、.. が含まれる場合は拒否します。

--agent を省略した場合は codex を起動します。指定した agent の実行ファイルが PATH にない場合は、起動前に error になります。

エージェント起動と danger mode

swt issue / swt pr に --agent を付けると、worktree 作成と task ファイル生成の後に agent を起動します。

swt issue 123 --agent           # claude を起動
swt issue 123 --agent=codex     # codex を起動
swt pr 456 --agent              # PR task でも同じ

swt issue / swt pr で --agent を値なしで指定した場合は claude です。swt task run で --agent を省略した場合は codex です。--danger または SWT_DANGER_MODE=1 を指定すると、agent 定義に登録された権限バイパス系の flag を付けます。

swt issue 123 --agent --danger
swt task run --danger
SWT_DANGER_MODE=1 swt task run

swt issue / swt pr では、--danger は --agent と組み合わせたときだけ意味があります。agent を起動しない場合、--danger は警告付きで無視されます。swt task run は常に agent を起動するため、--agent を省略しても --danger は有効です。agent が danger flag を持たない場合、swt は警告を出して通常起動します。

PR 作成戦略

--pr は task ファイルへ書き込む PR 作成戦略です。swt 自体がその場で PR を作るのではなく、task を読んだ agent が作業完了後に方針として使います。

値 意味
draft branch を push し、Draft PR を作る
create branch を push し、通常 PR を作る
none PR を作らない

swt issue のデフォルトは draft です。新しい Issue 起点の作業では PR 作成まで進むことが多いためです。

swt pr のデフォルトは none です。既存 PR の branch で作業するため、新しい PR 作成は通常不要です。

swt issue 123 --agent --pr draft
swt issue 123 --agent --pr create
swt issue 123 --agent --pr none
swt pr 456 --agent --pr none
swt pr 456 --agent --pr draft

Base Branch が task に入っている場合、組み込みテンプレートは agent に gh pr create --base <branch> を付けるよう指示します。

孤立 worktree をクリーンアップする

swt clean は Superset から削除されたが disk に残っている worktree を検出し、必要に応じて削除します。Superset 管理の worktree directory 配下だけを対象にし、Superset DB の worktree record に存在しない git worktree を孤立とみなします。

swt clean --list
swt clean
swt clean --delete-branch
swt clean --force

まず --list で削除候補を確認してください。

Flag 動作
--list, -l 削除せず、孤立 worktree の一覧だけを表示する
--delete-branch, -d worktree 削除に加えて local branch も削除する
--force, -f 未コミット変更があっても強制削除する

swt clean は Codex App 管理 worktree の旧 alias symlink を掃除対象から外します。Codex worktree の record cleanup や stale alias cleanup は Superset/Codex 連携 の swt codex unlink-workspace / swt codex prune-links を使ってください。

fzf と候補選択

swt issue、swt pr、swt task run は引数を省略した場合に fzf を使います。

swt issue
swt pr
swt task run

Issue/PR の fzf は GitHub から最大 200 件の候補を取得し、その取得済み候補をローカルで絞り込みます。GitHub へ検索 query を送り直す挙動ではありません。

fzf がない環境では、番号、URL、slug を直接指定してください。

このページは生成物です。原本は元リポジトリ側にあります。