docs: document interactive harness mode vs loop dispatch - #74
Merged
Conversation
A harness (interactive agent) creating an issue had no guidance on when to add boucle:triage (dispatch trigger) vs work interactively. Adding boucle:triage and then implementing the work itself races the loop: triage splits and dispatches workers on the same issue, duplicating effort. Add a dedicated section to AGENTS.md (synced to consumers via bin/setup) documenting the two modes (dispatch vs interactive), the explicit choice at issue-creation time, the interactive workflow, and the FORBIDDEN list. Update README.md to reference the new section instead of prescribing boucle:triage unconditionally.
… harden status Three fixes for the interactive harness CLI: 1. Auto-detect forge identity (project, host, forge) from the origin git remote when CI vars are absent — the local harness case. Strips embedded credentials from OAuth URLs (https://user:pass@host/...). Resolves BOUCLE_PROJECT_ID via the forge API. Fails with a clear message if identity cannot be resolved, instead of dying silently under set -euo pipefail when forge_issue_get returns empty. 2. Add 'boucle help' (and -h/--help, and no-arg) — one-line description per command with examples and forge-auth docs. 3. Add 'boucle list' / 'boucle ls' [state] — lists open boucle issues from the forge, grouped by boucle state, with optional state filter. 4. Harden cmd_status: handle empty/null forge_issue_get return with a clear error instead of jq-on-empty killing the script. Show the issue title in the status output. Tested locally on urgence-palestine.fr (framagit/GitLab): boucle help → full usage boucle list → open boucle issues table boucle status 105 → title + state + label + assignee + branch + MR
baderdean
force-pushed
the
docs/interactive-harness-mode
branch
from
August 22, 2026 16:44
7cdefc1 to
3576b66
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TL;DR
Document the two modes a local harness (interactive agent) has when creating an issue: dispatch the loop (
boucle:triagelabel) vs work interactively (no boucle labels). The gap caused a race condition where a harness addedboucle:triageand then implemented the work itself, duplicating the loop's effort.Problem
A harness creating an issue had no guidance on when to add
boucle:triage(the dispatch trigger) vs work interactively. Addingboucle:triageand then implementing the work itself races the loop: triage splits the issue, dispatches workers on sub-issues, all while the harness is doing the same work on its own branch. Result: duplicated branches, wasted CI runners, conflicting MRs.This happened on a consumer project (urgence-palestine.fr #105): the harness created the issue with
boucle:triage, implemented all 5 features, and the loop simultaneously split into 5 sub-issues and started working on one.Fix
AGENTS.md (synced to consumers via
bin/setup): new section "Interactive agents (harness) — issue-driven work" documenting:boucle:triagelabel as dispatch trigger (not a tag)boucle:triageto an issue you implement yourself)README.md: updated "After install" step 2 to reference the new section instead of prescribing
boucle:triageunconditionally.Why upstream
AGENTS.md is engine-owned —
bin/setupcopies it to consumers andbin/updatere-syncs it. A local fix in a consumer would be overwritten on the next engine bump. The fix must live upstream.Checklist