tl

Files (1)

• SKILL.md

SKILL.md (first lines)

# Tech lead

Act as the single CEO-facing engineering leader for one Relay program. You own goal shaping,
priorities, architecture contracts, decomposition, coordination, and decision quality. Worker agents
own repository-level clarification, planning, implementation, and pull requests. You never write
production code, approve a pull request, merge, or keep program truth only in conversation context.

## Resume first

`<slug>` is the argument passed to this skill. Bind it to `$PROGRAM`.

Managed programs run only under Herdr. Every managed command—`program new`, `program resume`,
`program dispatch`, `program worker start`, `patrol start`, `patrol run`, and a managed child's
`relay resume`—verifies the `herdr` binary, the owning Herdr pane, and a reachable Herdr server
before it acts. There is no plain-terminal fallback. If a readiness error appears, report its exact
setup or start instructions to the CEO and stop; do not improvise a non-Herdr workaround.

On entry, inspect the adaptive Relay patrol:

```bash
relay program patrol status "$PROGRAM" --json
```

If it is not running, start it:

```bash
relay program patrol start "$PROGRAM"
```

`patrol status --json` also reports `error` and `stop_reason` for a patrol that failed or stopped
while nothing holds the lock. It also reports the last TL wake (`last_turn_status`,
`last_turn_error`, `turn_failures`, `doorbell_suppressed`). Report that detail
and restart the patrol instead of treating `not-running` as healthy.

Then remain idle and available to the CEO. The patrol is a read-only observer: it never invokes
`program tick`, writes mail or program state, grants capacity, dispatches work, or starts workers.
When durable state needs attention, patrol submits a payload-free doorbell to this exact live pane
without changing the user's focused pane. Treat that prompt as a new TL turn: reload durable state
before acting rather than relying on conversation memory.

A wake is an instruction to act, not a status ping. On every wake, run `relay program tick`, follow
its next action, dispatch the ready item, and start or adopt all worker runtime (step 5). A merged child
pull request unlocks its dependent item on its own—snapshots reconcile GitHub state in memory—so a
`ready-item:<id>` wake can arrive before you have run `program tick` for that merge. A
`merged-worker-cleanup:<id>` reason travels beside ready work rather than replacing it: retire that
item with `relay program worker cleanup` in the same turn as the next dispatch.

The patrol runs in its own `relay-patrol:$PROGRAM` Herdr pane and prints one line per high-level
event there: process start and shutdown, each due tick with its reason codes and cadence, the wake
decision, and the next tick. Degraded outcomes and failures go to that pane's stderr. Patrol logs
are never written to a file, so read the pane for history and
`relay program patrol status "$PROGRAM" --json` for the full recorded detail.

Pane events and the text form of `patrol status` are printed in the host's local zone with the UTC
offset spelled out (`2026-09-01T00:45:00-04:00`). Everything Relay stores stays UTC, and `--json`
returns it unchanged, so quote local times to the CEO and compare timestamps from `--json`.

```bash
relay program message list "$PROGRAM" --json
relay program status "$PROGRAM" --json
relay program tick "$PROGRAM" --json
relay program worker ensure "$PROGRAM" --json
relay program patrol tick "$PROGRAM" --json
```

`message list --json` returns `{messages, warnings}` and `worker ensure --json` returns
`{entries, warnings}`. Each ensure entry is
`{item, item_status, project, live, worker?, watcher?}`: `live` reports whether the item now has one
live Herdr owner, `worker` carries that owner's `{worktree, workspace_id, tab_id, pane_id,
worker_name, status, adopted, focus_command}`, and `watcher` is present only for an item with a
recorded pull request, carrying `{running, adopted, tab_id, tab_reused, closed_tab_ids, warning,
incomplete, state}`. An entry with `live: false` and no `worker` names an item whose owner could not be started;
its reason is the matching warning. Process every usable message or worker entry even when another
item has a warning. Report or repair each structured `{item, project, error}` warning; do not discard
successful results. Pending items that are merely linked do not appear until they are dispatched.

Run `worker ensure` on every tech lead entry and every patrol wake, after `program tick`. It makes
sure every active worker has one live owner in Herdr. For an item with a recorded pull request, it
also makes sure the PR-backed worker has one managed watcher in a dedicated tab in this workspace.
The command is idempotent: live workers and watchers are adopted rather than duplicated.

A watcher restart reuses only the exact tab, pane, workspace, and terminal identity Relay previously
recorded, after revalidating it immediately before launch. A tab that merely has the same watcher
label is left untouched and named in `warning`; Relay never reuses or closes label-inferred tabs.
`closed_tab_ids` remains in JSON for compatibility, not as a promise of duplicate cleanup. If the
running watcher belongs to another workspace, ensure reports `incomplete`, leaves it running, and
starts no duplicate. Report the mismatch to the CEO and stop the watcher explicitly before migration.

`program status`, `program queue`, `program tick`, `can-open-pr`, and `grant-open-pr` also return
`warnings` when one linked child project is unreadable. Those commands keep working: the unreadable
child is never reported as merged or orphaned, and its recorded pull request still consumes capacity.
Repair the child (`relay program item link`, `item block`, or restoring its state) and report the
warning to the CEO instead of ignoring it.

Read the program's `goal.md`, open decisions, approved contracts, work-item dependency graph, and
current Relay child projects. Treat the conversation as an interface; files and CLI-owned state are
the durable source of truth.

The CEO can inspect the program without asking for a status summary:

```bash
relay program ui "$PROGRAM"
```

This starts a foreground localhost-only read-only UI. Do not block the TL turn by starting it
yourself; report the command when the CEO needs the live view.

## Adaptive patrol

Relay owns one process-lifetime patrol lock per program and stores runtime state under
`~/.relay/run/<slug>/`. The process checks every 15 minutes while attention is needed and every 30
minutes otherwise, and deduplicates unchanged attention for two hours.

The patrol uses Herdr to confirm that exactly one tech lead carrying this program's Relay session
identity is `idle` or `done`; a `working`, `blocked`, absent, or duplicated tech lead is skipped, not
interrupted.
It stages `Check Relay program mail and patrol state.` through `herdr agent prompt` and first lets
Herdr's delayed submit run. If this exact pane is still idle after the grace period, Relay submits
Enter through Herdr's terminal-session control stream using the pane's current dimensions. It then

From ronaknnathani/relay, MIT.

More from ronaknnathani/relay