edict

Setup, sync, and runtime for multi-agent workflows. Bootstraps projects with workflow docs and companion tool configurations, keeps them synchronized across upgrades, and provides built-in agent loop subcommands with protocol guidance.

Eval Results

32 behavioral evaluations across Opus, Sonnet, and Haiku. The eval framework tests whether agents follow the edict protocol when driven autonomously through the botty-native spawn chain (hooks → botty spawn → edict run).

Takeaway: The full autonomous pipeline works. Agents spawn via hooks, coordinate across projects via bus channels, review each other's code via crit, and merge work through maw — all without human intervention. Friction comes from CLI typos, not protocol failures. See evals/results/ for all 32 runs and detailed findings.

What is edict?

edict is a Rust CLI (stable edition 2024) that:

1. Initializes projects for multi-agent collaboration (interactive or via flags)
2. Syncs workflow docs from embedded templates to .agents/edict/
3. Validates health via doctor command
4. Runs agent loops as built-in subcommands (dev-loop, worker-loop, reviewer-loop, responder)
5. Provides protocol commands that guide agents through state transitions (protocol start, merge, finish, etc.)

It glues together 5 companion tools (bus, maw, br/bv, crit, botty) into a cohesive workflow and provides the runtime that drives agent behavior.

Install

cargo install edict-cli
# or from source:
cargo install --path .

Usage

# Bootstrap a new project (interactive)
edict init

# Bootstrap with flags (for agents)
edict init --name my-api --type api --tools beads,maw,crit,bus --reviewers security --no-interactive

# Sync workflow docs after edict upgrades
edict sync

# Check if sync is needed
edict sync --check

# Validate toolchain and project setup
edict doctor

# Run agent loops (typically invoked by botty spawn, not manually)
edict run dev-loop --agent myproject-dev
edict run worker-loop --agent myproject-dev/worker-1
edict run reviewer-loop --agent myproject-security

# Protocol commands — check state and get guidance at transitions
edict protocol start <bead-id> --agent $AGENT
edict protocol merge <workspace> --agent $AGENT
edict protocol finish <bead-id> --agent $AGENT

What gets created?

After edict init:

.agents/edict/          # Workflow docs (embedded in binary, synced to project)
  docs/
    triage.md            # Find work from inbox and beads
    start.md             # Claim bead, create workspace, announce
    update.md            # Post progress updates
    finish.md            # Close bead, merge workspace, release claims
    worker-loop.md       # Full triage-start-work-finish lifecycle
    review-request.md    # Request code review via crit
    review-response.md   # Handle reviewer feedback (fix/address/defer)
    review-loop.md       # Reviewer agent loop
    merge-check.md       # Verify approval before merge
    preflight.md         # Validate toolchain health
    cross-channel.md     # Ask questions, report bugs across projects
    report-issue.md      # Report bugs/features to other projects
    planning.md          # Turn specs/PRDs into actionable beads
    scout.md             # Explore unfamiliar code before planning
    proposal.md          # Create and validate proposals before implementation
    groom.md             # Groom backlog
    mission.md           # Mission-based parallel dispatch (dev-loop)
    coordination.md      # Multi-agent coordination patterns
  design/
    cli-conventions.md   # CLI tool design for humans, agents, and machines
  prompts/
    reviewer.md          # Generic reviewer prompt template
    reviewer-security.md # Security reviewer prompt template
  hooks/                 # Claude Code event hooks (SessionStart, PostToolUse)
  .version               # Version hash for sync tracking
AGENTS.md                # Generated with managed section + project-specific content
CLAUDE.md -> AGENTS.md   # Symlink
.edict.json             # Project configuration

Workflow docs

The workflow docs in .agents/edict/docs/ define the protocol. These are embedded in the Rust binary as compile-time templates and synced to projects during edict init and edict sync.

When edict updates, run edict sync to pull the latest workflow doc changes.

Agent loops

Agents are spawned automatically via botbus hooks when messages arrive on project channels. The spawn chain:

message → botbus hook → botty spawn → edict run responder → edict run dev-loop

Agent loops are built-in Rust subcommands of the edict binary:

• edict run responder — Universal router. Routes !dev, !q, !bead prefixes; triages bare messages.
• edict run dev-loop — Lead dev. Triages work, dispatches parallel workers, monitors progress, merges.
• edict run worker-loop — Worker. Sequential: triage → start → work → review → finish.
• edict run reviewer-loop — Reviewer. Processes crit reviews, votes LGTM or BLOCK.
• edict run triage — Token-efficient triage. Wraps bv --robot-triage with scannable output.
• edict run iteration-start — Combined status snapshot. Aggregates inbox, beads, reviews, claims.

No manual agent management needed — send a message to a project channel and the hook chain handles the rest.

Ecosystem

Edict coordinates five specialized Rust tools that work together to enable multi-agent workflows:

Flywheel connection

Edict is inspired by and shares tools with the Agentic Coding Flywheel ecosystem. We use the same br (beads_rust) for issue tracking and bv (beads_viewer) for triage. The built-in edict run triage command wraps bv --robot-triage to provide token-efficient work prioritization using PageRank-based analysis.

How they work together

1. botbus provides the communication layer: agents send messages, claim resources (beads, workspaces), and discover each other
2. beads tracks work items and priorities, exposing a triage interface (br ready, bv --robot-next)
3. maw creates isolated workspaces so multiple agents can work concurrently without conflicts
4. crit enables code review: agents request reviews, reviewers comment, and changes merge after approval
5. botty spawns and manages agent processes, handling crashes and lifecycle

edict configures projects to use these tools, keeps workflow docs synchronized, and runs the agent loops (edict run dev-loop, edict run worker-loop, etc.) that drive the entire workflow.

Architecture

Edict is a Rust project (edition 2024) with:

• Zero build step beyond cargo build — workflow docs are embedded at compile time via include_str! and rendered with minijinja
• Agent loops as subcommands — dev-loop, worker-loop, reviewer-loop, responder are built into the binary
• Protocol commands — edict protocol start/merge/finish check preconditions and output guidance
• Config migrations — edict sync runs version-based migrations to update .edict.json and botbus hooks

See CLAUDE.md for full architecture docs, development conventions, and companion tool deep dives.

Cross-project feedback

The #projects registry on botbus tracks which tools belong to which projects:

# Find who owns a tool
bus history projects -n 50 | grep "tools:.*botty"

# File bugs in their repo
cd ~/src/botty
br create --actor $AGENT --owner $AGENT --title="Bug: ..." --type=bug --priority=2
bus send --agent $AGENT botty "Filed bd-xyz: description @botty-dev" -L feedback

See .agents/edict/docs/report-issue.md for full workflow.

Development

Runtime: Rust (stable, edition 2024). Tooling: clippy (lint), rustfmt (format), cargo check (type check).

# From ws/default/ (maw v2 bare repo layout)
maw exec default -- just install    # cargo install --path .
maw exec default -- just lint       # cargo clippy
maw exec default -- just fmt        # cargo fmt
maw exec default -- just check      # cargo check
maw exec default -- just test       # cargo test

This project uses Jujutsu (jj) for version control and maw for workspace management. Source files live in ws/default/, not at the project root. Run maw exec default -- <command> to execute commands in the workspace context.

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT