Harden PR visual recap publishing and links (#1174) · rangle/agent-native@ee66e0a · GitHub
Skip to content

Commit ee66e0a

Browse files
steve8708steve8708
authored
Harden PR visual recap publishing and links (BuilderIO#1174)
* fix(recap): harden visual recap publishing * feat(recap): support themed recap screenshots * feat(plan): apply recap screenshot theme colors * docs(visual-plans): require standalone published plans * feat(plan): finish recap screenshot theming * feat(recap): capture light and dark thumbnails * feat(plan): add plan report storage * feat(plan): add public visual plan reporting action * feat(recap): sync themed thumbnails across workflows * docs(visual-plans): sync bundled standalone guidance * feat(plan): expose visual plan report mutation * docs(recap): describe theme-aware PR thumbnails * chore: add changeset for theme-aware recap screenshots * feat(plan): add public report controls * test(plan): cover public visual plan reporting * fix(plan): denylist moderation reports from raw db tools * fix(recap): sync visual plan marketplace and formatting * fix(auth): serialize auto dev account creation * chore: add changeset for auto dev account race * fix(plan): sync visual plan template skill
1 parent 17f3eae commit ee66e0a

45 files changed

Lines changed: 1574 additions & 214 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/plugins/agent-native-visual-plans/.codex-plugin/plugin.json‎

Lines changed: 1 addition & 1 deletion

‎.agents/plugins/agent-native-visual-plans/skills/visual-plan/SKILL.md‎

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -57,10 +57,13 @@ plan needs a richer review surface.
5757
even if most of the feature ships later. Then scope to the smallest first cut that
5858
proves the approach without foreclosing it, stating both what is in and what is
5959
explicitly deferred.
60-
- **Preserve existing plans.** If the user pasted, referenced, or already has a
61-
Codex / Claude Code / Markdown plan, treat it as source material. Preserve its
62-
intent, do not invent codebase facts, label inferred visuals as inferred, and
63-
build the visual review structure around the plan the user already has.
60+
- **Publish standalone plans.** If the user pasted, referenced, or already has a
61+
Codex / Claude Code / Markdown plan, treat it as source material, but rewrite
62+
the published plan as a clean standalone proposal. Preserve the source plan's
63+
useful intent and codebase facts, label inferred visuals as inferred, and avoid
64+
revision language such as "preserve the prior plan", "do not drop the old
65+
idea", "unlike the previous version", or "this revision changes...". A reader
66+
who never saw the chat or earlier drafts should understand the plan.
6467
- **Planning is read-only.** Make no source edits while building or reviewing the
6568
plan. Start editing only after the user approves the direction.
6669
- **Clarify vs. assume.** Do not ask how to build it — explore and present the
@@ -77,7 +80,9 @@ plan needs a richer review surface.
7780
separate "does this look good?" question.
7881
- **The document is the source of truth, not the chat.** When scope shifts,
7982
update the plan with `update-visual-plan` rather than only changing course in
80-
chat, and re-read the approved plan before major steps.
83+
chat, and make the updated document stand alone. Do not describe the update as
84+
a correction to an earlier draft inside the plan itself. Re-read the approved
85+
plan before major steps.
8186

8287
## Always Publish As An Agent-Native Plan — Never Inline
8388

@@ -111,14 +116,16 @@ exception.
111116
for prototype-first plans, `create-plan-design` for design-first plans,
112117
`create-visual-questions` only when the user explicitly asks for a visual
113118
intake questionnaire. When a source plan already exists,
114-
pass it as `planText` and preserve the original plan's intent while adding
115-
structured review content.
119+
pass it as `planText` and preserve the original plan's useful intent while
120+
producing a standalone plan document, not a revision memo.
116121
3. Compose or enrich any top UI/product visual surface and write the document
117122
with native blocks (see `references/canvas.md` and
118-
`references/document-quality.md`). Keep the document close to the Markdown
119-
plan the agent would normally output, or to the existing plan when one was
120-
provided. For non-visual plans, skip the top visual surface (Visual Surface
121-
Choice below owns the rule) and put `diagram`, `data-model`,
123+
`references/document-quality.md`). Keep the document close to the standalone
124+
Markdown plan the agent would normally output. If an existing plan was
125+
provided, carry forward the right facts and decisions without referring to
126+
the previous draft or explaining how this version differs. For non-visual
127+
plans, skip the top visual surface (Visual Surface Choice below owns the rule)
128+
and put `diagram`, `data-model`,
122129
`api-endpoint`, `diff`, `file-tree`, `code`, and `annotated-code` blocks
123130
directly next to the relevant prose.
124131
4. Surface the returned Plans link or inline MCP App and ask the user to review.

‎.agents/plugins/agent-native-visual-plans/skills/visual-plan/references/document-quality.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,14 @@ behavior). Replace vague prose with specifics; never ship a step like "make it
1818
work." No hero art, gradients, logos, nav bars, slogans, value props, giant
1919
landing-page headings, or marketing cards unless the user explicitly asks.
2020

21+
**Every published plan must stand alone.** Even when the agent is revising an
22+
existing plan, the output is a plan to do the work, not a changelog of the
23+
conversation. Do not write phrases like "preserve the previous plan", "do not
24+
drop the old idea", "as discussed above", "this revision", "unlike the prior
25+
version", or "correction from the earlier plan". Fold the right decisions into
26+
the plan as normal objective, architecture, scope, and roadmap prose. A reviewer
27+
who opens the plan from a link with no chat history should understand it.
28+
2129
**When top visuals exist, they and the document never duplicate each other.**
2230
For UI work, the UI story lives in the top visual surface: canvas artboards for
2331
static inspection, plus prototype tabs when the flow should be functional. The

‎.changeset/auto-dev-account-race.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@agent-native/core": patch
3+
---
4+
5+
Serialize local auto dev account creation so concurrent first-page requests do not race into duplicate Better Auth user inserts.

‎.changeset/floating-ui-peer.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@agent-native/core": patch
3+
---
4+
5+
Declare the Floating UI DOM runtime dependency required by TipTap floating menu support.

‎.changeset/github-recap-picture-screenshots.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@agent-native/core": patch
3+
---
4+
5+
Capture PR Visual Recap screenshots in GitHub-matched light and dark modes and embed them with a theme-aware picture element.

‎.changeset/pr-visual-recap-full-catalog.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@agent-native/core": patch
3+
---
4+
5+
Ensure PR visual recap agents request the full Plan MCP catalog and refresh stale Codex MCP config before publishing recaps.

‎.changeset/visual-recap-link-access.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@agent-native/core": patch
3+
---
4+
5+
Fix PR visual recap comments and hosted recap links so failed runs no longer advertise stale private recap URLs, and public `/recaps/:id` links resolve for signed-out viewers.

‎.github/workflows/pr-visual-recap-fork.yml‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -527,17 +527,23 @@ jobs:
527527
run: |
528528
set -uo pipefail
529529
pnpm exec playwright install --with-deps chromium 2>/dev/null || npx -y playwright@1 install --with-deps chromium || true
530-
SHOT_JSON="$($RECAP_CLI recap shot --url "$PLAN_URL" --token "$PLAN_RECAP_TOKEN" --app-url "$PLAN_RECAP_APP_URL" --out recap.png || echo '{}')"
531-
IMAGE_URL=$(node -e 'try{process.stdout.write(JSON.parse(process.argv[1]).imageUrl||"")}catch{process.stdout.write("")}' "$SHOT_JSON")
530+
LIGHT_SHOT_JSON="$($RECAP_CLI recap shot --url "$PLAN_URL" --token "$PLAN_RECAP_TOKEN" --app-url "$PLAN_RECAP_APP_URL" --out recap.png --theme light || echo '{}')"
531+
DARK_SHOT_JSON="$($RECAP_CLI recap shot --url "$PLAN_URL" --token "$PLAN_RECAP_TOKEN" --app-url "$PLAN_RECAP_APP_URL" --out recap-dark.png --theme dark || echo '{}')"
532+
IMAGE_URL=$(node -e 'try{process.stdout.write(JSON.parse(process.argv[1]).imageUrl||"")}catch{process.stdout.write("")}' "$LIGHT_SHOT_JSON")
533+
DARK_IMAGE_URL=$(node -e 'try{process.stdout.write(JSON.parse(process.argv[1]).imageUrl||"")}catch{process.stdout.write("")}' "$DARK_SHOT_JSON")
532534
echo "image_url=$IMAGE_URL" >> "$GITHUB_OUTPUT"
533-
if [ -f recap.png ]; then echo "captured=true" >> "$GITHUB_OUTPUT"; else echo "captured=false" >> "$GITHUB_OUTPUT"; fi
535+
echo "light_image_url=$IMAGE_URL" >> "$GITHUB_OUTPUT"
536+
echo "dark_image_url=$DARK_IMAGE_URL" >> "$GITHUB_OUTPUT"
537+
if [ -f recap.png ] || [ -f recap-dark.png ]; then echo "captured=true" >> "$GITHUB_OUTPUT"; else echo "captured=false" >> "$GITHUB_OUTPUT"; fi
534538
535539
- name: Upload recap screenshot artifact
536540
if: steps.shot.outputs.captured == 'true'
537541
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
538542
with:
539543
name: pr-visual-recap-fork-${{ github.event.pull_request.number }}
540-
path: recap.png
544+
path: |
545+
recap.png
546+
recap-dark.png
541547
if-no-files-found: ignore
542548
retention-days: 14
543549

@@ -547,6 +553,8 @@ jobs:
547553
env:
548554
PLAN_URL: ${{ steps.url.outputs.plan_url }}
549555
RECAP_IMAGE_URL: ${{ steps.shot.outputs.image_url }}
556+
RECAP_LIGHT_IMAGE_URL: ${{ steps.shot.outputs.light_image_url }}
557+
RECAP_DARK_IMAGE_URL: ${{ steps.shot.outputs.dark_image_url }}
550558
SUPPRESSED: ${{ steps.scan.outputs.suppressed }}
551559
SUPPRESSED_JSON: ${{ steps.scan.outputs.json }}
552560
DIFF_HUGE: ${{ steps.diff.outputs.huge }}

‎.github/workflows/pr-visual-recap-reusable.yml‎

Lines changed: 15 additions & 7 deletions

0 commit comments

Comments
 (0)