From 5eea194f284d4fe721a4e1d265dac6140e373f68 Mon Sep 17 00:00:00 2001 From: Jeff Casimir Date: Fri, 17 Jul 2026 08:28:43 -0600 Subject: [PATCH] feat(refresh): seed the writing voice guide across boxes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit /ce:refresh already syncs the writing personas (Perkins + the seven-voice panel) from ce-reviewers-jsl, but the voice-guide.md those reviewers judge against had no propagation path — the devbox entrypoint seed loop is .yaml-only. Boxes other than the author's fell back to first principles. Add seed-voice-guide.sh + a refresh step that fetches voice/voice-guide.md from the persona source repos (orchestrator config first, then reviewer) into ~/.config/compound-engineering/voice-guide.md. Seed-if-absent: the guide is a living document (the writing orchestrator's compound phase edits the local copy and commits the canonical version back to the source repo), so an existing local copy is never overwritten. No-op if no source repo hosts a voice guide. No version bump (per contributor rules); no component-count change. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../skills/refresh/SKILL.md | 12 ++- .../skills/refresh/seed-voice-guide.sh | 91 +++++++++++++++++++ 2 files changed, 102 insertions(+), 1 deletion(-) create mode 100755 plugins/compound-engineering/skills/refresh/seed-voice-guide.sh diff --git a/plugins/compound-engineering/skills/refresh/SKILL.md b/plugins/compound-engineering/skills/refresh/SKILL.md index 1da13a825..16b2be77e 100644 --- a/plugins/compound-engineering/skills/refresh/SKILL.md +++ b/plugins/compound-engineering/skills/refresh/SKILL.md @@ -115,7 +115,17 @@ bash "$PLUGIN_DIR/skills/refresh/generate-shims.sh" "$PLUGIN_DIR" Show the script's output to the user — it lists which shims were generated. -## Step 7: Show results +## Step 7: Seed the writing voice guide + +Writing reviewers (the Perkins panel, category `writing`) judge prose against a **voice guide** — the ground-truth artifact that defines the target voice. Seed it from the persona source repos, if absent: + +```bash +bash "$PLUGIN_DIR/skills/refresh/seed-voice-guide.sh" +``` + +The script fetches `voice/voice-guide.md` from the repos in the persona source configs (orchestrator first, then reviewer) and writes it to `~/.config/compound-engineering/voice-guide.md`. It is **seed-if-absent**: the voice guide is a living document (the writing orchestrator's compound phase edits the local copy and commits the canonical version back to the source repo), so an existing local copy is never overwritten. To pull a newer canonical guide, delete the local copy and re-run. If no source repo hosts a voice guide, this is a no-op. Show the script's one-line output to the user. + +## Step 8: Show results The sync script writes summaries to `~/.config/compound-engineering/`: - `last-reviewer-refresh-summary.md` — reviewer sync results diff --git a/plugins/compound-engineering/skills/refresh/seed-voice-guide.sh b/plugins/compound-engineering/skills/refresh/seed-voice-guide.sh new file mode 100755 index 000000000..7a133f293 --- /dev/null +++ b/plugins/compound-engineering/skills/refresh/seed-voice-guide.sh @@ -0,0 +1,91 @@ +#!/usr/bin/env bash +# +# seed-voice-guide.sh — seed the writing voice guide from a persona source repo. +# +# The voice guide is the ground-truth artifact the writing reviewers (the Perkins +# panel) check prose against. It lives alongside the personas in a source repo +# (e.g. JumpstartLab/ce-reviewers-jsl at voice/voice-guide.md). +# +# Seeds ~/.config/compound-engineering/voice-guide.md ONLY IF ABSENT. The guide is +# a living document — Perkins's compound phase edits the local copy and commits the +# canonical version back to the source repo — so a box's existing copy is never +# overwritten here. To pull a newer canonical guide, delete the local copy and +# re-run /ce:refresh. +# +# Fetches from the repos named in the persona source configs (orchestrator first, +# then reviewer). If none host a voice guide, this is a no-op and the reviewers +# fall back to first principles. + +set -u + +DEST_DIR="$HOME/.config/compound-engineering" +DEST="$DEST_DIR/voice-guide.md" +GUIDE_PATH="voice/voice-guide.md" + +if [ -f "$DEST" ]; then + echo "Voice guide already present ($DEST) — left as-is (seed-if-absent)." + exit 0 +fi + +# Gather candidate repos (repobranch) from the persona source configs. +repos_raw="$(python3 - "$DEST_DIR" <<'PY' +import os, sys +d = sys.argv[1] +out = [] +for cfg in ("orchestrator-sources.yaml", "reviewer-sources.yaml"): + p = os.path.join(d, cfg) + if not os.path.exists(p): + continue + repo, branch = None, "main" + def flush(): + if repo: + out.append(f"{repo}\t{branch}") + for line in open(p): + s = line.strip() + if s.startswith("- name:"): + flush(); repo, branch = None, "main" + elif s.startswith("repo:"): + repo = s.split(":", 1)[1].strip() + elif s.startswith("branch:"): + branch = s.split(":", 1)[1].strip() + flush() +seen, uniq = set(), [] +for r in out: + if r not in seen: + seen.add(r); uniq.append(r) +print("\n".join(uniq)) +PY +)" + +# Fall back to the canonical JSL personas repo if no configs are present. +if [ -z "${repos_raw//[$'\n\t ']/}" ]; then + repos_raw=$'JumpstartLab/ce-reviewers-jsl\tmain' +fi + +mkdir -p "$DEST_DIR" + +while IFS=$'\t' read -r repo branch; do + [ -n "$repo" ] || continue + [ -n "$branch" ] || branch="main" + if command -v gh &>/dev/null; then + if gh api "repos/${repo}/contents/${GUIDE_PATH}?ref=${branch}" \ + -H "Accept: application/vnd.github.raw+json" > "$DEST" 2>/dev/null && [ -s "$DEST" ]; then + echo "Seeded voice guide from ${repo}@${branch}:${GUIDE_PATH} -> $DEST" + exit 0 + fi + rm -f "$DEST" + elif command -v git &>/dev/null; then + tmp="$(mktemp -d)" + if git clone --depth 1 --branch "$branch" "https://github.com/${repo}.git" "$tmp" 2>/dev/null \ + && [ -s "$tmp/$GUIDE_PATH" ]; then + cp "$tmp/$GUIDE_PATH" "$DEST" + rm -rf "$tmp" + echo "Seeded voice guide from ${repo}@${branch}:${GUIDE_PATH} -> $DEST" + exit 0 + fi + rm -rf "$tmp" + fi +done <<< "$repos_raw" + +echo "No ${GUIDE_PATH} found in configured persona sources — skipped (writing reviewers will fall back to first principles)." +exit 0