| name | autopilot-setup |
| description | Use when a user initializes autopilot in a project that lacks .claude/autopilot.config.yaml, requests /autopilot-setup, asks to bootstrap autopilot configuration, or needs autopilot to detect project tech stack, services, agents, and test suites for the first time. |
| argument-hint | [可选: 项目根目录路径] [--non-interactive 跳过向导] |
Autopilot Setup — 项目配置初始化
扫描项目结构，自动检测技术栈和服务，生成 .claude/autopilot.config.yaml。
Wizard 模式（默认启动）
执行前读取: references/setup-wizard.md（完整 Wizard 交互流程和预设模板定义）
默认进入引导式向导，3 步完成配置，降低 60+ 配置项的认知负担。
- 选择预设模板 — AskUserQuestion 展示 Strict / Moderate / Relaxed 3 个预设
- 确认自动检测 — 运行项目检测流程，展示结果摘要供用户确认
- 应用预设 + 写入 — 将预设值覆盖到检测结果上，生成最终配置
跳过 Wizard: 传入 --non-interactive 时跳过预设选择，直接执行检测流程（向后兼容）。
执行流程
执行前读取: references/setup-detection-rules.md（完整检测规则 + 推导表）
Step 1-2.6: 项目检测
自动检测技术栈、服务端口、项目上下文和安全工具。检测规则详见 references/setup-detection-rules.md，包含：
- Step 1: 后端/前端/Node 服务/测试框架检测
- Step 2: 服务端口提取
- Step 2.5: 项目上下文（测试凭据、项目结构、Playwright 登录流程）
- Step 2.6: 安全工具检测
Step 3: 生成配置
读取模板: references/config-schema.md（完整 YAML 配置模板）
根据 Step 1-2.6 的检测结果，按 config-schema.md 中的模板生成配置文件。所有 {detected} 占位符替换为实际检测值。
Step 4: 用户确认
通过 AskUserQuestion 展示生成的配置摘要：
"已检测到以下项目结构，生成了 autopilot 配置:"
检测结果:
- 后端: {tech_stack} (port {port})
- 前端: {framework} (port {port})
- 测试: {test_frameworks}
- 测试凭据: {username}/{检测状态}
- 项目结构: {backend_dir}, {frontend_dir}, {node_dir}
选项:
- "确认写入 (Recommended)" → 写入 .claude/autopilot.config.yaml
- "需要调整" → 展示完整 YAML 让用户修改后再写入
4.1 未检测到的字段补充
对 project_context 中值为空的字段，逐个通过 AskUserQuestion 提示用户补充：
IF test_credentials.username 为空:
AskUserQuestion: "未检测到测试凭据。请提供测试账号用户名（或跳过，后续由 Phase 1 自动发现）："
选项: "输入凭据" / "跳过，由 Phase 1 自动发现 (Recommended)"
IF playwright_login.steps 为空 且检测到 Playwright:
AskUserQuestion: "未检测到 Playwright 登录流程。请选择处理方式："
选项: "由 Phase 1 Auto-Scan 自动发现 (Recommended)" / "手动描述登录流程"
降级策略：所有 project_context 字段均为可选。未填写的字段由 Phase 1 的 Auto-Scan + Research Agent 在运行时自动发现，不阻断 init 流程。
Step 5: 写入配置
将配置写入 .claude/autopilot.config.yaml。
如果文件已存在 → AskUserQuestion 确认是否覆盖。
Agent 与模型引导
执行前读取: references/setup-agent-model-guide.md（Agent 安装引导 + 模型路由引导）
执行前读取: references/setup-domain-agent-guide.md（域级 Agent 推荐映射表 + 安装引导）
Step 5.3: Agent 安装引导
始终通过 AskUserQuestion 引导用户安装专业 Agent。详见 references/setup-agent-model-guide.md。
Step 5.3.5: 域级 Agent 配置引导
基于 Step 1 检测到的项目结构（project_structure.backend_dir / frontend_dir / node_dir）以及扩展目录扫描，引导用户配置 implementation.parallel.domain_agents 的域级 Agent 映射。详见 references/setup-domain-agent-guide.md。
IF Wizard 预设的 domain_agents_strategy == "skip":
→ 输出 "跳过域 Agent 配置（Relaxed 模式）"
→ 继续后续步骤
ELIF 检测到至少一个目录域（backend_dir/frontend_dir/node_dir 非空，或扩展扫描发现额外目录）:
IF domain_agents_strategy == "recommended":
→ 自动安装推荐域 Agent（不弹 AskUserQuestion）
ELSE:
→ 按 references/setup-domain-agent-guide.md Section D 的标准交互流程引导
→ 安装选定的 VoltAgent/OMC 域级 Agent 到 .claude/agents/
→ 更新 config domain_agents 映射
ELSE:
→ 输出 "未检测到多域项目结构，跳过域级 Agent 配置"
域级 Agent 配置是可选步骤，跳过不影响 autopilot 功能。未配置时使用 default_agent (fallback)。
Step 5.3.6: Phase 2-7 Agent 配置引导（必须执行）
在 Step 5.3 / 5.3.5 之后，遍历以下 8 个 Phase 2-7 关键 agent 字段，逐个执行 "scan candidates → 推荐预设 → AskUserQuestion 选择 → 写 config"：
| 字段 | 推荐预设（来源 Skill spec-autopilot:autopilot-agents 的 recommend 模式） |
|---|
phases.openspec.agent | OMC planner |
phases.testing.agent | OMC test-engineer |
phases.implementation.parallel.default_agent | OMC executor |
phases.implementation.review_agent（即 parallel.review_agent） | OMC code-reviewer |
phases.redteam.agent | OMC code-reviewer（备选 Anthropic red-team-critic） |
phases.reporting.agent | OMC qa-tester |
phases.code_review.agent | OMC code-reviewer |
phases.archive.agent | OMC git-master |
Wizard 分支控制（参见 references/setup-wizard.md 的 phase_agents_strategy）：
IF phase_agents_strategy == "recommended":
→ 对每个字段：若推荐 agent 已安装则直接写入，否则自动调用
Skill("spec-autopilot:autopilot-agents" "install") 后写入（不弹 AskUserQuestion）
→ 输出汇总表
ELIF phase_agents_strategy == "fallback_general_purpose":
→ 所有 8 字段默认写 "general-purpose"，供用户后续手动替换
ELSE (phase_agents_strategy == "ask" 或未指定):
# 标准交互流程
FOR field IN 上述 8 个字段:
# 1. 扫描已安装候选（同 Step 5.3 规则，含 plugin:agent 命名空间）
# 2. 计算推荐 agent 是否已安装
IF 推荐 agent 未安装:
→ AskUserQuestion: "{field} 推荐使用 {recommended_agent}，当前未安装。如何处理？"
选项:
- "立即安装（调用 autopilot-agents install-mode）" →
Skill("spec-autopilot:autopilot-agents" "install") 完成后写入推荐 agent
- "保持空字段稍后手动安装" → 写入 ""（Schema 校验会提示未完成）
- "降级 general-purpose" → 写入 "general-purpose"
ELIF 候选为 1 个（仅推荐 agent）:
→ 直接写入推荐 agent，输出 "✓ {field}: {agent}"
ELSE:
→ AskUserQuestion: "选择 {field} 使用的 agent：" 选项=候选列表（推荐标 Recommended 首位，
始终追加 "立即安装其它推荐" / "保持空字段" 两个特殊选项）
→ 写入用户选择
二次校验：写入后若某字段为空且当前预设非 Relaxed/fallback_general_purpose → 输出警告并记录到 Schema 校验清单（见 Step 6）。
Step 5.4: 模型路由引导
引导用户配置模型路由策略。详见 references/setup-agent-model-guide.md。
LSP 推荐
执行前读取: references/setup-lsp-recommendation.md（LSP 推荐映射表 + 交互）
Step 5.5: LSP 插件推荐
根据检测到的技术栈推荐 Claude Code LSP 插件。详见 references/setup-lsp-recommendation.md。
Step 5.6: Agent 工具权限自动适配（必须执行）
问题背景: 社区 Agent（如 OMC analyst、code-reviewer、explore 等）frontmatter 常含 disallowedTools: Write, Edit，但 autopilot 各 Phase 大多需要写盘权限。若直接拉来用，子 Agent 在 Phase 1/2/4/5/7 会无法写产物，触发 L2 阻断或交付物缺失。
适配协议（确定性、幂等）:
Bash('python3 ${CLAUDE_PLUGIN_ROOT}/runtime/scripts/adapt-agent-tools.py --project-root "$(pwd)"')
脚本行为：
- 读取
.claude/autopilot.config.yaml 中所有 phases.*.agent（含 parallel.default_agent、parallel.domain_agents.*.agent、research.agent、review_agent、code_review.agent）。
- 对每个 (phase, agent) 二元组，按内置
PHASE_REQUIRED_TOOLS 矩阵计算 disallowedTools ∩ required_tools。
- 冲突非空时，fork 源 agent 文件到
.claude/agents/{name}.md，剥离冲突项；写入 HTML 注释标记 fork 来源与原因；不修改 marketplace 源文件。
- 已 fork 或无冲突 → 跳过；幂等可重复执行。
- 输出结构化 JSON（
forked / would_fork / already_forked / ok / missing 计数与详情），由主线程渲染摘要给用户。
展示给用户:
✓ Agent 工具权限适配完成
- 已 fork 适配: {forked} 个
- 未冲突保留: {ok} 个
- 未找到源文件: {missing} 个 → 请检查 agent 是否已安装
适配产物: .claude/agents/*.md
设计意图：消除"agent 想写但被 disallowedTools 挡住"导致的运行期 L2 失败。fork 而非原地修改，保持 marketplace agent 干净，可随时 rm .claude/agents/{name}.md 回退。
Step 6: Schema 验证
读取规则: references/config-schema.md（Schema 验证规则章节）
写入后必须按 config-schema.md 中的 schema 验证配置完整性。校验失败 → 输出缺失/错误的 key 列表，AskUserQuestion 要求用户修正后重试。
幂等性
多次运行不会破坏已有配置。已存在时必须用户确认才能覆盖。
