docs: document agent-team dispatch input hardening and add troubleshooting guide#136
Draft
github-actions[bot] wants to merge 1 commit into
Draft
Conversation
- Update catalog/agent-team/README.md:
- Input propagation gotcha: describe exact error behavior (state:blocked
+ specific comment text) and missing_data fallback when issue_number
is absent — mirrors the fail-loud contract added in #69
- New `pr_number` gotcha: clarify blank = first-attempt (new PR) vs
real number = kickback (update existing PR)
- Step 4 re-dispatch: replace vague prose with concrete gh workflow run
examples for each role, covering both first-attempt and kickback paths
- New Troubleshooting section: three scenarios — inputs not propagated,
duplicate PR from missing pr_number, silent spec-agent on label add
- Update CONTRIBUTING.md:
- Fix inaccurate "no automated test harness" claim: the repo ships a
tiered test suite (tests/run-tests.sh) that runs Claude Code headlessly
- Add test-suite commands and guidance to run tier-3 e2e tests for
catalog/agent-team changes
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
github-actions
Bot
added
automation
documentation
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
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.
What changed and why
Follow-up documentation for #69 (
fix(agent-team): fail loud on missing dispatch inputs+fix(agent-team): harden optional implementer pr_number). The code behavior was updated in that commit but the reference docs didn't reflect the new contracts — this PR closes that gap.catalog/agent-team/README.mdstate:blockedand posts the specific error comment (🛑 agent-team: workflow_dispatch inputs were not propagated. Re-dispatch with valid inputs.), or emitsmissing_datawhenissue_numberitself is absent. Explicitly calls out that no inference from labels/activity ever happens.pr_numbergotcha — documents the implementer's optional input semantics: blank/absent = open a new draft PR (first attempt); real PR number = push updates to existing branch (kickback). This was hardened in [codex] fix agent-team manual workflow_dispatch inputs #69 but undocumented.gh workflow runmention with concrete commands for all four re-dispatch scenarios (planner, implementer first-attempt, implementer kickback, reviewer), so a human debugging a stuck pipeline can copy-paste rather than guess.pr_number, and silent spec-agent on label churn.CONTRIBUTING.mdtests/run-tests.shruns Claude Code headlessly to assert skill behavior. Corrected to describe the actual test suite and how to run it.catalog/agent-team/*.mdchanges should be validated with the tier-3 e2e tests, not just the fast tier-1/2 suite.Testing
Documentation-only change — no code modified. Verified diff reads correctly and cross-references resolve.