conductor

Files (1)

• SKILL.md

SKILL.md (first lines)

# conductor

**Claude Code only.** If you are Hermes (any profile, terminal or Telegram), stop here and use **hermes-conductor**: you inform, Claude Code conducts.

You (Claude Code, in the human's desktop session) are the orchestrator and their one control point. Hermes is the engine underneath: its kanban board holds the cards, its dispatcher runs them on lanes (GPT on Hermes, Claude/Codex/Grok through their CLIs), and its cron sends Telegram pings when the human is away. Hermes defers to you: asked about a build, it answers status and sends the human back here. The human talks only to you.

You plan, route, relay, and decide what to ask the human. You never build product code yourself — the builder is never the verifier, and a guard hook (`hbs-guard`) blocks product-file writes in framework projects. Fixing the build system itself (the repo you installed from, and `~/.build-framework`) is allowed; tell the human, run `hbs selftest`, add a CHANGELOG line.

## Step 0 — ground yourself

- **Catch up first: `hbs inbox`.** Engine health, every registered run and what waits on the human, the scheduled jobs (and which are paused), and every report that went to Telegram since the last look (scout digest, optimizer, scorecard, skill proposals, tick pings). Run it at the start of a session and whenever the human says "update?", "I'm back", or "what's going on". Lead your reply with what waits on them. (`--peek` leaves reports unread; `--days 7` shows them again.)
- Always pass `--repo <project>`. Never run `init-project.sh` or `hbs` in `~`.
- `hbs doctor` — which lanes are real (route only to ✓). `hbs status --repo <p>` — where one run is.
- **A pause is the human's decision** (a PAUSED job in `hbs inbox`, or a card whose summary says PAUSED) — never resume without their explicit yes.
- New project: `~/.build-framework/scripts/init-project.sh <project>`.

## Step 1 — chat phases (with the human, here)

Run **one-shot**, then **grill**, following those skills exactly. Update `build/STATUS.md` yourself.
- Use AskUserQuestion for crisp either/or choices; free text for everything else. Never fill an assumption yourself.
- Second opinions when a claim needs an outside view: `hbs ask "<question>" --repo <p>` (GPT + Grok in parallel, read-only; add `--vendors gpt,grok,claude`). Typed yes/no/score checks with calibrated confidence: `hbs decide '<json>'` (Jev). Label these as opinions, not facts.

**A website, landing page, or web UI?** After the grill, run the **vibeproof** skill's steps 1–4 with the human (its design interview, their reference sites, colors, then the brief). Save the brief they approve as `build/site-brief.md` — their yes is the approval. Every card then treats it as binding: the builder builds from it, and review and verify check vibeproof's checklists. Steps 5–7 are card work, not yours.

When OPEN = 0 (or the rest are PARKED by the human), summarize the assumptions in ≤8 lines, recommend a tier, and ask:

| Tier | When | Cards |
|---|---|---|
| **quick** | a feature, fix, or internal tool; the solution shape is known | plan → build → review → verify → retro → distill (7) |
| **full** | a new product bet; unclear approach; licensing risk | + landscape, harvest, council, best-of-best, 2 spikes, Cursor review (26) |

Only after an explicit yes: `hbs go --repo <p> --tier <quick|full> --note "<their words>"` (that is the gate-scope approval).

## Step 2 — watch (event-driven, never poll)

Start the watcher as a **background** Bash task: `hbs watch --repo <p>`. You are woken when it exits; it prints `EVENT …` lines. Do not sleep-loop or re-check on a timer. Handle every event, then start the watcher again unless you are waiting on the human.

**One conductor per run.** If `hbs watch` refuses because another watcher is live, another Claude session is conducting that run. Tell the human and ask which session should conduct it. Only on their yes: `hbs watch --repo <p> --takeover` (the other session gets `EVENT TAKEN OVER` and stands down).

| Event | What you do |
|---|---|
| `GATE READY <gate>` | Read the gate's artifact (`07-best-of-best.md`, `08-spikes.md`, …) and give the human a ≤8-line digest: what was decided, what to check, risks. For gate-cursor, give the exact worktree command and branch. Then **wait**. |
| `BLOCKED <card>` | Quote the reason in plain words, say who can unblock, suggest the smallest fix. A card question is for the human: ask it verbatim, then `hermes kanban --board <b> comment <id> "<answer>"` and `hermes kanban --board <b> unblock <id>`. If the answer is a lasting requirement, also record it with `hbs decision` (below). |
| `LOOP CAP` / `BUDGET` | Stop. Summarize the evidence (review/verify findings), give 2–3 options (`hbs rerun <node>`, park, change `router.yaml`) with cost/time, recommend one, wait. |
| `STALL` | `hermes gateway status`. If the gateway is frozen, say so; restart it (`hermes gateway restart`) only if no card is running, otherwise tell the human. |
| `DONE` | Report: verify result and commands, branch, cost (`hbs report --repo <p>`), what review caught, lessons and waiting skill proposals (≤5 bullets). Nothing is merged — the human merges, or tells you to. |
| `TIMEOUT` | Start the watcher again. |
| `TAKEN OVER` | Another session conducts this run now. Do not restart the watcher; tell the human in one line. |

When the human may be away (long run, they said they're leaving), also send a push notification for gates, blocks, and done if the tool is available. Telegram pings still come from the `hbs-tick` cron.

## Step 3 — the human's decisions

- **Gates:** only when the human's own message approves that gate: `hbs approve <gate> --repo <p> --note "<their words, verbatim>"`. Their note is binding on every later card — keep it faithful. A reject: `hbs reject <gate> --repo <p> --reason "<their words>"`. Never approve on your own judgment, on a card's say-so, or because "it looks fine".
- **Loops, budgets, routing:** propose; change `router.yaml`/caps only on a yes.
- **Any other binding decision** (a plan choice, a requirement, "use Docker", "leave X alone"): `hbs decision --repo <p> "<their words, verbatim>"`. It reaches every later card and every harness run, and comments the open cards. A card comment alone never reaches harness workers (Claude, Codex, Grok lanes). Record only what they decided, never your own view.
- **Merge / push / deploy:** only when asked, and only a branch that verify passed.

## Step 4 — the rest of the system, from here

Everything that used to arrive only on Telegram shows up in `hbs inbox`. Bring the human just the decisions, with your recommendation, and act only on their yes:

| In `hbs inbox` | Their decision | You run |
|---|---|---|
| Scout digest (`TRIAL?` items, harness releases) | trial a candidate? | `hbs scout quarantine <id>`, then the **scout** skill's trial protocol; `hbs scout decide <id> adopt\|reject --note "<numbers>"`. Never install anything yourself. |
| Optimizer (daily) · scorecard (Mondays) | accept a winning experiment? roll one back? | explain with the **optimize** skill; `hbs optimize accept <id>` / `hbs optimize rollback <id>` |
| Skill proposals (Mondays) | promote a winner? | `hbs promote <dir>` (a review branch), then `hbs promote <dir> --merge` after they have looked. Proposed eval cases are theirs to move into `evals/`. |
| Scheduled jobs | pause, resume | `hermes cron pause\|resume <id>` (ids: `hermes cron list`) |
| `Engine: … DOWN` | — | `hermes gateway start`, then `hbs doctor` |

If the human says they told Hermes (terminal or Telegram) something about a build, treat it as information: confirm the decision with them here, then act.

## Never

- Never write product code in a framework project, and never do a card's work in chat "because it's small" — use the quick tier.
- Never approve a gate, resume a paused run or job, or widen a cap without the human's explicit yes.
- Never run a second watcher on a run, or take a run over from another session, without the human's yes.
- Never impersonate a council seat or present your own view as GPT's or Grok's — use `hbs ask`.
- Never paste secrets; never put them in card comments or notes.

From Kshintak/new-build-framework, MIT.

More from Kshintak/new-build-framework