agentleFS
alevialevi/redline/skills/redline-review/SKILL.md

redline-review

Skill7 starsChanged 6 months agoMITView on GitHub

Hand a markdown file you produced (spec, RFC, brief, plan) to the human for inline review, wait for them to finish, then continue with the approved document. Use whenever the human's sign-off on a document is the next step in the work.

  • Reads credentials

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. McGuireKevin/cell-site-lease-negotiation-toolkit★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository3 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    When the staging file is ready, hand it back to Redline:

    line 84
  2. Very specific:

    If invocation fails (binary missing, startup file never appears, etc.), surface the error verbatim and stop — do not try to recover.

    line 96
  3. Very specific:

    When the polling loop's shell call returns, the cat "$RESULT" at the end of it has printed the result JSON to stdout.

    line 114
  4. Distinctive:

    Write the markdown file to disk at an absolute path.

    line 135
  5. Very specific:

    When author-wait returns kind: "result" with status abandoned or error, the session has ended: stop and ask the human how to proceed.

    line 141

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Handing off a markdown doc for human review

When you've produced a markdown document that the human needs to read, comment on, and approve before you continue, use Redline. It opens a browser-based reader where the human leaves inline comments. You remain the authoring agent, reply with your existing task context, and revise a Redline-managed staging file when the human accepts a round. The human signs off, and the document on disk is left in its final approved state.

How to invoke it

The redline launcher lives at __REDLINE_BIN__ (substituted at install time — if you see the literal placeholder string, the skill was installed incorrectly; tell the human to re-run redline install-skill). Always invoke it by this absolute path. Do not call bare redline and do not try to "fix" PATH issues by running bun link or guessing where the repo lives.

Always detach the launcher with Node and poll. Never run __REDLINE_BIN__ as a foreground/blocking shell call: agent shell tools often buffer stdout until the process exits, so you would never see the URL the human needs to click and your "I'll wait while you review" message would be a lie. Also do not use nohup or a plain trailing &: in Codex-style short shell calls, the runner can clean up the shell's process group and take the Redline server with it. Use this pattern:

FILE=/abs/path/to/file.md
DIR=$(dirname "$FILE"); BASE=$(basename "$FILE")
STARTUP="$DIR/.review/$BASE.startup.json"
RESULT="$DIR/.review/$BASE.result"
LOG=/tmp/redline-$BASE.log

# Kick off the review in a detached process group and open it in the user's real browser.
node - "__REDLINE_BIN__" "$FILE" "$LOG" <<'JS'
const { spawn } = require("node:child_process");
const fs = require("node:fs");
const [launcher, file, logPath] = process.argv.slice(2);
const out = fs.openSync(logPath, "a");
const child = spawn(launcher, [file, "--responder", "caller", "--open"], {
  detached: true,
  stdio: ["ignore", out, out],
  env: process.env,
});
child.unref();
console.log(child.pid);
JS

# Step 1: wait for startup, read the URL.
for i in $(seq 1 60); do [ -f "$STARTUP" ] && break; sleep 0.5; done
if [ ! -f "$STARTUP" ]; then
  echo "redline did not start; check $LOG" >&2
  exit 1
fi
URL=$(grep -o '"url": *"[^"]*"' "$STARTUP" | sed 's/.*"\(http[^"]*\)".*/\1/')
PID=$(grep -o '"pid": *[0-9]*' "$STARTUP" | grep -o '[0-9]*')
echo "REDLINE_URL: $URL"
echo "REDLINE_PID: $PID"

# Step 2: tell the human the browser opened (you do this after the first shell call returns
# — see the next section), then wait until the reviewer sends you a turn or the
# review exits. Reply to caller turns with author-reply, then run author-wait again.
__REDLINE_BIN__ author-wait "$FILE"

The startup file at .review/<basename>.startup.json is written synchronously when the server begins listening; it contains url, port, file, result_file, started_at, pid. The result file at .review/<basename>.result is written when the session ends (approved, abandoned, or error).

In practice, run the script above as two separate shell calls so you can tell the human the URL between steps:

  1. First call: everything through echo "REDLINE_PID: $PID". Returns in ~1s with the URL and PID on stdout.
  2. Tell the human Redline opened in their browser, and include the URL only as a fallback (see "Surfacing the URL" below).
  3. Second call: __REDLINE_BIN__ author-wait "$FILE". It returns { "kind": "caller-turn", ... }, { "kind": "revision-request", ... }, { "kind": "result", ... }, or { "kind": "session-ended", ... }. Long timeout (timeout: 1800000 = 30 min, or longer). Handle caller turns and revision requests as described below, then run author-wait again. If it returns session-ended, inspect $LOG and relaunch only after explaining the failed session to the human.

author-wait is also the caller's liveness signal. Keep the wait loop active for the whole review. If you cannot continue serving the review, tell the human instead of silently switching it to another responder. Recovery is an explicit user choice through redline responder "$FILE" --mode local or --mode manual.

Reply to reviewer turns

caller-turn contains caller_turns, with the comment id, selected quote, surrounding context, latest reviewer request, and full thread. author-wait posts the thinking indicator before returning the turn. Answer from the context of the task in which you authored the document, using repository tools when the review question requires them.

Post each reply with a verdict:

__REDLINE_BIN__ author-reply "$FILE" <comment-id> \
  --message "<concise reply>" \
  --requires-revision <true|false> \
  --revision-reason "<short edit description when true>"

Set --requires-revision true when fully addressing the comment implies a document edit. Set it to false when the thread itself answers the comment. Omit --revision-reason when no edit is needed. After replying to every returned turn, run author-wait again. Do not leave the review loop to start unrelated work.

Apply an accepted revision

revision-request contains the accepted round, its settled comment threads, and revision_file, an absolute path to a Redline-managed staging copy. Read the current document and the settled threads, then edit only revision_file to apply what was agreed. Preserve the complete Markdown document and untouched sections. Do not edit the live document path directly.

When the staging file is ready, hand it back to Redline:

__REDLINE_BIN__ author-revise "$FILE" --round <round-number>

Redline verifies that the live source hasn't changed, validates the staged document, snapshots the live file, commits the revision, opens the next round, and reloads the browser.

On the first validation rejection, Redline keeps the accepted round and staging file pending and tells you to correct the draft and retry author-revise once. Surface the error, correct the staging file, and resubmit without asking for another approval. author-wait also returns this pending request with validation_error if you resume through the wait loop. This is a recoverable submission rejection, not a terminal review result.

If the correction also fails, or a different error cancels the transaction, surface the error and return to author-wait. The reviewer can click Revise again. Do not resubmit against a cancelled transaction, restart the session, copy the staging file over the live document, or bypass validation. A new request may include previous_revision_file, a preserved draft from the failed attempt. Read it alongside the new staging copy and current settled threads to recover edits that still apply. A new revision-request means the reviewer has already authorized another attempt; handle it immediately without asking for restart approval.

If invocation fails (binary missing, startup file never appears, etc.), surface the error verbatim and stop — do not try to recover. The human will re-run redline install-skill.

Pass context with --context

__REDLINE_BIN__ /abs/path/file.md --context "Draft of the auth-rewrite RFC — focus on the migration plan in §4."

The context string is shown in the reader's header so the human knows what they're being asked to review and what you'd like them to focus on. Use it whenever the file alone doesn't make the ask obvious. One sentence is plenty.

Surfacing the URL

The --open flag launches the review in the user's real browser via the OS opener (open on macOS, xdg-open on Linux, start on Windows). After the first shell call returns with REDLINE_URL: http://localhost:NNNN, tell the human the browser opened and include the URL only as a fallback. Do not make the URL the primary action; in some agent UIs, clicking localhost opens an embedded preview panel instead of the user's browser.

"I opened this in Redline in your browser. Fallback URL: http://localhost:NNNN. I'll continue once you click Done."

How to interpret the result

When the polling loop's shell call returns, the cat "$RESULT" at the end of it has printed the result JSON to stdout.

{
  "status": "approved",
  "file": "/abs/path/to/file.md",
  "rounds": 2,
  "comments": 5
}

Statuses:

  • approved — Human signed off. Re-read the file from disk and continue. Note: the file may be byte-identical to what you handed off — if every comment was Q&A the agent answered with accept-as-is, no revision pass ran. That's still a valid approval, not a no-op.
  • abandoned — Human closed the tab or Ctrl+C'd without clicking Done. The doc is in whatever state it was last revised to, but has not been signed off. Ask the human what they want to do.
  • error — The session ended with an error. The result file includes a reason field with the failure message; .review/errors.log next to the file has more detail. Surface both to the human. A failed author-revise command while the session is still running is handled by the recovery steps above.

Outer-agent handoff pattern

The full loop, when you are the outer agent producing the doc:

  1. Write the markdown file to disk at an absolute path.
  2. Tell the human in one sentence what's about to happen.
  3. First shell call: launch __REDLINE_BIN__ <abs-path> --responder caller --context "<one-liner>" --open in the background and poll for .startup.json. Returns in ~1s with the URL.
  4. Tell the human Redline opened in their browser and include the URL only as a fallback.
  5. Second shell call: run __REDLINE_BIN__ author-wait "$FILE". Answer every caller-turn with author-reply, including the revision verdict. Apply every revision-request through its staging file and author-revise. Then run author-wait again. If it returns kind: "session-ended", inspect the log path from step 1 and tell the human the session died instead of silently relaunching. Do not start unrelated work while the session runs.
  6. On approved: re-read the file from disk (it may have been revised) and continue with whatever required sign-off.
  7. When author-wait returns kind: "result" with status abandoned or error, the session has ended: stop and ask the human how to proceed. This does not apply to a rejected submission in a live session or a new revision-request.

You reply to comments and apply accepted revisions because you are the agent that authored and launched the review. Use author-revise for the staged handback; do not invoke redline resolve separately.

When not to use this

  • The doc doesn't need human sign-off — just commit it.
  • The human is not at the keyboard (e.g. an autonomous run). Redline requires a live browser session.
  • The doc is something other than markdown.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.