do-setup

Project Setup

Role

You are a senior developer advocate responsible for project initialization, tooling configuration, and ensuring the agent-assisted development environment is correctly set up.

Autonomous Execution Policy

CRITICAL: NEVER pause, stop, or wait for user input during execution. Proceed through ALL steps autonomously without asking the user to "continue", "proceed", or confirm intermediate results. The ONLY acceptable reasons to stop and ask the user are:

The mandatory initial AI tool selection question (Step 0). This is the FIRST action the skill performs and is always required.
When there is a genuine doubt or ambiguity that cannot be resolved by reading the project files.

Execution Constraints

CRITICAL: This skill MUST NOT execute the application, run tests, start servers, compile code, or perform any runtime validation. Its sole purpose is to analyze the project structure and produce the configuration document. All analysis must be done by reading files and inspecting the directory structure — never by running the application.

Procedures

Preamble: Parse Invocation Argument Check if the user invoked this skill with the argument agents (e.g., /do-setup agents).

If the argument is agents: set mode = agents-only. Skip Steps 1–4 and 6. Execute only Step 0 (AI tool selection) and Step 5 (install agents).
If no argument or any other argument: set mode = full. Execute all steps in order.

Step 0: Ask the User Which AI Tool to Configure (MANDATORY FIRST ACTION — HARD STOP)

⛔ HARD STOP — DO NOT SKIP THIS QUESTION UNDER ANY CIRCUMSTANCE.

This question is the very first action of the skill. It is MANDATORY even when:

you (the model) are running inside OpenCode, Claude Code, Cursor, or GitHub Copilot — the host you are running in is IRRELEVANT to the answer; the user may want to configure THIS project for a DIFFERENT tool;

the project already contains .claude/, .opencode/, AGENTS.md, .cursor/, .github/, opencode.json, CLAUDE.md, or any other tool-specific file or directory — these signals are forbidden inputs for this decision;

the user appears to have a "default" tool from prior conversations or memory — ignore it; ask again every time.

❌ DO NOT auto-detect, infer, guess, default, pre-fill, or assume the answer. ❌ DO NOT announce the answer and ask for confirmation ("I'll assume Opencode — ok?"). That is still skipping the question. ❌ DO NOT read any project file or run any directory listing before asking. ✅ DO stop execution right now and ask the user the question below verbatim.

The question to ask (verbatim)

Present these four options to the user, exactly:

Para qual ferramenta agêntica o projeto deve ser configurado?

Claude Code — gera CLAUDE.md, usa .claude/skills/, instala agentes em .claude/agents/ e comandos em .claude/commands/.

GitHub Copilot — gera .github/copilot-instructions.md, usa .github/ para instruções, instala agentes em .github/agents/ e prompts em .github/prompts/.

Cursor AI — gera .cursor/rules/project.mdc (ou .cursorrules legado), usa .cursor/rules/, instala agentes em .cursor/agents/ e comandos em .cursor/commands/.

Opencode — gera AGENTS.md, usa .agents/skills/, instala agentes em .opencode/agents/ e comandos em .opencode/commands/.

How to ask

If the host provides a structured question tool (e.g., AskUserQuestion in Claude Code), use it with these four options.
Otherwise, emit the four numbered options as plain text in your reply and end the turn immediately. Do not call any other tool, do not read files, do not write anything. Yield control to the user and wait for their reply.
After yielding, the next user message is the answer. Accept the option number (1–4) or the tool name. If the answer is ambiguous, ask again — never guess.

Acceptance criteria (you must satisfy ALL before proceeding to Step 1)

The four options were presented to the user in this turn or a previous turn of the current invocation.
The user has explicitly replied with one of: 1, 2, 3, 4, Claude Code, GitHub Copilot, Cursor AI, or Opencode.
You have NOT read any project file, listed any directory, or run any Bash command yet.

If any criterion is unmet, return to the top of Step 0 and ask again.

Resolution table

Once the user answers, store these values internally for use in every subsequent step:

Option	AI Tool	Config file	Skills directory	Agents directory	Commands directory
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` (or `.cursorrules` if the user explicitly asks for the legacy format)	`.cursor/rules/`	`.cursor/agents/`	`.cursor/commands/`
4	Opencode	`AGENTS.md`	`.agents/skills/`	`.opencode/agents/`	`.opencode/commands/`

Only after the user has explicitly selected one option, continue to Step 1 using the selected tool's paths and conventions consistently.

Step 1: Initialize Project Configuration The initialization strategy depends on the AI tool selected by the user in Step 0:

Claude Code: Execute the /init skill/command to generate the initial CLAUDE.md. Wait for it to complete before proceeding.
Opencode: No bash CLI available for initialization (opencode init is not a valid command — opencode's CLI interprets the first positional argument as a project path, so opencode init would try to cd into a directory named init and fail). Create AGENTS.md at the project root directly using the Write tool if it doesn't exist. Do not invoke opencode init via Bash under any circumstances.
GitHub Copilot: No built-in init command. Create .github/copilot-instructions.md if it doesn't exist.
Cursor AI: No built-in init command. Create the config file as determined in Step 0:
- If using .cursor/rules/project.mdc: create the .cursor/rules/ directory if needed, then create the file with the following frontmatter header:
```
---
description: Project instructions and conventions for the development orchestrator
globs:
alwaysApply: true
---
```
- If using .cursorrules (legacy): create the file at the project root.

For all tools: if the config file already exists, proceed to Step 2 without overwriting it.

Step 2: Deep Project Analysis

Read the project configuration file at the path determined in Step 0, and README.md if it exists.
Read root config files if they exist: package.json, go.mod, pom.xml, build.gradle, build.gradle.kts, docker-compose.yml, tsconfig.json, settings.gradle, .nvmrc, Makefile, Dockerfile.
Scan directory structure recursively, ignoring:
- Dependencies: node_modules/, .venv/, venv/, vendor/, .gradle/, .m2/
- Build: target/, build/, dist/, out/, .next/, __pycache__/
- Hidden: any path starting with . (except .claude/, .github/, and .cursor/)
- Binaries/media: *.jar, *.class, *.png, *.jpg, *.pdf
Read representative files from each layer (e.g., a controller, a use case, a repository) to understand adopted patterns.
Build an internal summary with:
- Main stack and versions
- Adopted architecture (Clean Arch, MVC, DDD, etc.)
- Naming and organization patterns
- System purpose
- External integrations (queues, databases, APIs)
Check test infrastructure:
- Look for a test script in package.json (or equivalent for the stack).
- Scan for test files (*.test.*, *.spec.*, __tests__/, test/, tests/).
- If neither is found, include in the project configuration file output: "⚠️ 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."

Step 3: Identify Relevant Skills

List all available skills by scanning the skills directory corresponding to the AI tool the user selected in Step 0:
- Claude Code: .claude/skills/
- Opencode: .agents/skills/
- GitHub Copilot: .github/ (look for instruction files)
- Cursor AI: .cursor/rules/ (scan all .mdc files) List every skill/rule file found and read its content.
EXCLUDE all do-* skills entirely — they are internal workflow skills and must NOT appear anywhere in the output artifact. Only evaluate technology/library skills (e.g., claude-api, find-skills).
For each remaining (non-do-*) skill, read its descriptor file (SKILL.md for Claude Code, the .mdc content for Cursor AI).
Based on the Step 2 summary, evaluate if the skill is relevant to the project.
A skill is relevant if it covers at least one of:
- The project's primary language or framework
- The adopted architecture
- An identified pattern or integration (queues, database, API, etc.)

Step 4: Update the project configuration file Merge the following sections into the project configuration file at the path determined in Step 0. Preserve all existing content and append or update only the sections below.

Instrução ao agente (não incluir no arquivo gerado): Na seção ## Available Skills, escreva SOMENTE o parágrafo IMPORTANTE, o exemplo e a tabela. Nunca inclua skills do-* (do-setup, do-create-prd, do-create-techspec, do-create-tasks, do-execute-task, do-execute-review, do-execute-qa, etc.) na tabela. O parágrafo IMPORTANTE é obrigatório — não omita, não parafraseie.

## 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]

Step 5: Install Orchestration Agents & Commands Based on the AI tool selected by the user in Step 0, install the agent-execute-task worker subagent and the slash command for orchestration. The orchestration logic of the queue lives in different places depending on the AI tool's subagent nesting policy:

In every supported AI tool the orchestration loop lives inside the slash command/prompt itself (running on the main/primary agent), and only agent-execute-task is installed as a subagent. Each task is delegated via the platform's task tool — exactly one nesting level, which every tool allows.

Claude Code, Cursor, GitHub Copilot: subagents cannot spawn other subagents by default (Claude Code docs; Copilot requires chat.subagents.allowInvocationsFromSubagents=true, off by default; Cursor allows one nesting level since 2.5, but a grandchild cannot launch further subagents).
Opencode: nesting is capped by subagent_depth (default 1), and a subagent only receives the task tool if it declares permission.task. Even with subagent_depth: 2, permission prompts raised inside a grandchild session may never render in the TUI — the queue then waits forever. So no agent-execute-all-tasks orchestrator is installed here either.

Naming convention: skills and commands keep the do- prefix; agents use the agent- prefix to avoid name collisions with the underlying skill.

Resolve <skill-dir> inside the current project only. The templates were copied alongside the SKILL.md when the user ran npx skills add.
- Check these paths, in order, relative to the project root, and use the first that exists: .agents/skills/do-setup, .claude/skills/do-setup. If neither exists, use the do-setup directory that npx skills add created inside the project root.
- NEVER use a do-setup copy outside the project root (parent directories such as ~/projects/.agents/, global/home skill directories, other projects). Those copies can be stale and install an obsolete orchestrator. Do not run a recursive Glob from a parent directory to find it.
- Sanity check: <skill-dir>/agents/<tool>/agents/ must contain agent-execute-task.md (agent-execute-task.agent.md for GitHub Copilot) and must not contain any *execute-all-tasks* file. If the check fails, the copy is stale: STOP and tell the user to run npx skills add fabio-barboza/development-orchestrator again in this project.
Execute only the installation block that matches the AI tool selected by the user in Step 0. Do not install assets for other tools.

Claude Code (if the user selected option 1):
- Run mkdir -p .claude/agents .claude/commands
- Copy <skill-dir>/agents/claude/agents/agent-execute-task.md → .claude/agents/agent-execute-task.md
- Copy <skill-dir>/agents/claude/commands/do-execute-all-tasks.md → .claude/commands/do-execute-all-tasks.md
- Do NOT copy any agent-execute-all-tasks.md — orchestration is embedded in the slash command (Claude Code does not allow subagents to spawn other subagents).
- Delete any orchestrator agent left by previous installs (all legacy names): rm -f .claude/agents/agent-execute-all-tasks.md .claude/agents/do-execute-all-tasks.md .claude/agents/execute-all-tasks.md.
Cursor AI (if the user selected option 3):
- Run mkdir -p .cursor/agents .cursor/commands
- Copy <skill-dir>/agents/cursor/agents/agent-execute-task.md → .cursor/agents/agent-execute-task.md
- Copy <skill-dir>/agents/cursor/commands/do-execute-all-tasks.md → .cursor/commands/do-execute-all-tasks.md
- Do NOT copy any agent-execute-all-tasks.md — orchestration is embedded in the slash command.
- Delete any orchestrator agent left by previous installs (all legacy names): rm -f .cursor/agents/agent-execute-all-tasks.md .cursor/agents/do-execute-all-tasks.md .cursor/agents/execute-all-tasks.md.
GitHub Copilot (if the user selected option 2):
- Run mkdir -p .github/agents .github/prompts
- Copy <skill-dir>/agents/github/agents/agent-execute-task.agent.md → .github/agents/agent-execute-task.agent.md
- Copy <skill-dir>/agents/github/prompts/do-execute-all-tasks.prompt.md → .github/prompts/do-execute-all-tasks.prompt.md
- Do NOT copy any agent-execute-all-tasks.agent.md — orchestration is embedded in the prompt.
- Delete any orchestrator agent left by previous installs (all legacy names): 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 (if the user selected option 4):
- Run mkdir -p .opencode/agents .opencode/commands
- Copy <skill-dir>/agents/opencode/agents/agent-execute-task.md → .opencode/agents/agent-execute-task.md
- Copy all <skill-dir>/agents/opencode/commands/*.md → .opencode/commands/
- Do NOT copy any agent-execute-all-tasks.md — orchestration is embedded in the /do-execute-all-tasks command and must run in the primary session. Um command com subtask: true delegando a um orquestrador subagente cria dois níveis de aninhamento: falha com Subagent depth limit reached no default (subagent_depth: 1) e, mesmo com subagent_depth: 2, prompts de permissão do neto podem não aparecer na TUI e a fila trava indefinidamente.
- Delete any orchestrator agent left by previous installs (all legacy names): rm -f .opencode/agents/agent-execute-all-tasks.md .opencode/agents/do-execute-all-tasks.md .opencode/agents/execute-all-tasks.md.
Verify the installation before reporting:
- The agents directory of the selected tool contains agent-execute-task and no file matching *execute-all-tasks*.
- The installed do-execute-all-tasks command/prompt is byte-identical to the template in <skill-dir> (compare with cmp). For Opencode, it must not contain subtask: true nor an agent: field in the frontmatter — that would route the queue to a subagent orchestrator.
- If any check fails, fix it (re-copy / delete) and verify again. Never report success with a legacy orchestrator installed.
Confirm to the user which files were installed, for which tool, and the <skill-dir> used as source.

Use Bash to run cp commands. <skill-dir> is the project-local do-setup directory resolved in item 1 (e.g. .agents/skills/do-setup).

Step 6: Report Results & Sync Progress (Mandatory)

SYNC INTERNAL PROGRESS: Once the project configuration file is updated, use the TaskUpdate tool to mark all corresponding items in your internal task tracking as completed.
ARTIFACT PATH VERIFICATION: Before reporting, confirm the config file was written to the exact path resolved in Step 0. Read the file back to verify it exists and contains the expected content.
Provide a summary of the setup performed.
COMPLIANCE CHECK: Before responding to the user, verify:
- Is the project configuration file saved at the correct path (resolved in Step 0)?
- Did you accurately identify the project stack and skills?
- Leia a seção ## Available Skills no arquivo gerado e confirme que o parágrafo **IMPORTANTE:** está presente antes da tabela. Se não estiver, insira-o agora antes de responder ao usuário.

Output Language

Todos os artefatos gerados (seções do arquivo de configuração do projeto, resumos) devem ser escritos em Português do Brasil (PT-BR). Apenas exemplos de código, nomes de variáveis e caminhos de arquivos permanecem em inglês.

Error Handling

If no config files are found (no package.json, go.mod, etc.), warn the user that the project may not be initialized and ask for clarification about the stack.
If the project configuration file does not exist, create it from scratch.
If the project configuration file already exists, merge new sections without overwriting user-written content — append or update only the sections defined in Step 4.
If the skills directory is empty or missing, report that no skills are available and suggest the user install skills.
If the directory scan reveals an unrecognizable project structure, document what was found and ask the user for guidance.

References

Output: Project configuration file (e.g., CLAUDE.md for Claude Code, AGENTS.md for Opencode, .github/copilot-instructions.md for GitHub Copilot, .cursor/rules/project.mdc or .cursorrules for Cursor AI)
Skills directories:
- Claude Code: .claude/skills/ (each skill has a SKILL.md)
- Opencode: .agents/skills/ (each skill has a SKILL.md)
- GitHub Copilot: .github/ (instruction files)
- Cursor AI: .cursor/rules/ (.mdc files with frontmatter)