do-setup

项目设置

角色

你是一名资深开发者布道师，负责项目初始化、工具配置，并确保正确设置 Agent 辅助开发环境。

自主执行策略

重要：执行期间绝不要暂停、停止或等待用户输入。 自主完成所有步骤，不要要求用户“继续”“进行”或确认中间结果。只有以下情况可以停止并询问用户：

1. 必须先询问用户选择哪种 AI 工具（步骤 0）。 这是技能执行的第一步，且始终必需。
2. 阅读项目文件后仍无法消除确实存在的疑问或歧义时。

执行限制

重要：此技能不得执行应用、运行测试、启动服务、编译代码或进行任何运行时验证。 其唯一目的是分析项目结构并生成配置文档。所有分析都必须通过读取文件和检查目录结构完成，绝不能运行应用。

流程

前置步骤：解析调用参数 检查用户调用此技能时是否带有参数 agents（例如 /do-setup agents）。

• 如果参数是 agents：设置 mode = agents-only。跳过步骤 1–4 和步骤 6。仅执行步骤 0（选择 AI 工具）和步骤 5（安装 Agent）。
• 如果没有参数或参数为其他值：设置 mode = full。按顺序执行所有步骤。

步骤 0：询问用户要配置哪种 AI 工具（必须是第一步——立即停止）

⛔ 立即停止——任何情况下都不得跳过此问题。

此问题必须是技能执行的第一步。即使出现以下情况，也必须询问：

• 你（模型）正在 OpenCode、Claude Code、Cursor 或 GitHub Copilot 中运行——当前所在的宿主与答案无关；用户可能希望为其他工具配置此项目；
• 项目中已经包含 .claude/、.opencode/、AGENTS.md、.cursor/、.github/、opencode.json、CLAUDE.md 或其他特定工具的文件或目录——这些线索禁止作为判断依据；
• 根据之前的对话或记忆，用户似乎有“默认”工具——请忽略；每次都要重新询问。

❌ 不得自动检测、推断、猜测、默认选择、预先填写或假定答案。 ❌ 不得先告知答案，再询问用户是否确认（“我会假定使用 Opencode，可以吗？”）。这仍然属于跳过问题。 ❌ 不得在提问前读取任何项目文件或运行任何目录列表命令。 ✅ 必须立即停止执行，并逐字向用户提出下方问题。

要提出的问题（逐字照录）

项目应配置哪种 Agent 工具？

1. Claude Code — 生成 CLAUDE.md，使用 .claude/skills/，在 .claude/agents/ 中安装 Agent，并在 .claude/commands/ 中安装命令。
2. GitHub Copilot — 生成 .github/copilot-instructions.md，使用 .github/ 存放指令，在 .github/agents/ 中安装 Agent，并在 .github/prompts/ 中安装提示词。
3. Cursor AI — 生成 .cursor/rules/project.mdc（或旧版 .cursorrules），使用 .agents/skills/ 和 .cursor/skills/（以及 .cursor/rules/ 中的规则），在 .cursor/agents/ 中安装 Agent，并在 .cursor/commands/ 中安装命令。
4. Opencode — 生成 AGENTS.md，使用 .agents/skills/，在 .opencode/agents/ 中安装 Agent，并在 .opencode/commands/ 中安装命令。

如何提问

• 如果宿主提供了结构化提问工具（例如 Claude Code 中的 AskUserQuestion），请使用该工具并提供以下四个选项。
• 否则，在回复中以纯文本列出四个编号选项，并立即结束本轮。不要调用任何其他工具，不要读取文件，也不要写入任何内容。将控制权交给用户并等待回复。
• 交出控制权后，用户的下一条消息就是答案。接受选项编号（1–4）或工具名称。如果答案含糊不清，请再次询问，绝不要猜测。

验收标准（继续执行步骤 1 前，必须全部满足）

• 在当前调用过程中，四个选项已在本轮或先前轮次中提供给用户。
• 用户已明确回复以下其中一项：1、2、3、4、Claude Code、GitHub Copilot、Cursor AI 或 Opencode。
• 你尚未读取任何项目文件、列出任何目录或运行任何 Bash 命令。

如果任何标准未满足，返回步骤 0 开始处并再次提问。

选项对应表

用户回答后，将以下值保存在内部，供后续每个步骤使用：

选项	AI 工具	配置文件	Skills 目录	Agents 目录	Commands 目录
1	Claude Code	CLAUDE.md	.claude/skills/	.claude/agents/	.claude/commands/
2	GitHub Copilot	.github/copilot-instructions.md	.github/	.github/agents/	.github/prompts/
3	Cursor AI	.cursor/rules/project.mdc（如果用户明确要求使用旧版格式，则为 .cursorrules）	.agents/skills/、.cursor/skills/	.cursor/agents/	.cursor/commands/
4	Opencode	AGENTS.md	.agents/skills/	.opencode/agents/	.opencode/commands/

只有在用户明确选择一个选项后，才能使用所选工具的路径和约定继续执行步骤 1。

步骤 1：初始化项目配置 初始化策略取决于用户在步骤 0 中选择的 AI 工具：

• Claude Code：执行 /init 技能/命令以生成初始的 CLAUDE.md。等待其完成后再继续。
• Opencode：没有可用于初始化的 Bash CLI（opencode init 不是有效命令——opencode 的 CLI 会将第一个位置参数解释为项目路径，因此 opencode init 会尝试切换到名为 init 的目录并失败）。如果项目根目录中不存在 AGENTS.md，请直接使用 Write 工具创建该文件。任何情况下都不要通过 Bash 调用 opencode init。
• GitHub Copilot：没有内置的初始化命令。如果 .github/copilot-instructions.md 不存在，请创建它。
• Cursor AI：创建步骤 0 中确定的配置文件：
  • 如果使用 .cursor/rules/project.mdc：如有需要，创建 .cursor/rules/ 目录，然后创建文件，并添加以下 frontmatter 标头：

    ---
    description: 面向开发编排器的项目说明和约定
    globs:
    alwaysApply: true
    ---
    
    

  • 如果使用 .cursorrules（旧版）：在项目根目录创建该文件。

对于所有工具：如果配置文件已存在，请继续执行步骤 2，不要覆盖它。 步骤 2：深入分析项目

1. 阅读步骤 0 中确定路径下的项目配置文件，以及（如果存在）README.md。
2. 阅读根目录中的配置文件（如果存在）：package.json、go.mod、pom.xml、build.gradle、build.gradle.kts、docker-compose.yml、tsconfig.json、settings.gradle、.nvmrc、Makefile、Dockerfile。
3. 递归扫描目录结构，忽略：
   • 依赖项：node_modules/、.venv/、venv/、vendor/、.gradle/、.m2/
   • 构建产物：target/、build/、dist/、out/、.next/、__pycache__/
   • 隐藏项：任何以 . 开头的路径（.claude/、.github/ 和 .cursor/ 除外）
   • 二进制文件/媒体文件：*.jar、*.class、*.png、*.jpg、*.pdf
4. 阅读各层的代表性文件（例如控制器、用例、仓库），以了解项目采用的模式。
5. 生成内部摘要，包括：
   • 主要技术栈及版本
   • 采用的架构（Clean Arch、MVC、DDD 等）
   • 命名和组织模式
   • 系统用途
   • 外部集成（队列、数据库、API）
6. 检查测试基础设施：
   • 在 package.json（或该技术栈的等效文件）中查找 test 脚本。
   • 搜索测试文件（*.test.*、*.spec.*、__tests__/、test/、tests/）。
   • 如果两者都未找到，则在项目配置文件输出中加入："⚠️ AVISO: Nenhuma infraestrutura de testes detectada. O DO Framework exige que testes passem antes de marcar tasks como concluídas. Configure um test runner antes de usar do-execute-task."

步骤 3：识别相关技能

1. 扫描与用户在步骤 0 中选择的 AI 工具对应的技能目录，列出所有可用技能：
   • Claude Code：.claude/skills/
   • Opencode：.agents/skills/
   • GitHub Copilot：.github/（查找指令文件）
   • Cursor AI：.agents/skills/ 和 .cursor/skills/（每项技能都包含一个 SKILL.md），以及 .cursor/rules/（扫描所有 .mdc 文件） 列出找到的每个技能/规则文件，并阅读其内容。
2. 完全排除所有 do-* 技能——它们是内部工作流技能，绝不能出现在任何输出内容中。只评估技术/库相关技能（例如 claude-api、find-skills）。
3. 对每项剩余（非 do-*）技能，阅读其描述文件（技能为 SKILL.md，Cursor 规则为 .mdc 内容）。
4. 根据步骤 2 的摘要，评估该技能是否与项目相关。
5. 符合以下至少一项的技能即为相关：
   • 涵盖项目的主要语言或框架
   • 涵盖采用的架构
   • 涵盖已识别的模式或集成（队列、数据库、API 等）

步骤 4：更新项目配置文件 将以下各节合并到步骤 0 中确定路径下的项目配置文件。保留所有现有内容，仅追加或更新以下各节。

给 Agent 的指令（不要写入生成的文件）： 在 ## Available Skills 部分中，只写 IMPORTANT 段落、示例和表格。绝不能在表格中包含 do-* 技能（do-setup、do-create-prd、do-create-techspec、do-create-tasks、do-execute-task、do-execute-review、do-execute-qa 等）。IMPORTANT 段落为必填项——不要省略或改写。

## Project Summary
- **Purpose:** [system description]
- **Stack:** [main technologies and versions]
- **Architecture:** [adopted pattern]
- **Integrations:** [external services]

## Available Skills
**IMPORTANTE: Antes de iniciar qualquer tarefa, leia o arquivo da skill correspondente à tecnologia ou padrão envolvido usando a ferramenta de leitura de arquivos disponível na sua plataforma. As skills contêm convenções, restrições e padrões obrigatórios para este projeto — não prossiga sem lê-las.**

Exemplo: para trabalhar com [primeira-tecnologia], leia o arquivo `[caminho-da-primeira-skill]` antes de qualquer implementação.

| Skill | Caminho | Quando usar |
|-------|---------|-------------|
| [name] | [skills-dir]/[skill]/SKILL.md | [usage context] |

## Uncovered Skills
| Tecnologia | Observação |
|------------|------------|
| [e.g., Java/Quarkus] | Nenhuma skill disponível localmente — adicione manualmente ao diretório de skills |

## Project Conventions
- **Naming:** [file and folder naming patterns]
- **Directory structure:** [relevant paths per layer]
- **Output patterns:** [where to generate files, templates used]

步骤 5：安装编排 Agent 和命令 根据用户在步骤 0 中选择的 AI 工具，安装 agent-execute-task 工作子 Agent 和用于编排的斜杠命令。队列的编排逻辑位于不同位置，具体取决于 AI 工具对子 Agent 嵌套策略的规定：

在每款受支持的 AI 工具中，编排循环都位于斜杠命令/提示词本身（由主 Agent 运行），且只安装 agent-execute-task 作为子 Agent。每项任务都通过平台的任务工具委派——嵌套层级恰好一层，所有工具均允许。

• Claude Code：从 v2.1 起，子 Agent 可以启动子 Agent（最多三层，CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH；文档），但队列仍由主 Agent 执行，因此每项任务都保持在一层深度，权限提示也会显示在主会话中。委派工具是 Agent（在 v2.1.63 中从 Task 更名而来；Task 仍是别名）。run_in_background 仅在部分模式下提供（在 claude -p 中可用，在启用了 fork 模式的交互式会话中不可用）：子 Agent 可以在后台启动，并通过完成通知报告结果，因此编排器必须先等待通知，再执行下一项任务。agent-execute-task 使用 disallowedTools: Agent 而非 tools 允许列表来阻止委派，因此仍可使用 MCP 工具（浏览器/E2E 测试所需），并通过 skills 预加载 do-execute-task 技能。
• Cursor、GitHub Copilot：子 Agent 默认不能启动其他子 Agent（Copilot 需要设置 chat.subagents.allowInvocationsFromSubagents=true，默认关闭；Cursor 自 2.5 起允许嵌套一层，但孙级 Agent 无法继续启动子 Agent）。
• Opencode：嵌套深度受 subagent_depth 限制（默认值为 1），并且只有在子 Agent 声明了 permission.task 时，它才会获得 subagent 工具（旧版本中名为 task）。不要将 agent-execute-task 标记为 hidden: true：从 opencode 2.1 起，隐藏的 Agent 会从 subagent 工具的“可用子 Agent”列表中省略，因此编排器无法看到工作 Agent。即使设置了 subagent_depth: 2，在孙级会话中触发的权限提示也可能永远不会在 TUI 中显示，导致队列一直等待。因此这里也不会安装 agent-execute-all-tasks 编排器。

命名约定：技能和命令保留 do- 前缀；Agent 使用 agent- 前缀，以避免与底层技能重名。

1. 仅在当前项目内解析 <skill-dir>。用户运行 npx skills add 时，模板会与 SKILL.md 一起复制。

   • 按顺序检查相对于项目根目录的以下路径，并使用第一个存在的路径：.agents/skills/do-setup、.claude/skills/do-setup。如果两者都不存在，则使用 npx skills add 在项目根目录内创建的 do-setup 目录。
   • 绝不可使用项目根目录之外的 do-setup 副本（例如 ~/projects/.agents/ 等父目录、全局/主目录技能目录或其他项目中的副本）。这些副本可能已过时，并会安装旧版编排器。不要从父目录运行递归 Glob 来查找它。
   • 完整性检查：<skill-dir>/agents/<tool>/agents/ 必须包含 agent-execute-task.md（GitHub Copilot 使用 agent-execute-task.agent.md），且不得包含任何 *execute-all-tasks* 文件。如果检查失败，说明副本已过时：停止操作，并告知用户在此项目中再次运行 npx skills add fabio-barboza/development-orchestrator。

2. 只执行与用户在步骤 0 中选择的 AI 工具相匹配的安装部分。不要为其他工具安装资源。

   Claude Code（用户选择了选项 1 时）：

   • 运行 mkdir -p .claude/agents .claude/commands
   • 将 <skill-dir>/agents/claude/agents/agent-execute-task.md 复制到 .claude/agents/agent-execute-task.md
   • 将 <skill-dir>/agents/claude/commands/do-execute-all-tasks.md 复制到 .claude/commands/do-execute-all-tasks.md
   • 不要复制任何 agent-execute-all-tasks.md——编排逻辑内置于斜杠命令中，因此每项任务都保持在一层子 Agent 深度。
   • 删除之前安装遗留的任何编排器 Agent（包括所有旧名称）：rm -f .claude/agents/agent-execute-all-tasks.md .claude/agents/do-execute-all-tasks.md .claude/agents/execute-all-tasks.md。 Cursor AI（如果用户选择了选项 3）：
   • 运行 mkdir -p .cursor/agents .cursor/commands
   • 将 <skill-dir>/agents/cursor/agents/agent-execute-task.md 复制到 .cursor/agents/agent-execute-task.md
   • 将 <skill-dir>/agents/cursor/commands/do-execute-all-tasks.md 复制到 .cursor/commands/do-execute-all-tasks.md
   • 不要复制任何 agent-execute-all-tasks.md——编排逻辑已嵌入斜杠命令中。
   • 删除之前安装留下的任何编排 Agent（包括所有旧名称）：rm -f .cursor/agents/agent-execute-all-tasks.md .cursor/agents/do-execute-all-tasks.md .cursor/agents/execute-all-tasks.md。

   GitHub Copilot（如果用户选择了选项 2）：

   • 运行 mkdir -p .github/agents .github/prompts
   • 将 <skill-dir>/agents/github/agents/agent-execute-task.agent.md 复制到 .github/agents/agent-execute-task.agent.md
   • 将 <skill-dir>/agents/github/prompts/do-execute-all-tasks.prompt.md 复制到 .github/prompts/do-execute-all-tasks.prompt.md
   • 不要复制任何 agent-execute-all-tasks.agent.md——编排逻辑已嵌入提示词中。
   • 删除之前安装留下的任何编排 Agent（包括所有旧名称）：rm -f .github/agents/agent-execute-all-tasks.agent.md .github/agents/do-execute-all-tasks.agent.md .github/agents/execute-all-tasks.agent.md。

   Opencode（如果用户选择了选项 4）：

   • 运行 mkdir -p .opencode/agents .opencode/commands
   • 将 <skill-dir>/agents/opencode/agents/agent-execute-task.md 复制到 .opencode/agents/agent-execute-task.md
   • 将 <skill-dir>/agents/opencode/commands/*.md 中的所有文件复制到 .opencode/commands/
   • 不要复制任何 agent-execute-all-tasks.md——编排逻辑已嵌入 /do-execute-all-tasks 命令中，且必须在主会话中运行。使用 subtask: true 将任务委派给编排子 Agent 的命令会形成两层嵌套：在默认设置（subagent_depth: 1）下会因 Subagent depth limit reached 而失败；即使设置 subagent_depth: 2，孙级 Agent 的权限提示也可能不会显示在 TUI 中，导致队列无限期卡住。
   • 删除之前安装留下的任何编排 Agent（包括所有旧名称）：rm -f .opencode/agents/agent-execute-all-tasks.md .opencode/agents/do-execute-all-tasks.md .opencode/agents/execute-all-tasks.md。

3. 在报告前验证安装：

   • 所选工具的 agents 目录中包含 agent-execute-task，且没有任何匹配 *execute-all-tasks* 的文件。
   • 已安装的 do-execute-all-tasks 命令/提示词与 <skill-dir> 中的模板逐字节完全相同（使用 cmp 比较）。对于 Opencode，文件中不得包含 subtask: true，frontmatter 中也不得包含 agent: 字段——否则队列会被路由到子 Agent 编排器。
   • 如果任何检查未通过，请修复（重新复制/删除）并再次验证。绝不要在仍安装有旧版编排器时报告成功。

4. 告知用户安装了哪些文件、对应哪个工具，以及作为源的 <skill-dir>。

5. 告知用户在运行 /do-execute-all-tasks（或任何新安装的命令）前重启 AI 工具。Claude Code 只会监视会话启动时已存在的 Agent 目录，因此在本次设置期间创建的 .claude/agents/ 在重启前不可见；其他工具也可能会缓存 Agent 和命令列表。在第 6 步的最终报告中加入此重启提示。

使用 Bash 运行 cp 命令。<skill-dir> 是第 1 项中解析出的项目本地 do-setup 目录（例如 .agents/skills/do-setup）。 步骤 6：报告结果并同步进度（必需）

1. 同步内部进度：更新项目配置文件后，使用 TaskUpdate 工具，将内部任务跟踪中的所有对应项目标记为 completed。
2. 验证产物路径：报告前，确认配置文件已写入步骤 0 中解析出的确切路径。重新读取文件，验证文件存在且包含预期内容。
3. 提供所执行设置的摘要，并以步骤 5 第 5 项中的重启提示结尾（在运行 /do-execute-all-tasks 之前重启 AI 工具）。
4. 合规检查：回复用户前，请确认：
   • 项目配置文件是否保存在正确的路径（步骤 0 中解析出的路径）？
   • 是否准确识别了项目技术栈和技能？
   • 阅读生成文件中的 ## Available Skills 部分，并确认表格前存在 **IMPORTANTE:** 段落。如果不存在，请在回复用户前插入该段落。

输出语言

所有生成的产物（项目配置文件章节、摘要）都必须使用巴西葡萄牙语（PT-BR）编写。仅代码示例、变量名称和文件路径保留英文。

错误处理

• 如果未找到配置文件（没有 package.json、go.mod 等），请告知用户项目可能尚未初始化，并询问项目技术栈。
• 如果项目配置文件不存在，请从头创建。
• 如果项目配置文件已存在，请合并新增章节，不要覆盖用户编写的内容——仅追加或更新步骤 4 中定义的章节。
• 如果技能目录为空或缺失，请报告没有可用技能，并建议用户安装技能。
• 如果目录扫描发现无法识别的项目结构，请记录发现的内容并向用户寻求指导。

参考

• 输出：项目配置文件（例如，Claude Code 使用 CLAUDE.md，Opencode 使用 AGENTS.md，GitHub Copilot 使用 .github/copilot-instructions.md，Cursor AI 使用 .cursor/rules/project.mdc 或 .cursorrules）
• 技能目录：
  • Claude Code：.claude/skills/（每个技能都包含一个 SKILL.md）
  • Opencode：.agents/skills/（每个技能都包含一个 SKILL.md）
  • GitHub Copilot：.github/（指令文件）
  • Cursor AI：.agents/skills/ 和 .cursor/skills/（每个技能都包含一个 SKILL.md）；规则位于 .cursor/rules/（带有 frontmatter 的 .mdc 文件）