herdr-pm-init

herdr-pm-init — a PM/CTO for every agent tab

You are inside herdr (a terminal multiplexer) where several AI agents run in parallel, one per project. This skill is the fleet launcher: it gives each live agent-tab its own conductor — a manager split in beside the agent, in its tab, that reads the session, decides what's next, asks the human scored questions in-pane, and drives the existing agent via herdr — fanning independent work into parallel worktree lanes. One manager per tab — never one brain juggling all sessions.

The manager's behavior lives in the herdr-pm-agent skill, which this launcher installs and mounts. You (the launcher) only discover, set up, spawn, and hand off. (herdr-pm-agent is also independently invocable — a human can point it at a single tab without going through this launcher; it then self-bootstraps. This skill is the multi-tab front door.)

When to use / not

• Use when you have running herdr agent sessions and want them supervised/driven by PMs.
• Not for the per-tab logic itself → that is herdr-pm-agent (mounted automatically).
• Not for a one-off Codex side-task → use claude-to-codex.
• Not outside herdr → if HERDR_ENV is unset, stop and say so.

Prerequisites

HERDR_ENV=1 and herdr status --json shows a running, compatible server. You cannot start herdr from bash (it needs a TUI) — if it is down, tell the user. Scripts live in this skill's scripts/ dir, referenced below as $HPM/scripts where HPM="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/skills/herdr-pm-init" (the plugin root when installed as a plugin, else the ~/.claude/skills pool).

Workflow

1. Discover the live agent-tabs

python3 "$HPM/scripts/discover_and_spawn.py" discover

Returns JSON: backends_available (offer only CLIs that exist), manage (live agent-tabs with ids, workspace label/number, session, cwd, foreground cwd, repo_root when git can resolve it, and has_conductor — true = a PM already sits in that tab: list as "already managed", never spawn a second), skip_conductors (your own PMs — filtered by registered pm-* name when Herdr exposes it, with fixed ◆ PM … pane labels as the durable fallback), skip_executors (ex-* lanes), skip_idle (empty panes, fully addressable — report, don't manage). Ids are opaque strings: copy them verbatim, never construct one. Detail → references/launcher-workflow.md.

2. Confirm scope with the human

Show the detected agent-tabs; let the human mark which to manage — via your host's interactive question tool (Claude → AskUserQuestion; Codex → request_user_input when available, otherwise an active numbered prompt in-pane; never a passive plain-text list the human must type against). Default = live tabs only (crash-restore of dead sessions is out of scope — offer it only if asked). If a tab is ambiguous, ask.

3. Setup questions — exactly two, one batched ask

Peek at each chosen session first, then ask context-aware questions — options from each project's actual work, not a fixed menu:

• Manager backend — ask as [conductor] will manage [managed] (e.g. claude will manage claude, codex will manage claude); default codex.
• Autopilot — render as ASCII bars, not digits (▰▱▱▱ observe · ▰▰▱▱ consult · ▰▰▰▱ autonomous (default) · ▰▰▰▰ full); frame around the project's risky/safe steps. The assignment carries the level number.

Never ask about: mode — auto-detect it ([ -d <repo>/.herdr-pm ] → power, else light; a human can opt a fresh repo into power by saying so, but it is not a question you raise). Placement — every conductor splits side-by-side into its managed agent's tab; there is no other mode. Relay rhythm — gone; humans answer PMs in their tabs. Codex reviews — not a setup question; the conductor offers them just-in-time on its first branch/worktree review when ~/.codex exists. Goals / the mandate — not a launcher question; in POWER the conductor runs its own deep onboarding interview ("why did you hire me?") on its first turn. This is exactly why launcher setup stays at two questions: you place the hire, the hire learns the job.

4. Codex question-tool preflight (only if any conductor backend is codex)

Before spawning a codex conductor, make sure its default/code mode can actively ask the human:

codex features list | grep -E '^default_mode_request_user_input[[:space:]]+' || true

If it is not true, ask the human through your current host's active question tool: "Enable Codex request_user_input in default/code mode so PM conductors can ask scored questions directly?" If they approve, run:

codex features enable default_mode_request_user_input

Then re-check codex features list. This edits the user's Codex config intentionally and may require a fresh codex session/restart for already-running Codex panes; new conductors spawned after the change should see it. If the human declines or the command is unavailable, continue with the documented active numbered-prompt fallback.

5. Install the operator skill (before spawning — backends scan skills at startup)

HPM="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/skills/herdr-pm-init"
python3 "$HPM/scripts/install_agent_skill.py" --name herdr-pm-agent \
  --src "${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/skills/herdr-pm-agent" --scope global \
  --backends codex --dry-run   # review, then drop --dry-run

Only codex needs this — claude/pi/hermes already see the operator via the canonical ~/.agents/skills pool. Install global (avoids dropping a symlink + skills-lock.json into the repo). Per-backend dirs + invocation (/name claude, $name codex) → references/backend-matrix.md.

6. Mode is auto-detected; scaffold + charter a fresh, explicitly-requested power world

[ -d <repo>/.herdr-pm ] → spawn with --mode power --cwd <repo>/.herdr-pm (the world already exists — no question, no re-init). Otherwise --mode light --cwd <repo>, unless the human explicitly asked for power — only then gather a 1–2 sentence mandate (the north star + win-condition; ask one scoped question if unclear — not a long interview) and scaffold:

python3 "$HPM/scripts/init_power_world.py" --repo <repo> --slug <slug> \
  --managed-pane <pane> --managed-term <term> --session-id <sid> \
  --autopilot <N> --language <lang> \
  --goal "<the 1-2 sentence mandate you gathered>"   # writes GOAL/00-charter.md

init_power_world.py builds the full canonical world (spec → herdr-pm-agent references/power-world.md): the folders (GOAL/ TODO/ PLAN/ DECISION/ LEARNING/ MEMORY/), the projection fixtures (STATE/DIGEST/RUNLOG), MEMORY/INDEX + drive-facts, the PLAN/ planning fixtures, a pointers-only hub AGENTS.md (folder map + read-order + plan-first — it does NOT defer to a long interview), and GOAL/00-charter.md from your --goal. On its first power turn the conductor just confirms the mandate (one light touch) and drives (herdr-pm-agent → references/onboarding-interview.md §1). If you couldn't gather a mandate, omit --goal — the charter lands PENDING and the conductor captures it in one question. Git-ignored. Re-running init on an existing world is safe — it completes a partial one (idempotent fill, clobbers nothing), --check audits it, --upgrade refreshes a stale hub; --force is a full reset (fresh only). Several PMs on one repo → --world-dir .herdr-pm-<role> per PM, then spawn with --world (auto-detect stays exactly .herdr-pm). Detail → references/launcher-workflow.md.

7. Spawn one manager per tab (serial by default)

One script call per conductor — it splits the conductor side-by-side into the managed agent's tab and runs the whole atomic flow (split-start → registration wait → fixed pane-label rename ◆ PM <REPO_UPPER> + read-back verify → best-effort 70/30 resize → write + prime the assignment → resend-if-eaten → auth check), emitting one JSON result. Tabs are never renamed; the conductor's pane label is fixed after spawn, and live state uses custom_status:

python3 "$HPM/scripts/discover_and_spawn.py" spawn \
  --slug <slug> --backend <claude|codex|pi|hermes> \
  --cwd <repo-or-.herdr-pm> --repo-upper <REPO_UPPER> \
  --managed-pane <pane> --managed-term <term> --session-id <sid> \
  --repo <repo> --mode <light|power> --autopilot <N> --language <lang>

Check "ok": true and every verify.* flag; layout_70_30 is informational, not a gate. On auth_ok: false, the script closes only the conductor pane and reports closed_conductor_pane; keep the managed agent's tab. The assignment lands at ~/.local/state/herdr-pm/<slug>/assignment.md (durable — never /tmp), carries your_term, notes $HERDR_PANE_ID for self-targeted status updates, and (power, optional) --world; pane ids still renumber, so any rare pane operation must re-resolve first (references/pitfalls.md #4/#20). Never spawn the next conductor until this one's JSON came back ok. Raw per-step commands (fallback / debugging) → references/backend-matrix.md; traps → references/pitfalls.md.

8. Hand off — the PMs talk to the human directly

Each conductor sits beside its agent and asks the human in-pane (custom_status: awaiting you plus one best-effort notification means a decision is waiting). Your job after spawning: report the spawn results + which conductors already await a decision, fire one summary toast (notification show "PMs ready" …), then get out of the way. A conductor is self-sufficient: it dispatches missions via pm.py dispatch --file (each minting a unique marker — TASK_DONE reuse false-fires, pitfall #28; parallel worktree lanes for independent work), arms a backgrounded dual-arm wait (minted-marker wait primary + agent wait <managed_term> status secondary — terminal id, never a pane id; references/pitfalls.md #23) and self-wakes, verifies, reports — you don't babysit it. On request you can survey all conductors (board digest) or answer a conductor's widget for the human via pm.py keys (#19); re-poke one only as a fallback if it stalls past its wait. Conductors keep a short, stable ◆ PM <REPO_UPPER> pane label and never rename tabs. Survey + live autopilot change → references/launcher-workflow.md.

9. Offer monitor mode (optional — the manager-of-managers loop)

After hand-off, offer to stay on as an autonomous fleet supervisor for a window the human sets through the host's active question tool: "Enter monitor mode for [duration]? I'll keep the whole fleet moving with zero blockers — auto-recover freezes / rate-limits / codex-limits / hung-shells, and auto-answer every PM question with full autonomy (a fresh decision sub-agent reads both scrollbacks and picks the most momentum-forward option). PAUSE anytime via touch ~/.local/state/herdr-pm/PAUSE." If yes → read references/monitor-mode.md and follow it: store the deadline → start the deterministic floor (scripts/monitor-loop.sh, backgrounded) → arm the read-only Monitor (pm_monitor.py --watch) → arm a 4-min ScheduleWakeup heartbeat, then run the per-wake loop. Within the window the human's grant is full autonomy — every action (incl. prod deploy / force-push / delete / migration / spend) is pre-authorized; never leave a blocker. If no → you're done at Step 8. The detector script: pm_monitor.py --dry-run (human report) · --json (orchestrator snapshot) · --watch (the Monitor tripwire) · default ACT (the floor).

Decision rules

• One manager per tab; isolated context. Don't consolidate sessions unless the human asks (offer it only for clearly-similar repos, with a before→after tab-rename preview).
• Install (codex only) before spawn — global by default (no repo pollution); claude/pi/hermes need no install (canonical pool). Project scope is an explicit opt-in.
• Spawn serial by default; offer a wave only if the human wants speed over a calm question flow.
• Pass minimal context at spawn (ids + mode) and let the operator skill carry the how — don't inline the whole method.
• On a re-run, mode auto-detects (.herdr-pm/ exists → power) and .herdr-pm/AGENTS.md pre-fills autopilot — re-ask only backend if relevant. Skip executors too: discovery's skip_executors (ex-* panes) are a conductor's parallel lanes, never manageable agents.
• Stay in the human's language; never hardcode one.

Guardrails

• Never change the human's focus or active window — not even to "restore" it. Every herdr tab create / agent start uses --no-focus; all conductor reads and waits run in the background. Never call herdr tab focus / pane focus / agent focus / pane zoom|swap automatically: if the human navigated to a pane themselves, leave it — they own focus and the view entirely. Never run herdr update, server stop|reload-config, session, or integration commands — infra is the human's.
• Never use --current or omit a target id in automation — omitted targets resolve to the human's focused pane/workspace, not yours (pitfall #27). Explicit --pane/--workspace/--cwd, always.
• Confirm the conductor is actually alive, not just spawned. After priming, read the pane and verify the operator skill loaded AND there is no auth/login error (e.g. token_revoked, "sign in again"). A backend can spawn, go working, then die on auth — if so, fall back to another backend.
• Outside herdr (HERDR_ENV unset) or herdr down → stop, explain, do not improvise.
• Never clobber a real skill dir on install (the script reports skip-real); never edit a tracked .gitignore (power world uses .git/info/exclude).
• SKILL.md description has a hard 1024-char ceiling — codex enforces it, claude doesn't. Over it, codex prints ⚠ invalid description: exceeds maximum length of 1024 characters, skips loading the skill, and the warning surfaces on every codex pane. Re-measure after ANY frontmatter edit; both this skill (~996) and herdr-pm-agent (~972) already hug the ceiling, so trim before adding. Symptom + measure command → references/pitfalls.md #32. (It caps only the description — the body is unbounded, so put detail there.)
• Re-resolve pane ids from terminal_id — they renumber (references/pitfalls.md).
• The managers do the project work; you set them up and relay. Don't start editing project code yourself.
• Monitor mode is full-autonomy by design (references/monitor-mode.md): within the user-set window the orchestrator auto-answers every question and takes any action — including irreversible/prod ones — without a second ask; the window IS the authorization. The only brakes are the PAUSE file (~/.local/state/herdr-pm/PAUSE) and a human typing in a pane (took-the-wheel). Stay the single in-session writer; run one --watch at a time (watch.lock); resolve ids at call time; two-phase consequential widget keys.

Reference routing

File	Read when
references/launcher-workflow.md	Running discovery, the setup-question shaping, install, and the per-tab spawn loop end to end.
references/backend-matrix.md	Spawning/installing/invoking a specific backend (claude/codex/pi/hermes) — exact commands + JSON keys.
references/pitfalls.md	Any herdr/codex spawn-or-drive trap (pane renumbering, done≠idle, lost sends, reserved names, plain-text reads).
references/monitor-mode.md	Running the autonomous fleet-supervisor loop (Step 9 / "monitor mode"): the --watch/--json flags, the ScheduleWakeup+Monitor wake loop, the full-autonomy decision sub-agent, the hung-shell (ESC×2) + recovery playbook.