bmad-loop-sweep

Triages deferred-work ledger entries into a machine-readable partition for the bmad-loop orchestrator.

Updated Mar 1, 2026
One-click install
npx skills add https://github.com/Hexalith/Hexalith.Parties --skill bmad-loop-sweep-hexalith
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bmad-loop-sweep
Source: https://github.com/Hexalith/Hexalith.Parties/tree/main/.agents/skills/bmad-loop-sweep
Command: npx skills add https://github.com/Hexalith/Hexalith.Parties --skill bmad-loop-sweep-hexalith

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Deferred-work ledgers accumulate stale, already-fixed, or blocked entries whose statuses are unreliable, and an unattended orchestrator needs a validated, machine-readable triage plan before it can close, bundle, or escalate that work. ## Core Features & Use Cases - Code-Verified Triage: Verifies every open DW entry against the actual codebase (file reads, greps, git history) and partitions entries into already_resolved, bundles, blocked, skip, and human decisions with concrete evidence. - Machine-Readable Output: Writes a strictly validated result.json (open_ids, bundles with kebab-case names, decision options with recommendations) that the bmad-loop orchestrator checks deterministically. - Legacy Ledger Migration: A --migrate mode rewrites freeform pre-DW-format ledgers into canonical DW-<n> entries while preserving existing entries, gate tokens, and done states byte-identically. - Use Case: During a bmad-loop sweep run, the orchestrator spawns this skill to classify 12 open deferred-work entries; it returns 3 already-resolved items with commit evidence, 2 buildable bundles, 1 blocked item, and 1 human decision, which the orchestrator then executes. ## Quick Start Run a bmad-loop sweep session with BMAD_LOOP_MODE=1 set so this skill triages the deferred-work ledger and writes its result.json for the orchestrator.

Frequently Asked Questions about bmad-loop-sweep

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I triage a deferred-work ledger automatically?

Run a bmad-loop sweep session, which spawns this skill with BMAD_LOOP_MODE=1. It reads deferred-work.md, verifies each open entry against the code, and writes a result.json partitioning entries into already_resolved, bundles, blocked, skip, and decisions.

How do I migrate a legacy deferred-work file to the DW entry format?

Invoke the sweep with --migrate and a manifest path. The skill rewrites freeform legacy items into canonical DW-<n> entries, preserving existing entries byte-identically, and returns a key-to-DW-id mapping validated by the orchestrator.

Can I run bmad-loop-sweep manually outside the orchestrator?

No. The skill checks the BMAD_LOOP_MODE environment variable and ends immediately unless it equals 1. It is automation-only, designed to be spawned and validated by the bmad-loop orchestrator, not invoked by humans.

Why does a sweep result fail validation?

Validation fails when open_ids do not exactly match the ledger's open entries, an id appears in multiple categories, bundle names violate the kebab-case 40-character pattern, or required fields like evidence, blocker, or reason are empty. A --feedback file lists the exact defects for retry.

When is a deferred entry treated as a human decision instead of a bundle?

Entries involving frozen spec-block renegotiations, reversals of human-approved scope, API-shape changes affecting unbuilt consumers, or explicit needs-human-decision deferrals always become decisions with 2-4 options and a recommendation, never bundles.