Problem
The current AGENTS.md convention says:
ROADMAP.md updates happen on merge (don't move issues to Completed prematurely)
In practice, this is routinely skipped — especially during multi-agent swarm runs where N agents merge N PRs in rapid succession. After the first full 4-agent swarm (PRs #154–#157, 14 issues closed), ROADMAP.md was never updated. The roadmap still shows those issues as open despite being merged and released as v0.10.1.
Analysis
Three options were considered:
Option 1: Update at merge time (current convention)
Each PR's agent moves its issues to Completed before merging.
- ✅ Roadmap stays accurate between releases
- ❌ Agents edit a shared file → more merge conflicts during swarms
- ❌ Frequently skipped in practice (agents stop after PR creation or review cycle)
- ❌ During swarms, N agents touching ROADMAP.md violates the file-overlap audit
Option 2: Update in the release commit (recommended)
Batch-move all merged issues to Completed during the CHANGELOG promotion commit.
- ✅ One person (monitor or release manager) does it once
- ✅ Eliminates ROADMAP.md as a merge-conflict source during swarms
- ✅ Release becomes a single checkpoint where CHANGELOG + ROADMAP are synchronized
- ❌ Roadmap is stale between merges — but this already happens in practice
Option 3: Update as post-release housekeeping
Separate commit after the tag.
- ❌ Most likely to be forgotten
- ❌ Roadmap stale until someone remembers
- ❌ No natural trigger
Recommendation
Option 2 — move ROADMAP.md updates to the release commit. Update the AGENTS.md convention from:
ROADMAP.md updates happen on merge
To:
ROADMAP.md updates happen at release time — batch-move merged issues to Completed during the CHANGELOG promotion commit
This also means:
- Remove ROADMAP.md from the swarm file-overlap audit exceptions (agents no longer touch it)
- Add a release checklist step: "Move closed issues to Completed in ROADMAP.md"
- The
deft-swarm skill's Phase 6 (Close) should reference this convention
Immediate action needed
Regardless of which option is chosen, ROADMAP.md currently needs updating — 14 issues from v0.10.1 are shown as open but are actually closed. This should be addressed during the next triage/roadmap refresh.
Related
Problem
The current AGENTS.md convention says:
In practice, this is routinely skipped — especially during multi-agent swarm runs where N agents merge N PRs in rapid succession. After the first full 4-agent swarm (PRs #154–#157, 14 issues closed), ROADMAP.md was never updated. The roadmap still shows those issues as open despite being merged and released as v0.10.1.
Analysis
Three options were considered:
Option 1: Update at merge time (current convention)
Each PR's agent moves its issues to Completed before merging.
Option 2: Update in the release commit (recommended)
Batch-move all merged issues to Completed during the CHANGELOG promotion commit.
Option 3: Update as post-release housekeeping
Separate commit after the tag.
Recommendation
Option 2 — move ROADMAP.md updates to the release commit. Update the AGENTS.md convention from:
To:
This also means:
deft-swarmskill's Phase 6 (Close) should reference this conventionImmediate action needed
Regardless of which option is chosen, ROADMAP.md currently needs updating — 14 issues from v0.10.1 are shown as open but are actually closed. This should be addressed during the next triage/roadmap refresh.
Related
meta/lessons.md— Parallel Agent Swarm lessons (2026-04)skills/deft-swarm/SKILL.md— Phase 6 Close