Agents System Setup
ytthuan/agents-system-setup
Replique sistemas multi-agente entre 5 runtimes com segurança governada
Ver no GitHubAgent multi-runtime que bootstrapeia, atualiza e replica sistemas multi-agente em GitHub Copilot CLI, Claude Code, OpenCode e OpenAI Codex. Gera arquitetura completa com orquestração paralela, governança de segurança obrigatória e replicação bidirecional a partir de um skill único.
Instalação
npx convez-ai ytthuan/agents-system-setup1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Orquestração de equipes de agentes IA em múltiplos runtimes
- Governança de segurança e auditoria em sistemas multi-agente
- Replicação bidirecional de arquiteturas de agentes entre plataformas
Veredito

Ferramenta enterprise para orquestração complexa de sistemas multi-agente com forte foco em governança. Exige domínio técnico profundo e é mais útil em cenários de equipes distribuídas que precisam sincronizar agentes entre runtimes.
README
A tradução para o português deste README ainda está na fila.
agents-system-setup
- A multi-runtime plugin/skill package that bootstraps, updates, improves, upgrades, or replicates a complete multi-agent system across five supported runtimes: GitHub Copilot CLI, Claude Code, OpenCode, OpenAI Codex (CLI + App), and Gemini CLI artifact layouts — from a single skill, with a Canonical IR for bidirectional replication, parallel-aware orchestration, mandatory security/audit/architecture governance, version-stamped artifacts, and compact-by-default context output baked in.
What it generates
AGENTS.mdat repo root with a Read First section, Context Loading Policy, Directory Architecture, Agent Roster (with parallel-safety waves), Capability Matrix, Security & Audit Matrix, Threat Model, Architecture / Design Pattern Decisions, ADR Index, and Quality Gates.- Host-session Orchestration Operating Model + N specialized subagents — the host CLI session (Copilot CLI, Claude Code, OpenCode, Codex CLI, Gemini CLI) reads the new
## Orchestration Operating Modelsection inAGENTS.mdand adopts the orchestrator role directly. No runtime emits anorchestrator.agent.md/.claude/agents/orchestrator.md/.opencode/agents/orchestrator.md/.codex/agents/orchestrator.toml/.gemini/agents/orchestrator.mdsubagent file. Specialized subagents (3–50, sized to scope) are emitted in each runtime's native format with a fan-out clause so parallel-safe subagents always run in one wave.@orchestratorremains a routing alias for the host session. - A Plan Handoff Contract that normalizes VS Code Plan agent output, Spec-Kit
/plan, or user-written plans before emitting runtime-correct Copilot, Claude Code, OpenCode, Codex, or Gemini CLI artifacts. AGENT-TEAMS.mdfor Claude Code projects when the roster benefits from peer-to-peer teammates (3+ independent concerns).- Project-scoped skills under each runtime's conventional path.
- Curated plugin / MCP recommendations from vendor-official catalogs, every recommendation tagged
[Tier · Vendor]and opt-in per item. - Mandatory MCP approval gate — no MCP config is ever written without explicit user approval.
- Source-backed governance baseline — OWASP GenAI, NIST SSDF, MCP Security Best Practices, GitHub Code Security, SLSA, OPA, Azure Well-Architected, C4, and TOGAF (enterprise only).
- Code Quality & Maintainability standards — for software-dev projects, generated coding agents apply source-backed authoring craft while writing (Google Eng-Practices, ISO/IEC 25010, refactoring/code-smells, Clean Code concepts, McCabe complexity), leading with conform to the project's existing linters/conventions first. A read-only
code-quality-reviewerreports code smells; the host loads thecode-qualityskill before code edits. Complementary to the SDLC Build Gate (verification) and distinct from content-quality (generated-prose review). - Context-optimized output profiles —
Balancedby default, withCompactandFulloptions for generated files and summaries. - Artifact tracking choice — generated systems can be team-shared in git, local-only via
.git/info/exclude, or written to personal/global runtime paths. - Memory & Learning System — generated agents can load curated learnings, run a before-finish Learning Check, and propose durable project lessons without silently overwriting past memory.
- Runtime update audit — latest upstream drift is tracked in
plugins/agents-system-setup/skills/agents-system-setup/references/runtime-updates.mdfor all supported runtimes and future candidates. - Optional model overrides — opt-in only. The interview never asks about model selection by default; the question only surfaces when the user has spontaneously named a model or asked for BYOK/multi-model/cost-perf tuning. Per-runtime accepted formats, defaults, and source-linked rate-limit pointers live in
plugins/agents-system-setup/skills/agents-system-setup/references/models.md. - Version-stamped artifacts + central manifest. Every generated
AGENTS.md, subagent, and skill carries anagents-system-setup:generated-by: vX.Y.Zmarker;.agents-system-setup/generated.jsonrecords the authoritative version.upgrademode reads stamps and walks the per-version delta playbook to migrate old systems to the current principles non-destructively. - Sharper context engine — generated
AGENTS.mdincludes a Task-Type Routing Map, a context-freshness rule, and a single canonical Delegation Packet schema inreferences/handoff.mdso subagents skip duplicated reads and load only what each task tag needs. - Richer task assignments — host-orchestrator → subagent handoffs use a canonical Task Assignment Contract with required minimum + opt-in expansion blocks (Goal & Definition of Done, Scope, File Inventory, Background, Reproduction, Constraints, Assumptions, Known Risks, Verification Protocol, Reporting Protocol, Coordination, Size & Timebox, Clarification Protocol). Subagent templates ship with an Acceptance Checklist and Reporting Template so handoffs are well-structured by default.
- Gemini CLI artifact support — generated Gemini subagents use
.gemini/agents/*.mdor Gemini extensionagents/*.md; no Gemini plugin install command is claimed. - Cross-OS scripts (
.sh+.ps1),.gitattributesfor line-ending safety.
Modes
| Mode | When to use |
|---|---|
init | Brand-new repo, no agent artifacts |
update | Existing artifacts, regenerate managed blocks non-destructively |
improve | Audit existing system → propose checklist of targeted fixes → opt-in apply |
upgrade | Version-aware migration of an existing agent system to the current plugin's principles (reads agents-system-setup:generated-by stamps + .agents-system-setup/generated.json, walks per-version delta playbook). Trigger: /agents-system-setup upgrade or agents-system-setup upgrade |
replicate | Port agents/skills/MCP from one runtime to another (Copilot ↔ Claude ↔ OpenCode ↔ OpenAI Codex ↔ Gemini CLI) via Canonical IR |
Install — per runtime
Each runtime has a different install/use mechanism. The repo ships plugin manifests where a runtime supports them; Gemini CLI support is artifact-based and does not claim a plugin install.
GitHub Copilot CLI
copilot
> /plugin install ytthuan/agents-system-setup
> /agents-system-setup
Reads the root plugin.json and exposes the bundled skill as /agents-system-setup. Generated Copilot CLI specialized subagents apply a Standard Tool Profile by default — tools: [vscode, execute, read, agent, edit, search, todo] for edit-capable subagents, narrows to [read, search] for reviewers/auditors, and offers runner / research / inherit variants via interview Q9c. The orchestrator role lives in AGENTS.md (read by the host Copilot CLI session); no orchestrator subagent file is emitted.
Claude Code
claude
> /plugin install ytthuan/agents-system-setup
> /agents-system-setup:agents-system-setup
Reads .claude-plugin/plugin.json. Skills are namespaced as /<plugin>:<skill>. Source: https://docs.anthropic.com/en/docs/claude-code/plugins.
OpenAI Codex CLI install
codex plugin marketplace add ytthuan/agents-system-setup
codex
> /plugins # browse and install agents-system-setup
> /skills # list available skills from installed plugins
> $agents-system-setup # invoke the bundled skill
Reads .codex-plugin/plugin.json and the marketplace descriptor at .agents/plugins/marketplace.json. Source: https://developers.openai.com/codex/plugins/build.
After installing via /plugins, invoke the bundled skill with $agents-system-setup in the Codex CLI prompt, or use /skills to list and select skills interactively.
Generated Codex project artifacts are compatible with OpenAI Codex CLI + App surfaces that load repo artifacts: AGENTS.md contains project memory plus the host-session Orchestration Operating Model (orchestrator role), .codex/agents/*.toml contains specialized subagents, and .codex/config.toml contains [agents] defaults. Plugin marketplace install and slash-command examples above are CLI-only; generated repo artifacts remain compatible with both CLI and App. No .codex/agents/orchestrator.toml is emitted (Codex has always followed this pattern; v1.3.0 normalizes Copilot/Claude/OpenCode/Gemini to it).
OpenCode
OpenCode plugins are JS/TS hooks — not skill bundles — so install by clone-and-copy:
git clone https://github.com/ytthuan/agents-system-setup.git
cd agents-system-setup
./scripts/install-opencode.sh project # or "global"
Windows / cross-platform PowerShell:
git clone https://github.com/ytthuan/agents-system-setup.git
cd agents-system-setup
pwsh ./scripts/install-opencode.ps1 -Scope project
This places the skill at .opencode/skills/agents-system-setup/ (or ~/.config/opencode/skills/ for global).
Gemini CLI artifact support
Gemini CLI support is generated artifact support, not a plugin install. This repo does not publish or document a Gemini plugin installation command. Generate or copy Gemini artifacts into the target project, then run Gemini CLI normally:
# Project-local generated subagents
ls .gemini/agents/
gemini
Inside Gemini CLI, invoke generated subagents with Gemini's agent invocation syntax, for example @<agent-name>. Supported artifact shapes are project .gemini/agents/*.md, user ~/.gemini/agents/*.md, and extension-bundled agents/*.md when packaging a Gemini extension yourself.
Usage
Once installed, invoke the skill — no arguments needed; it auto-detects mode:
/agents-system-setup
Or be explicit:
/agents-system-setup init
/agents-system-setup update
/agents-system-setup improve
/agents-system-setup replicate
For Gemini CLI, there is no /plugin install or /agents-system-setup command documented by this repo. Use Gemini normally after generated .gemini/agents/*.md artifacts are present, then call the generated subagents with @<agent-name>.
Wizard flow
The wizard starts by detecting the current repo, then shows a compact profile: existing agent artifacts, recommended mode, inferred project type, and target runtime defaults. For low-risk repos, you can accept detected/safe defaults for non-gated setup questions. The wizard still asks explicitly for artifact tracking, MCP/config approvals, plan approval, and security-sensitive writes.
Agent behavior choices are grouped together: optional model overrides, Copilot
CLI tool profile, output detail (Balanced by default), and Memory & Learning
profile. Model overrides are opt-in and scoped by all agents, role, or
exceptions so large rosters do not trigger one prompt per agent.
Parallel subagents & Claude Code agent teams
The host CLI session orchestrator always fans out parallel-safe subagents in one wave (multiple Task calls in a single response), then awaits before the next wave. Parallel-safety is computed automatically from the Directory Architecture — see parallelism reference.
For Claude Code, when 3+ subagents are independent and would benefit from peer-to-peer challenge, the generator additionally emits AGENT-TEAMS.md with the opt-in env var (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1), settings snippet, suggested teammate roster, and a token-cost warning. Source: https://docs.anthropic.com/en/docs/claude-code/agent-teams.
Context optimization
Generated output is compact by default. The skill asks for an output profile (Balanced, Compact, or Full) and records where long detail lives. AGENTS.md stays the routing and policy index; exhaustive marketplace research, long threat rationale, full ADR text, and platform schema detail are linked as references instead of repeated in every agent file.
Local-only vs git-tracked agents
Before writing project-scoped agent files, the skill asks whether artifacts should be git-tracked, local-only, or personal/global. Local-only project artifacts are hidden through .git/info/exclude in the current checkout, not .gitignore, so team ignore rules are not changed accidentally.
Why a plugin (not a bare skill)?
- A skill is the unit of capability.
- A plugin is the distribution unit.
- Wrapping the skill in plugin manifests for installable runtimes makes it one-line installable on Copilot CLI / Claude Code / Codex CLI, clone-and-copy installable on OpenCode, and able to generate artifact-only support for Gemini CLI.
Repo layout
agents-system-setup/
├── plugin.json # Copilot CLI manifest
├── .claude-plugin/plugin.json # Claude Code manifest
├── .codex-plugin/plugin.json # Codex CLI plugin manifest
├── .agents/plugins/marketplace.json # Codex marketplace descriptor
├── scripts/
│ ├── install-opencode.sh # OpenCode installer (POSIX)
│ └── install-opencode.ps1 # OpenCode installer (PowerShell)
├── plugins/
│ └── agents-system-setup/
│ ├── .claude-plugin/plugin.json
│ ├── .codex-plugin/plugin.json
│ └── skills/
│ └── agents-system-setup/
│ ├── SKILL.md
│ ├── references/ # platforms, marketplaces, replication, governance, …
│ ├── assets/ # AGENTS.md + agent/skill templates
│ └── scripts/ # git-init.sh + .ps1, link-project-memory.sh + .ps1
├── README.md
├── DESIGN.md # rationale per phase / hard rule
├── CHANGELOG.md
├── LICENSE # MIT
├── .gitignore
└── .gitattributes
Compatibility
| Runtime | Plugin install | Artifact / skill format compatible | Parallel subagents | Agent teams |
|---|---|---|---|---|
| GitHub Copilot CLI | ✅ /plugin install | ✅ | ✅ | n/a |
| Claude Code | ✅ /plugin install | ✅ | ✅ | ✅ (opt-in env var) |
| OpenAI Codex (CLI + App artifacts) | ✅ CLI: marketplace add + /plugins | ✅ via AGENTS.md + .codex/agents/*.toml | ✅ | n/a |
| OpenCode | ⚠️ clone + script copy | ✅ | ✅ | n/a |
| Gemini CLI | ❌ no plugin install claimed | ✅ via .gemini/agents/*.md / extension agents/*.md artifacts | ✅ with non-recursive subagent use | n/a |
Cross-OS: Linux, macOS, Windows (native PowerShell + Git Bash + WSL).
Gemini CLI note: Gemini CLI now has official subagent docs; this repo documents it as supported artifact-first rather than candidate-only. Do not use or document a Gemini plugin install unless Gemini publishes compatible plugin-install semantics and this repo adds matching manifests.
Design rationale
The procedure is intentional, not arbitrary. See DESIGN.md for the reasoning behind every phase (why interview-first, why MCP gate, why Canonical IR, why per-item opt-in, why parallel-by-default).
Contributing
PRs welcome. The skill is documented heavily in plugins/agents-system-setup/skills/agents-system-setup/references/. New marketplace sources go in references/marketplaces.md with a [Tier · Vendor] tag.
License
MIT — see LICENSE.