---
name: herdr-workflow
description: "Coordinate authorized work in a confirmed native Herdr environment: preserve user panes, orient with compact queries and organize independent Task-Pis in native worktrees. Not an installer, remote-access grant or replacement for the installed CLI skill."
---

# Herdr workflow

An adaptable Workbench example, not an installed resource. Read [CUSTOMIZE.md](CUSTOMIZE.md) when creating a responsible original.

## Establish capability and authority

First inspect the actual session's tools and rules. Use Herdr only when `HERDR_ENV` equals `1` and `HERDR_WORKSPACE_ID`, `HERDR_TAB_ID` and `HERDR_PANE_ID` are nonempty; check without printing values. After a resource reload, repeat detection and load the installed native skill again.

When confirmed, run `herdr --skill` and read its complete output before control operations. The installed CLI skill and current command help own syntax and runtime behavior, not this example. Start discovery with `herdr --help`; inspect relevant command groups as directed by the installed skill. Do not run bare `herdr` or probe mutating commands by omitting arguments. A failed or incomplete skill load blocks Herdr control.

If Herdr or required native functionality is absent, say what is missing and offer to research a suitable extension when material. This example grants no installation or activation permission. Do not impersonate the runtime or control another focused session. Use an actually available authorized execution form instead when it fulfills the goal. Do not substitute another multiplexer without the user's requested method and actual rules allowing it.

## Stay in the assigned workspace

Work in the assigned workspace and its authorized task workspaces, not unrelated sessions. A user-provided pane is intentional task access: verify its actual identity, target and connection, then use it within the commissioned scope without an invented second assignment. It does not grant a new connection or unrelated task. Remote forwarding and attachment remain remote transports subject to the actual access rules.

Preserve user-opened panes, layout and focus. Do not close, hide, resize or repurpose them merely for tidiness. Use `--no-focus` for authorized background creation. Loading this workflow does not authorize creating panes, agents, worktrees or connections.

Use actual injected caller IDs or explicit observed targets, not the UI-focused pane. Read new identities from native responses. Pane IDs, agent names and Intercom addresses are different identities; never derive one from another.

## Orient compactly

After required native discovery, the following read-only Fish commands illustrate targeted orientation. Confirm them against the installed CLI before use:

```fish
herdr pane current --current
herdr pane layout --pane "$HERDR_PANE_ID"
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
```

Keep a compact in-session map of the calling workspace/tab/pane and relevant neighbors. Use a directional neighbor query when that is the question, rather than a workspace dump. Reuse observed IDs; refresh affected state after moves, splits, closes, target failures or lost context. Use native structured output or an actually available structured-data tool to select only necessary fields; no extra package is required by this example.

Occasional status checks at useful work boundaries are orientation, not completion detection. Do not poll workspace snapshots on a timer. Observe native process exit/completion immediately and evaluate the status. On failure inspect and handle or report it; do not wait for a marker after the process has ended. A timeout is only an upper safety bound.

## Add an authorized pane or agent

Inspect layout and choose a suitable sibling split, preserve the project cwd and keep user focus unchanged. Start an agent only in a verified available shell pane. Before sending shell input, verify the actual foreground shell has an empty prompt and no partial input; send one simple command in that shell's syntax. Use the recipient's actual shell rules rather than assuming a personal default.

These are descriptive patterns, not runnable commands; substitute only observed or authorized task values and quote for the target shell:

```text
herdr pane split --current --direction <right-or-down> --cwd <project-directory> --no-focus
herdr agent start <meaningful-name> --kind pi --pane <returned-pane-id>
```

Native `agent start` success reports interactive readiness; do not add a redundant readiness wait. A submission acknowledgement alone is not execution or completion evidence. On blocked, failed or ambiguous outcomes, inspect actual state before retrying. Do not answer an unfamiliar approval dialog by assumption.

For communication, verify the actual Intercom session, cwd and Herdr location. An agent name or title is not an address. Read [Intercom protocol](../intercom-protocol/SKILL.md) before sending or handling messages; use only actual exposed communication tools.

## Independent Task-Pis — form III

This form always requires an authoritative governing specification. Establish a missing one with the user before assignment; reuse the accepted original rather than creating a competing copy. Forms I (inline) and II (bounded native Subagents) acquire no specification requirement merely from their organization; project and selected-method requirements still bind.

1. **Bound the main tasks.** Supply each task's goal, relevant specification excerpts/anchors, constraints, method, inputs, exact writable paths and acceptance checks. Agree the accepted base and integration branch. The leading orchestrator keeps overall scope, decisions, safety and integration.
2. **Use supported native task worktrees.** Verify the installed CLI supports the required native topology and that its creation is authorized. From the main checkout, use the native worktree operation; let Herdr choose the path and branch and retain its returned workspace, root-pane and worktree identities:

   ```text
   herdr worktree create --workspace "$HERDR_WORKSPACE_ID" --base <accepted-base> --label <task-label> --no-focus
   ```

   A task workspace has its own checkout/index. Do not substitute a hand-built checkout/tab wrapper or shadow worktree runtime. Missing native support blocks this form; choose another authorized form only when it still fulfills the user's method.
3. **Start independent user-facing sessions.** Start a meaningfully named Pi in each returned available pane. Each Task-Pi is a user-facing suborchestrator, not a native Subagent. It cuts its internal tasks using actual bounded native Subagents where supported. Do not create a recursive cascade of Task-Pis.
4. **Assign through actual Intercom.** After startup, use Intercom for bounded assignments, necessary questions and results rather than further pane input. Pass the real protocol path to every communicating participant. Send necessary context, not the full conversation. If Intercom is required but unavailable, stop this branch and report the capability gap.
5. **Supervise against authority and evidence.** Review submitted plans, questions and actual checks against the governing specification, confirmed constraints and recipient's configured KISS method. Resolve matters within the assignment; escalate unresolved user decisions. Status chatter and peer approval rounds do not replace supervision. Use asynchronous native completion notifications rather than blocking or polling; block only when explicitly required by the user for a same-turn result.
6. **Accept and integrate serially.** Examine the complete changed-path set, cumulative diff, base/candidate state and actual checks. A Task-Pi's report or one green check is not acceptance. Each Task-Pi owns its worktree index; the leading orchestrator owns integration. Use the recipient's actually configured Git/project workflow for integration, fixed-result validation and any authorized synchronization. No publication or remote grant is created here.
7. **Clean up only accepted owned work.** After integration and required corrections, remove only the returned, owned, clean task workspace using the installed native operation:

   ```text
   herdr worktree remove --workspace <returned-task-workspace>
   ```

   This is not the main caller workspace. Preserve user/foreign/dirty workspaces and user-opened panes. Do not force cleanup. Apply actual destructive-action gates, including approval for destructive changes outside the authorized project workroot. Inspect failed or ambiguous native outcomes before retrying; a connection failure does not prove nothing changed.

## Evidence and execution

Keep all executable logic inspectable as plaintext. Follow real project/harness action gates and configured external owners for remote access, shell use, credentials and Git; this workflow supplies no replacement policy. Report performed operations and concrete checks separately from missing runtime/model evidence. Source review or a text simulation does not validate native discovery, live coordination, model compliance or E2E behavior.