refactor(agents): conductor/faculty tiers + rename health→vitals, doctor→health - #11
Merged
Merged
Conversation
…ealth Capture the conventions converged on during the first end-to-end Health Agent run: md mobile card as the default surface, severity-then-capability reason grouping, unknown-CI tiles kept secondary, an explicit local-checks-blind confidence downgrade when repos live outside PYAUTO_ROOT, fix-citation discipline, staleness handling, and the expected-first-run-gap vs real-problem separation. Presentation/triage only — the verdict is still adopted from Heart verbatim. Co-Authored-By: Claude <noreply@anthropic.com>
Make the two-tier structure explicit in the filesystem: front-door agents a human drives (decide AND act) live under agents/conductors/; read-only reasoning capabilities the conductors consult (only opine, never dispatch or mutate) live under agents/faculties/. - Move feature/build/release -> agents/conductors/; health -> agents/faculties/ (git-tracked renames, history preserved). - Repoint sourcing (../_common.sh -> ../../_common.sh) and the consult_health_agent_verdict path to faculties/health/. - Dispatcher (bin/pyauto-brain): tier-grouped help menu, tier-aware doc lookup, and the new doctor conductor registered. - Add each spec a "Tier:" declaration line; describe the two tiers in the top-level AGENTS.md and README. Add the doctor conductor (skeleton): the organism's clinician that runs the health loop with a human — assess -> triage -> (on go-ahead) dispatch a validation leg -> re-judge — until Heart goes green. It consults the health faculty for every verdict and delegates all dispatch to the release conductor; scope is validation + recommend, checkpointing every dispatch. Edit-in fixes are a deliberate follow-up. Verified: help menu, cross-tier doc lookup, bash -n on all moved scripts, the pyauto-agent shim, and a full `pyauto-brain doctor` run exercising the moved consult chain (doctor -> _common -> faculties/health -> Heart). Co-Authored-By: Claude <noreply@anthropic.com>
…alth Sharpen the two-tier naming so it reads as an intrinsic organ, not an external visitor: - Faculty health -> vitals (agents/faculties/vitals/): the read-only "reads the Heart's pulse" judge. `vitals` reads as a read-only measurement, matching the faculty's opine-only role, and steps on nothing (unlike `pulse`, which is PyAutoHeart's own deprecated-but-live alias). - Conductor doctor -> health (agents/conductors/health/): the organism's clinician is named for what it manages (the organism's health), not an outside doctor. Mechanics: - git-tracked renames of both dirs + their entry scripts (vitals.sh, health.sh). - consult_health_agent_verdict -> consult_vitals_verdict in _common.sh (path now faculties/vitals/vitals.sh), with a back-compat alias kept. - Dispatcher: menu + registry updated; `pyauto-brain vitals` (faculty read), `pyauto-brain health` (conductor loop). - Repoint every "Health Agent" (the judge) -> "vitals faculty" across specs, scripts, and skills, and every subcommand-forwarding `pyauto-brain health` -> `pyauto-brain vitals` (the conductor only accepts `assess`; forwarding a Heart subcommand must go through the faculty). - Pulse metaphor preserved as prose in the vitals description, not as an identifier. Verified: help menu + tiered doc lookup, bash -n / ast parse on all scripts, the back-compat alias, `pyauto-brain vitals` (card) and `pyauto-brain health` (assess -> consult vitals -> YELLOW -> recommend) end-to-end, and `build --dry-run` consulting the vitals faculty. Co-Authored-By: Claude <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR refactors PyAutoBrain’s agent filesystem and CLI to make the two-tier architecture explicit: conductors (front-door, acting agents) and faculties (read-only, consultable reasoning capabilities). As part of that, it renames the former “health agent” (read-only judge) to the vitals faculty, and introduces a new health conductor skeleton that runs the assess → recommend loop while delegating judgment to vitals and dispatch to release.
Changes:
- Split agents into
agents/conductors/vsagents/faculties/, and update the CLI dispatcher/help to group and route both tiers. - Rename health-judge surface to
vitals(faculty) and update call sites (consult_*helpers, build/release/feature scripts, skills, and docs). - Add a new
healthconductor skeleton (assessloop) that consults vitals and recommends the next validation checkpoint without dispatching.
Reviewed changes
Copilot reviewed 25 out of 26 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/WORKFLOW.md | Updates workflow diagrams and guidance to reference the vitals faculty as the Heart gate consult surface. |
| skills/ship_workspace/SKILL.md | Updates ship-workspace skill description to reference vitals faculty instead of the prior health agent. |
| skills/ship_workspace/ship_workspace.md | Updates the ship_workspace how-to flow and gate instructions to use pyauto-brain vitals. |
| skills/ship_library/SKILL.md | Updates ship-library skill description to reference vitals faculty. |
| skills/ship_library/ship_library.md | Updates the ship_library how-to flow and gate instructions to use pyauto-brain vitals. |
| skills/ship_library/reference.md | Updates the execution contract prose to reference vitals faculty for the GREEN gate. |
| README.md | Documents the conductor/faculty tier split and updates examples (health conductor vs vitals faculty). |
| bin/pyauto-brain | Updates CLI dispatch to tiered agent paths and tier-grouped help output (adds vitals, repurposes health). |
| agents/faculties/vitals/vitals.sh | Implements the renamed read-only vitals faculty wrapper that ticks + renders dashboard by default and forwards other subcommands to Heart. |
| agents/faculties/vitals/HEART_CAPABILITIES.md | Renames and updates the Heart capability audit to be “vitals faculty” centric. |
| agents/faculties/vitals/AGENTS.md | Updates faculty spec: tier declaration, run commands, boundaries, and operating defaults framing. |
| agents/conductors/release/validate.sh | Updates common sourcing path and renames references from health agent → vitals faculty. |
| agents/conductors/release/release.sh | Updates common sourcing path and renames references from health agent → vitals faculty. |
| agents/conductors/release/rehearse.sh | Updates common sourcing path and renames consult helper usage to consult_vitals_verdict. |
| agents/conductors/release/AGENTS.md | Updates release conductor docs to describe consulting the vitals faculty and tier semantics. |
| agents/conductors/health/health.sh | Adds the new health conductor skeleton (assess/adopt verdict/recommend next checkpoint). |
| agents/conductors/health/AGENTS.md | Adds the health conductor spec, scope/boundaries, and run instructions. |
| agents/conductors/feature/MIND_TAXONOMY.md | Updates the “health → PyAutoHeart” routing line to go via vitals faculty. |
| agents/conductors/feature/feature.sh | Updates common sourcing path and optional consult to use consult_vitals_verdict. |
| agents/conductors/feature/AGENTS.md | Updates feature conductor docs to describe consulting the vitals faculty (--check-health). |
| agents/conductors/feature/_feature.py | Updates human-facing recommendations to reference vitals faculty (pyauto-brain vitals). |
| agents/conductors/build/build.sh | Updates common sourcing path and consult flow to use consult_vitals_verdict and pyauto-brain vitals. |
| agents/conductors/build/BUILD_CAPABILITIES.md | Updates capability audit/prose so health-shim commands point to vitals faculty instead of health agent. |
| agents/conductors/build/AGENTS.md | Updates build conductor spec to describe consulting vitals faculty and tier semantics. |
| agents/_common.sh | Introduces consult_vitals_verdict (and keeps a back-compat alias) and documents tier-aware agent layout. |
| AGENTS.md | Updates the repo-level agent architecture doc to describe tiers and rename health-judge → vitals faculty (plus new health conductor). |
Comments suppressed due to low confidence (1)
agents/conductors/release/rehearse.sh:14
- The pipeline overview still says “(Health judges)” when the consulted component is now the vitals faculty. This can mislead readers about which agent is responsible for the verdict.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Address the PR #11 Copilot review: - health conductor: an unknown subcommand now exits 5 (usage error) instead of 2, which the contract reserves for a YELLOW verdict — so CLI misuse is no longer indistinguishable from a real YELLOW for callers branching on exit codes. Documented in the header and spec. - AGENTS.md: the `pyauto-brain build` Running example now says "consult vitals" (it consults the vitals faculty, not "health"). - rehearse.sh: pipeline comment now reads "(vitals judges)" instead of the stale "(Health judges)". Co-Authored-By: Claude <noreply@anthropic.com>
Front-load the temporal clause so it no longer reads as the awkward "reason on a routine run". Same nit Copilot raised on the operating-agreement text in PR #10; fixed here too since the section lives in the vitals spec. Co-Authored-By: Claude <noreply@anthropic.com>
…t re-review) The fresh Copilot pass caught a "consult Health" comment the earlier Health-Agent/command passes missed: - skills/WORKFLOW.md: build entry-point comment now "consult vitals". - feature/AGENTS.md: --check-health example comment now "also consult vitals" (the flag name is unchanged; only the prose was stale). - release/validate.sh: two hyphenated "Health-Agent consult" comments (which the space-delimited pass skipped) now "vitals-faculty consult". Co-Authored-By: Claude <noreply@anthropic.com>
…re-review) - `readiness.yellow_reasons` implied a nested JSON shape; the readiness output has `yellow_reasons` at the top level. Reworded to "the readiness output's top-level `yellow_reasons`". - The `pyauto-heart fix <ci|dirty|drift|timing>` shorthand read as literal syntax and was inconsistent with the Procedure section's explicit forms; now `pyauto-heart fix <topic>` with the topics listed as examples. Co-Authored-By: Claude <noreply@anthropic.com>
|
|
||
| echo | ||
| # 2. Read the authoritative verdict *through* the faculty — never re-derived here. | ||
| verdict="$(consult_vitals_verdict --refresh)" |
…eview) Mirror the PR #10 fixes into the vitals spec: clarify that severity-first ordering applies to ranking/triage and the card (the structured report keeps the Output-schema section order), and rewrap the Unknown-CI-tiles bullet. Co-Authored-By: Claude <noreply@anthropic.com>
Jammy2211
changed the base branch from
claude/health-agent-e2e-run-w5slh7
to
main
July 6, 2026 09:34
…tals-w5slh7 # Conflicts: # agents/faculties/vitals/AGENTS.md
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
Makes PyAutoBrain's two-tier agent structure explicit in the filesystem, and adds the
healthconductor (the conversational health loop). Two commits:split Brain agents into conductor and faculty tiers—agents/conductors/(front doors you drive: decide and act) vsagents/faculties/(read-only reasoning the conductors consult: only opine). Plus the new doctor conductor skeleton.rename faculty health→vitals, conductor doctor→health— sharpen the names so they read as intrinsic organs, not an external visitor.Why
Three of the four existing agents (
feature,build,release) already consult the health judge, and the judge consults nothing but Heart — the tier split was already latent in the code; this names it. The rule it encodes: keep the conductor set small and human-meaningful; let faculties multiply behind them. The litmus is "does it act, or only opine?"Naming rationale:
healthis intrinsic — a system you engage with.vitalsreads as a read-only measurement (matching the faculty's opine-only role);healthread too broad/systemic for a pure-read faculty. Avoidedpulsebecause it is PyAutoHeart's own deprecated-but-still-live alias (pyauto-pulse,pulse-health.yml) — reusing it would collide with a sibling organ mid-rename. The pulse metaphor is kept as prose in the vitals description, not as an identifier.Final shape
pyauto-brain vitals— faculty: reads the Heart's pulse, renders the card, forwards subcommands topyauto-heart(read-only).pyauto-brain health— conductor (skeleton): runs the assess → triage → (on your go-ahead) dispatch → re-judge loop toward green. Scope: validation + recommend, checkpoint every dispatch. Edit-in fixes are an explicit follow-up.Mechanics
consult_health_agent_verdict→consult_vitals_verdictin_common.sh(path nowfaculties/vitals/vitals.sh), with a back-compat alias kept.skills/.pyauto-brain health <cmd>→pyauto-brain vitals <cmd>(the conductor only acceptsassess; a forwarded Heart subcommand must go through the faculty).Tier:declaration line at the top of every spec; the two tiers described inAGENTS.mdandREADME.md.Verification
bash -non all scripts,ast.parseon_feature.py.help, cross-tierhelp <agent>doc lookup, thepyauto-agentshim.pyauto-brain vitalsrenders the card;pyauto-brain healthruns assess → consults vitals → adopts YELLOW → recommends the next checkpoint, end-to-end.build --dry-runconsults the vitals faculty and emits aBuildDecision.No behavioural/gating change — this is structure + naming + the conductor skeleton. Observer boundaries preserved (the vitals faculty stays read-only; the health conductor delegates all dispatch to the release conductor).
🤖 Generated with Claude Code
https://claude.ai/code/session_01RLqU83iWW3R7ks33TzSyYs
Generated by Claude Code