debug-loop
SkillProductivitySystematic debugging playbook for the Forge agentic loop (src/core/loop.ts and src/agents/executor.ts). Use when a task is stuck, looping, or emitting wrong tool calls.
Available today. Use it from your connected AI after setup.
No other account needed.
Connect ahel once, and every AI you use reads what you have installed.
Then ask your AI: use the debug-loop skill
What this skill tells your AI
The instructions your AI receives, as published by hoangsonww/forge-agentic-coding-cli in .agents/skills/debug-loop/SKILL.md and read by ahel’s review.
The loop is the most expensive place to be wrong. Instrument before you change anything.
1. Reproduce deterministically
FORGE_LOG_LEVEL=debug ./bin/forge.js <command>
Capture the session id. Events land in
~/.config/forge/events/<session>.ndjson.
If the bug only reproduces against a real provider, pin the model and disable router fallback:
FORGE_MODEL=... FORGE_ROUTER_FALLBACK=0 ./bin/forge.js <command>
2. Read the event stream, not the terminal
Each turn emits: turn.start, model.call, tool.call,
tool.result, validation.result, turn.end. Missing or
out-of-order events are your bug.
3. Check the usual suspects, in order
- Mode caps (
src/core/mode-policy.ts) — is the agent hitting turn/token cap? - Validation gate (
src/core/validation.ts) — is a valid step being rejected? - Tool registry — is the requested tool actually registered?
tool.callwithclass: not_foundmeans no. - Permissions — silently denied?
tool.result.denied=true. - State machine (
src/persistence/tasks.ts) — illegal transition attempted?
4. Add a failing test before the fix
Template: test/unit/executor-loop.test.ts. Mock callModel. If the
test you add doesn't turn green after your fix, you fixed the wrong
thing.
5. Finish with verify.
Signals
- GitHub stars
- 22
- Forks
- 9
- Last commit
- Sep 2026
Advanced
- Catalog kind
- skill
- Gateway key
debug-loop- Source
- github.com/hoangsonww/forge-agentic-coding-cli