Agent skill

bacchus

Multi-agent coordination for parallel development. Use when asked to parallelize work, coordinate multiple agents, or manage tasks across a codebase.

View SKILL.md on GitHub Repository
Stars 0
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/vu1n/bacchus/tree/main/skills/bacchus

SKILL.md

Bacchus: Multi-Agent Coordination

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

Swarm Methodology

Use this control loop:

  1. Plan atomic tasks with dependencies, footprints, and archetypes
  2. Admit only dependency-clear, non-overlapping tasks
  3. Execute one task per worker in isolated jj workspaces
  4. Reconcile merges plus stale/failed worker recovery
  5. Measure with bacchus eval reliability + throughput metrics

Quick Start

Use Ralph mode by default:

bash
claude

Use yolo mode only for trusted local repos when fully autonomous execution is required:

bash
claude --dangerously-skip-permissions

Then: plan -> import -> orchestrate

bash
# 0. Bootstrap repo (jj + tasks template + optional epic)
bacchus init --epic-id <EPIC>

# 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

Agentic Quick Start Prompt (Paste Into LLM)

text
Use bacchus to implement: <GOAL>

Execution contract:
1) Ensure jj is initialized for this repo (colocated with git if needed).
2) Create/update tasks in .bacchus/tasks.yaml with dependencies, footprints, and archetypes.
3) Import tasks and verify ready queue.
4) Start orchestrator session with max concurrency 3.
5) Dry-run spawn once, then launch workers.
6) Process releases and recover stale/failed workers until done.
7) Finish with eval metrics and a concise risk summary.

Required commands:
- bacchus task import --epic-id <EPIC>
- bacchus task list --ready
- bacchus session start orchestrator --max-concurrent 3
- bacchus session spawn-workers --count 3 --dry-run
- bacchus session spawn-workers --count 3
- bacchus process-releases
- bacchus eval --days 7

Workflow Commands

Command Purpose
bacchus init [--skip-jj] [--force-tasks] [--epic-id X --epic-title Y] Bootstrap bacchus in current repo
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 heartbeat <id> <agent> Refresh claim heartbeat
bacchus release <id> --status done Complete task
bacchus process-releases Orchestrator merge step
bacchus events --limit 50 Inspect orchestration event log
bacchus session start agent --task-id X [--agent-id Y] Start agent session (heartbeat loop starts when owner is known)
bacchus session start orchestrator Start orchestrator session
bacchus session start architect --agent-id X Start architect session
bacchus session spawn-workers [--count N] [--dry-run] Launch ready workers once for active orchestrator session
bacchus session stop Clear session
bacchus session prune [--minutes N] Remove stale scoped sessions and orphaned expired leases
bacchus message claim <agent> --limit N Claim architect/agent messages
bacchus message ack <id> <agent> Ack claimed message
bacchus message fail <id> <agent> --reason X Fail claimed message
bacchus epic set-status <id> <status> Move epic through planning/active/closed

Autonomous Worker Spawning

Worker config lives in .bacchus/config.yaml (generated by bacchus init):

yaml
worker:
  cmd: "claude --dangerously-skip-permissions -p '/bacchus-worker $BACCHUS_AGENT_ID $BACCHUS_TASK_ID'"
  # auto_spawn: true     # auto-spawn on session check (default: true)
  # max_retries: 3
  # retry_backoff_ms: 60000
  # stale_grace_ms: 60000
  # max_runtime_ms: 1800000  # optional: 30-min runtime budget
  # kill_stale: false        # optional: terminate stale worker PIDs

Env vars override config.yaml for CI/scripting (e.g., BACCHUS_WORKER_CMD, BACCHUS_WORKER_MAX_RETRIES).

Use bacchus session spawn-workers --dry-run to preview ready tasks/slots before launching. Stale worker recovery is automatic: stale worker rows are failed and their tasks are reset to open.

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

  1. Get the archetype for a task:
bash
bacchus archetype select TASK-001
  1. Spawn agent with Task tool in background. Use --dangerously-skip-permissions only in trusted yolo flows:
Task tool:
  subagent_type: "general-purpose"
  run_in_background: true
  prompt: |
    Run with:
    - Ralph mode default: no extra flag
    - Yolo mode (trusted repo only): --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}" --agent-id agent-{unique_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: Ralph mode is preferred for safety and observability. Use yolo mode only in explicitly trusted environments.

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 --agent-id agent-1

# 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

# Cleanup stale scoped session files
bacchus session prune --minutes 240

When running multiple agents from the same repo root, set BACCHUS_SESSION_ID per agent/session to avoid session-state collisions.

Only one orchestrator can hold the leader lease at a time. If another orchestrator is active, a new start is rejected.

Orchestrator Loop

Each iteration:

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

If not running via stop-hook loop, trigger merges manually:

bash
bacchus process-releases

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:

  1. Task is marked needs_resolution
  2. Agent resolves: jj -R .bacchus/workspaces/{task_id} resolve
  3. 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

# 3.1 Optionally spawn ready workers immediately
bacchus session spawn-workers --count 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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

mattpocock/skills

migrate-to-shoehorn

Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data.

111,310 9,758
Explore
mattpocock/skills

git-guardrails-claude-code

Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code.

111,310 9,758
Explore
mattpocock/skills

handoff

Compact the current conversation into a handoff document for another agent to pick up.

111,310 9,758
Explore
mattpocock/skills

scaffold-exercises

Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.

111,310 9,758
Explore
mattpocock/skills

setup-pre-commit

Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.

111,310 9,758
Explore
mattpocock/skills

obsidian-vault

Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian.

111,310 9,758
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results