Mforge CLI Skill

Use this skill when the task involves Microforge (mforge) workflows or requires correct CLI command usage.

Preconditions

• •Prefer an active rig context; most commands assume mforge context set <rig> has been run.
• •Mailboxes == Beads (tasks/assignments are Beads issues; inbox/outbox live under each cell worktree).

Core flows

Rig + context

mforge init <rig> --repo <path>
mforge context set <rig>

Rig messaging

mforge rig message <rig> [--cell <cell>] [--role <role>] --text "<msg>"

Agent lifecycle

mforge agent create <path> --description "<text>" [--class crew|worker]
mforge agent bootstrap <name>
mforge agent spawn <cell> <role>
mforge agent wake <cell> <role>
mforge agent send <cell> <role> "<message>"
mforge agent logs <cell> <role> --follow
mforge agent logs --follow --all
mforge agent status --cell <cell> --role <role> --json
mforge status --cell <cell> --role <role> --json
mforge agent exit <cell> <role>
mforge agent restart <cell> <role>

Epic planning + status

mforge epic create --title "<title>" --short-id <id>
mforge epic design <id|short-id>
mforge epic tree <id|short-id>

Turn + round orchestration

mforge round start --wait
mforge round review --wait
mforge round review --all
mforge round review --changes-only
mforge round review --base <branch>
mforge round merge --feature <branch> [--base <branch>]
mforge turn start --name "<name>"
mforge turn status
mforge turn end --report
mforge turn list
mforge turn diff --id <turn>
mforge checkpoint --message "round N"
mforge convoy start --epic <id> [--role <role>] [--title "<text>"]

Quick assignment + status

mforge quick-assign <bead-id> <cell> [--role <role>] [--promise <token>]
mforge assign --task <id> --cell <cell> --role <role> --promise <token> --quick
mforge bead status <id> in_progress

Supervisor

mforge manager tick --watch
mforge manager tick --stop-idle
mforge watch --interval 60
mforge watch --role builder
mforge watch --fswatch
mforge watch --tui

Engine loop

mforge engine run --rounds <n>
mforge engine run --completion-promise "<text>"
mforge engine emit --type <EventType> --scope <path> --title "<title>" --payload '<json>'

Task decomposition

mforge task decompose --task <id> --titles "step a,step b" [--kind plan]

Migrations

mforge migrate beads --all
mforge migrate rig --all

Behavior notes

• •Assignments are created as Beads issues of type assignment and linked with related:<task_id>.
• •A round start assigns unassigned tasks to cells based on scope, then wakes the appropriate role.
• •A round review defaults to changes-only (skips cells without git diffs); use --all to force reviews for every cell.
• •A round review auto-spawns reviewer/cell agents before waking them.
• •Round merge aggregates all cell branches into a feature branch.
• •Convoys assign all epic tasks and wake relevant agents.
• •Agent spawn/wake/relaunch refuses non-bootstrapped cells; assignment/round paths auto-bootstrap.
• •Agent spawn preflight checks for worktree code + write access (skip only with MF_ALLOW_EMPTY_WORKTREE=1 or test envs).
• •Assignments only auto-close when an outbox promise is met and the latest git commit message includes the assignment or related task ID.
• •Assignment claims are recorded in bead meta (claimed_by, claimed_at) and written to inbox headers.
• •Manager tick writes completion signals to mail/signals/task-complete-<assignment>.json.
• •mforge watch nudges idle agents when inbox has tasks; --fswatch uses filesystem events if installed.
• •Turns are computed from git + beads + cell activity; turn end --report writes a markdown report.
• •Claude settings must use object permissions form: "permissions": { "allow": [...] } (generated by cell bootstrap / migrate rig).

Live integration test

make test-e2e-claude

When unsure

• •Use mforge scope list and mforge scope show --scope <path> to confirm scope mappings.
• •Use mforge bead list --type task to inspect outstanding tasks and dependencies.