wirasm/prp/prp-companion

PRP Companion

Write one HTML page that lets a human take in a plan or review with less reading. The markdown stays the artifact that agents and later skills read: never edit it. The page is derived from it and is overwritten on every run.

Input: $ARGUMENTS — a plan (*.plan.md) or review report (pr-*-review.md). If blank, use the newest of either in $PRP_DIR/plans/ and $PRP_DIR/reviews/. For any other kind of markdown, say the companion covers plans and reviews only, and stop.

The agent that just wrote the artifact writes its companion, in the same context. Do not hand it to a fresh agent.

Resolve the store

# --- PRP store resolver (canonical; keep byte-identical across skills) ---
# Adopt the store that already records this root; mint a key only when none does.
_gd="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
case "$_gd" in */.git) _root="${_gd%/.git}" ;; "") _root="$PWD" ;; *) _root="$_gd" ;; esac
_root="$(cd "$_root" && pwd -P)"
_name="$(basename "$_root" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-*//;s/-*$//')"
_home="${PRP_HOME:-$HOME/.prp}"
_hit="$(grep -lsF "\"path\": \"$_root\"" "$_home"/*/project.json 2>/dev/null | head -1)"
PRP_DIR="${_hit%/project.json}"
[ -n "$PRP_DIR" ] || PRP_DIR="$_home/${_name:-project}-$(printf %s "$_root" | git hash-object --stdin | cut -c1-8)"
mkdir -p "$PRP_DIR"; [ -f "$PRP_DIR/project.json" ] || printf '{"path": "%s", "name": "%s"}\n' "$_root" "${_name:-project}" > "$PRP_DIR/project.json"

Write the page

1. Read the whole markdown artifact.
2. Build the theme <style>: templates/default-theme.css verbatim, then $PRP_DIR/companion.css

verbatim after it when that file exists, so any token the store's file leaves out keeps its default. A host UI that wants pages in its own look writes that file; prp never writes it.

1. Read templates/companion.md and follow it exactly.
2. Write the page beside the markdown: same directory, final .md replaced by .html

(x.plan.md → x.plan.html, pr-12-review.md → pr-12-review.html).

1. Before reporting, check the page against the markdown once: every risk, finding, required outcome,

acceptance criterion and changed Part is on the page as the markdown's own words, and nothing on the page is absent from the markdown. Fix the page, never the markdown.

1. When the artifact is a review or a plan and command -v bench succeeds, the page is live in helm: read

templates/live.md and follow it. It adds the page's script, writes <stem>.data.json beside the page and opens the page. Otherwise the page stays static.

Report

One line: the companion's absolute path, and in live mode the data file's path or why it was not written.

Resources

• templates/companion.md — the page contract: file rules, fidelity, ids, diagrams, plan and review layouts
• templates/default-theme.css — the built-in theme, always pasted first; the store's companion.css overrides it
• templates/live.md — live mode for a review or plan page in helm: the data file, opening the page, answering its mail
• templates/live.js — the live page's script, pasted verbatim in live mode only