Bacchus: Multi-Agent Coordination

Bacchus coordinates parallel agent work on codebases using isolated jj workspaces.

Quick Start

For fully autonomous multi-agent work, start Claude in yolo mode:

bash

claude --dangerously-skip-permissions

Then: plan -> import -> orchestrate

bash

# 1. Initialize tasks file
bacchus task init

# 2. Edit .bacchus/tasks.yaml with your task breakdown

# 3. Import to SQLite
bacchus task import --epic-id <EPIC>

# 4. Check ready tasks
bacchus task list --ready

Workflow Commands

Command	Purpose
`bacchus task init`	Create tasks.yaml template
`bacchus task import --epic-id X`	Import to SQLite
`bacchus task list [--ready]`	List tasks
`bacchus task show <id>`	Show task details
`bacchus claim <id> <agent>`	Claim a task
`bacchus release <id> --status done`	Complete task
`bacchus session start agent --task-id X`	Start agent session
`bacchus session start orchestrator`	Start orchestrator session
`bacchus session stop`	Clear session

Handle Commands (Token-Saving)

Use handles to reduce token overhead when searching symbols:

Command	Purpose
`bacchus symbols --handle`	Return handle instead of full data
`bacchus handle expand <handle> [-n N]`	Retrieve data from handle
`bacchus handle filter <handle> --kind X`	Filter creating new handle
`bacchus handle list`	List active handles
`bacchus handle clear`	Clear all handles

Example:

bash

bacchus symbols --search "validate" --handle  # Returns $sym1
bacchus handle expand $sym1 --limit 5         # Get first 5 results
bacchus handle filter $sym1 --kind function   # Returns $sym2 (filtered)

Planning Tasks

Create .bacchus/tasks.yaml:

yaml

version: 1

tasks:
  # Implementation tasks
  # type = PM workflow (bug_fix, feature, refactor, test, docs, infra, generic)
  # archetype = Agent specialization (frontend, backend, data, test, infra, review, security, generic)
  - id: TASK-001
    title: "Add login endpoint"
    type: feature           # PM workflow type
    archetype: backend      # Agent specialization
    priority: 1
    status: open
    depends_on: []
    footprint:
      creates: ["src/api/login.rs"]
      modifies: ["src/api/mod.rs::*"]

  - id: TASK-002
    title: "Add login form component"
    type: feature
    archetype: frontend
    priority: 2
    depends_on: [TASK-001]
    footprint:
      creates: ["src/components/LoginForm.tsx"]

  # Review tasks (depend on implementation)
  - id: TASK-001-SECURITY
    title: "Security review of login endpoint"
    type: feature           # It's a feature task (the review itself)
    archetype: security     # But needs security expertise
    priority: 3
    depends_on: [TASK-001]

  - id: TASK-002-REVIEW
    title: "Code review of login form"
    type: feature
    archetype: review
    priority: 3
    depends_on: [TASK-002]

Archetype System

Bacchus uses archetypes to provide specialized prompts for agents. The planner explicitly assigns an archetype to each task based on the required expertise. Archetypes are defined in archetypes.yaml.

Type vs Archetype:

type: PM workflow category (what kind of work: bug_fix, feature, refactor, test, docs, infra, generic)
archetype: Agent specialization (what expertise: frontend, backend, data, test, infra, review, security, generic)

Archetype Commands

bash

# List available archetypes
bacchus archetype list

# Show archetype details
bacchus archetype show frontend

# Get the prompt for an archetype
bacchus archetype prompt security

# Select best archetype for a task
bacchus archetype select TASK-001

Discovering Archetypes

Archetypes are defined in archetypes.yaml. Use CLI commands to explore:

bash

bacchus archetype list                    # List all archetypes
bacchus archetype show frontend           # See details for one

Customizing Archetypes

Copy to your project to customize:

bash

cp ~/.claude/skills/bacchus/archetypes.yaml .bacchus/archetypes.yaml

Project-level .bacchus/archetypes.yaml takes precedence over the skill default.

Orchestrator Mode

When orchestrating, spawn agents using the Task tool with archetype-specific prompts.

Prerequisites

Before spawning agents, ensure jj is initialized:

bash

# Check if jj is initialized
if ! jj root 2>/dev/null; then
  # Initialize jj in colocated mode (works with existing git repo)
  jj git init --colocate
  jj config set --repo user.name "Bacchus"
  jj config set --repo user.email "bacchus@localhost"
  jj bookmark create main -r @
  jj describe -m "Initial commit"
  jj new
fi

Spawning Agents

Get the archetype for a task:

bash

bacchus archetype select TASK-001

Spawn agent with Task tool in background, using --dangerously-skip-permissions for autonomous execution:

Task tool:
  subagent_type: "general-purpose"
  run_in_background: true
  prompt: |
    Run with: --dangerously-skip-permissions

    [Archetype prompt from bacchus archetype prompt <type>]

    ## Your Task

    Task ID: {task_id}
    Title: {title}
    Description: {description}

    ## Setup

    Start your session and claim the task:
    ```bash
    bacchus session start agent --task-id "{task_id}"
    bacchus claim "{task_id}" agent-{unique_id}
    ```

    ## Work in Workspace

    IMPORTANT: Never `cd` into the workspace. Use `jj -R` flag instead.

    ```bash
    jj -R .bacchus/workspaces/{task_id} status
    jj -R .bacchus/workspaces/{task_id} describe -m "Your commit message"
    jj -R .bacchus/workspaces/{task_id} diff
    ```

    ## Complete

    When done:
    ```bash
    bacchus release {task_id} --status done
    ```

Note: Agents run in yolo mode (--dangerously-skip-permissions) to work autonomously without permission prompts.

Session Management

Sessions enable stop hooks that prevent premature exit:

bash

# Agent mode - blocks until task is closed
bacchus session start agent --task-id TASK-42

# Orchestrator mode - blocks while work remains
bacchus session start orchestrator --max-concurrent 3

# Check status
bacchus session status

# Clear session to allow exit
bacchus session stop

Orchestrator Loop

Each iteration:

Check status: bacchus task list && bacchus task list --ready && bacchus list
Select archetypes: bacchus archetype select <task_id> for each ready task
Spawn agents for ready tasks (up to max_concurrent) with appropriate archetype prompts
Monitor progress: Check for completed/failed agents
Handle releases: Tasks marked ready_for_release get merged by orchestrator
Cleanup stale work: bacchus stale --minutes 30 --cleanup

When session ends (all tasks complete):

bash

git push  # Push all completed work to remote

Note: jj git export runs automatically after each task completes, keeping local git in sync.

Conflict Resolution

If the orchestrator detects merge conflicts:

Task is marked needs_resolution
Agent resolves: jj -R .bacchus/workspaces/{task_id} resolve
Agent marks resolved: bacchus resolve {task_id}

Force Exit

To exit without completing:

bash

bacchus session stop

Example: Full Workflow

bash

# User asks to implement authentication with multiple agents

# 1. Plan the work - create tasks with types and reviews
bacchus task init
# Edit .bacchus/tasks.yaml with implementation + review tasks

# 2. Import tasks
bacchus task import --epic-id AUTH

# 3. Start orchestrator session
bacchus session start orchestrator --max-concurrent 3

# 4. Check ready tasks and their archetypes
bacchus task list --ready
bacchus archetype select AUTH-001  # Shows: backend archetype

# 5. Spawn agents with appropriate archetypes
# (use Task tool with archetype prompts)

# 6. Monitor and wait for completion
bacchus task list
bacchus list  # Active claims

# 7. All done - push to remote and end session
git push
bacchus session stop

Search AI Tools

bacchus

Install this agent skill to your Project

SKILL.md

Bacchus: Multi-Agent Coordination

Quick Start

Workflow Commands

Handle Commands (Token-Saving)

Planning Tasks

Archetype System

Archetype Commands

Discovering Archetypes

Customizing Archetypes

Orchestrator Mode

Prerequisites

Spawning Agents

Session Management

Orchestrator Loop

Conflict Resolution

Force Exit

Example: Full Workflow