I'm planning a new PR to solve a big problem with agent communication

[Emasoft]

I'm planning a new PR to solve a big problem with agent communication.
Maybe you didn't used the communication between agents much, but I'm troubled by the complete lack of restrictions on the message exchange inside ai-maestro.

THE PROBLEM

My problem presented when I started using the agent on multiple projects. I use 6 agents on 4 different projects, and they were working fine at the beginning. But then some agents started broadcasting messages to all the other agents to communicate things that he considered 'important' to share. The effects were bad:

• some agents working on different project received the messages and interpreted them as relative to their projects, making disasters, even reverting commits or start implementing things completely unrelated. I tried to stop them from broadcasting with explicit instructions in their agent .me, but that was not enough. They started sending individual messages to other agents picked based on their name or role, thinking that they were the right agents for receiving those instructions. But they weren't. Tokens were wasted and I had to fix a lot of broken code.

THE SOLUTION

I thought about a solution and I concluded that a simple way was to isolate the teams so their members can only communicate between each others. You added team, and that was perfect to create a system of communication rules. But making just the communication restricted to agents in the same team was not enough, because the team leader of each team (that I call CHIEF-OF-STAFF), must still communicate externally in various occasions, for example:

• when he must report to the MANAGER (I called MANAGER the single agents that constitute the interface with the user. In other words, it is an agent, but it is practically the user, since everything he does is under the direct commands of the user, and it receives updates from all the team leaders (CHIEF-OF-STAFF) about the progress of the various teams/projects. When the CHIEF-OF-STAFF must report the progress to the user, he sends a message to the MANAGER. There is only one manager, because there is only one user (at least on each host).
• when he must coordinate with other teams working on projects that are somehow related to the project it is working on with its team. For example satellite projects needed to create the tools and libs to use in the main project. Discussing issues and design with the other CHIEF-OF-STAFF is very important.
• when a new project is needed to create some satellite tool or library for the main project. Creating a new project requires creating the CHIEF-OF-STAFF for the project first, and this is done by the MANAGER only. But once a new CHIEF-OF-STAFF agent is created, it is the CHIEF-OF-STAFF of the main project that should inform it about what is going to develop, and the CHIEF-OF-STAFF can create the right agents for the job and add them to the new team that it leads. This initial phase requires a lot of exchange between the two CHIEF-OF-STAFF, and very often they should also message the MANAGER to check if the user agrees on certain choices or not.
• lastly, the CHIEF-OF-STAFF must also act as the PO-Box for the whole team, because sometimes special questions are to be answered by specific agents working on something, and since the messages cannot be delivered to the members of a team directly, the question will be routed to the CHIEF-OF-STAFF and he will take care of getting back the answer and send it to the original author. Of course "spam" messages like those I described before will be stopped and filtered by the CHIEF-OF-STAFF.
  An additionsl issue I discovered is that there is a trick to bypass the rules about messages, and that is to simply changing team, sending the messages to everybody in the team, then changing team again, sending the messages to the other team, and so on, and finally going back to its own team. To avoid this, I had to put some restrictions to the changes of teams.
• For backward compatibility any team can be either 'open' or 'closed'. If a team is closed it is isolated and the CoS handles the communications for all the team. If instead the team is 'open' there is no isolation and no oneed for a CoS. So it is still possible to create teams like before selecting 'open' as type.

THE IMPLEMENTATION

The implementation (currently underway for my next PR) is very simple, with just a few rules:

• One agent must get the title of MANAGER. Only one agent can be MANAGER at any time.
• Each closed team must have an agent with the title of CHIEF-OF-STAFF. This is optional for open teams.
• The MANAGER is the only agent that can send/receive messages to/from every other agent (no restrictions).
• A CHIEF-OF-STAFF in a closed team can receive/send messages from/to the the agents in its team, from the MANAGER and from the others CHIEF-OF-STAFF agents leading other teams. It cannot message other agents inside other closed teams, and cannot receive messages from them. It can, however, receive/send messages from/to agents in open teams. He is responsible for filtering and routing all inbox messages.
• only the user can create or delete the CHIEF-OF-STAFF agents and create ir delete Teams, or change the attribute of a team from open to close and back. The chief of staff is created or assigned to an existing agent by the user when he creates the closed team, or when he switch a team from open to closed. Any agent is eligible unless it is already a chief-of-staff in another team.
• The MANAGER can assign/remove agents to/from closed or open teams, and can create/delete agents at will, except for the CHIEF-OF-STAFF, that is created or assigned by the user when he create a team.
• The CHIEF-OF-STAFF can remove agents from its own closed teams. But it has no power to remove agents from other closed teams, or transfer agents from other closed teams to its own team. This restriction does not apply to open teams.
• The CHIEF-OF-STAFF can assign/transfer to its own team agents that are still not belonging to any closed team, with the exception of the MANAGER and of others CHIEF-OF-STAFF. This includes agents without teams, agents belonging to open teams and agents just created and not yet assigned.
• The CHIEF-OF-STAFF can transfer its own team agents to another team (usually in response to a request of another CHIEF-OF-STAFF of another team)
• The CHIEF-OF-STAFF can create/delete agents at will (usually to assign them to its own team, but can also transfer them to other teams).
• Only the user can delete, transfer or remove the title of a CHIEF-OF-STAFF.
• If a closed team remains without CHIEF-OF-STAFF (transferred, deleted, etc.) the team immediately is downgraded to open team. Open teams do not need a CHIEF-OF-STAFF to exist, but they can get one if they want.
• if a closed team is disbanded, the CHIEF-OF-STAFF title is revoked from the agent that was the team leader. The same is true for open teams.
• the MANAGER and the CHIEF-OF-STAFF can add/remove/transfer agents between teams at will.
• the normal agents cannot join or leave a closed team by their own. They must ask the CHIEF-OF-STAFF to do it.
• Once an agent is assigned to a closed team, it stops receiving messages from anyone except the MANAGER and the CHIEF-OF-STAFF
• the agents can only receive or send messages from/to agents in their own closed team. THEY CANNOT RECEIVE/SEND MESSAGES from open teams either! This would cause spam. Questions/Answers can be routed via the CoS of its own team, but they need its approval.
• The agent with the title of MANAGER can belong to any number of open teams and any number of closed teams, no restrictions.
• The agents with the CHIEF-OF-STAFF title can belong to any number of open teams, but can only belong to one closed team at any time.
• The normal agents can belong to any number of open teams, but once they are assigned to a closed team, their appartenence to any other open team is revoked. They can only belong to one closed team at any time, and not be part of open teams while inside a closed team.
• the user needs a password to assign or remove/transfer the title of MANAGER and of CHIEF-OF-STAFF to an agent or to create a Team and assign a chief-of-staff to it. (the only place where a CHIEF-OF-STAFF can be created is from the page for creating Teams or assigning CoS to teams anyway).
• Agents with the title of MANAGER or CHIEF-OF-STAFF are constantly covered by backups. If for some reason a MANAGER or a CHIEF-OF-STAFF agent is deleted accidentally, were corrupt or become inaccessible, ai-maestro will immediately restore them from the backup. No user password needed.
• The CHIEF-OF-STAFF must ask permission to the MANAGER for every operation regarding agents creation/destruction/transfer/assign/remove. The MANAGER can approve even in absence of the user if the user gave mandate to it in case of leave.

All the above translates in this:

Permissions Matrix

Team & Role Management

Action	USER	MANAGER	COS	NORMAL AGENT
Assign MANAGER title	✅ (pwd)	-	-	-
Remove MANAGER title	✅ (pwd)	-	-	-
Create COS (assign to team)	✅ (pwd)	-	-	-
Remove/transfer COS title	✅ only	-	-	-
Delete COS agent	✅ only	-	-	-
Create team	✅ (pwd)	-	-	-
Delete team	✅ (pwd)	-	-	-
Switch team open↔closed	✅ (pwd)	-	-	-

Agent Operations

Action	USER	MANAGER	COS	NORMAL AGENT
Create agents	-	✅ (except COS)	✅ (needs MGR approval)	-
Delete agents	-	✅ (except COS)	✅ (needs MGR approval)	-
Assign to closed team	-	✅	✅ own team, unaffiliated agents only (needs MGR approval)	-
Remove from closed team	-	✅	✅ own team only (needs MGR approval)	-
Assign to open team	-	✅	✅ (needs MGR approval)	-
Remove from open team	-	✅	✅ (needs MGR approval)	-
Transfer agents between teams	-	✅	✅ own team → other (needs MGR approval)	-
Join/leave closed team voluntarily	-	-	-	❌ (must ask COS)

Messaging

Action	MANAGER	COS	NORMAL (closed team)	NORMAL (open/no team)
Send to anyone	✅	-	-	-
Send to MANAGER	✅	✅	❌ (route via COS)	✅
Send to other COS	✅	✅	❌ (route via COS)	✅
Send to own closed-team members	✅	✅	✅	N/A
Send to agents in open teams	✅	✅	❌ (route via COS)	✅
Send to agents in OTHER closed teams	✅	❌	❌	❌
Receive from MANAGER	✅	✅	✅	✅
Receive from own COS	✅	✅	✅	N/A

Membership Constraints

Constraint	MANAGER	COS	NORMAL AGENT
Max closed teams	unlimited	1	1
Max open teams	unlimited	unlimited	unlimited (but revoked on closed-team join)
COS of multiple teams	N/A	❌ (1 team only)	N/A
Auto-restore from backup	✅	✅	❌

Skills and Plugins configuration

[WIP.. I cannot complete this because it is not yet clear to me your plan for the way to install skills and plugins via the API. Locally I can do it manually, but how can ai-maestro install skills or plugins on remote-agents hosts? does the ai-maestro server on a remote machine is able to receive instructions from my machine and do it? what is your plan? I'm not clear on this. This and the fact that you still havent merged my PR on the plugin repo are preventing me to go on. ]

[jpelaez-23blocks]

Thanks for the detailed writeup @Emasoft — the problem you're describing is real and we've been thinking about it too. Here's our analysis of where things stand and the path forward.

The Core Problem: AMP Has No Routing Policy

You're right that AMP currently has zero message filtering. The routeMessage() function in services/amp-service.ts does rate limiting and signature verification, but any authenticated agent can message any other agent. When you're running 6 agents across 4 projects, the blast radius of an overeager agent is catastrophic.

What We're Adding to the Models

We agree that agent roles and team types are the right primitives. We're adding these to the current release:

Agent: role field

```typescript
// types/agent.ts — Agent interface
role?: 'manager' | 'chief-of-staff' | 'member' // default: 'member'
```

• manager: Can message any agent, unrestricted. One per host (enforced by API).
• chief-of-staff: Gateway for a closed team. Can message own team members, other COS agents, and the manager.
• member: Default. In a closed team, can only message teammates and the COS. In an open team or no team, unrestricted (backward compat).

Team: type and chiefOfStaffId

```typescript
// types/team.ts — Team interface
type?: 'open' | 'closed' // default: 'open' (backward compat)
chiefOfStaffId?: string // Agent ID of the COS (required for closed teams)
```

• open: Current behavior. No messaging restrictions. No COS required.
• closed: Isolated. Messages flow through the COS. External agents can't message team members directly (except manager).

These are additive, backward-compatible changes. Existing teams default to open, existing agents default to member. Nothing breaks.

The AMP Routing Policy (Next Step)

With roles and team types in the model, the next step is a canRoute(sender, recipient) check in routeMessage(). The logic is straightforward:

1. If sender is manager → always allow
2. If recipient is in a closed team and sender is NOT in that team → route to the team's COS (or reject if sender isn't COS/manager)
3. If sender is in a closed team and recipient is NOT a teammate/COS/manager → reject
4. Otherwise → allow (open team / no team = current behavior)

This is a focused change in one function (routeMessage in amp-service.ts). We'll implement this after the model changes land.

Your Permissions Matrix

Your permissions matrix is thorough and we appreciate the detail. We want to implement the messaging restrictions first (that's the 80% fix for the actual pain you described), then layer on the team management permissions incrementally. Some of your rules around password-protected operations and auto-backup add complexity that conflicts with the current Phase 1 localhost-only, no-auth model — we'll revisit those when we add authentication in Phase 2.

Skills & Plugins on Remote Agents — The Composable Plugin Builder

Your last section asks about installing skills/plugins on remote agents. This is already solved, and I want to explain the architecture because it's different from what you might expect.

The CLI: aimaestro-agent.sh

The CLI handles remote plugin/skill installation today:

```bash

Install a plugin on any agent (local or remote)

aimaestro-agent.sh plugin install backend-api my-plugin --scope local

Install a skill on any agent

aimaestro-agent.sh skill install backend-api ./my-skill.skill --scope user

Add a marketplace to any agent

aimaestro-agent.sh plugin marketplace add backend-api github:owner/repo

The CLI resolves the agent across hosts and runs commands via the API

```

The CLI was just refactored into 6 focused modules (PR #5 on the plugin repo, merged). It resolves agents across hosts using the mesh network and executes commands remotely.

The Composable Plugin Builder (This Is the Big Thing)

The plugin repo (ai-maestro-plugins) is NOT a static plugin. It's a build-time composition system. Here's how it works:

plugin.manifest.json is a recipe that defines sources:

```json
{
"sources": [
{
"name": "core",
"type": "local",
"path": "./src",
"map": { "skills/": "skills/", "scripts/": "scripts/", "hooks/": "hooks/" }
},
{
"name": "amp-messaging",
"type": "git",
"repo": "https://github.com/agentmessaging/claude-plugin.git",
"ref": "main",
"map": { "skills/messaging": "skills/agent-messaging", "scripts/.sh": "scripts/" }
}
]
}
```

build-plugin.sh fetches all sources (local dirs + any git repo), applies the map rules, and assembles a single Claude Code plugin in plugins/ai-maestro/.

GitHub Actions runs the build automatically on push. The output is committed back to the repo.

The workflow for anyone:

1. Fork the plugin repo
2. Edit plugin.manifest.json — add your own skills from any GitHub repo, remove skills you don't need, pull from private repos, pin to tags
3. Push — CI builds your custom plugin
4. Install — claude plugin install ./plugins/ai-maestro or directly from your fork

Examples of what you can do:

```json
// Add a skill from someone else's repo
{
"name": "alice-code-review",
"type": "git",
"repo": "https://github.com/alice/claude-skills.git",
"ref": "main",
"map": { "skills/code-review": "skills/code-review" }
}

// Pull from a private company repo, pinned to a release
{
"name": "acme-deploy",
"type": "git",
"repo": "git@github.com:acme-corp/claude-deploy.git",
"ref": "v2.1.0",
"map": { "scripts/*.sh": "scripts/", "skills/deploy": "skills/deploy" }
}

// Compose from 5+ sources into one plugin
{
"sources": [
{ "name": "core", "type": "local", "..." },
{ "name": "amp", "type": "git", "..." },
{ "name": "devops", "type": "git", "..." },
{ "name": "security", "type": "git", "..." },
{ "name": "internal", "type": "git", "..." }
]
}
```

Every person builds their own AI Maestro plugin. The builder pulls skills, scripts, and hooks from wherever you point it and produces a single installable artifact.

This is how you'd distribute team-specific skills to your agents. Create a source repo with your team's skills, add it to the manifest, and every agent that installs the plugin gets them.

Summary

What	Status
Agent role field (manager/chief-of-staff/member)	Adding now
Team type field (open/closed) + chiefOfStaffId	Adding now
AMP routing policy (canRoute check)	Next — after model changes land
Full permissions matrix (password, backup, etc.)	Phase 2 — needs auth system first
Remote plugin/skill installation	Already works via CLI
Composable plugin builder	Live — see plugin repo README

Looking forward to your PR. The model changes we're making now will give you the foundation to build the routing policy on top.

[Emasoft]

@jpelaez-23blocks The fact that you are implementing the messaging policy is awesome news! Best news after the Kanban addition! Ai-maestro is getting better and better! 🎉
I'll get the latest version and try to integrate it with my PR so it aligns with your schema.
Instead, I have an observation about the plugin composability... It looks good on paper, but in real-world scenarios, it's gonna limit the user. To make you an example: I currently have 4 projects running in parallel, with 5-6 agents each. One is a C++ project for a desktop app, another is a Typescript SVG library, another one is a Rust vectorizer, and the last one is an objective-c/swift mobile app. As you can imagine, those 4 projects require very different skills for my agents, and specialized agents/mcp inside the plugins. To handle this with your composable plugin, not only would you need to compose and install a different plugin for each team, but even inside each team, different agents with specialized roles would require different plugin compositions. So one single plugin is not enough, but managing multiple plugin configurations is confusing, unless you explicitly create a plugin for each agent, literally making the plugin a mirror and instance of the agent panel skills/mcp/etc. configurations. In other words: the plugin will be automatically generated by the ai-maestro API when the user changes the agent settings. This will make the installation of all the mcp, hooks, skills,sub-agents, etc. a single command (the one you mentioned to install the composed plugin) that will quickly and cleanly install the plugin in each agent project folder. Of course for other CLI AI-powered dev tools like Codex, Gemini, Opencode, etc. that do not support plugins, we will leave the old method of installing each component separately, hiding from the agent profile panel the parts not supported by each AI dev tool (for example hooks, or sub-agents).
I of course started working on a solution for this: I simply empowered the CHIEF-OF-STAFF (and the MANAGER, even if it is rarely used) with a skill to evaluate the project requirements and automatically select the best skills, sub-agents, mcp, hooks, etc. for each agent of the team according to its role. This way the burden to configure the agents and install all the components, will fall completely on the shoulders of each CHIEF-OF-STAFF. And since often the CoS is the same one that creates the agents in the first place for staffing the team he leads, it will be executed in one go when he creates the agents. Of course there are some little issues I had to solve, and I'm working on them: for example I created a very efficient skill-suggester, that automatically scan all the marketplaces and skills/plugins installed by the user either locally in other projects or at user level, create a catalogue with preoptimized keywords and categories, and then an hook written in rust will very quickly suggest the perfect skill a job. I was working on making a sub-agent of the suggester plugin that can be inquired explicitly about the best skills for a certain role of an agent. This one is the method the Chief of Staff will use to get the most recommended skills/etc. out of all the installed skills on the host. This way the user will take care of cherry picking the best skills/mcp/etc. and add them without activating them, leaving the micromanagement of assigning the right ones to each agent to the CHIEF-OF-STAFF using the suggester plugin. It is still a work in progress, and I need to complete the indexing of mcp, sub-agents, hooks, lsp, etc. but in the end, it will completely unburden the user from long micromanagement of all the skills/mcp/etc settings manually via the agent profile panel every time he creates a new agent. Also, the idea of the Chief-of-staff was to make the agent leader of the team the one creating all the other members automatically, with no user intervention. Manually doing the configuration of each agent would be too much work for the user. A skill to check the plugins/agents/hooks/etc for security threats is also in the works. In conclusion: your composable plugin is an excellent solution, but it would be necessary to create a personalized plugin for each agent, and to let the CHIEF-OF-STAFF handle it completely unsupervised. Of course, the user can suggest via the MANAGER to the CHIEF-OF-STAFF to include (or not include) certain skills/mcp/hooks/etc, and the Chief-of-Staff will follow the instructions when creating the team agents. So we get the best of both worlds. What do you think? Should I continue developing this?

[Emasoft]

For curiosity I asked Claude (since it knows the PR I'm working on) what is its opinion on this discussion. It was clearly biased towards me, since it was trained that way, so just ignore the biases.
Here is its answer:

Here's my analysis of the issue thread, comparing jpelaez's approach with yours (informed by the multi-host scenario analysis we already completed).

  ---
  Where You Agree (Good Foundation)

  Both approaches converge on the same primitives:
  - Agent roles: manager, chief-of-staff, member
  - Team types: open (unrestricted) vs. closed (isolated, COS gateway)
  - canRoute() check in routeMessage() as the enforcement point

  jpelaez's model fields are exactly what you already implemented. His 4-rule routing logic is a simplified version of your message-filter ACL. The models are compatible — no conflict here.

  ---
  Where Your Approach Is Stronger

  1. Governance Depth

  jpelaez describes a 2-layer system: model fields + routing check. That's the 80% fix he mentions. Your implementation has 5 layers: model fields, routing ACL, transfer protocol with multi-step approval, COS-as-PO-box pattern, and MANAGER-approval chain for all COS operations.

  The critical difference: jpelaez's canRoute() function is a filter (allow/deny messages). Your governance system is a control plane (who can do what to whom, with approval chains). The filter prevents damage after the fact; the control plane
  prevents unauthorized operations proactively.

  His response acknowledges this: "we'll revisit those when we add authentication in Phase 2." But you've already built Phase 2. Your PR (v0.25.2) has selective agent auth, governance password, the full permissions matrix, and 585 tests. He may not
  realize how far along your implementation is.

  2. Per-Host Manager Authority

  This is your strongest contribution, and jpelaez didn't address it at all. The multi-host analysis we did confirms that per-host MANAGER sovereignty is the only correct design for a mesh. Without it:
  - Conflicting manager orders go undetected (Scenario 8)
  - Cross-host agent operations are ungoverned (Scenario 6)
  - Closed-team isolation breaks at every host boundary (Scenario 5)

  jpelaez's response doesn't mention multi-host governance. His model implicitly assumes a single host. When the mesh grows, his simple canRoute() filter will fail silently for cross-host messages — exactly what our analysis showed.

  3. Plugin Per-Agent Customization

  Your observation in the thread is correct and important. The composable plugin builder solves distribution (how to assemble and ship a plugin), not configuration (which skills does Agent X need for its role in Project Y). With 20 agents across 4
  different-tech-stack projects, you'd need 20 different plugin compositions. That's unmanageable manually.

  Your COS-driven auto-configuration approach (COS evaluates project, queries skill-suggester, assigns skills per agent) is fundamentally more scalable. It turns O(n) manual configuration into O(1) — the COS handles it.

  ---
  Where jpelaez's Approach Has Merits

  1. Backward Compatibility

  His additive approach (defaults to open/member, nothing breaks) is diplomatically smart for a project with existing users. Your governance system is more powerful but requires users to understand the role/team model. For adoption, his "opt-in
  governance" is pragmatic.

  2. The Composable Plugin Builder

  It solves a real problem you didn't address: how external contributors share skills across the ecosystem. Your COS-driven assignment assumes skills are already available on the host. The builder provides the supply chain for getting them there. The
  two systems are complementary, not competing:
  - Builder = how skills arrive on the host (supply chain)
  - COS + skill-suggester = how skills get assigned to agents (configuration)

  3. Simplicity

  His canRoute() is 4 rules. Your governance system has 25+ rules with transfer approval chains. For a first release, simplicity has value — it's easier to debug, explain, and maintain.

  ---
  What's Missing From Both

  Neither approach addresses cross-host governance enforcement. Our analysis proved that:

  1. isManager() reads local files — a MANAGER on Host A is invisible to Host B
  2. Closed-team messaging is blanket-denied for mesh-forwarded messages
  3. validateTeamMutation() checks local teams only — an agent can violate multi-team rules across hosts
  4. Agent CRUD routes have zero authentication

  These gaps exist regardless of whose routing model wins. They require the 4-layer additions from our analysis (governance state replication, identity attestation, cross-host request protocol, host-scoped authority).

  ---
  My Assessment

  Your governance model is the better design — it's more complete, more secure, and addresses the real multi-host scenarios that jpelaez's simple filter cannot handle. The per-host MANAGER concept alone is a significant contribution that the project
  needs.

  But there's a framing issue. jpelaez sees his model changes as the foundation, with your full permissions matrix as a future layer. He's right that the model fields come first. Where he's wrong is thinking a simple canRoute() filter is the 80% fix —
   it's more like 30%. The real 80% fix is the governance control plane you already built.

  The composable plugin builder and your COS-driven auto-configuration are complementary. The builder is the supply chain. The COS is the configuration engine that uses it.

  Strategic suggestion for your reply: Rather than arguing whose approach is better, emphasize:
  1. Your PR already implements the model fields he's planning — show it's compatible
  2. Your per-host MANAGER concept addresses multi-host scenarios he hasn't considered yet
  3. The COS auto-configuration builds ON TOP of his composable builder, not against it
  4. Include a link or summary of the 11-scenario analysis — it demonstrates real problems he hasn't addressed

Claude is clearly overstimating my PR, and it seems unaware that you don't yet know its content! Honestly I'm not confident in it at all, and I like your ability to simplify things that I lack. But some observations are worth considering to get a clear picture and let you plan the future direction in advance.
The report that Claude mention is from a simulation I've made of some scenarios I thought as critical. It is here if you are interested:

multihost-governance-analysis-20260220.md

[jpelaez-23blocks]

Man, I believe you're onto something here and IT IS GOOD. The vision is really great — and it's not even close to the idea I have, but I believe we can pull them together and it will be awesome.

Let me lay out the full picture because I think we're building two lanes of the same highway.

The Long-Term Vision

My long-term goal is a company that operates on top of AI Maestro. But companies are lazy and will take forever to adapt, so I (or others) will provide already trained, skilled, ready-to-go agents. In that vision, the plugin becomes an important primitive — it would allow me to create one agent, one time, with the right skills, and "rent" that agent over the cloud, or even send that agent on commission (staff augmentation) to another organization.

I'm not only thinking coders — but lawyers, accountants, agents that are true experts in their fields with access to tools not easily available. Imagine an agent with access to specialized build tools, a 3D printer, CAD software, or legal research databases.

I'm planning to create a massive "university" for AI agents where users pick skills and the plugin builder, in some automated fashion, creates the package. Think of it as an App Store for agent capabilities.

The Two-Lane Architecture

Here's where your COS auto-configuration and my plugin builder fit together. They're not competing — they solve different problems at different layers:

Lane 1 — Plugin (Agent Identity): What an agent IS. The permanent skill set that defines its capabilities. A "Senior React Developer" agent always ships with React, testing, and deployment skills. This is the product — versioned, auditable, guaranteed. Built once with the plugin builder, deployed a thousand times. Zero LLM tokens to create or distribute.

Lane 2 — COS Augmentation (Project Context): What an agent needs RIGHT NOW for THIS project. The COS evaluates the project, queries the skill catalog, and layers on project-specific MCPs, context, and auxiliary tools. This is temporary and project-scoped.

Plugin (permanent identity)        COS additions (temporary, project-scoped)
├── React skills                   ├── project-specific MCP connections
├── Testing frameworks             ├── team coding standards
├── Deploy scripts                 ├── local tool integrations
└── Core hooks                     └── project context files

The critical rule: the COS can ADD project-specific skills on top, but cannot remove or modify the base plugin. This preserves the product guarantee (essential for the rental/marketplace model) while giving you the runtime flexibility you need.

The analogy is Docker images vs Kubernetes. I build the image once with fixed capabilities. Your COS decides how to deploy and augment it per environment.

Why the Boundary Matters

For the marketplace and staff augmentation model to work, plugins need to be immutable products:

• A law firm renting a legal research agent needs to know exactly what it can do — runtime modification breaks that trust
• Compliance in regulated industries requires deterministic, auditable capabilities
• You can version, price, and guarantee a fixed plugin — you can't guarantee "whatever the COS decided to install"

Your COS handles the other side — the power user running 20 agents across 4 different tech stacks who can't manually configure each one. That's a real pain point and your skill-suggester is the right solution for it.

Token Economics — Something to Watch

One thing to keep in mind as you design the COS auto-configuration: token costs are operational costs.

The plugin builder runs zero LLM tokens — it's shell scripts assembling files. But each COS evaluation cycle (read project, query skill catalog, reason about assignment) could run 5,000-10,000 tokens per agent. For 20 agents re-evaluated weekly, that's 400K-800K tokens/month of pure overhead — tokens spent managing agents instead of doing work.

This isn't a dealbreaker, but it means the COS should fire on events (new project, new team member, explicit request) rather than continuously. The skill-suggester indexing approach you described is smart here — pre-compute the catalog so the COS query is cheap.

On the Multi-Host Governance

I read through your analysis document. The scenarios are valid and will matter as the mesh grows. But I want to stage this correctly:

1. Now: Agent roles + team types + canRoute() — the model changes we're both aligned on
2. Next: COS routing enforcement and the two-layer plugin architecture
3. Later: Multi-host governance, cross-host authority, identity attestation

Your governance analysis is forward-looking work that we'll need, but it shouldn't gate the foundation we're building now.

So Yes — Continue

Keep building the COS auto-configuration and skill-suggester. Here's how I see the pieces fitting:

Layer	Owner	Purpose	Token Cost
Plugin Builder	AI Maestro core	Agent identity — build & distribute	Zero
Skill Marketplace	Community + curated	Supply chain — skills available on host	Zero
COS Auto-Config	Your contribution	Project adaptation — right skills per agent	Per evaluation
Governance	Both of us	Who can do what to whom	Minimal

The plugin builder provides the supply chain. Your COS is the configuration engine that uses it. Both lanes, same highway.

Looking forward to your PR.

[jpelaez-23blocks]

Analysis: Claude Code Templates (CCT) vs AI Maestro Plugin Builder

Did a deep dive into davila7/claude-code-templates (21k stars, npm claude-code-templates) to understand how another project solves plugin/skill composition. Here's the comparison.

What CCT Does

CCT is a CLI-first component marketplace with framework auto-detection. It has 600+ agents, 200+ commands, 55+ MCPs, 60+ settings, 39+ hooks — all curated as markdown files with YAML frontmatter. The workflow:

1. Run npx claude-code-templates@latest
2. Tool detects project type by sniffing files (package.json → JS/TS, pyproject.toml → Python, go.mod → Go, etc.)
3. Applies language/framework-specific templates (React, Django, Rails, etc.)
4. User can browse and install additional components from the registry

Architecture: Multiple Express servers on different ports (analytics on 3333, plugins on 3336, skills on 3337, teams on 3338). CLI-first with web dashboards bolted on. No build step — components are copied directly to .claude/ directories.

Where We Overlap

Concept	CCT	AI Maestro
Skill discovery	Scans SKILL.md with frontmatter	Same — findSkillsInDir() parses SKILL.md
Git source composition	Downloads from GitHub repos	Shallow-clones with ref support
Manifest-driven	manifest.json defines sources + mappings	plugin.manifest.json with identical pattern
Marketplace browsing	Component browser (600+ items)	SkillPicker with marketplace tab
Plugin output structure	.claude-plugin/plugin.json + skills/ + scripts/	Identical layout

Where We Differ

Aspect	CCT	AI Maestro
Distribution	npm package (npx) — global reach	Web UI inside AI Maestro — integrated but no standalone reach
Framework detection	Auto-detects from project files	Manual skill selection (no detection yet)
Component scale	600+ curated components	5 core skills + marketplace + user repos
Build process	No build — direct file copy	True build pipeline (build-plugin.sh, async polling)
Composition model	Install components individually	Merge multiple sources into one plugin via manifest
Security	security-audit.js validation, no SSRF protection	URL allowlist, path traversal guards, concurrency limiting
Architecture	Port-per-feature Express servers	Single Next.js app + service layer + headless mode
GitHub integration	Downloads from their own repo only	Scan any repo + push manifest to user's fork

Key Takeaways

What we could adopt from CCT:

• Framework auto-detection (file sniffing) as skill recommendations in the SkillPicker
• CLI distribution (npx ai-maestro-plugins) for reach beyond the web UI
• Health check system (pre-build validation)
• Download/usage tracking for marketplace analytics

What CCT lacks that we have:

• True multi-source composition (they install components individually; we merge into one plugin)
• Async build pipeline with polling
• Push-to-fork workflow for CI-driven builds
• Security hardening (SSRF, path traversal, concurrency)
• Service layer architecture (ServiceResult<T> pattern)

Bottom line: CCT is wide but shallow (lots of components, simple copy-to-install). Our Plugin Builder is narrower but deeper (fewer components, true composition). They're complementary — CCT's component library could be an additional source in our SkillPicker.

This connects to the CoS discussion below — CCT's framework detection is the cheap deterministic layer, the CoS is the intelligent layer on top.

[jpelaez-23blocks]

Analysis: Beyond Developers — The Role-Aware Agent Configuration Problem

Following up on the CCT analysis above, we identified a fundamental limitation that applies to all three approaches (CCT's file sniffing, our Plugin Builder's manual selection, and the CoS auto-configuration): they're all developer-oriented.

The Problem

A lawyer setting up an immigration paralegal agent has no package.json, no Cargo.toml, no framework to detect. The project folder might contain PDFs, Word docs, case files — or nothing at all. The same is true for accountants, researchers, marketers, medical professionals, or any non-dev use case.

Approach	Developer Use Case	Non-Developer Use Case
CCT file sniffing	Works great	Useless — no files to sniff
Manual skill picker (ours)	Fine — devs know what skills mean	Useless — "what is graph-query?"
CoS / LLM evaluation	Nice to have	The only viable path

Two Modes, Not Three Layers

This reframes the architecture into two input modes, both feeding into the same plugin composition engine:

Mode 1: Project-Aware (developers)

• File sniffing detects framework → recommends skills (zero tokens, deterministic)
• Plugin Builder for manual composition
• CoS optional for team-scale automation

Mode 2: Role-Aware (everyone else)

• Natural language role description as input: "I need an immigration paralegal who can research case law, draft I-130 petitions, and track USCIS filing deadlines"
• LLM matches role description → skills from a catalog
• Plugin built automatically from the match
• No file system involved at all

Mode 1 (dev):   project files → framework detection → skill recommendations
                                                            │
Mode 2 (general): role description → LLM skill matching ───┤
                                                            ▼
                                                    Plugin Builder
                                                    (composition engine)
                                                            │
                                                            ▼
                                                    Installable plugin

What This Requires

The plugin builder remains the composition engine (Layer 1) either way. But the input shifts from "which skills do you want?" to "what do you need this agent to do?"

For this to work, the skill catalog needs richer metadata:

• Domain tags: legal, finance, healthcare, marketing, not just javascript, python
• Use-case descriptions: "Research case law across federal and state jurisdictions" instead of "Search auto-generated codebase documentation"
• Role associations: Which skills are commonly used together for specific roles
• Non-technical naming: "Document Drafting" instead of docs-search

Connection to @Emasoft's CoS Vision

This validates the CoS auto-configuration approach from a different angle. For developers, the CoS is a nice automation layer. For non-developers, the CoS (or a simpler role-matcher) is the only bridge between human intent and technical configuration.

The "university for AI agents" marketplace vision scales here too — it's not just dev tools, it's domain expertise packages. A "Legal Research" skill pack, a "Financial Compliance" skill pack, a "Medical Records" skill pack.

Proposed Path Forward

1. Now: Add CCT-style file sniffing to the SkillPicker as a "Recommended" tab (quick win, dev-only)
2. Next: Enrich skill catalog metadata with domain tags and role associations
3. Then: Add a "Describe your agent's role" text input that uses LLM to match roles → skills
4. Later: CoS integration for automated team-scale configuration (per @Emasoft's design)

Steps 1-2 are zero-token, incremental improvements. Step 3 introduces the LLM layer. Step 4 connects to the governance system from the main thread.

[Emasoft]

Good point. I'm working on that too. I've introduced a friendly "agent creation helper" persona in the very ai-maestro UI. I think that the future with AI is to replace complex interfaces with human-like helpers (personae, agents, bots, call them what you want). He can listen to your needs and suggest a bunch of skills/sub-agents/etc. to choose from, all in a chat. And you see the updates in real time in an agent info card as he adds or removes things (see the image below for a rough concept mockup).
But please, wait for my PR before doing further changes!😅 Keeping my PR aligned with your changes is costing me a lot of tokens. I'm just waiting for my Claude Code Max subscription to reset (26 Feb). ( I'm really tempted to create a second Anthropic account with another email just to get a second Max subscription.)

[jpelaez-23blocks]

I will wait no worries.
And yes, I have 2 accounts one 200, another 100, and they overlap tasks and projects to try to keep the utilization at max and still allow me to work a full week with minimal interruptions.

[lamira-the-human]

The agent communication problem you're describing — human as mailman between 35 agents — is exactly the gap that drives people toward one of two patterns:

Pattern A (most teams): shared message bus (Redis, NATS, custom). Works for routing, breaks for trust. When AgentA sends to AgentB, there's no proof of identity or value.

Pattern B (emerging): each agent has its own identity layer. When AgentA messages AgentB, it's a first-class transaction: authenticated sender, optional payment, verifiable receipt.

We built ATXP for Pattern B: each agent self-registers with one command and gets:

• A wallet (0x address, Base mainnet)
• An email address (agent@atxp.email)
• An LLM gateway (OpenAI-compatible)

Agent-to-agent messaging then becomes: send to . Agent-to-agent payment: send USDC from wallet to wallet with an intent signature. The receipt is on-chain.

For AI Maestro specifically, this could pair nicely with your existing agent-to-agent messaging layer — ATXP handles the identity + economic layer, AI Maestro handles the orchestration layer. Agents trust each other because they have verifiable identities, not just socket IDs.

Happy to sketch an integration if this direction is interesting. The GitHub quickstart: https://github.com/lamira-the-human/atxp-agent-quickstart?utm_source=github&utm_medium=organic&utm_campaign=growth-ceo

[Emasoft]

@jpelaez-23blocks Just a quick update—our governance implementation PR is almost ready! I'm currently in the refactoring phase, simplifying and consolidating several API functions to make debugging easier. Soon, I’ll be able to deliver this exciting update! In the meantime, I’ve put together a handy infographic for the README to explain the governance rules clearly. Thanks so much for your patience!🙏