| name | gh-discuss |
| description | Coordinate multi-agent development via GitHub Discussions. Use when starting a session (discover tasks), claiming work, posting progress, requesting decisions, or completing tasks. Triggers on: "find work", "claim task", "post status", "ask decision", "coordination", "what should I work on".
|
gh-discuss: Multi-Agent Coordination via GitHub Discussions
Agents coordinate through GitHub Discussions — a durable, web-visible layer that works across worktrees, sessions, and tools.
Orientation — which bus am I on? The live execution bus is GitHub Issues + the label taxonomy (ready/claimed/review/mergeable), driven by sync-execution-state.py and the Factory review lane. Claim and work issues there — see docs/agents/triage-labels.md and backlog/AGENTS.md. On Discussions, the actively-used flow is the cron team's [idea] → owner-👍 → planned-issue pipeline (Peter Planner). The [task]/[claimed:] claim-and-complete grammar below is a secondary path for ad-hoc, cross-worktree coordination — reach for it when work doesn't yet have an issue or spans harnesses; use Issues + labels for the standing execution loop.
Script Location
.agents/skills/gh-discuss/scripts/gh-discuss.py <command>
Quick Reference
| Action | Command |
|---|
| See current state | gh-discuss.py dashboard |
| Find available work | gh-discuss.py list --unclaimed |
| Create a task | gh-discuss.py create "Title" --body "Details" |
| Create from backlog | gh-discuss.py create --from-backlog backlog/some-plan.md |
| Claim a task | gh-discuss.py claim <NUMBER> |
| Post progress | gh-discuss.py update <NUMBER> "Status message" |
| Complete a task | gh-discuss.py complete <NUMBER> --pr <PR> |
| Abandon a task | gh-discuss.py abandon <NUMBER> |
| Create in specific category | gh-discuss.py create "[idea] Title" --body "Details" --category General |
| Ask a blocking question | gh-discuss.py create --decision "Question?" --body "Options" |
| Check pending decisions | gh-discuss.py list --decisions |
| Verify app credentials | gh-discuss.py setup |
| Live bot identity test | gh-discuss.py verify |
| Run unit tests | test_gh_discuss.py |
| Run all tests (+ live) | test_gh_discuss.py --live |
Category Mapping
Uses existing default GitHub Discussion categories — no custom categories needed.
| Category | Purpose |
|---|
| General | Task discussions and idea proposals — agents discover, claim, and complete work; cron agents post [idea] proposals |
| Q&A | Blocking decisions — marking an answer unblocks the agent |
| Announcements | Session summaries, protocol changes (human/lead only) |
| Show and tell | Completed work demos |
Conventions
Title Prefixes
All discussion titles use machine-parseable prefixes. These are the source of truth for task state — the script filters on them.
[task] Implement workspace creation progress UI
[task][claimed:el-paso-v1] Implement workspace creation progress UI
[decision] Pane tree: reducer vs direct state?
[idea] Quick switcher (Cmd+P) for repo/workspace navigation
[idea][endorsed] Quick switcher — approved by human for implementation
[shipped] Ghostty split actions working
Agent Identity
Auto-detected from worktree directory name (e.g. el-paso-v1, albany-v2). Every comment includes a header:
**Agent**: `el-paso-v1` | **Branch**: `feat/progress-ui`
Workflow
Session Start
- Run
dashboard to see open tasks, claimed work, and pending decisions
- Run
list --unclaimed to find available work
claim a task before starting work
During Work
- Post
update comments at major milestones
- If blocked,
create --decision to ask for input
- Check
list --decisions for answers to previous questions
Session End
complete finished tasks (link the PR)abandon any tasks you can't finish (frees them for other agents)
Race Conditions
After claiming, the script re-reads the discussion title to verify the claim stuck. If another agent overwrote it, the claim exits with an error.
Backlog Integration
Discussions augment backlog/*.md files — they don't replace them.
- Backlog file = detailed design document (versioned in git)
- Discussion = work order for an active agent
Create a task from a backlog file:
gh-discuss.py create --from-backlog backlog/some-plan.md
This extracts the first # heading as the title and includes the file content in the discussion body.
GitHub App (Optional)
Posts as a bot account instead of your personal account. See references/github-app-setup.md for setup instructions. Run gh-discuss.py setup to validate credentials.
