spec-workflow-init

spec-workflow-init — 开发工作流生成器

通过交互式对话生成项目专属的 issue-to-pr-workflow.md。此工作流用作 spec-implement 和开发 Agent 的操作手册。

语言规则

1. 自动检测输入语言 → 使用相同语言输出
2. 日语输入 → 使用日语输出，并采用 references/workflow-template.ja.md
3. 英语输入 → 使用英语输出，并采用 references/workflow-template.md
4. 明确指定的语言优先（例如“用英语”“日本語で”）

子 Agent 模板选择（生成 Agent 定义时）：

• 英语 → references/agents/claude/workflow-*.md
• 日语 → references/agents/claude/workflow-*.ja.md
• Codex 模板：英语 → references/agents/codex/workflow-*.toml，日语 → references/agents/codex/workflow-*.ja.toml

执行流程

第 1 步：初始检查

1. 验证 Git 仓库：

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

   如果不是 Git 仓库，则发出警告并跳过分支检测。继续执行其他检查。

2. 检查当前目录：

   pwd
   ls -la
   

3. 检测现有工作流文件：

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

   如果找到文件且未设置 --force，则显示现有文件路径并进入第 7 步（幂等性处理）。

第 2 步：环境检测

运行以下检查以自动检测项目环境：

包管理器：

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

容器使用情况：

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

CI/CD 服务：

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

分支信息：

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

语言、框架和脚本：

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

数据库：

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

Lint 工具：

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

编码规则文件：

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

审查规则文件：

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

cmux 环境：

echo $CMUX_SOCKET_PATH

向用户展示检测结果，并使用摘要表格：

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"}

请用户确认或更正检测结果后再继续。

第 3 步：交互式对话

通过 AskUserQuestion 轮次收集工作流配置。

第 1 轮：输出路径

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 配下"

第 2 轮：分支策略

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"

第 3 轮：质量门禁

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" / "カバレッジ基準"

第 4 轮：开发风格

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

第 5 轮：E2E 测试级别

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

第 6 轮：执行策略

根据第 2 步检测到的 cmux 情况显示选项。

如果检测到 cmux（CMUX_SOCKET_PATH 已设置）：

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 で別ペインに各ロールを起動（進捗がリアルタイムで見える）"

如果未检测到 cmux：

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

第 7 轮：Agent 目标（仅当选择 Multi-agent 或 Multi-agent (cmux) 时）

询问要生成哪些 Agent 定义。不要根据 .claude/ / .codex/ 目录检测结果来决定目标。

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

第 8 轮：Agent AI 分配（仅当在第 6 轮选择 Multi-agent (cmux) 时）

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"

使用所选内容填充角色表中的 {implementer_ai}、{tester_ai}、{reviewer_ai}。

第 8.5 轮：第二意见（仅当在第 6 轮选择 Multi-agent (cmux) 时）

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

其他问题（特定于项目类型）：

• Docker 项目：“是否在 Docker 中运行所有命令？” / “Docker内で全コマンドを実行しますか？”
• Next.js 项目：“是否在工作流中包含构建检查？” / “ビルド確認をワークフローに含めますか？”

第 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. 选择开发风格部分：

   • Implementation First → 保留 {if_implementation_first}...{end_implementation_first}，移除 TDD/BDD 块
   • TDD → 保留 {if_tdd}...{end_tdd}，移除其他块
   • BDD → 保留 {if_bdd}...{end_bdd}，移除其他块

4. 处理条件部分：

   • 未选择 Browser E2E → 移除 {if_browser_e2e}...{end_browser_e2e} 块
   • 未选择 Multi-agent（选择了 Single agent）→ 移除 {if_multi_agent}...{end_multi_agent} 块
   • Agent 目标包含 Claude → 保留 {if_claude_agents}...{end_claude_agents}，否则移除
   • Agent 目标包含 Codex → 保留 {if_codex_agents}...{end_codex_agents}，否则移除
   • 跳过 Agent 生成 → 保留 {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}
   • 选择了 Multi-agent（cmux）→ 保留 {if_cmux_dispatch}...{end_cmux_dispatch} 和 {if_second_opinion}...{end_second_opinion}
   • 未选择 Multi-agent（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 步：子 Agent 生成

完整阅读 references/agent-and-pipeline-setup.md（日语请阅读 .ja.md），然后按顺序执行其中的第 6a 至 6d 步骤。仅当第 6 轮选择了 Single agent 或第 7 轮选择了 Skip generation 时，才跳过 Agent 生成；流水线配置和 watchdog 处理仍遵循参考文档中的独立条件。

第 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 执行失败	跳过包管理器 / 测试 / lint 检测。通过对话收集信息
写入权限错误	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" / "追加アクションなしで完了"