spec-workflow-init

spec-workflow-init — Development Workflow Generator

Generate a project-specific issue-to-pr-workflow.md through interactive dialogue. The workflow serves as a playbook for spec-implement and development agents.

Language Rules

1. Auto-detect input language → output in the same language
2. Japanese input → Japanese output, use references/workflow-template.ja.md
3. English input → English output, use references/workflow-template.md
4. Explicit override takes priority (e.g., "in English", "日本語で")

Sub-agent template selection (when generating agent definitions):

• English → references/agents/claude/workflow-*.md
• Japanese → references/agents/claude/workflow-*.ja.md
• Codex templates: English → references/agents/codex/workflow-*.toml, Japanese → references/agents/codex/workflow-*.ja.toml

Execution Flow

Step 1: Initial Checks

1. Verify Git repository:

   git rev-parse --is-inside-work-tree 2>/dev/null
   

   If not a Git repo, warn and skip branch detection. Continue with other checks.

2. Check current directory:

   pwd
   ls -la
   

3. Detect existing workflow file:

   find . -name "issue-to-pr-workflow.md" -maxdepth 3 2>/dev/null
   

   If found and --force is not set, show the existing file path and proceed to Step 7 (idempotency handling).

Step 2: Environment Detection

Run the following checks to auto-detect the project environment:

Package manager:

ls pnpm-lock.yaml yarn.lock package-lock.json bun.lockb 2>/dev/null

Container usage:

ls docker-compose.yml docker-compose.yaml Dockerfile 2>/dev/null

CI/CD service:

ls -d .github/workflows .gitlab-ci.yml .circleci 2>/dev/null

Branch information:

git branch -r 2>/dev/null | head -10

Language, framework, and scripts:

cat package.json 2>/dev/null | grep -A 50 '"scripts"'
cat package.json 2>/dev/null | grep -A 30 '"dependencies"'
ls go.mod requirements.txt pyproject.toml 2>/dev/null

Database:

ls prisma/schema.prisma 2>/dev/null
grep -l "postgres\|mysql\|mongo" docker-compose.yml 2>/dev/null

Lint tools:

ls .eslintrc* biome.json 2>/dev/null

Coding rules file:

find . -name "coding-rules.md" -maxdepth 3 2>/dev/null

Review rules file:

find . -name "review_rules.md" -maxdepth 3 2>/dev/null

cmux environment:

echo $CMUX_SOCKET_PATH

Present the detection results to the user in a summary table:

Detected project environment:
  Language/FW:       {detected}
  Package Manager:   {detected}
  Container:         {detected}
  Test:              {detected}
  CI/CD:             {detected}
  Branch:            {detected}
  Database:          {detected}
  Lint:              {detected}
  Coding Rules:      {detected or "Not found"}
  Review Rules:      {detected or "Not found"}
  cmux:              {detected or "Not available"}

Ask the user to confirm or correct the detection results before proceeding.

Step 3: Interactive Dialogue

Gather workflow configuration through AskUserQuestion rounds.

Round 1: Output Path

question: "Where to save issue-to-pr-workflow.md?" / "issue-to-pr-workflow.md の出力先は？"
header: "Output"
options:
  - "docs/issue-to-pr-workflow.md (Recommended)" / "docs ディレクトリ直下（推奨）"
  - "docs/development/issue-to-pr-workflow.md" / "docs/development 配下"

Round 2: Branch Strategy

Q1:
question: "Base branch (PR target)?" / "ベースブランチ（PRターゲット）は？"
header: "Branch"
options:
  - "develop (Recommended)" / "feature → develop → main（Git Flow）"
  - "main" / "feature → main（GitHub Flow）"
  - "trunk" / "Short-lived branches → main（Trunk-based）"

Q2:
question: "Feature branch naming convention?" / "featureブランチの命名規則は？"
header: "Naming"
options:
  - "feature/{issue}-{slug} (Recommended)" / "e.g. feature/42-add-auth"
  - "{issue}-{slug}" / "e.g. 42-add-auth"
  - "{type}/{issue}-{slug}" / "e.g. fix/42-login-bug, feat/43-dashboard"

Round 3: Quality Gates

question: "Quality gates before PR creation?" / "PR作成前の品質ゲートは？"
header: "Gates"
multiSelect: true
options:
  - "All tests must pass (Recommended)" / "テスト全パス（推奨）"
  - "Lint and type check must pass" / "Lint / Typecheckパス"
  - "Coverage threshold" / "カバレッジ基準"

Round 4: Development Style

question: "Select your development style" / "開発スタイルを選択してください"
header: "Style"
options:
  - "Implementation First (Recommended)" / "実装 → レビュー → テスト → テストレビュー → 品質ゲート → PR"
  - "TDD" / "テスト(RED) → 実装(GREEN) → リファクタ → レビュー → 品質ゲート → PR"
  - "BDD" / "E2Eシナリオ → テスト(RED) → 実装(GREEN) → レビュー → 品質ゲート → PR"

Round 5: E2E Test Level

question: "E2E test scope?" / "E2Eテストの範囲は？"
header: "E2E"
options:
  - "API level only (Recommended)" / "supertest等でリクエスト→レスポンスを検証"
  - "API + Browser E2E" / "上記 + Playwrightでクリティカルパスを検証"

Round 6: Execution Strategy

Show options based on cmux detection from Step 2.

If cmux detected (CMUX_SOCKET_PATH is set):

question: "Select your execution strategy" / "実行戦略を選択してください"
header: "Strategy"
options:
  - "Single agent" / "単独実行 — メインエージェントが全工程を順番に実行（シンプル・安全）"
  - "Multi-agent (Recommended)" / "マルチエージェント（推奨） — Codex custom agents または Claude Code agent team で役割分担"
  - "Multi-agent (cmux)" / "マルチエージェント(cmux) — cmux で別ペインに各ロールを起動（進捗がリアルタイムで見える）"

If cmux NOT detected:

question: "Select your execution strategy" / "実行戦略を選択してください"
header: "Strategy"
options:
  - "Single agent" / "単独実行 — メインエージェントが全工程を順番に実行（シンプル・安全）"
  - "Multi-agent (Recommended)" / "マルチエージェント（推奨） — Codex custom agents または Claude Code agent team で役割分担"

Round 7: Agent Targets (only if Multi-agent or Multi-agent (cmux) selected)

Ask which agent definitions to generate. Do NOT decide targets based on .claude/ / .codex/ directory detection.

question: "Which agent definitions should be generated?" / "どのエージェント定義を生成しますか？"
header: "Agents"
options:
  - "Both Claude + Codex (Recommended)" / "Claude と Codex の両方を生成"
  - "Claude only" / "Claude のみ生成"
  - "Codex only" / "Codex のみ生成"
  - "Skip generation" / "生成しない"

Round 8: Agent AI Assignment (only if Multi-agent (cmux) selected in Round 6)

question: "Which AI to assign to each role?" / "各ロールにどのAIを割り当てますか？"
header: "AI Assignment"
options:
  - "Implement=Codex, Test=Codex, Review=Claude (Recommended)"
  - "All Claude Code" / "全て Claude Code"
  - "All Codex" / "全て Codex"

Use the selection to fill {implementer_ai}, {tester_ai}, {reviewer_ai} in the role table.

Round 8.5: Second Opinion (only if Multi-agent (cmux) selected in Round 6)

question: "Run second opinion at review gates?" / "レビューゲートでセカンドオピニオンを実施しますか？"
header: "Opinion"
options:
  - "Always (Recommended)" / "毎回実施（推奨）"
  - "On user request only" / "ユーザーが要求した場合のみ"
  - "Never" / "実施しない"

Additional Questions (project-type specific):

• Docker project: "Run all commands inside Docker?" / "Docker内で全コマンドを実行しますか？"
• Next.js project: "Include build check in workflow?" / "ビルド確認をワークフローに含めますか？"

ステップ 4：ワークフローの生成

1. 言語ルールに基づいてテンプレートを選択します：

   • 英語 → references/workflow-template.md
   • 日本語 → references/workflow-template.ja.md

2. テンプレートを読み込み、プレースホルダーを収集した値に置き換えます：

   • {package_manager}、{container_tool}、{database}、{test_framework} など
   • {pr_target}、{branch_naming}、{dev_style}
   • {test_command}、{lint_command}、{typecheck_command}、{build_command}
   • {e2e_test_command}、{browser_e2e_command}、{coverage_command}
   • {timestamp} → 現在の日付／時刻

3. 開発スタイルのセクションを選択します：

   • 実装優先 → {if_implementation_first}...{end_implementation_first} を残し、TDD／BDD ブロックを削除します
   • TDD → {if_tdd}...{end_tdd} を残し、その他を削除します
   • BDD → {if_bdd}...{end_bdd} を残し、その他を削除します

4. 条件付きセクションを処理します：

   • ブラウザー E2E が選択されていない → {if_browser_e2e}...{end_browser_e2e} ブロックを削除します
   • マルチエージェントが選択されていない（シングルエージェントを選択） → {if_multi_agent}...{end_multi_agent} ブロックを削除します
   • エージェントの対象に Claude が含まれる場合 → {if_claude_agents}...{end_claude_agents} を残し、それ以外は削除します
   • エージェントの対象に Codex が含まれる場合 → {if_codex_agents}...{end_codex_agents} を残し、それ以外は削除します
   • エージェントの生成をスキップする場合 → {if_no_agent_files}...{end_no_agent_files} を残し、それ以外は削除します
   • 型チェックコマンドがない → {if_typecheck}...{end_typecheck} を削除します
   • ビルドコマンドがない → {if_build}...{end_build} を削除します
   • review_rules.md が検出された → {if_review_rules}...{end_review_rules} を残し、{if_no_review_rules}...{end_no_review_rules} を削除します
   • review_rules.md が検出されなかった → {if_no_review_rules}...{end_no_review_rules} を残し、{if_review_rules}...{end_review_rules} を削除します
   • マルチエージェント（cmux）が選択された → {if_cmux_dispatch}...{end_cmux_dispatch} と {if_second_opinion}...{end_second_opinion} を残します
   • マルチエージェント（cmux）が選択されていない → cmux／second-opinion の両方のブロックを削除します
   • {review_rules_path} を検出されたパス（またはプレースホルダー）に置き換えます
   • {implementer_ai}、{tester_ai}、{reviewer_ai} を選択した AI の値（ラウンド 8 から）に置き換えます。デフォルト：claude
   • AI 列が該当しない場合（cmux のディスパッチがない場合）、役割テーブルから AI 列を削除します

5. 残ったプレースホルダーと条件マーカーを整理します

6. 必要に応じて出力ディレクトリを作成します：

   mkdir -p {output_directory}
   

7. 指定された出力パスにファイルを書き込みます

ステップ 5：冪等性の処理

既存のワークフローファイルが検出された場合（ステップ 1 または生成中）：

1. --force を指定していない場合：既存ファイルのパスとともに警告を表示します

   question: "Existing workflow found at {path}. Overwrite?" / "既存のワークフローが {path} に見つかりました。上書きしますか？"
   header: "Overwrite"
   options:
     - "Yes, overwrite" / "はい、上書きする"
     - "No, cancel" / "いいえ、キャンセル"
   

2. --force を指定した場合：確認なしで上書きします

ステップ 6：サブエージェントの生成

references/agent-and-pipeline-setup.md を 最後まで読み込み（日本語の場合は .ja.md）、ステップ 6a から 6d を順番に実行します。 エージェントの生成をスキップするのは、ラウンド 6 でシングルエージェントが選択された場合、またはラウンド 7 で生成をスキップする選択がされた場合のみです。パイプライン設定とウォッチドッグの処理は、引き続き参照ドキュメントの独立した条件に従います。

ステップ 7：AGENTS.md／CLAUDE.md の参照を更新

1. 規約ファイルを確認します：

   ls AGENTS.md CLAUDE.md 2>/dev/null
   

2. CLAUDE.md が AGENTS.md へのシンボリックリンクの場合、AGENTS.md のみを更新します：

   readlink CLAUDE.md 2>/dev/null
   

3. いずれかのファイルが存在する場合、確認を求めます：

   question: "Add workflow reference to AGENTS.md / CLAUDE.md?" / "AGENTS.md / CLAUDE.md にワークフローの参照を追記しますか？"
   header: "Update"
   options:
     - "Yes, add reference (Recommended)" / "はい、参照を追記する（推奨）"
     - "No, skip" / "いいえ、スキップ"
   

4. 承認された場合、以下のセクションを追加します（出力の言語に合わせてください）：

   英語：

   ## Development Workflow
   
   Follow the development workflow for Issue → Implementation → PR:
   - [{workflow_path}]({workflow_path}) — Development workflow generated by spec-workflow-init
   

   日本語：

   ## Development Workflow
   
   開発フロー（Issue → 実装 → PR）は以下のファイルに従ってください:
   - [{workflow_path}]({workflow_path}) — spec-workflow-init で生成された開発ワークフロー
   

5. どちらのファイルも存在しない場合、警告を出力します：

   "Warning: Neither AGENTS.md nor CLAUDE.md found. Skipping reference update."
   / "警告: AGENTS.md も CLAUDE.md も見つかりません。参照追記をスキップします。"
   

オプション

オプション	説明
--force	既存のファイルを確認なしで上書きします

エラー処理

エラー	検出方法	対応
Git リポジトリではない	git rev-parse が失敗	警告を表示し、ブランチの検出をスキップします。他のチェックは続行します
package.json がない	ls package.json が失敗	パッケージマネージャー／テスト／リンターの検出をスキップします。対話を通じて情報を収集します
書き込み権限エラー	mkdir -p またはファイルへの書き込みが失敗	エラーを表示し、AskUserQuestion を使って出力パスを再度尋ねます
ネットワークエラー（git branch -r）	コマンドがタイムアウトするか、ゼロ以外の終了コードを返す	リモートブランチをスキップします。ローカルブランチのみを使用します。対話を通じて情報を収集します
既存ファイルとの競合	出力パスにファイルが見つかる	--force なしの場合：警告を表示し、上書きするか尋ねます。--force ありの場合：上書きします

使用例

# Generate workflow with dialogue
"Generate development workflow"
「開発ワークフローを生成」

# Generate with force overwrite
"Create workflow --force"
「ワークフロー生成 --force」

# After spec-rules-init
"Now create the development workflow"
「次に開発フローを作って」

完了後のアクション

ワークフローを生成した後：

question: "Workflow generated. What's next?" / "ワークフローを生成しました。次のアクションは？"
options:
  - "Run spec-implement" / "spec-implement を実行する"
    description: "Start implementing with the generated workflow" / "生成したワークフローで実装を開始"
  - "Review and customize" / "レビューしてカスタマイズ"
    description: "Open the generated file and make adjustments" / "生成されたファイルを開いて調整"
  - "Done for now" / "完了"
    description: "Finish without further action" / "追加アクションなしで完了"