| name | aicoder-unblock-and-patch |
| description | Self-health check, doom-loop recovery, and patch propagation workflow for the aicoder-opencode control plane |
| user-invocable | false |
aicoder-unblock-and-patch
Maintenance and unblock workflow for the aicoder-opencode control plane.
When to use
- The control plane itself is broken: failing tests, build errors, import failures.
- A target repo is stuck in a doom-loop and has not recovered on its own.
- A shared skill or plugin needs patching and the fix must propagate across targets.
Self-health check procedure
- Run
bun run check (build + tests). Fix any failures before proceeding.
- Run
make validate-dr-repo and make validate-letta-workspace. Confirm
target paths exist and launchers resolve.
- Run
make doom-loop-dr-repo. If stalled, proceed to the target unblock
procedure below.
Target unblock procedure
When a doom-loop fires on a target:
- Read the target's
docs/plans/ active-slice to understand what was in flight.
- Read checkpoint files under
.opencode/state/checkpoints/ to see last known
state.
- Determine whether work was actually complete (false positive) or genuinely
stuck.
- If stuck: identify the blocker, apply a minimal patch, clear the stale state.
- If false positive: update the active-slice to reflect completion, then reset
the loop guard state under
.state/doom-loop/.
Patch propagation procedure
When a shared skill or plugin needs updating:
- Make the change in the control plane source (
src/plugins/ or
.agents/skills/).
- Run
bun run check to verify.
- For skills that are overlaid into product repos: update
targets/<target>/overlay/.agents/skills/ shim or content.
- Verify the target can still launch:
make validate-<target>.
- Commit in one atomic change so the skill version and overlay stay in sync.
Avoid
- Patching multiple targets in one commit before the first has been verified.
- Silently swallowing errors during any step of the procedure.
- Changing shared skills to serve one target's quirk without confirming the
change is safe for all other targets.