mexus-agent-team

Standalone Markdown-only Agent Team plugin for Claude Code and Codex. Coordination happens through ordinary Markdown files in the current pr

Open source Open in the app JSON README (API)

About

Standalone Markdown-only Agent Team plugin for Claude Code and Codex. Coordination happens through ordinary Markdown files in the current project: agent-team/ ├── mission-workflow.md ├── agents.md └── missions/<mission-name>/ ├── mission.md ├── agents.md ├── kanban.md ├── roundtable.md └── squad-lead.md

Details

Kind: Plugins
Topic: Files & documents
Publisher: yofine
Origin: marketplace
Category: ferramentas
Stars: 11
Last push: 2026-06-04T16:23:54Z
Repository state: ativo
Language: JavaScript
Added: 2026-08-30 01:48:58
Updated: 2026-08-30 01:48:58
Origin id: yofine/mexus-agent-team/mexus-agent-team

README

<div align="center">
<h1>Mexus Agent Team</h1>
<p><b>A Markdown-only agent team workflow for Claude Code and Codex.</b></p>
</div>

<br/>

## Why

A **Mission** is a bounded objective. A **Squad Lead** decomposes it, names a squad, and publishes tasks to a kanban. Background Agents claim tasks, do the work, and write results back. Every handoff is a Markdown edit you can open, diff, and review.

The kanban file *is* the coordination protocol. If you can read `kanban.md`, you know what every agent is doing and why.

This is a standalone plugin for **Claude Code** and **Codex**. It does not require a Mexus server, panes, a Mission Inbox, or external A2A messaging — coordination happens entirely through the `agent-team/` Markdown files.

## How It Works

Coordination lives entirely in one directory of your project:

```text
agent-team/
├── mission-workflow.md the reusable collaboration rules
├── agents.md repository-level reusable agent roster
└── missions/<mission-name>/
├── mission.md goal, lifecycle, constraints
├── agents.md this Mission's squad and prompts
├── kanban.md task source of truth — the protocol
├── roundtable.md shared decisions
├── squad-lead.md Squad Lead coordination log
└── artifacts/ long-form deliverables (research, decisions, docs)
```

- **Squad Lead** is a fixed coordination role — it plans, dispatches, sequences, and accepts. It never writes another agent's results.
- **Mission Agents** are background workers, named at random from the 72 spirits of the Ars Goetia. Each claims one scoped task, self-tests it, and fills in its own kanban block.
- **Publisher acceptance**: whoever publishes a task (`From`) reviews and accepts it. Squad Lead does mission-level acceptance on top.

Starting a new Mission archives the previous active one. Agents communicate only through the kanban file.

## Artifacts

Long-form deliverables that are not source code — research reports, market scans, decision rationales, design memos — live as Markdown files under `agent-team/missions/<name>/artifacts/`. Each file starts with a YAML frontmatter block (`title`, `author`, `date`, optional `related` and `tags`) so the board can list and render it.

Three rules keep artifacts from being skipped:

- **Research and document tasks** must name the artifact path in their `Acceptance` field. The executor writes the file and lists the path in `Files:`.
- **RoundTable proposals that pass review** must produce a decision-record artifact (`artifacts/<date>-rt-<topic-slug>.md`) before they are considered closed.
- **Mission-level acceptance** checks both of the above before Squad Lead declares the Mission complete.

The board's **Artifacts tab** renders each file as HTML and shows author, date, related refs, and tags. See `references/artifact-template.md` for the file skeleton and `agent-team/mission-workflow.md` (`## Artifacts`) for the full rules.

## Commands

Plugin skills are namespaced by the plugin. This plugin uses the `mexus-team` namespace.

Within one `/mexus-team:mission` session, Squad Lead dispatches follow-up tasks on its own — you do not run a command for that. `/mexus-team:continue` exists only to pick a Mission back up after the original session has ended.

## Install

In Claude Code, add the marketplace from the GitHub repo and install the bundle:

```text
/plugin marketplace add yofine/mexus-agent-team
/plugin install mexus-team@mexus-team
/reload-plugins
```

`mexus-team@mexus-team` is `<plugin-name>@<marketplace-name>`. Both are defined in `.claude-plugin/marketplace.json`; the GitHub repo slug (`mexus-agent-team`) is not the install handle.

The bundle registers all five commands under the `mexus-team:` namespace. The marketplace also carries per-skill entries such as `mexus-team-mission@mexus-team` for future single-skill installs; install the bundle for now.

To update after the upstream changes:

```text
/plugin uninstall mexus-team
/plugin install mexus-team@mexus-team
/reload-plugins
```

## Workflow

A typical Mission, start to finish:

1. **Create and run** — `/mexus-team:mission "Implement the feature or fix"`. This plans the squad, publishes kanban tasks, starts the board, and dispatches the first Agents. Squad Lead keeps coordinating follow-up work in the same session.
2. **Watch** — open the board separately with `/mexus-team:board` if you want a live view. It shows Mission Plan, Kanban, Agents, Squad Lead Log, and RoundTable.
3. **Decide** — `/mexus-team:roundtable "Choose the API boundary"` when a choice spans multiple agents or shared interfaces.
4. **Check** — `/mexus-team:status` for a quick terminal summary.
5. **Resume** — `/mexus-team:continue` in a new session to keep an unfinished Mission moving.

## Board

The board command starts a local Vite app and an API server. By default it binds to `0.0.0.0`, so it can be opened from another device on your network. If a board is already running for the project, it is reused and its URL reprinted instead of starting a second one.

```text
/mexus-team:board --host 0.0.0.0
/mexus-team:board --host 0.0.0.0 --public-host <lan-ip-or-hostname>
```

The board is read-only and runs in the foreground — stop it with `Ctrl+C` in its terminal.

## Roster Maintenance

`agent-team/agents.md` is the repository-level roster of reusable Agents. It is updated from accepted Mission work, not edited as scratch space — the active Mission's `agents.md` and accepted `kanban.md` tasks are the source for durable module ownership, known strengths, and work history.

## Design Notes

- The whole protocol is Markdown in the repo. Coordination is a file edit, review is a diff, and the history is in `git log`.
- `Squad Lead` is the single fixed coordination role; execution Agents are named at random from the Ars Goetia set, so a name is a handle and not a task label.
- Commands have non-overlapping jobs: `mission` only creates, `continue` only resumes, the rest only observe.

## Verify Locally

```bash
node tests/standalone-smoke.test.mjs
```

Try it against a temp project:

```bash
mkdir -p /tmp/mexus-agent-team-demo
cd /tmp/mexus-agent-team-demo

node /absolute/path/to/mexus-agent-team/scripts/start-mission.mjs \
--root "$PWD" --name demo-mission --request "Build a small demo feature"

node /absolute/path/to/mexus-agent-team/scripts/status.mjs --root "$PWD" --name demo-mission
node /absolute/path/to/mexus-agent-team/scripts/start-board.mjs --root "$PWD" --host 0.0.0.0
```

## License

Apache-2.0. Use it and contribute back.

mexus-agent-team

About

Details

README

More