Crowd Workflows - Multi-Agent Collaboration Guide

Overview

Responsible-Vibe-MCP supports collaborative workflows that enable teams of specialized AI agents to work together on software development tasks. Each agent has a specific role (business-analyst, architect, developer) and follows the same workflow with role-appropriate instructions.

Quick Setup

1. Copy Agent Configurations

Use the CLI to copy pre-configured agent definitions to your project:

npx responsible-vibe-mcp@latest agents copy

This creates three agent configurations in .crowd/agents/:

• business-analyst.yaml - Requirements and specification expert
• architect.yaml - System design and planning expert
• developer.yaml - Implementation expert

Each agent is pre-configured with:

• VIBE_ROLE environment variable (business-analyst, architect, or developer)
• VIBE_WORKFLOW_DOMAINS=sdd-crowd to access collaborative workflows
• System prompts explaining team collaboration
• MCP server connection to responsible-vibe-mcp

2. Give This Prompt to Your Orchestrator

Copy this prompt and give it to your orchestrating agent (the one with access to crowd-mcp tools):

You are orchestrating a team of AI agents using crowd-mcp and responsible-vibe-mcp.

## Agent Discovery

The project has three pre-configured agents:
- business-analyst
- architect
- developer

## Your Orchestration Process

When I ask you to start a collaborative development task:

1. **Spawn the team** using spawn_agent() with the agent type matching the filename
   - spawn_agent(task="[task] - analysis", agentType="business-analyst")
   - spawn_agent(task="[task] - architecture", agentType="architect")
   - spawn_agent(task="[task] - implementation", agentType="developer")

2. **Choose workflow** based on task type:
   - Feature development → sdd-feature-crowd (starts with business-analyst)
   - Bug fixing → sdd-bugfix-crowd (starts with developer)
   - New project → sdd-greenfield-crowd (starts with architect)

3. **Kick off** by sending message to the starting agent:
   - send_message(to: [agent-id], content: "Start [workflow-name] for [task description]")

4. **Monitor** using get_messages() to see progress updates from agents.
IMPORTANT: The agents will work for long intervals. You may check as often as you like, but don't bother them with repeated questions or status updates

5. **Relay** when agents send_message_to_operator() with questions you cannot answer as they need more information on the context of the development.

## Rules

- Spawn all three agents at start (they work as a persistent team)
- Agents will message each other directly - you monitor and intervene when needed
- When agents ask you questions, ask me and relay my answer

## Example

When I say: "Build user authentication"

You should:
1. spawn_agent(task="Build user authentication - analysis", agentType="business-analyst")
2. spawn_agent(task="Build user authentication - architecture", agentType="architect")
3. spawn_agent(task="Build user authentication - implementation", agentType="developer")
4. send_message(to: business-analyst, content: "Start sdd-feature-crowd for user authentication system")
5. Monitor messages and keep me updated

3. Start Collaborating

Tell your orchestrator to start a development task:

Build a search feature for the product catalog

The orchestrator will:

• Spawn the three agents
• Start the business-analyst with sdd-feature-crowd workflow
• Monitor progress and report back to you

Available Workflows

sdd-crowd Domain - Collaborative specification-driven development workflows:

sdd-feature-crowd

Collaborative feature development with full team participation.

Phases: analyze → specify → clarify → plan → tasks → implement

Role Flow:

• Business-analyst drives: analyze, specify, clarify
• Architect drives: plan, tasks
• Developer drives: implement

Use when: Building new features or enhancing existing ones with a team

sdd-bugfix-crowd

Collaborative bug fixing with systematic approach.

Phases: reproduce → specify → test → plan → fix → verify

Role Flow:

• Developer drives: reproduce, test, fix, verify
• Business-analyst drives: specify
• Architect drives: plan

Use when: Fixing complex bugs that benefit from team expertise

sdd-greenfield-crowd

Collaborative new project development from scratch.

Phases: constitution → specify → plan → tasks → implement → document

Role Flow:

• Architect drives: constitution, plan, tasks
• Business-analyst drives: specify
• Developer drives: implement
• All contribute to: document

Use when: Starting new projects with comprehensive team planning

How Collaboration Works

The RCI Model

Each phase assigns agents one of three roles:

• Responsible (R): Primary driver
  • Edits the plan file
  • Calls proceed_to_phase() to advance
  • Drives the work forward
• Consulted (C): Available for questions
  • Monitors messages
  • Provides expert input when asked
  • Cannot edit plan or proceed
• Informed (I): Passive monitoring
  • Stays aware of progress
  • No active participation required

Note: The human operator is always implicitly informed.

Role Assignment Examples

sdd-feature-crowd specify phase:

• Business-analyst: RESPONSIBLE (drives specification)
• Architect: CONSULTED (answers technical feasibility questions)
• Developer: CONSULTED (provides complexity estimates)

sdd-feature-crowd implement phase:

• Developer: RESPONSIBLE (drives implementation)
• Architect: CONSULTED (answers design questions)
• Business-analyst: CONSULTED (clarifies requirements)

Collaboration Protocol

1. Handoff Pattern:

Business-analyst (RESPONSIBLE in specify phase):
  1. Completes specification work
  2. Sends: send_message(architect-id, "Please take lead for plan phase")
  3. Reports: send_message_to_operator("Spec complete, handing to architect")
  4. Calls: proceed_to_phase(target_phase: "plan")
  5. Becomes: CONSULTED in plan phase

Architect (CONSULTED → RESPONSIBLE):
  1. Receives handoff message
  2. Becomes RESPONSIBLE in plan phase
  3. Drives planning work

2. Consultation Pattern:

Architect (RESPONSIBLE in plan phase):
  1. Has question about requirements
  2. Sends: send_message(business-analyst-id, "What does requirement X mean?")

Business-analyst (CONSULTED in plan phase):
  1. Receives: get_my_messages()
  2. Responds: send_message(architect-id, "Requirement X means...")

Architect:
  3. Continues planning with clarified information

Agent Configuration

System Prompts

All agent system prompts follow the same pattern:

• Explain team structure and roles
• Describe available tools (whats_next, send_message, etc.)
• Emphasize important rules (only responsible edits plan, always call whats_next)
• Keep role responsibilities generic (workflow provides specific tasks)

Example Configuration

name: business-analyst
displayName: Business Analyst
systemPrompt: |
  You are working as a business-analyst in a collaborative team.

  Your team: business-analyst (you), architect, developer

  ## How Collaboration Works
  You follow structured workflows. In each phase, you may be:
  - RESPONSIBLE (driving), CONSULTED (answering questions), or INFORMED (monitoring)

  ## Available Tools
  - whats_next(): Get phase guidance (call after every message)
  - proceed_to_phase(): Move forward (only when responsible)
  - send_message(to, content): Collaborate with team
  - send_message_to_operator(content): Report to human
  - get_my_messages(): Check for questions

mcpServers:
  responsible-vibe:
    type: stdio
    command: npx
    args: [responsible-vibe-mcp@latest]
    env:
      VIBE_ROLE: business-analyst
      VIBE_WORKFLOW_DOMAINS: sdd-crowd

Workflow Features

$VIBE_ROLE Variable

Workflows use $VIBE_ROLE for dynamic agent identification:

default_instructions: |
  You are $VIBE_ROLE working in a collaborative team.
  Current phase: SPECIFY

Substituted at runtime:

• Business-analyst sees: "You are business-analyst working..."
• Architect sees: "You are architect working..."

Role-Specific Instructions

Each transition provides role-appropriate guidance:

transitions:
  - trigger: spec_complete
    to: plan
    role: business-analyst
    additional_instructions: |
      You are RESPONSIBLE. Create spec, then hand off.

  - trigger: spec_complete
    to: plan
    role: architect
    additional_instructions: |
      You are CONSULTED. Answer questions when asked.

Transition Filtering

Each agent only sees transitions for their role:

• Business-analyst sees only role: business-analyst transitions
• Architect sees only role: architect transitions
• Developer sees only role: developer transitions
• Transitions with no role shown to everyone

Validation

Tool Validation (proceed_to_phase):

• Verifies agent has valid transition to target phase
• Prevents agents from proceeding when not responsible
• Clear error messages when validation fails

Plan File Editing:

• Enforced via instructions (cannot validate at tool level)
• RESPONSIBLE: "Only you can edit the plan file"
• CONSULTED: "Do NOT edit the plan file"

Usage Examples

Starting a Feature with Team

# Human operator (via Claude Desktop + crowd-mcp):
"Spawn business-analyst, architect, and developer agents to build user authentication"

# Agents spawn and start sdd-feature-crowd workflow
# Each agent calls whats_next() and gets role-specific instructions

# Business-analyst (RESPONSIBLE in analyze):
- Analyzes requirements
- Messages architect: "What authentication patterns do we use?"
- Messages developer: "How complex is OAuth integration?"
- Completes analysis
- Hands off to specify phase

# Business-analyst (RESPONSIBLE in specify):
- Creates specification
- Messages team for review
- Hands off to architect

# Architect (RESPONSIBLE in plan):
- Creates technical plan
- Messages developer for feedback
- Creates task breakdown
- Hands off to developer

# Developer (RESPONSIBLE in implement):
- Implements features
- Messages architect with design questions
- Messages business-analyst for requirement clarifications
- Completes implementation

Agent Perspectives

What business-analyst sees in specify phase:

You are RESPONSIBLE for the specify phase.

You have exclusive control:
- Only you can edit the plan file
- Only you can proceed to next phase

Tasks:
- Create specification...
- Use send_message to ask architect about technical feasibility
- Use send_message to ask developer about implementation complexity

Before proceeding:
- Send handoff message to architect
- Report to operator
- Call proceed_to_phase

What architect sees in specify phase:

You are CONSULTED during the specify phase.

Business-analyst is driving this work.

Your responsibilities:
- Monitor messages for questions
- Provide technical feasibility input
- Review specification when asked

Constraints:
- Do NOT edit plan file
- Do NOT proceed to next phase

Best Practices

1. Always Call whats_next()

Every agent should call whats_next() after each user message to get current phase guidance.

2. Use Messaging Proactively

Agents should actively collaborate:

• Ask questions when uncertain
• Request reviews before proceeding
• Share information proactively
• Keep operator informed of progress

3. Respect Role Boundaries

• Only RESPONSIBLE agent edits plan file
• Only RESPONSIBLE agent calls proceed_to_phase
• CONSULTED agents wait for questions
• Clear communication about role transitions

4. Explicit Handoffs

When transitioning phases:

1. Complete your work
2. Send handoff message to next responsible agent
3. Notify other team members
4. Report to operator
5. Call proceed_to_phase

Troubleshooting

"Agent with role 'X' cannot proceed"

Cause: Agent trying to proceed when not responsible for target phase

Solution: Only the responsible agent can call proceed_to_phase. Check workflow to see who should be driving the target phase.

Agent Not Seeing Transitions

Cause: VIBE_ROLE not set or doesn't match workflow roles

Solution: Verify agent configuration has VIBE_ROLE environment variable set correctly.

Multiple Agents Editing Plan File

Cause: Agents not following role instructions

Solution: Ensure agents read and follow their role-specific instructions. Only RESPONSIBLE agent should edit plan file.

Technical Details

Environment Variables

• VIBE_ROLE: Agent's role (business-analyst, architect, developer)
  • Required for collaborative workflows
  • Optional for single-agent workflows
• VIBE_WORKFLOW_DOMAINS: Filter workflows by domain
  • Set to sdd-crowd for collaborative workflows
  • Can combine: sdd-crowd,sdd for both

Workflow Schema

Collaborative workflows extend the standard workflow schema:

• role?: string on transitions
• collaboration?: boolean in metadata
• requiredRoles?: string[] in metadata

All fields optional - backward compatible with existing workflows.

Resources

• Agent Templates: .crowd/agents/

  • business-analyst.yaml
  • architect.yaml
  • developer.yaml

• Workflows: resources/workflows/sdd-crowd/

  • sdd-feature-crowd.yaml
  • sdd-bugfix-crowd.yaml
  • sdd-greenfield-crowd.yaml

• Tests: test/integration/crowd-workflows.test.ts

  • 11 tests covering all collaboration features

• Integration: Designed for crowd-mcp