wf-next

前後工程

• 前工程: /wf-new, /wf-new
• 後工程: /analytics, /analytics --flop
• 委譲先: /music --master, /music --generate, /video --generate, /video --describe, /publish --playlist, /publish --upload

成果物

• 書き込む: collections/<id>/workflow-state.json, collections/<id>/20-documentation/upload_tracking.json

動画説明 JSON+HTML pair の書き込みは /video --describe owner へ委譲する。

• 読み込む: collections/<id>/workflow-state.json, collections/<id>/01-master/*, collections/<id>/10-assets/*, config/channel/workflow.json

Overview

既存コレクションを次工程へ進めるオーケストレーター。完了済みの素材を自動検出し、未完了のステップから再開する。 /wf-new --auto から固定 collection を委譲された場合も本スキルが state 更新の単一責務を持つ。統合 runner の allow_external_publish = false 制約ではローカル動画・metadata 生成まで進め、YouTube 書き込み直前で停止する。対話 gate の承認後は同じ run へ結果を返し、resolver が実成果物を再評価する。

Hard Gates: subagent 委譲境界

1. メインエージェントだけが owner CLI 経由で workflow-state.json の assets と制御面の phase / stage / upload / updated_at を更新する。subagent は委譲先 skill の入力確認に必要な場合だけ state を読み、書き込まない。
2. AskUserQuestion、skip_*_approval の承認ゲート、候補選択、playlist 初期化などの承認はメインエージェントが完了させる。未承認の操作を subagent へ委譲しない。
3. 状態判定で選んだ一段（後述の公開フローを含む）を進め、その中の生成・変換処理は原則として Agent ツールで一作業ずつ subagent へ委譲する。唯一の並列例外は公開フローの「並列 A」で、動画生成と説明文生成の2 Agentだけを同時起動できる。別の段・collectionや他の作業へ並列許可を広げない。委譲プロンプトには入力パス、実行する skill / CLI、期待成果物、state 書き込み禁止、完了報告形式を明記する。
4. subagent 終了後（並列 A は両 Agent の終了後）、メインエージェントが期待成果物の存在と現在の phase / assets との整合を実ファイルで検証する。すべて PASS の場合だけ state を更新する。失敗、欠落、不整合時は state を変更せず、同じステップから再実行できる状態で停止する。

委譲プロンプトには上記 3 の要素を具体値で埋め、成果物は絶対パスで受け取る。subagent の status: success だけを更新根拠にせず、実ファイルで検証する。

workflow-state 制御面の更新境界

対象 collection を確定したら、その絶対 path を COLLECTION_DIR として固定する。メインも制御面キー (phase / stage / upload / updated_at) を Edit / Write で直接変更しない。必要な更新は次の owner CLI だけを使い、各更新と同じ owner lock 内で updated_at も更新させる。CLI が非 0 の場合は state を再編集せず、同じ工程から再開できる状態で停止する。

uv run yt-workflow-state --collection "$COLLECTION_DIR" set-phase <planning|prepared|mastered|publishing|complete>
uv run yt-workflow-state --collection "$COLLECTION_DIR" set-stage <planning|live>
uv run yt-workflow-state --collection "$COLLECTION_DIR" set-upload --video-id <video-id> [--video-url <url>] [--publish-at <timestamp>]
uv run yt-workflow-state --collection "$COLLECTION_DIR" touch

資産系キー (assets.* / planning.*) も直接変更せず、set-asset / set-planning を使う。yt-upload-collection / yt-upload-auto や owner reference script が state を更新済みの場合は、同じ変更を CLI で重ねない。

このセッションで初めて /wf-* を呼ぶ場合は、先に docs/workflow-cheatsheet.md の判定フローを 1 回だけユーザーに提示すること。

When to Use

状況	使う？
制作中コレクションがあり、次工程へ進める意思がある	✅ 使う
制作中コレクションがそもそも無い	❌ /wf-new を使う（企画候補が未確定でも同じ入口）
「進んでる？」と読み取りだけ求められた	❌ /wf-status を使う
公開済み動画の振り返り	❌ /analytics --analyze または /analytics --flop

/wf-next は workflow-state.json::phase を読み取り、対応する次工程を 1 段だけ実行して assets / phase を更新する。冪等性あり：途中エラーで停止しても、再実行で未完了ステップから再開する。ユーザーが workflow-state.json を手で編集すると冪等性の前提が崩れる（扱い基準）。

前提

config/channel/ が存在すること（load_config() でロード可能）。

存在しない場合、ユーザーに確認:

• 新規チャンネル → /setup --channel を案内
• 既存チャンネル（YouTube で既に運営中）→ /setup --import を案内

承認ゲート（config 駆動）

config/channel/workflow.json の workflow.wf_next で、フェーズ進行前に承認を取るかをチャンネルごとに宣言できる。boolean は skip_manual_mastering と同じく true = 手動工程（承認）を省いて自動進行 の向きに統一されている（#1744）。SKILL.md 本体を書き換える運用は不要（yt-skills sync の衝突を避けるためにも本ファイルは編集しない）。

{
  "workflow": {
    "wf_next": {
      "skip_audio_approval": true,
      "skip_upload_approval": true,
      "skip_manual_mastering": false
    }
  }
}

• skip_audio_approval (default true): false にすると prepared フェーズ 2-B（音源承認ゲート）で、最終マスター候補を検出した時点で承認を取る
• skip_upload_approval (default true): false にすると mastered フェーズ 3-B（アップロード承認ゲート）で、/publish --upload 実行直前に承認を取る
• 既定値は両方 true で、workflow.json に何も書かれていない既存チャンネルは従来通り全自動進行（後方互換）
• 旧キー approval_gates.audio / approval_gates.upload は廃止済みで、設定に残っている場合は ConfigError で停止する。skip_audio_approval / skip_upload_approval へ移行する
• 値の解決は youtube_automation.configuration.load_config().workflow.wf_next 経由（skip_audio_approval / skip_upload_approval / skip_manual_mastering。コード側で参照可能）

skip_*_approval = false のゲートに到達したら、本 skill は AskUserQuestion で承認を取り、却下されたらフロー停止 + ガイダンスのみで終了する。

raw master 直採用（skip_manual_mastering）

workflow.wf_next.skip_manual_mastering（default false）は、prepared フェーズ 2-B（マスター音源検出）で raw master と別の最終マスター候補が 01-master/ に見つからないときの挙動を切り替える。

• true: assets.raw_master のファイル名をそのまま assets.master_audio として採用し、phase: "mastered" へ進む。「raw（自動クロスフェード結合出力）を外部 DAW でマスタリングせずそのまま公開する」運用（raw=final）をチャンネル単位で宣言するためのオプション
• false（未設定含む）: 従来通り、ユーザーが最終マスターを 01-master/ に配置するまで停止する

skip_audio_approval とは独立した設定であることに注意。skip_audio_approval は「候補を採用する前に確認プロンプトを出すかどうか」だけを制御し、候補そのものの自動採用／スキップ判断には関与しない。skip_manual_mastering: true かつ skip_audio_approval: false の場合は、raw master を採用する前に承認を取る。

想定 API call 数

API	call 数 / 実行	変動要因
videos.insert（1,600 units / 本、mastered フェーズの yt-upload-collection / yt-upload-auto）	アップロード本数	collection / release 型・進行フェーズ
playlists.insert / playlistItems.insert（各 50 units、yt-playlist-manager --init）	新規プレイリスト数 + 割当本数	プレイリスト構成
Vertex AI Lyria（subagent /music --generate 委譲時）	/music --generate の「想定 API call 数」を参照	API engine パス採否

• 上限 / 承認: upload 前に --plan で事前確認し、playlist 系は --dry-run を使う。/video --generate /music --master /video --describe はローカル処理で API 0。委譲先 skill の見積もりは各 skill の「想定 API call 数」を参照。

Instructions

直接実行の canonical timing 契約

/wf-next を直接呼んだ場合も、state 判定・lease・history/timing の正は /wf-new --auto と同じ state script とする。下記「1. アクティブなコレクションの特定」の既存手順で対象名を <fixed-name> として固定した後、フェーズ処理や子 skill を開始する前に、チャンネルルートで次の順序を守る。

STATE_SCRIPT=.claude/skills/wf-new/references/wf-auto-state.py
uv run python "$STATE_SCRIPT" acquire --channel-dir .
uv run python "$STATE_SCRIPT" plan --channel-dir . --collection <fixed-name> --token <token>
uv run python "$STATE_SCRIPT" heartbeat --channel-dir . --token <token>
uv run python -c 'from datetime import UTC, datetime; print(datetime.now(UTC).isoformat())'

acquire の busy / exit 20 では作業を開始しない。plan には必ず同じ <token> を渡す。plan 後は heartbeat の JSON 応答が status: refreshed の場合だけ lease owner の確認成功として AI 開始時刻を取得し、stdout を同じ attempt 専用の <current-attempt-ai-started-at> として保持する。status: not-owner も exit 0 で返るため、exit 0 だけでは owner と判定しない。status: not-owner では開始時刻を取得せず停止する。resolver が返した固定 collection と action を <resolver-action> としてそのまま使い、公開許可や実成果物から action を独自再判定せず、別 action へ読み替えない。別 collection ID や timing 保存処理も作らない。

resolver が blocked / external_publish_disabled を返した対話実行では、公開範囲と API write を明示してユーザー承認を取る。承認時は record / release せず、owner token で approve --approval external-publish を実行し、同じ token・collection で plan を再実行する。これにより durable な workflow.scheduled_automation.allow_external_publish は変更せず、同じ canonical attempt が publish_ready へ進む。却下時だけ blocked を記録して release する。

uv run python "$STATE_SCRIPT" approve --channel-dir . --token <token> --approval external-publish
uv run python "$STATE_SCRIPT" plan --channel-dir . --collection <fixed-name> --token <token>

resolver action と直接入口の既存責務は次の対応を正とする。

resolver action	直接 /wf-next の処理
wf-new	planning が未完了であることを報告し、/wf-new を再開 action として blocked で閉じる
lyria / suno-helper / masterup	prepared の既存のフェーズ別処理をそのまま実行し、同じ action ID で記録する
wf-next-local / wf-next	mastered / publishing の既存のフェーズ別処理を実行する。wf-next-local は resolver が許可したローカル成果物までに限定し、YouTube write を行わない
publish	production 完了を検証して /publish を再開 action として blocked で閉じ、公開後処理を本 skill へ複製しない
blocked	resolver の reason / resume action を変更せず blocked で閉じる
complete	下記 complete の既存検証を通過した場合だけ success で閉じる

既存の成果物検証、承認 gate、state 更新責務を変更せず、子 skill の終了報告だけで成功にしない。期待成果物と state を検証した後、成功だけを success、手動介入または責務外 action への handoff を blocked、検証失敗を含むその他を failed とし、すべて同じ固定 collection、resolver action、同じ attempt の AI 開始時刻で閉じる。対話 gate の時間分類と --human-interval は /wf-new --auto の canonical timing 契約をそのまま使う。

uv run python "$STATE_SCRIPT" record --channel-dir . --token <token> --collection <fixed-name> --action <resolver-action> --status success|blocked|failed --reason <reason> [--resume-action <resolver-resume-action>] --ai-started-at <current-attempt-ai-started-at> [--human-interval <human-start> <human-end>]...

status を記録した後は、成功時だけでなく blocked / failed の停止報告前にも同じ固定 collection を plan --channel-dir . --collection <fixed-name> --token <token> で再評価し、次回の再開 action を推測しない。全終了経路の finally 相当で release --channel-dir . --token <token> を実行し、他 token の lease は変更しない。ただし上記の対話承認待ちはまだ終了経路ではなく、承認を attempt context に保存して再 plan するまで record / release しない。

/wf-new --auto が token、resolver の action / collection、attempt の開始時刻を固定して本 skill へ委譲した場合は、その実行文脈を再利用する。nested acquire や独自 attempt の作成・記録・release は行わず、成果物と state の検証結果を呼び出し元へ返し、canonical history の記録と lease 解放は /wf-new --auto に一度だけ行わせる。

1. アクティブなコレクションの特定

• collections/planning/ の workflow-state.json を探索

• 複数ある場合はユーザーに選択を促す

• 対象確定後、フェーズ処理へ進む前に骨格プリフライトを実行する（fail-loud、#1494）:

  uv run yt-collection-preflight <collection-dir-name>
  

  [NG]（01-master/ 等の欠落）が報告されたら uv run yt-collection-preflight <collection-dir-name> --fix で補完してから続行する。欠落したまま後工程へ進むと /music --master / /video --generate がマスター音源の置き場を見失う

2. フェーズ別処理

prepared → 段階的サポート

完了済みの素材と音楽エンジンを確認し、未完了の作業を案内・実行。

Suno パス:

1. assets.music_prompts = true + assets.raw_master = null:
   • workflow-state.json::planning.music.suno_playlist_url の記録有無と 02-Individual-music/ の音声ファイル（mp3 / m4a / wav）実在を確認する
   • 02-Individual-music/ に音声ファイルが 1 件以上存在（URL 記録の有無は問わない）:
     • AskUserQuestion による URL 入力はスキップする。title list は /music --master Step 1.6 がローカルファイル名から自動復元するため playlist URL は不要。メインが /music --master の

---

Content truncated.