/hc-agent

name: hc-agent
description: "Manage AI agent fleets in the Herdr desktop app via hc and herdr-app: split workers beside root, prompt/wait/read, fleet status, steer, teardown; `help` lists all. Don't use for the Herdr TUI (herdr-agent), tmux, or Rex."
license: MIT
compatibility: "Requires the Herdr desktop app's hc (herdr-core) and herdr-app CLIs on PATH and a session inside one of the app's terminals (HC_TERMINAL_ID set) for every operation except `help`, which runs no command. Observed with hc 0.1.20 and Herdr.app 0.1.15 on macOS; workers must report OSC 7501 status."
effort: medium
metadata:
  version: 1.0.0
  author: "Luong NGUYEN <luongnv89@gmail.com>"

hc Agent

Build and control an AI-agent fleet in the root agent's tab of the **Herdr desktop app**. Keep the **root pane** as orchestrator; add each **worker** as a split to the right running the main agent's own launch profile; then prompt, wait, read, monitor, steer, or tear down through `hc` (herdr-core, which runs the terminals) and `herdr-app` (which arranges the window), wrapped by this skill's scripts.

The app is not the Herdr TUI: its terminals set `HC_TERMINAL_ID`, not `HERDR_ENV`, and the `herdr` CLI on PATH there reaches a separate TUI server. This skill never calls `herdr`. A worker's **name** is its `hc-agent.name` label, and its **status** is the OSC 7501 state its CLI reports (`hc get`). Relay reply deltas, not whole screens, to protect the context and token budget.

Choose the Workflow

| Request | Follow | |---|---| | `help`, or what this does and how to drive it | Help in `references/help-request.md` — answer and stop | | Spawn workers beside root | Phases 1–2, then 4–6 if assigning work | | Message an existing agent | Phases 3–5 | | Give several workers different tasks | Phases 3 and 7 (`dispatch`) | | Read without sending | Phase 3, then Phase 5 read only | | Check what the fleet is doing | Phase 6 | | Broadcast to a fleet | Phases 3 and 7 | | Focus/steer a pane | Phase 3, then Phase 7 | | Close workers | Phase 7 teardown | | Main agent's own context is filling up | Phase 8 HANDOFF |

Read only the reference needed by that branch:

• See `references/app-vs-tui.md` for every herdr-agent operation and how it behaves here (same, different, or unavailable), the observed versions, and what is still unverified.
• See `references/hc-recipes.md` for the scripts resolver, spawn waves, what `--start` runs, steering, teardown, and edge cases.
• See `references/launch-profile.md` for where a worker's kind, model, thinking level, flags and wrapper come from, and what never carries over.
• See `references/delivery-and-waiting.md` for the status table, the prompt contract and exit codes, reading replies, the file fallback, and fleet monitoring.
• See `references/context-succession.md` for the main agent's context gate, HANDOFF procedure, and handoff brief template.
• See `references/final-report.md` for the closing report's status words, required parts, and examples.

Answer a Help Request

Resolve this branch **before** Prerequisites: someone asking how this works may not have the app installed yet. Take it on `help`, `--help`, `/hc-agent help`, or any plain question about what the skill does. Print the text in `references/help-request.md`, or for a narrower question (how to broadcast, what differs from herdr-agent) answer from that one phase or from `references/app-vs-tui.md` and name it. Run no `hc` or `herdr-app` command, change nothing, and emit no completion report.

**Done when:** the user has the summary or their specific answer, and no command ran.

Check Prerequisites

1. **Route the TUI away.** If `HERDR_ENV=1`, this is a Herdr TUI pane: stop and use `herdr-agent`. If neither `HERDR_ENV` nor `HC_TERMINAL_ID` is set, this is not a Herdr terminal at all: stop, `BLOCKED`. 2. Set `here` to the `scripts/` directory beside this SKILL.md. When the harness does not show the skill's base directory, use the resolver in `references/hc-recipes.md`. 3. Run `python3 "$here/agent.py" check`. It confirms `hc` and `herdr-app` are on PATH (`command -v hc herdr-app`), that `hc get $HC_TERMINAL_ID` resolves with `herdr.space` and `herdr.tab` labels (so the window shows this terminal), and that `herdr-app ls` lists its pane in that tab. On any failure it prints the fix, and the run ends `BLOCKED`. Never act on whatever the window happens to show. 4. Treat the installed CLIs as authoritative: check an uncertain command with `hc <command> --help` or `herdr-app commands`. Never run bare `herdr-app`, which opens the person's window.

Follow Non-Negotiable Rules

1. **Keep root as a role.** Never replace or close the root pane during fleet work. The one exception is a Phase 8 HANDOFF, where the orchestrator role migrates to a ready successor pane; even then the outgoing pane is retired to read-only, never closed without Rule 8 confirmation. 2. **Run exactly one orchestrator.** Only the current main agent writes to fleet terminals. After a HANDOFF `GO`, the outgoing agent issues no further prompts, splits, or closes. 3. **Never call `herdr`, and spawn only with an explicit split.** Workers come from `herdr-app do pane.split --pane <explicit pane>` through `launch_profile.py --start`. Never use `terminal.open` or `terminal.keep`, which place relative to the focused pane, and never `hc run`, whose children die with their parent and stay hidden from the window. 4. **Address terminals, not names.** Resolve a worker by its exact `hc-agent.name` label in the root's tab, then pass its `t…` address to every `hc` call. hc resolves bare words against its own `--name` namespace, so a label name could reach a different terminal. 5. **Fail closed before writes.** Refuse a `working`, `blocked`, unverifiable (no status), agent-less, or finished target, and never write to your own terminal. A missing status is never idle. 6. **Wait before follow-ups.** Never prompt while an agent is working. Every follow-up is its own `agent.py prompt` cy