|
| 1 | +# Community agent |
| 2 | + |
| 3 | +> **Tier: conductor** — a front-door agent you *drive*. The *Ears* — the |
| 4 | +> organism's receptive language function: it hears the community (user-filed |
| 5 | +> GitHub issues across every repo) and drafts what the organism says back; the |
| 6 | +> human remains the mouth. Wernicke to the Workspace Agent's Broca: that |
| 7 | +> *Voice* speaks to users through examples and tutorials, this agent |
| 8 | +> *comprehends and converses* — it reads an outsider's issue, judges whether |
| 9 | +> the context is sufficient, drafts every reply for human approval, and routes |
| 10 | +> actionable work into the dev flow. It never posts, labels, edits or releases |
| 11 | +> anything itself. |
| 12 | +
|
| 13 | +Grown from demonstrated need: user-filed issues were handled ad-hoc (paste the |
| 14 | +GitHub link into an agent chat), the `start_dev_for_user` skill already owned |
| 15 | +the downstream dev entry, and the founding prompt asked for both a dedicated |
| 16 | +listening/communicating agent and a `/wake_up` summary of what the community |
| 17 | +is waiting on. Founding prompt: |
| 18 | +PyAutoMind `active/community_communication_agent_listen_and_respond.md` |
| 19 | +(issue PyAutoBrain#119). |
| 20 | + |
| 21 | +## Modes |
| 22 | + |
| 23 | +Both modes are live, deterministic and **read-only** — they emit surfaces the |
| 24 | +`/community` skill session reasons over. The judgment (actionable vs |
| 25 | +ask-for-more, the reply prose, the routing call) is the session's; the human |
| 26 | +gates every outward message. |
| 27 | + |
| 28 | +| Mode | Surface | Consumed by | |
| 29 | +|------|---------|-------------| |
| 30 | +| `scan` *(default)* | every `PyAutoMind/repos.yaml` repo → open issues authored by non-self humans (bots filtered), with **awaiting-response** detection (the conversation's last word is not ours) ranked by waiting time | `/community` step 1; the `/wake_up` community sensory leg | |
| 31 | +| `triage <issue-ref>` | one issue → context-sufficiency signals (code block, traceback, versions, expected-vs-actual, data pointer), missing-signal clarifying-question seeds, comment tail, route | `/community` steps 2–3 | |
| 32 | + |
| 33 | +``` |
| 34 | +pyauto-brain community # scan: who is waiting on us? |
| 35 | +pyauto-brain community scan --json |
| 36 | +pyauto-brain community triage <url | owner/repo#N> [--json] |
| 37 | +``` |
| 38 | + |
| 39 | +Repo enumeration comes from `PyAutoMind/repos.yaml` (the body map) under |
| 40 | +`PYAUTO_ROOT`; the org is searched wholesale, non-org homes individually. |
| 41 | +GitHub access is the `gh` CLI — `COMMUNITY_GH` overrides the binary (hermetic |
| 42 | +tests), `COMMUNITY_SELF` the self logins (default `Jammy2211`). A failed |
| 43 | +search degrades honestly (`degraded:` in the surface), never silently. |
| 44 | + |
| 45 | +## Fundamental principles |
| 46 | + |
| 47 | +- **The conductor hears; the human speaks.** Every outward message — receipt, |
| 48 | + clarifying question, plan update, closing note — is drafted in the session |
| 49 | + and presented to the human before posting. The CLI itself never mutates |
| 50 | + GitHub. Autonomy for community work is `human-required` by design; `--auto` |
| 51 | + changes nothing here. |
| 52 | +- **Conversation state lives on GitHub + Mind, never here.** Labels |
| 53 | + (`needs-info`, `pending-release`) and the issue thread itself are the |
| 54 | + conversation's memory; in-flight dev state is the `user-facing: true` entry |
| 55 | + in `PyAutoMind/active.md`. The conductor owns no registry, no cache, no |
| 56 | + paired repo. |
| 57 | +- **Delegate the conversation's dev half.** Actionable issues route into |
| 58 | + `/start_dev_for_user`, which already owns the receipt comment, the |
| 59 | + clarification gate, the plan comment and the milestone cadence |
| 60 | + (~5 milestones for bugs, ~4 for features — see its `reference.md`). This |
| 61 | + conductor never re-implements those templates. |
| 62 | +- **Stdlib / bash only** — like every conductor, it must never drag the |
| 63 | + science stack into the Brain. |
| 64 | + |
| 65 | +## Boundaries |
| 66 | + |
| 67 | +- **vs the Workspace Agent (the Voice)** — split by *direction of speech*. The |
| 68 | + Voice is expressive: it plans how the organism speaks to practitioners and |
| 69 | + learners through authored examples. The Ears are receptive: they hear what |
| 70 | + individual outsiders say back (issues, requests, bug reports) and hold up |
| 71 | + the organism's end of the conversation. |
| 72 | +- **vs intake** — intake conceives tasks from the *developer's* raw ideas and |
| 73 | + files Mind prompts; community converses with an *external reporter* whose |
| 74 | + issue already exists on GitHub. When a community conversation yields work, |
| 75 | + it routes via `start_dev_for_user` (issue-first), not intake (prompt-first). |
| 76 | +- **vs start_dev_for_user** — that skill is the dev-flow entry for one |
| 77 | + already-actionable issue. Community is the layer above: discovery (scan), |
| 78 | + assessment (triage), the ask-for-more conversation, and the ongoing |
| 79 | + reporter-facing updates after routing. |
| 80 | +- **vs bug / feature** — they classify and plan the *work*; community manages |
| 81 | + the *relationship* with the person who reported it. |
| 82 | +- **vs health / hygiene / release** — no verdicts, no upkeep, no releases; |
| 83 | + external PRs and review requests are out of scope for v1 (a staged |
| 84 | + follow-up recorded here). |
| 85 | + |
| 86 | +## Capability audit — what the modes read |
| 87 | + |
| 88 | +- **GitHub search** (`gh api search/issues`): `org:PyAutoLabs` plus the |
| 89 | + non-org homes from `repos.yaml`, `is:issue is:open -author:<self>`, bot |
| 90 | + authors post-filtered. |
| 91 | +- **Issue comments** (`gh api repos/<o>/<r>/issues/<n>/comments`): last-actor |
| 92 | + detection for awaiting-response (capped at 30 issues per scan) and the |
| 93 | + triage comment tail. |
| 94 | +- **PyAutoMind `repos.yaml`**: the body map, parsed for `github:` homes |
| 95 | + (regex, stdlib-only — the Brain takes no yaml dependency). |
0 commit comments