bmad-loop-sweep

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

6|Updated Aug 29, 2026
One-click install
npx skills add https://github.com/HordRicJr/Akomagni --skill bmad-loop-sweep-hordricjr
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bmad-loop-sweep
Source: https://github.com/HordRicJr/Akomagni/tree/main/bmad-core/.agents/skills/bmad-loop-sweep
Command: npx skills add https://github.com/HordRicJr/Akomagni --skill bmad-loop-sweep-hordricjr

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Deferred-work ledgers accumulate stale, unreliable entries: items marked open are often already fixed, blocked, or moot, and no one verifies them against the actual code. This Skill automates that triage inside a bmad-loop sweep session, verifying every open entry against the codebase and returning a validated, machine-readable partition the orchestrator can execute. ## Core Features & Use Cases - Code-Verified Triage: Reads each open DW-<n> entry, checks the referenced file or component, greps for the symptom, and inspects git history to classify entries as already_resolved (with file:line or commit evidence), bundles, blocked, skip, or decisions. - Bundle Planning: Groups buildable entries sharing a touchpoint into cohesive kebab-case-named bundles sized for one dev session, each with a 2-6 sentence intent. - Human Decision Surfacing: Routes frozen-block renegotiations, scope reversals, and API-shape changes to a decisions list with 2-4 concrete options and a recommendation. - Legacy Ledger Migration: With --migrate, rewrites freeform pre-DW-format ledgers into canonical ### DW-<n>: entries while preserving existing entries byte-identically and emitting a key-to-DW-id mapping. - Use Case: During an unattended bmad-loop sweep run, the orchestrator spawns this Skill to drain a project's deferred-work.md: it verifies 12 open entries, proves 4 already resolved with commit evidence, bundles 5 into two dev sessions, blocks 2 on a future epic, and escalates 1 as a human decision — all written to result.json for deterministic validation. ## Quick Start Invoke this Skill inside a bmad-loop sweep session with BMAD_LOOP_MODE=1 set, optionally passing --migrate with a manifest path or --feedback with prior validation errors, and it will write the triage result.json automatically.

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, which spawns this Skill with BMAD_LOOP_MODE=1. It reads deferred-work.md, verifies each open entry against the code and git history, and writes a result.json partitioning entries into already_resolved, bundles, blocked, skip, and decisions.

How does the sweep verify that a deferred item is already fixed?

It reads the entry's location in the current tree, greps for the described symptom, and checks git log for commits touching the area since the entry's origin date. Concrete evidence such as a file:line or commit hash is required; 'probably fixed' is rejected.

Can I run bmad-loop-sweep manually outside a sweep session?

No. The Skill checks the BMAD_LOOP_MODE environment variable and exits unless it equals 1. It is automation-only, invoked by the bmad-loop orchestrator, and never asks humans questions or edits code.

How do I migrate a legacy freeform deferred-work.md file?

Invoke the sweep with --migrate and a manifest path. The Skill rewrites legacy bullets and sections into canonical DW-<n> entries, keeps existing entries byte-identical, and returns a mapping of manifest keys to DW ids for orchestrator validation.

What happens when a deferred entry needs a human decision?

Frozen-block renegotiations, scope reversals, and API-shape changes are classified as decisions, never bundles. Each decision gets 2-4 concrete options with build, close, or keep-open effects plus a recommendation for the human to choose.

Why did my sweep result.json fail validation?

Validation fails if open_ids do not exactly match the ledger's open entries, an entry appears in zero or two categories, bundle names violate the kebab-case 40-character pattern, or required fields like evidence, blocker, or reason are empty. Retry feedback lists the exact defects to fix.