Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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: 12 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,16 @@ humans invoke identically, so behaviour isn't re-derived from prose each time.
the target, consults the sizing faculty and persists Difficulty/Autonomy/
Priority into the header, and emits an `IntakeDecision`. Files a prompt only;
never starts dev (the step *before* `create_issue`/`start_dev`).
- **`agents/conductors/community/`** — the *Ears*: the organism's receptive
language function — it hears the community (user-filed GitHub issues across
every `repos.yaml` repo) and drafts what the organism says back; the human
remains the mouth. Wernicke to the Workspace Agent's Broca/Voice. Two
read-only modes: `scan` (open external issues + awaiting-response ranking —
also the `/wake_up` community sensory leg) and `triage <issue-ref>`
(context-sufficiency signals + clarifying-question seeds). The `/community`
session judges, drafts every outward reply for human approval, and routes
actionable work via `start_dev_for_user`; conversation state stays on
GitHub + `active.md`. Never posts, labels or writes anything.
- **`agents/conductors/feature/`** — the *Growth Agent*: selects the next
PyAutoMind `feature/*` task (or plans a named one), estimates difficulty,
decides phasing, consults PyAutoMemory (and vitals for risky work), and emits
Expand Down Expand Up @@ -232,6 +242,7 @@ the `/<verb>` slash commands.
| Verb | Purpose | Entrypoint |
|------|---------|------------|
| `intake` | Conceive a task: turn raw input into a formal, headed PyAutoMind prompt (files it; never starts dev) | `bin/pyauto-brain intake` |
| `community` | The ears — the organism's receptive function: scan/triage user-filed GitHub issues across the repos; drafts stay human-gated, dev work routes via start_dev_for_user (never posts) | `bin/pyauto-brain community` |
| `feature` | Reason over PyAutoMind feature tasks: select, size, phase, plan for start_dev | `bin/pyauto-brain feature` |
| `bug` | The immune system: classify a bug/regression/Heart finding, locate the fix, plan the repair | `bin/pyauto-brain bug` |
| `refactor` | The renewal function: plan behaviour-preserving restructuring — RefactorDecision; default-safe under --auto | `bin/pyauto-brain refactor` |
Expand Down Expand Up @@ -269,6 +280,7 @@ the Brain routes it to the right agent; normal usage never says "PyAutoBrain".
| Command | Routes to | Tier |
|---------|-----------|------|
| `/intake` | Intake Agent → files a PyAutoMind prompt (before `start_dev`) | real conductor |
| `/community` | Community Agent → scan/triage user-filed issues → human-approved replies → `start_dev_for_user` | real conductor |
| `/feature` | Feature Agent → `start_dev` | real conductor |
| `/bug` | Bug Agent → `start_dev` (health mode → vitals + Heart issues) | real conductor |
| `/build` | Build Agent → vitals → Heart → PyAutoBuild | real conductor |
Expand Down
95 changes: 95 additions & 0 deletions agents/conductors/community/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
# Community agent

> **Tier: conductor** — a front-door agent you *drive*. The *Ears* — the
> organism's receptive language function: it hears the community (user-filed
> GitHub issues across every repo) and drafts what the organism says back; the
> human remains the mouth. Wernicke to the Workspace Agent's Broca: that
> *Voice* speaks to users through examples and tutorials, this agent
> *comprehends and converses* — it reads an outsider's issue, judges whether
> the context is sufficient, drafts every reply for human approval, and routes
> actionable work into the dev flow. It never posts, labels, edits or releases
> anything itself.

Grown from demonstrated need: user-filed issues were handled ad-hoc (paste the
GitHub link into an agent chat), the `start_dev_for_user` skill already owned
the downstream dev entry, and the founding prompt asked for both a dedicated
listening/communicating agent and a `/wake_up` summary of what the community
is waiting on. Founding prompt:
PyAutoMind `active/community_communication_agent_listen_and_respond.md`
(issue PyAutoBrain#119).

## Modes

Both modes are live, deterministic and **read-only** — they emit surfaces the
`/community` skill session reasons over. The judgment (actionable vs
ask-for-more, the reply prose, the routing call) is the session's; the human
gates every outward message.

| Mode | Surface | Consumed by |
|------|---------|-------------|
| `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 |
| `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 |

```
pyauto-brain community # scan: who is waiting on us?
pyauto-brain community scan --json
pyauto-brain community triage <url | owner/repo#N> [--json]
```

Repo enumeration comes from `PyAutoMind/repos.yaml` (the body map) under
`PYAUTO_ROOT`; the org is searched wholesale, non-org homes individually.
GitHub access is the `gh` CLI — `COMMUNITY_GH` overrides the binary (hermetic
tests), `COMMUNITY_SELF` the self logins (default `Jammy2211`). A failed
search degrades honestly (`degraded:` in the surface), never silently.

## Fundamental principles

- **The conductor hears; the human speaks.** Every outward message — receipt,
clarifying question, plan update, closing note — is drafted in the session
and presented to the human before posting. The CLI itself never mutates
GitHub. Autonomy for community work is `human-required` by design; `--auto`
changes nothing here.
- **Conversation state lives on GitHub + Mind, never here.** Labels
(`needs-info`, `pending-release`) and the issue thread itself are the
conversation's memory; in-flight dev state is the `user-facing: true` entry
in `PyAutoMind/active.md`. The conductor owns no registry, no cache, no
paired repo.
- **Delegate the conversation's dev half.** Actionable issues route into
`/start_dev_for_user`, which already owns the receipt comment, the
clarification gate, the plan comment and the milestone cadence
(~5 milestones for bugs, ~4 for features — see its `reference.md`). This
conductor never re-implements those templates.
- **Stdlib / bash only** — like every conductor, it must never drag the
science stack into the Brain.

## Boundaries

- **vs the Workspace Agent (the Voice)** — split by *direction of speech*. The
Voice is expressive: it plans how the organism speaks to practitioners and
learners through authored examples. The Ears are receptive: they hear what
individual outsiders say back (issues, requests, bug reports) and hold up
the organism's end of the conversation.
- **vs intake** — intake conceives tasks from the *developer's* raw ideas and
files Mind prompts; community converses with an *external reporter* whose
issue already exists on GitHub. When a community conversation yields work,
it routes via `start_dev_for_user` (issue-first), not intake (prompt-first).
- **vs start_dev_for_user** — that skill is the dev-flow entry for one
already-actionable issue. Community is the layer above: discovery (scan),
assessment (triage), the ask-for-more conversation, and the ongoing
reporter-facing updates after routing.
- **vs bug / feature** — they classify and plan the *work*; community manages
the *relationship* with the person who reported it.
- **vs health / hygiene / release** — no verdicts, no upkeep, no releases;
external PRs and review requests are out of scope for v1 (a staged
follow-up recorded here).

## Capability audit — what the modes read

- **GitHub search** (`gh api search/issues`): `org:PyAutoLabs` plus the
non-org homes from `repos.yaml`, `is:issue is:open -author:<self>`, bot
authors post-filtered.
- **Issue comments** (`gh api repos/<o>/<r>/issues/<n>/comments`): last-actor
detection for awaiting-response (capped at 30 issues per scan) and the
triage comment tail.
- **PyAutoMind `repos.yaml`**: the body map, parsed for `github:` homes
(regex, stdlib-only — the Brain takes no yaml dependency).
Loading