ronaknnathani/relay

# Write-Like-Me Builder

This skill builds a *personalized* writing-voice skill for one person. The output
is a `SKILL.md` that any agent can load to draft or edit prose in that person's
voice. You produce it by gathering the person's real writing from sources they
provide, analyzing it (both statistically and by reading it), and synthesizing a
profile grounded in real examples.

The core principle: **a voice profile is only as good as the real writing behind
it.** Don't invent traits. Every claim in the generated skill should trace to
something the person actually wrote. Quote them verbatim wherever you can.

## The workflow

# Clarify

Produce a requirements + acceptance-criteria artifact that pins down what success looks like, so a
planner never has to guess. The bar: every requirement is measurable and every acceptance criterion is
checkable — you could hand the artifact to someone else and they'd build the right thing. This is a
peer phase to `plan`, not its parent: it grounds itself in the code via `explore`, then hands its
artifact to `plan`. It does **not** design the implementation and does **not** invoke `plan`.

## Process

1. **Resolve from the codebase before asking.** If a question's answer is discoverable in the code —
   how a thing currently works, what the existing convention is, where an integration point lives —
   call `explore` (dispatch a sub-agent when available; otherwise do it inline) and find it. Only ask
   the user what you genuinely cannot determine. Bothering them with a discoverable fact erodes trust.

# Commit

Create a single git commit for the current changes.

## Gather context

First inspect the working tree. Run these read-only commands and read their output:

- `git status` — what is staged and unstaged
- `git diff HEAD` — the full staged and unstaged diff
- `git branch --show-current` — the current branch
- `git log --oneline -10` — recent commit message style to match

## Create the commit

# Deliver PR

Drive one change from a task to an open PR by orchestrating the foundation skills, one phase at a time,
with durable resumable state. You are a **router, not a worker**: you read state, dispatch the next
phase as a sub-agent, record the result, and move on. You do not do the phase work yourself, and you
stay context-light — you read digests and state, never file dumps.

## Session goal

In every agent harness, set `/goal` to the user's requested outcome. The `deliver-pr` workflow is the
execution method, not the goal. Keep `task.md`, requirements, and `relay state` as the durable
definition and progress record across resumes.

## Managed assignment — before state routing

# Explore

Build an accurate, cited map of a codebase — or one feature/area within it — so a downstream skill can
act on it. The output is understanding, not change: this skill **observes and reports only and must
never modify a file, run a mutating command, or write anything except its report.** The bar is a map a
reader can trust because every claim is either backed by a `file:line` reference or explicitly flagged
as unverified. Scope to the topic the caller named; do not map the whole repo when asked about a slice.

## Shared vocabulary

Use these terms so downstream skills that act on this map share one language:

- **Interface** — the surface a caller sees (signatures, exported names, public API).
- **Implementation** — the code behind that surface.

# Implement

Turn an implementation plan into working, tested code, one thin slice at a time, keeping the build and
existing tests green at every step. The bar: at any moment you could stop and the system is committable
— nothing half-built, nothing red. This phase consumes the artifact from `plan`; it does **not** design
the approach and does **not** open a PR. Decisions in the plan are settled — follow them; if one is
wrong or missing, stop and surface it rather than quietly inventing a different design.

## Process

1. **Load the plan and review it critically.** Read it end to end before touching code. If a task is
   ambiguous, a step is missing, or the approach looks wrong, raise it now — don't paper over a gap
   mid-implementation. Turn the plan's tasks into an ordered checklist of slices.
2. **Load coding guidance.** Read the repo's `AGENTS.md` when present, then read global guidance from

# Open PR

Take finished work from working tree to open pull request: stage specific files, commit with a
repo-style message, push, and open the PR in the author's house style. Read `<repo>/AGENTS.md` and
`~/.config/agents/AGENTS.md` first (repo-specific rules win) and follow those preferences for commit
messages and PR descriptions. Execute git/`gh` operations through this skill's bundled
`scripts/open-pr.sh` helper rather than inlining command sequences in the skill.

## Flags

- `--draft` — open the PR as a draft (`gh pr create --draft`). Default is open (ready for review).
- `--no-review` — skip the optional local review before push.

## Process

# Plan

Given a clarified requirements artifact, produce an implementation plan concrete enough that someone
with no prior context could execute it. The bar: exact file paths and names, one committed
architecture decision, and a phased build sequence `implement` consumes step by step — no abstract
advice, no "add appropriate error handling". This is a peer phase: it grounds itself in the code via
`explore`, picks ONE approach and commits, then hands a plan to `implement`. It does **not** clarify
requirements (that's `clarify`, upstream) and does **not** write production code (that's `implement`,
downstream). It does not invoke either.

## Process

1. **Ground in the codebase first.** Read the clarified artifact (`clarify`'s requirements + success
   criteria), then call `explore` (dispatch a sub-agent when available; otherwise inline) and consume

# PR Fix

Drive a PR to a mergeable state: a green CI, every review comment fixed-and-resolved or
replied-and-flagged, and no merge conflicts with the base. Work the three
fronts — CI, comments, conflicts — and loop until all are clear. Fix root causes, never silence
failures or guess an author's intent. Use `review`'s shared severity vocabulary (Critical / Important /
Suggestion). Run independent investigations as sub-agents when available; otherwise do them inline.

## Two modes — check your input first

**Delegated mode — a caller supplied a watcher worklist.** `pr-monitor` hands you items taken from a
`relay pr watch` digest: each carries `reason`, `source`, `id`, `answers`, `updatedAt`, `body`,
`thread_id`, `path`, `line`, and for checks the `check_name` and `check_run_id`. That worklist is **complete and
authoritative**:

# PR Monitor

Handle **one** pull request attention event, then stop. You are a **router**: the `relay pr watch`
runtime does the observing, you interpret its digest, delegate the fixing to `pr-fix`, re-observe the
pull request, and exit. You never write code, never post in your own voice, never approve, and never
merge.

There is **no acknowledgement**. The watcher never records that attention was handled, because a local
claim can be wrong. Every tick re-reads the live pull request, and an item disappears only when the
remote state itself no longer shows it: the check passes or reruns, the head SHA changes, the conflict
clears, the thread resolves, your reply lands on that exact source, auto-merge is armed, or the pull
request closes or merges. If nothing changed, the problem is still there and it will wake you again —
which is correct.

# Rebase — Rebase, Fix Conflicts, Push

Rebase the current branch onto the base branch (default: `main`), resolve any merge conflicts, and force-push.

## Steps

### 1. Determine Base Branch

- If `$ARGUMENTS` contains a branch name, use it as the base.
- Otherwise, default to `main`.

### 2. Pre-check Working Tree

```bash

# Relay Archive — Project Archival

```bash
relay archive $ARGUMENTS
```

# Relay Status — Project Status

Display the status of relay projects.

```bash
relay status $ARGUMENTS
```

# Review

Review a change with a library of specialized reviewer roles, score every finding for confidence,
drop the noise, and emit results in one of two modes. The goal is signal: high-confidence findings a
senior engineer would actually raise, each with a concrete fix — never a wall of nitpicks.

## Modes

- **report** (default) — produce a local, severity-ranked findings report for the author or a fix
  loop (e.g. `pr-fix`). Posts nothing.
- **inline** (`--comment`) — post a summary comment plus inline comments on the PR via `gh`.

## The reviewer-role library

# Review PR

Review a pull request the user did not write, the way their own generated code gets reviewed, and
leave a **draft** GitHub review they can edit and submit. The bar: every comment is something the
user would raise themselves, in their voice, anchored to the right line, and no earlier finding is
forgotten or raised twice. Never submit, approve, or request changes. The user does.

## Prepare the checkout and state

Bind `$PR` to the pull request the user named (a URL or `<owner>/<repo>#<number>`). If none was
named and the launch context does not name one, ask for it. Then run:

```bash
relay review "$PR" --no-launch

# Simplify

Make a change simpler and clearer without changing what it does. The bar: readable, explicit code over
clever, compact code — would a senior engineer call this overcomplicated? Scope is the **recently
changed code** — the working diff (e.g. `git diff` against the branch point) unless the caller names
files. This is quality-only: it does not hunt for bugs (that's `review`).

## Step 0 — the invariant

**Preserve functionality. Never change what the code does, only how it does it.** Every original
feature, output, and behavior stays intact. If a simplification would alter behavior, it is a `review`
or implementation concern, not a simplification — stop and surface it.

## Scan — three buckets

# Stack Ship

Drive a design or feature goal from intake to "all PRs merged" with **near-zero steering**. The
orchestrator is a **router, not a worker**: it owns the plan, state, delegation, and author-facing
decisions; subagents own execution and return structured digests.

The [guardrails](references/guardrails.md) are non-negotiable — **read them before acting.**

> Throughout this skill `master` denotes the repository's **default branch**; substitute the real
> default (`main`, etc.). Auto-merge is armed only on a default-branch-based PR — which, in a stack, is
> exactly the front PR.

## The one-paragraph model

# 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

# /todo — Repo-Scoped Todos

Capture todos from within a session for later pickup. Runs as a sub-agent to keep the main session context clean.

## Dispatch

{{subagent:fast}} with this prompt:

> Run the following shell command and report the output exactly as printed:
>
> ```bash
> relay todo $ARGUMENTS
> ```
>

# Validate

Decide whether a change is ready to ship and report the verdict — pass, or fail with the exact
failures someone else can act on. The bar: every acceptance criterion from `clarify`/`plan` is
demonstrably met, and every quality gate the repo defines is green, each shown by a command or
observation rather than asserted. This skill is a gate, not a fixer: on failure it hands precise
error-feedback to `pr-fix` or `implement` and stops. It does **not** edit code and does **not** ship.

## Process

1. **Gather the acceptance criteria.** Read the Success criteria from the `clarify`/`plan` artifacts.
   These are the goal-backward targets — what must be TRUE about the codebase. If no artifact exists,
   reconstruct the criteria from the task description and list them, so the verdict is checkable.
2. **Discover the repo's own gate commands.** Find how *this* repo lints, type-checks, tests, builds,

# Write Like Ronak

You are writing as Ronak. The goal is prose indistinguishable from what he'd
write himself. This guide tells you how. When in doubt, be plainer, shorter, and
more concrete than your default.

## Voice in one paragraph

Direct, concrete, unceremonious. Lead with the point in the first sentence.
Prefer short declarative sentences, one idea each. Say the *why* right after the
*what*. Reason in the open: lay out the options, give their tradeoffs, and mark
the one you'd pick. Often make a point by asking a question instead of asserting.
Stay collaborative ("we", "let's") even when disagreeing. Be generous with credit
and honest about how strongly you hold an opinion. Use plain words: no hype, no