From 526bcd21040adf0e67fe500875a02f10d596b366 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 4 May 2026 11:17:28 +0000 Subject: [PATCH] docs(agent-team): document manual dispatch inputs and recovery path Add a per-role input reference table to the "Kicking off a task" section so users know exactly which inputs are required vs optional when manually re-dispatching planner, implementer, or reviewer. Document the exact blocked-state error message and how to recover from a `state:blocked` caused by missing dispatch inputs (as opposed to a human-added block), since the recovery path differs. Expand the "Input propagation" gotcha to include the failure message and cross-reference the new table. Follows the behavioral fix in #69 (fail loud on missing workflow_dispatch inputs, harden optional implementer pr_number). Co-Authored-By: Claude Sonnet 4.6 --- catalog/agent-team/README.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/catalog/agent-team/README.md b/catalog/agent-team/README.md index 5490837..6fd5cf6 100644 --- a/catalog/agent-team/README.md +++ b/catalog/agent-team/README.md @@ -104,14 +104,27 @@ 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 via `gh workflow run`. All required inputs must be provided — missing or blank values trigger `state:blocked` immediately instead of letting the agent guess from labels or recent activity. + + Manual dispatch input reference: + + | Role | Required inputs | Optional inputs | + |---|---|---| + | `planner-agent` | `issue_number` | `iteration` (default: `"1"`) | + | `implementer-agent` | `issue_number` | `iteration` (default: `"1"`); `pr_number` — blank means create a new branch/PR, a real PR number means push to that PR's existing branch | + | `reviewer-agent` | `pr_number`, `issue_number` | `iteration` (default: `"1"`) | + + If any required input is missing or unresolved, the workflow sets `state:blocked` on the issue and stops with: `🛑 agent-team: workflow_dispatch inputs were not propagated. Re-dispatch with valid inputs.` + 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). + **If the block was caused by missing dispatch inputs** (issue comment says `workflow_dispatch inputs were not propagated`): clear `state:blocked`, then re-dispatch only the blocked role with the correct `workflow_dispatch` inputs. No need to re-run spec-agent unless you also want a fresh spec. + ## 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, and reviewer validate their `workflow_dispatch` inputs before doing any work. Missing, blank, or unresolved template literals (e.g. a raw `${{ github.event.inputs.issue_number }}` in the prompt body) cause the workflow to set `state:blocked` on the issue and stop — it will never infer the missing value from labels or recent activity. Recovery: clear `state:blocked`, then re-dispatch the blocked role with the correct inputs (see the table in step 4 above). - **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.