mult-agentes

Multi-agent framework: Claude Code in VS Code is the executor; the framework is the observability + governance layer. 684 skills across 39 areas, 7-phase pipeline saga, HMAC-chained audit log, real-time dashboard.

Install

pip install mult-agentes                                # core only
pip install "mult-agentes[dashboard,observability]"     # + FastAPI dashboard + OTel
pip install "mult-agentes[dashboard,observability,llm]" # + Anthropic SDK (optional)

Quickstart (60 seconds)

# 1. Boot the dashboard
make dashboard-real
# → http://localhost:8000 (green banner = connected)

# 2. Register work (replace with whatever you're building)
python -m src.bridge.cli start \
    --intent build_feature --specialist frontend-specialist \
    --description "Implementar autenticação JWT no FastAPI"
# → {"capsule_id": "cap_abc123", ...}

# 3. Record artifacts as you produce them
python -m src.bridge.cli artifact --capsule cap_abc123 --path src/auth.py

# 4. Finalize
python -m src.bridge.cli complete --capsule cap_abc123 --status success \
    --summary "JWT auth shipped + 12 tests passing"

The dashboard updates in real time via WebSocket. No Anthropic API key needed — Claude in your VS Code chat is the LLM.

Architecture in one sentence

You (humano) ⇄ Claude Code (VS Code) ⇄ src.bridge.Recorder ⇄ EventBus + WorldState + Audit + Memory ⇄ Dashboard

See docs/explanation/architecture.md for the full Mermaid diagrams.

What this repo holds

What's inside

Three layers of metadata over a flat collection of agent skills:

1. Skills — 684 individual SKILL.md files installed under <area>/.agents/skills/<name>/, each with YAML frontmatter (name, description, optional metadata, source_org, etc.)
2. Curated tier — 127 hand-selected skills with marketplace install counts and tier classification (docs/reference/registries/_skills-registry.yaml)
3. Capability graph + agents/orchestrators — taxonomy of sub-areas, declarative routing, and the multi-agent hierarchy

The 39 area folders (ai-ml, frontend, backend, cyber-segurança, …) are mapped 1:1 to capability domains in the routing compass.

Documentation

Docs follow the Diátaxis framework:

• 📘 Tutorials — step-by-step learning
• 🛠️ How-to guides — goal-oriented recipes
• 📖 Reference — canonical specs, templates, contracts, registries, policies
• 💡 Explanation — architecture, constitution, ADRs

Local docs portal: make docs-serve → http://localhost:8000

Implementation maturity

This repo implements a subset of the multi-agent framework specified in GUIA-ARTEFATOS-MULTIAGENT-v2.md (v3.2.2, 168 artifacts across 19 layers). Current coverage: 100% (168/168) — full documental coverage. Camadas 1-6 templated (44 templates including PROJECT-STRUCTURE); Camadas 7-19 specified (122 specs in docs/reference/specs/). Runtime implementation for Camadas 7-19 is staged via the ROADMAP.

v3.2.2 update (2026-05-24): new Camada 19 (Escalabilidade + Ciclo de Vida HomoSapiens) with 11 specs, PROJECT-STRUCTURE template in C3, and Regra 35 (Spec antes do código — SDD) added as 21st absolute rule. See _framework/ARTIFACTS-INVENTORY.md for the per-artifact gap analysis.

Fully documented today (all 19 Camadas):

• SKILL-CATALOG ↔ docs/reference/registries/_skills-registry.yaml (127 curated, 4 tiers) + registry-full.yaml (684 total)
• SKILL-TAXONOMY ↔ docs/reference/registries/CAPABILITY-GRAPH.yaml (39 areas × 64 sub_areas)
• 44 canonical templates in docs/reference/templates/
• 122 specs in docs/reference/specs/

Layout

.
├── docs/                              # Diátaxis-organized documentation
│   ├── tutorials/                     # Learn by doing
│   ├── how-to/                        # Recipes
│   ├── reference/
│   │   ├── specs/                     # 122 architecture + behavior specs (Camadas 7-19)
│   │   ├── templates/                 # 44 instance-ready templates (Camadas 1-6)
│   │   ├── contracts/                 # 5 JSON schemas
│   │   ├── registries/                # _skills-registry, registry-full, agents, orchestrators, …
│   │   ├── policies/                  # cost, error-handling, observability
│   │   └── runtime-api/               # Per-module Python API reference
│   └── explanation/                   # Architecture, constitution, ADRs
├── src/                               # Runtime (13 modules)
│   ├── pipeline/                      # 7-phase orchestrator (Camada 7)
│   ├── privacy/                       # PII, RBAC, audit chain (Camada 8)
│   ├── ai/                            # Model mgmt, RAG, memory, circuit breaker (Camada 9)
│   ├── skills/                        # Loader, router, invoker, versioning (Camada 10)
│   └── (meta_learning, agent_expansion, autonomy, growth, body, …)
├── _framework/                        # Instance docs + runtime data
│   ├── ARTIFACTS-INVENTORY.md         # Per-artifact gap analysis
│   ├── PRD.md, ROADMAP.md, BLUEPRINT.md, BUDGET.md, SCOPE.md, …
│   ├── memory/                        # Episodic + semantic memory (JSONL)
│   ├── locks/                         # Resource locks (JSON)
│   └── observability/                 # agent_metrics.jsonl
├── scripts/                           # Audits, registry sync, marketplace fetch (12 scripts)
├── tests/                             # pytest suites (unit + smoke)
├── <area>/                            # 39 area folders × 684 SKILL.md files
├── .githooks/                         # Versioned git hooks (pre-commit)
├── .github/workflows/                 # CI: audit + verify
├── pyproject.toml                     # PEP 621 metadata
├── Makefile                           # make help
├── README.md (this file)
├── CHANGELOG.md, LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md
└── mkdocs.yml                         # Docs portal config

Tier model

Tier section comments and _meta counts in _skills-registry.yaml are auto-synced by scripts/sync_registry.py.

Quickstart

git clone https://github.com/claudinoinsights/mult-agentes.git
cd mult-agentes
python -m venv .venv && source .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -e ".[dev,test,docs]"

# Set up the audit gate
python scripts/setup_hooks.py

# Validate everything (read-only)
make audit       # 5 audits (structural, semantic, paranoid, deep, verify_all)
make test        # pytest + coverage
make docs        # build MkDocs site

Pre-commit hook

Exit codes:

Bypass (not recommended): git commit --no-verify.

CI (GitHub Actions)

.github/workflows/audit.yml runs the same gate on every push to main/master and on every PR. Also verifies registry-full.yaml is in sync with the filesystem.

Catches commits made with --no-verify or by collaborators who haven't run setup_hooks.py.

Adding a skill

npx skills add <owner/repo@skill> -y
mv .agents/skills/<name> <area>/.agents/skills/<name>
python scripts/sync_registry.py
python scripts/gen_registry_full.py
make audit

If promoting to a curated tier, also add an entry under platinum/gold/silver/bronze in docs/reference/registries/_skills-registry.yaml.

Multi-agent hierarchy (Layer 1 → Layer 5)

Layer 1: Cortex (global orchestrator, haiku-4-5, always on)
Layer 2: Domain orchestrators (10 total: frontend, backend, ai_ml, devops, security, qa,
         finance_trading, integrations, iot, meta — sonnet-4-6, always on)
Layer 3: Task orchestrator (ephemeral, sonnet-4-6, spawned per story)
Layer 4: Specialists (20 total: frontend-specialist, backend-node-specialist, …, planner-opus)
Layer 5: Workers (5 total: code-writer, file-operator, api-caller, test-runner, git-worker)

Each agent declares capabilities, preferred_skills, budget_default_usd, and primary_orchestrator. See docs/explanation/architecture.md for the full mental model.

Routing flow

1. Cortex classifies user intent (one of 18 classes in ROUTING-COMPASS.yaml#intent_classification.classes)
2. Routing rule selects target domain orchestrator (possibly via classifier_subroutes)
3. Domain orch decomposes into stories, delegates to Layer 3 task orchestrators
4. Task orch sequences Layer 4 specialists, which invoke skills via Layer 5 workers
5. auditor-haiku runs after every artifact for constitutional compliance

See docs/reference/registries/ROUTING-COMPASS.yaml for the full intent → orchestrator mapping.

Zero-bugs rule

Audits run structural + semantic checks on every commit. Any of these fails the gate:

• YAML/JSON parse errors
• Missing or invalid SKILL.md frontmatter
• Curated entry without a matching SKILL.md on disk
• primary_area references a folder that doesn't exist
• preferred_skills references a skill name not on disk
• governs_areas references a folder that doesn't exist
• sub_areas references a sub_area not in CAPABILITY-GRAPH.yaml
• _meta counts diverge from filesystem reality
• Tier classification doesn't match install threshold (with official: true as escape hatch)

To see what's wrong without committing: make audit.

License

Apache 2.0 © 2026 Eric Claudino