convez.ai
AgenteDevOps & InfraestruturaAvançado
JDev-il

Multi Agents

JDev-il/multi-agents

Orquestração multi-agente com git worktrees para desenvolvimento full-stack paralelo

Ver no GitHub
InicialPluginScore · de 0 a 100

Orquestrador de workflow multi-agente para Claude Code com git worktrees isolados, rastreamento de estado estruturado e encadeamento autônomo de tarefas. Permite que múltiplos agentes trabalhem em paralelo em diferentes partes da aplicação (client, backend, segurança) sem conflitos, cada um em sua própria branch isolada.

Instalação

$npx convez-ai JDev-il/multi-agents

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 semana
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Desenvolvimento full-stack coordenado com múltiplos agentes Claude trabalhando simultaneamente
  • Scaffolding de projetos estruturado com Next.js, Express, NestJS e outras frameworks
  • Automação de tarefas de desenvolvimento (UI, lógica, testes, autenticação) em paralelo isolado

Veredito

Ferramenta robusta de orquestração para equipes que usam Claude para coding em larga escala. Elimina conflitos de merge através de worktrees isolados e rastreamento explícito de estado, mas exige disciplina no workflow (sem commits diretos em main). Ideal para projetos full-stack complexos.

README

A tradução para o português deste README ainda está na fila.

Multi Agents

Multi-agent workflow orchestration for Claude Code — isolated git worktrees, structured state tracking, autonomous task chaining.


Install

npm install -g multi-agents-cli

Quickstart

multi-agents init my-project
cd my-project
npm run agent

multi-agents init will:

  • Guide you through project name, stack, IDE, and build trajectory using arrow-key selection
  • Fetch all templates and workflow scripts from multi-agents-core
  • Generate BUILD_STATE.md, CONTRACTS.md, CLAUDE.md
  • Generate .scaffold/.paths.json with expected framework paths
  • Initialize agent tracking (.scaffold/.tracking.json)
  • Install prompts dependency for arrow-key navigation
  • Set up git remote handling (first agent session handles this automatically)

Workflow

1. Launch a task

npm run agent

Select scope → agent → describe the task (or press Enter for default) → workspace opens in your IDE automatically.

The agent reads TASK.md and executes autonomously.

2. Agent completes the task

The agent commits its work and runs npm run complete autonomously. This merges the branch into main, updates BUILD_STATE.md, and clears the tracking slot.

3. Repeat

npm run complete chains back to npm run agent. Pick the next agent and continue building.


Build Trajectories

Choose during multi-agents init:

Multi-Agent Driven Orchestration (recommended) Every task should start with npm run agent. Each agent works in its own git worktree — an isolated branch and folder that merges back into main via npm run complete. Faster builds and lower token spend than a single long session. ⚠ If you commit directly to main yourself, you bypass the framework and break task tracking for any active agent branches.

Shared Orchestration You and agents co-build — each owning a defined part of the codebase. Agent tasks run in git worktrees; your work happens directly in the project. Define boundaries before work begins. ⚠ If you and an agent touch the same file, expect merge conflicts.


Supported Frameworks

Client

Next.js · Angular · Vue/Nuxt · SvelteKit · Vite+React · Remix

Backend (separate)

Express · NestJS · Fastify · FastAPI · Django

Each framework has a dedicated scaffold instruction file in client/frameworks/ and backend/frameworks/ — agents read these before scaffolding to ensure files land in the correct location.


Agent Roster

Client

AgentDefault taskRequires
UIScaffolds full project structure—
LOGICState management, API integration, hooksUI ✓
FORMSForm components, validation, submissionUI ✓
ROUTINGPage routing, navigation, URL structureUI ✓
TESTINGUnit and integration testsUI ✓
ACCESSIBILITYa11y compliance, keyboard navigationUI ✓

Backend (separate only)

AgentDefault taskRequires
APIREST/GraphQL endpoints — start here—
LOGICBusiness logic, services, data processingAPI ✓
AUTHAuthentication, authorization, sessionsAPI ✓
DBDatabase schemas, migrations, queries—
EVENTSEvent queues, pub/sub, webhooksAPI ✓
JOBSBackground jobs, scheduled tasksAPI ✓
TESTINGAPI and integration testsAPI ✓

Shared

AgentDefault task
SECURITYShared auth utilities, encryption, validation

Start with UI (client) or API (backend). The launcher recommends the correct next agent dynamically based on what's already completed.


Running the App

After agents complete their tasks and merge into main:

cd client
npm install
npm run dev

For deployment (Vercel, Netlify etc.) set the root directory to client/ — not the repo root.


Remote Setup

multi-agents init does NOT configure a GitHub remote. Your first agent session handles remote setup automatically:

  1. Checks SSH, gh CLI, and HTTPS credentials in order
  2. If a remote repo exists — evaluates its state (orphaned branches, completion status, age)
  3. Auto-clears old sessions or surfaces a decision when unfinished work is detected
  4. If no remote — opens your browser to github.com/new with the repo name pre-filled

No manual git remote add needed.


Key Files

FilePurpose
CLAUDE.mdGlobal coordination rules — every agent reads this first
BUILD_STATE.mdLiving project state — what's built, what's next
CONTRACTS.mdShared types and interfaces — single source of truth
TASK.mdPer-task instructions — lives in the agent's worktree
.scaffold/.config.jsonProject config written at init time
.scaffold/.tracking.jsonActive agent state — managed by workflow scripts
.scaffold/.paths.jsonExpected and actual framework paths — updated by agents after scaffolding

Never edit BUILD_STATE.md directly. npm run complete owns all updates to it. Editing it in a worktree causes merge conflicts.


CLAUDE.md Waterfall

Context loads in this order for every agent:

Root CLAUDE.md             ← global rules, protocols, tracking schema
        ↓
client/CLAUDE.md           ← stack config, framework scaffold instructions
        ↓
client/frameworks/{fw}.md  ← exact scaffold commands and path conventions
        ↓
agents/UI.md               ← agent-specific behavior and constraints
        ↓
TASK.md                    ← the specific task to execute

Each layer narrows scope. Agents never need to be told what framework or language to use — it's resolved from config automatically.


Guard System

The launcher enforces structural rules before any worktree is created:

  • Skeleton guard — LOGIC/FORMS/ROUTING/TESTING require UI completed first
  • Prerequisite check — surfaces unmet dependencies, lets you proceed or repick
  • Active agent gate — if the same agent is already running, offers Continue / Complete / Abandon / Pick again
  • MISSING gate — if a worktree was deleted without completing, mandatory Recover or Reset decision
  • Coexistence check — if recovering, surfaces file conflicts and divergence before restoring

Tracking

.scaffold/.tracking.json is the runtime state ledger:

{
  "client": {
    "UI": {
      "branch": "agent/client/ui/1780403456467",
      "status": "ACTIVE",
      "launchedAt": "2026-06-04T10:21:00Z",
      "missingCount": 0,
      "worktreePath": "/path/to/worktrees/..."
    }
  }
}

Status values: null (never launched) · ACTIVE (running) · MISSING (worktree deleted without completing)

Managed entirely by agent.js and complete.js. Never edit manually.


Path Tracking

.scaffold/.paths.json maps expected and actual framework paths:

{
  "client": {
    "typesDir": {
      "expected": "client/src/types",
      "current": null,
      "status": "pending"
    }
  }
}

Status values: pending (not yet scaffolded) · verified (agent confirmed path) · diverged (actual path differs from expected)

Written at init time. Updated by agents after scaffolding their framework.


Running Commands From Anywhere

npm run agent and npm run complete self-relocate to the repo root via git rev-parse --git-common-dir. Run them from the worktree terminal, the repo root, or anywhere inside the git tree — they always work.


Architecture

my-project/
├── client/                    ← built by client agents, merges into main
│   ├── frameworks/            ← scaffold instruction files per framework
│   └── src/
├── backend/                   ← built by backend agents (if separate)
│   └── frameworks/            ← scaffold instruction files per framework
├── shared/
├── worktrees/                 ← local only, gitignored
│   └── client-my-project-ui-1780403456467/
├── CLAUDE.md
├── BUILD_STATE.md
├── CONTRACTS.md
├── .scaffold/
│   ├── .config.json
│   ├── .tracking.json
│   ├── .paths.json
│   └── .initialized
└── .workflow/
    ├── agent.js
    ├── complete.js
    └── guards.js

Each agent works in its own worktrees/ folder on a dedicated branch. On completion, its work merges into main. The final main branch is a complete, runnable application.

Ver o original no GitHub

Bom para

Relacionados