From 1017f07084559e2316a65b95b00525e52eed2585 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sun, 10 May 2026 10:54:42 +0000 Subject: [PATCH] docs(agent-team): document input propagation errors and manual re-dispatch MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Commit d688265 hardened all three dispatch agents to fail loudly on missing workflow_dispatch inputs instead of silently inferring from label state. Reflect this in the user-facing README: - Expand step 4 with exact `gh workflow run --field` commands for each role (planner, implementer, reviewer) so operators know the required inputs for manual re-dispatch. - Expand the "Input propagation" gotcha with the verbatim error message users will see on the issue (`🛑 agent-team: workflow_dispatch inputs were not propagated`) and the recovery steps (clear state:blocked, re-dispatch with explicit --field arguments). - Clarify the pr_number optional/kickback semantics inline: omit on first dispatch, include on reviewer kickback to update the existing PR branch. Co-Authored-By: Claude Sonnet 4.6 --- catalog/agent-team/README.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/catalog/agent-team/README.md b/catalog/agent-team/README.md index 5490837..84f292e 100644 --- a/catalog/agent-team/README.md +++ b/catalog/agent-team/README.md @@ -104,14 +104,28 @@ Then apply the OAuth token tweak to each `.lock.yml` per [`skills/install-workfl 1. Open an issue describing what you want built. 2. Add the single label `agent-team`. 3. Watch the thread. Each role posts its contribution as a comment; the implementer opens a draft PR that closes the issue when merged. -4. Human override at any time: add `state:blocked` to halt, edit a comment to steer the next agent, or manually `gh workflow run` a specific role to retry a stuck stage. Manual dispatches must pass the required `workflow_dispatch` inputs, and the downstream workflow markdown must read them via `${{ github.event.inputs.* }}`. +4. Human override at any time: add `state:blocked` to halt, edit a comment to steer the next agent, or manually re-dispatch a specific role. Required inputs vary by role: + + ```bash + # Re-dispatch the planner (spec exists; planner didn't fire or needs a retry) + gh workflow run planner-agent.yml --field issue_number= --field iteration= + + # Re-dispatch the implementer — omit pr_number for a new PR, include it to update an existing one + gh workflow run implementer-agent.yml --field issue_number= --field iteration= + gh workflow run implementer-agent.yml --field issue_number= --field iteration= --field pr_number= + + # Re-dispatch the reviewer + gh workflow run reviewer-agent.yml --field pr_number= --field issue_number= --field iteration= + ``` + + All three agents fail loudly if required inputs are missing — they never infer values from label state or recent activity. 5. **Retrying a blocked task**: clear `state:blocked`, then re-add `agent-team`. Spec-agent treats it as a fresh dispatch (because the state:* labels are gone and the spec markers are already satisfied — actually: to redo from scratch, also delete the prior spec comment). ## Limits and gotchas - **Concurrency**: each workflow uses `concurrency: group: agent-team-issue-${issue_number}` so only one role runs at a time per issue. - **Max iterations**: default 3 (reviewer kickback → implementer). The counter lives on the `iteration` input passed through the dispatch chain, bumped exclusively by the reviewer on kickback. -- **Input propagation**: planner / implementer / reviewer must fail loudly if required `workflow_dispatch` inputs are missing. Do not rely on label search or recent-activity inference as a fallback. +- **Input propagation**: planner / implementer / reviewer fail loudly if required `workflow_dispatch` inputs are missing or unresolved — they never infer values from label state or recent activity. If you see `🛑 agent-team: workflow_dispatch inputs were not propagated. Re-dispatch with valid inputs.` on an issue, clear `state:blocked` and manually re-dispatch the stalled role with explicit `--field` arguments (see "Kicking off a task" step 4 above). The `pr_number` input to the implementer is optional: omit it on first dispatch (a new draft PR is created); include it on reviewer kickback so the implementer pushes updates to the existing PR branch rather than opening a new one. - **Non-UI only**: no screenshot capture. Reviewer validates via tests/CI status + reading the diff. - **Cost**: a single task can easily spend 4× the tokens of a monolithic workflow. Set `timeout-minutes` conservatively and monitor the first few runs. - **No auto-merge**: the reviewer approves but never merges. Humans merge.