Skip to content

docs: align consumer multi-agent runner guide #3354

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stranske merged 4 commits into from
Sep 4, 2026
Merged

docs: align consumer multi-agent runner guide #3354

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
248da59
docs: align consumer multi-agent runner guide
Sep 4, 2026
6046661
test: bind runner docs to delivered jobs
Sep 4, 2026
c2b3a29
test: enforce exclusive consumer runner routes
Sep 4, 2026
7535743
docs: scope runner dispatch to pull requests
Sep 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions templates/consumer-repo/docs/LABELS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ This document describes all labels that trigger automated workflows or affect CI
| `autofix:clean` | PR labeled | Triggers clean-mode autofix (more aggressive)
| `agent:codex` | Issue or PR labeled | Routes the issue or PR to the Codex agent
| `agent:claude` | Issue or PR labeled | Routes the issue or PR to the Claude Code agent
| `agent:cursor` | Issue or PR labeled | Registered routing label; no consumer Gate-followup runner is currently wired
| `agent:gemini` | Issue or PR labeled | Registered routing label; no consumer Gate-followup runner is currently wired
| `agent:cursor` | Issue or PR labeled | Routes consumer Gate-followup keepalive to the Cursor runner
| `agent:gemini` | Issue or PR labeled | Routes consumer Gate-followup keepalive to the Gemini runner
| `agent:aider` | Issue or PR labeled | Routes the issue or PR to the Aider agent for cheap, low-complexity tasks — runner lands in a follow-up phase
| `agent:auto` | Issue or PR labeled | Delegates routing to the auto-delegation policy; do not combine with concrete `agent:<name>` labels
| `agent:retry` | PR labeled | Consolidated consumers require a manual Gate-followups dispatch; the root/non-consolidated keepalive workflow forces a retry and clears recovery labels
Expand Down Expand Up @@ -140,14 +140,14 @@ This document describes all labels that trigger automated workflows or affect CI

**Effect:**
1. Identifies Cursor as the intended route in registry-aware automation
2. Does **not** dispatch a consumer PR keepalive runner: `agents-81-gate-followups.yml` currently has runner jobs only for Codex and Claude
2. Dispatches the `run-cursor` consumer PR keepalive job in `agents-81-gate-followups.yml`
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated
3. Branch prefix `cursor/issue-<number>` is reserved for Cursor work (see `.github/agents/registry.yml`)
Comment thread
stranske marked this conversation as resolved.

**Prerequisites:**
- Repository has a valid `CURSOR_API_KEY` secret (per `.github/agents/registry.yml`)
- Issue or PR should have clear requirements

**Workflow:** Registry-aware workflows may recognize the label, but the consumer Gate-followup workflow has no Cursor runner job. Do not use this label to promise PR keepalive execution until that job is delivered from the canonical Workflows source.
**Workflow:** `agents-81-gate-followups.yml` dispatches `reusable-cursor-run.yml` after registry-backed routing and secret preflight succeed.

---

Expand All @@ -159,13 +159,13 @@ This document describes all labels that trigger automated workflows or affect CI

**Effect:**
1. Identifies Gemini as the intended route in registry-aware automation
2. Does **not** dispatch a consumer PR keepalive runner: `agents-81-gate-followups.yml` currently has runner jobs only for Codex and Claude
2. Dispatches the `run-gemini` consumer PR keepalive job in `agents-81-gate-followups.yml`
3. Branch prefix `gemini/issue-<number>` is reserved for Gemini work

**Prerequisites:**
- Repository has a valid `GEMINI_API_KEY` secret (per `.github/agents/registry.yml`)

**Workflow:** Registry-aware workflows may recognize the label, but the consumer Gate-followup workflow has no Gemini runner job. Do not use this label to promise PR keepalive execution until that job is delivered from the canonical Workflows source.
**Workflow:** `agents-81-gate-followups.yml` dispatches `reusable-gemini-run.yml` after registry-backed routing and secret preflight succeed.

---

Expand Down
9 changes: 7 additions & 2 deletions tests/docs/test_consumer_ci_system_guide.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,9 @@ def test_consumer_operator_docs_match_gate_followup_topology() -> None:
root_labels = Path("docs/LABELS.md").read_text(encoding="utf-8")
labels = Path("templates/consumer-repo/docs/LABELS.md").read_text(encoding="utf-8")
setup = Path("templates/consumer-repo/docs/SETUP_CHECKLIST.md").read_text(encoding="utf-8")
gate_followups = Path(
"templates/consumer-repo/.github/workflows/agents-81-gate-followups.yml"
).read_text(encoding="utf-8")

@chatgpt-codex-connector chatgpt-codex-connector Bot Sep 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Bind the guide check to the manifest-delivered runner jobs

If the workflow is re-scoped in .github/sync-manifest.yml, this test continues reading the stale template path, and even at the current path a leftover reusable-*-run.yml@main string passes without proving that run-cursor/run-gemini exists or selects the matching agent_type. Resolve the workflow source through the compiled manifest and parse its YAML to assert each delivered job's uses and routing condition; otherwise the guide can again promise a runner topology consumers do not receive while this regression test remains green.

AGENTS.md reference: AGENTS.md:L29-L35

Useful? React with 👍 / 👎.

@stranske stranske Sep 4, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed on exact head 6046661. Both the guide and workflow are now selected from compile_manifest output by their delivery targets. Parsed YAML must contain run-cursor and run-gemini with exact uses values and matching needs.evaluate.outputs.agent_type conditions, so stale template text or an unrelated leftover marker no longer passes. Validation: focused/template/manifest suite 55 passed with one credential-gated skip; template sync and strict completeness passed; drift check reports zero unallowlisted drift; Ruff, Black, and diff-check passed.


assert "Root/non-consolidated: sets `force_retry=true`" in root_labels
assert ".github/workflows/agents-keepalive-loop.yml" in root_labels
Expand All @@ -45,8 +48,10 @@ def test_consumer_operator_docs_match_gate_followup_topology() -> None:
):
assert retired_surface not in labels

assert "no Cursor runner job" in labels
assert "no Gemini runner job" in labels
for agent, display_name in (("cursor", "Cursor"), ("gemini", "Gemini")):
assert f"reusable-{agent}-run.yml@main" in gate_followups
assert f"Routes consumer Gate-followup keepalive to the {display_name} runner" in labels
assert f"dispatches `reusable-{agent}-run.yml`" in labels

@stranske stranske Sep 4, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed on exact head 6046661. The contract now resolves the delivered workflow and label guide through the compiled sync manifest, parses the workflow YAML, and asserts the run-cursor/run-gemini job IDs, their exact reusable workflow targets, each matching agent_type condition, and the matching detailed guide job IDs.

Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated
assert "applying the label does not trigger a retry by itself" in labels
assert "Does not set `force_retry`" in labels
assert "agents-keepalive-loop.yml" not in labels
Expand Down
Loading