feat : multi agent collaboration

[Nixxx19]

Summary

Implements a complete multi-agent collaboration framework for mofaClaw — specialized agents that work together through structured communication, workflow orchestration, and shared artifact management — and makes it accessible through natural language chat via a consolidated skill.

Previously, subagents had no coordination primitives, no shared state, and no role specialization. This PR closes all of those gaps and wires the system into the main agent loop so users can trigger multi-agent workflows conversationally.

---

Related Issues

Closes #58

---

Context & Pain Points Addressed

Before this PR

• Every subagent started from scratch — no shared memory, no roles, no handoffs
• Complex tasks (code review, design review, iterative implementation) required manual context copying between sessions
• No structured way to divide work by expertise
• No way for a user to say "have the team review this" — multi-agent was CLI-only
• Three separate skills (code-review, design-review, team-task) with overlapping triggers and no hub compatibility
• Workflows blocked the caller — start_workflow would not return until the entire workflow completed
• Steps within a workflow ran sequentially even when independent
• No persistence — teams and workflows vanished on restart

After this PR

• Full multi-agent collaboration accessible via natural language ("review my code", "use the team")
• A single consolidated multi-agent skill with ClawHub-compatible manifest.json
• Non-blocking workflow execution — start_workflow returns a workflow_id immediately
• Parallel step execution within topological layers (e.g. code review + test writing run concurrently)
• Teams and workflows persist across restarts; inactive teams show in list_teams with "recreate to use" guidance
• 171 tests passing, zero clippy warnings

---

Architecture

Current Implementation

flowchart TD
    User[User Message] --> AgentLoop[Main AgentLoop]
    AgentLoop --> SkillsManager[SkillsManager]
    SkillsManager --> MultiAgentSkill[multi-agent Skill]
    MultiAgentSkill --> AgentLoop

    AgentLoop --> ToolRegistry[ToolRegistry]
    ToolRegistry --> MultiAgentTools[Multi-Agent Tools]
    MultiAgentTools --> TeamManager[TeamManager]
    MultiAgentTools --> WorkflowEngine[WorkflowEngine Controller]
    MultiAgentTools --> SharedWorkspace[SharedWorkspace]

    TeamManager --> AgentTeam[AgentTeam]
    WorkflowEngine -->|process_direct| DevAgent[Developer Agent]
    WorkflowEngine -->|process_direct| RevAgent[Reviewer Agent]
    WorkflowEngine -->|process_direct| ArchAgent[Architect Agent]

    style MultiAgentTools fill:#4a90e2,color:#fff
    style MultiAgentSkill fill:#f39c12,color:#fff
    style WorkflowEngine fill:#e74c3c,color:#fff
    style TeamManager fill:#9b59b6,color:#fff

Loading

The proposed event-driven architecture (agents with persistent event loops, WorkflowEngine as coordinator, AgentMessageBus as hub) is documented in docs/MULTI_AGENT_ARCHITECTURE.md and deferred to a future PR when a concrete use case requires it.

---

Changes

Skill & Hub Integration (skills/)

• Consolidated code-review/, design-review/, team-task/ into one skills/multi-agent/SKILL.md
• Trigger phrases cover all use cases: "review my code", "review this PR", "review this architecture", "review this design", "have the team work on this", "use the team", "multi-agent review"
• skills/multi-agent/manifest.json — ClawHub-compatible permissions manifest declaring all 12 multi-agent tools; no filesystem or network access needed
• skills/README.md updated

Non-Blocking Workflow Execution (core/src/agent/collaboration/workflow.rs)

• WorkflowEngine::start_async() — spawns workflow in a background tokio::task, returns unique workflow_id immediately (format: code_review-{uuid8})
• StartWorkflowTool now returns {workflow_id, status: "started", message: "Poll get_workflow_status..."} instead of blocking
• GetWorkflowStatusTool returns step results with output previews for polling

Parallel Step Execution

• compute_execution_layers() — topological sort grouping independent steps into concurrent layers
• Steps with no intra-layer dependencies run via join_all() — e.g. code review + test writing run in parallel after implementation completes
• Falls back to sequential on dependency cycles with a warning

Persistence

• Workflows: serde Serialize/Deserialize on all types; save_workflow_state() after every transition; load_persisted_workflows() on startup (stale Running/WaitingApproval → Failed)
• Teams: TeamSnapshot (id, name, roles, member_count, created_at) saved to {data_dir}/teams/{id}.json; TeamManager::with_persistence() async constructor; list_teams_detailed() returns active + inactive with status
• GetTeamStatusTool falls back to snapshot for inactive teams with "recreate to use" message
• Both TeamManager and WorkflowEngine use with_persistence() in CLI entry points

Orchestrator Artifact Access

• register_multi_agent_tools() now always registers CreateArtifactTool, using a synthetic AgentId("main", "orchestrator", "main") when no agent_id is provided — previously the tool was silently skipped for the main agent

CLI Integration (cli/src/main.rs)

• Both command_gateway() and command_agent() now instantiate TeamManager::with_persistence(), WorkflowEngine::with_persistence(), SharedWorkspace, and call register_multi_agent_tools() — multi-agent tools available in all agent modes without any config

Agent Roles (core/src/agent/roles/)

• AgentRole trait: name(), description(), system_prompt(), allowed_tools(), capabilities()
• RoleCapabilities: can_read_files, can_write_files, can_execute_commands, can_spawn_subagents, max_iterations, temperature
• Four concrete roles: ArchitectRole, DeveloperRole, ReviewerRole, TesterRole
• RoleRegistry for lookup

Inter-Agent Communication (core/src/agent/communication/)

• AgentId (team_id + role + instance_id), serialized as "team:role:instance"
• AgentMessage variants: Request, Response, Broadcast, ArtifactUpdate
• RequestType: AskQuestion, RequestReview, RequestImplementation, RequestTesting, ShareFinding, RequestApproval, RequestInformation
• AgentMessageBus — tokio broadcast channel with topic subscriptions and per-agent routing

Shared Workspace (core/src/agent/collaboration/workspace.rs)

• Artifact with versioning, author tracking, ArtifactType (CodeFile, DesignDoc, TestFile, ReviewComment)
• create_artifact(), update_artifact() (auto-increments version), get_artifact(), list_artifacts()
• Disk persistence to {base_dir}/{team_id}/artifacts.json
• RBAC-aware variants check can_write_files/can_read_files role capabilities
• Conflict resolution: LastWriteWins, ManualMerge, AutomaticMerge

Tools (core/src/tools/)

• team.rs — CreateTeamTool, ListTeamsTool (detailed with active/inactive), GetTeamStatusTool (snapshot fallback)
• workflow.rs — StartWorkflowTool (non-blocking), GetWorkflowStatusTool, ListWorkflowsTool
• workspace.rs — CreateArtifactTool, GetArtifactTool, ListArtifactsTool
• agent_message.rs — SendAgentMessageTool, BroadcastToTeamTool, RespondToApprovalTool
• multi_agent.rs — register_multi_agent_tools() wires everything with a single call

Documentation

• docs/MULTI_AGENT_ARCHITECTURE.md — current vs proposed architecture with mermaid diagrams, 4-phase migration plan, use case trigger table
• docs/MULTI_AGENT_INTEGRATION_PLAN.md — implementation plan with current + proposed architecture diagrams

---

How it was Tested

cargo fmt --check  →  clean
cargo clippy       →  0 warnings (from new code)
cargo test -p mofaclaw-core

running 171 tests
test result: ok. 171 passed; 0 failed; 5 ignored

New Tests Added

• test_start_async_is_non_blocking — verifies start_async returns in <500ms
• test_start_async_unique_ids — 3 runs produce 3 distinct workflow IDs
• test_team_snapshot_persistence — two TeamManager instances over same TempDir, verifies persistence round-trip
• test_workflow_serialization — serde round-trip for full Workflow struct
• test_compute_execution_layers_code_review — verifies 3 layers, layer 1 has 2 parallel steps
• test_compute_execution_layers_design — verifies 3 sequential layers

---

Examples

• examples/multi_agent_team_example.rs — creates a team, assigns roles, member access patterns
• examples/multi_agent_workflow_example.rs — code review workflow end-to-end, context propagation
• examples/multi_agent_config.json — sample config for a three-agent team

---

Breaking Changes

None — all existing single-agent workflows, tool registries, and channel integrations unaffected

---

Checklist

Code Quality

• cargo fmt clean
• cargo clippy — zero warnings in new code
• Rust idioms followed throughout

Testing

• 171 tests passing, 0 failures
• New async tests for non-blocking execution, persistence, unique IDs
• cargo build --examples passes

Documentation

• Public APIs documented
• Architecture doc with mermaid diagrams (docs/MULTI_AGENT_ARCHITECTURE.md)
• Integration plan (docs/MULTI_AGENT_INTEGRATION_PLAN.md)

PR Hygiene

• No breaking changes
• Commit messages explain why, not only what

[Copilot]

Pull request overview

Adds an opt-in multi-agent collaboration subsystem to mofaclaw, introducing role-specialized agents, inter-agent messaging, workflow orchestration with approval gates, shared workspace artifacts, and CLI/tooling to operate the new features.

Changes:

• Introduces agent roles (architect/developer/reviewer/tester) with capability/tool constraints and a role registry.
• Adds inter-agent communication (protocol + message bus), team management, and a workflow engine with step context propagation and approvals.
• Adds workspace artifact management + persistence, plus new tools, CLI subcommands, docs, and examples.

Reviewed changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
examples/multi_agent_workflow_example.rs	Demonstrates team creation + workflow execution.
examples/multi_agent_team_example.rs	Demonstrates team creation and listing members.
examples/multi_agent_config.json	Sample JSON config for teams + workflows.
docs/MULTI_AGENT_COLLABORATION.md	End-user documentation for the multi-agent system and CLI/tools.
core/src/tools/workspace.rs	Adds workspace-related tools (create/get/list artifacts).
core/src/tools/workflow.rs	Adds workflow-related tools (start/status/list).
core/src/tools/team.rs	Adds team-related tools (create/list/status).
core/src/tools/multi_agent.rs	Helper to register the multi-agent tool suite into a registry.
core/src/tools/mod.rs	Exposes new tool modules and re-exports.
core/src/tools/agent_message.rs	Adds tools for agent-to-agent messaging + approval responses.
core/src/rbac/tests.rs	Formatting/refactor in RBAC tests (no functional change).
core/src/rbac/path_matcher.rs	Formatting/refactor in RBAC matcher tests (no functional change).
core/src/rbac/mod.rs	Reorders RBAC re-exports.
core/src/rbac/manager.rs	Formatting/refactor; minor readability changes.
core/src/lib.rs	Adjusts module ordering (adds/positions rbac).
core/src/channels/discord/mod.rs	Removes an extraneous blank line.
core/src/agent/roles/tester.rs	Implements Tester role + tests.
core/src/agent/roles/reviewer.rs	Implements Reviewer role + tests.
core/src/agent/roles/mod.rs	Adds roles module and RoleRegistry.
core/src/agent/roles/developer.rs	Implements Developer role + tests.
core/src/agent/roles/base.rs	Adds AgentRole trait + RoleCapabilities.
core/src/agent/roles/architect.rs	Implements Architect role + tests.
core/src/agent/mod.rs	Wires new collaboration/communication/roles modules and re-exports.
core/src/agent/loop_.rs	Adds AgentLoop::with_agent_and_tools_custom for per-role overrides.
core/src/agent/communication/protocol.rs	Defines AgentId, AgentMessage, and message enums + tests.
core/src/agent/communication/mod.rs	Exposes communication submodules and re-exports types.
core/src/agent/communication/bus.rs	Implements AgentMessageBus with broadcast-based delivery + tests.
core/src/agent/collaboration/workspace.rs	Implements SharedWorkspace artifacts, versioning, persistence, conflict handling + tests.
core/src/agent/collaboration/workflow.rs	Implements WorkflowEngine, workflow/step/result structs, built-in workflows + tests.
core/src/agent/collaboration/tests.rs	Adds collaboration integration tests (some ignored).
core/src/agent/collaboration/team.rs	Implements TeamManager, AgentTeam, member creation with role-specific tool filtering + tests.
core/src/agent/collaboration/mod.rs	Exposes collaboration modules and re-exports types.
core/Cargo.toml	Registers new examples for the core crate.
cli/src/main.rs	Adds CLI subcommands for team/workflow/workspace operations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.