Publish Rewind with complete local setup by 3mdistal · Pull Request #2345 · BuilderIO/agent-native

3mdistal · 2026-07-23T12:00:26Z

Problem

Rewind is a local screen-memory capability in Clips Desktop, not a standalone prompt. An agent needs both the Rewind instructions and a local Model Context Protocol (MCP) connection to Clips. The public skills installer previously treated Rewind like an ordinary copied skill, which could leave users with instructions that referenced tools their agent could not call.

First-time users also need a safe path to install Clips. Because Clips can capture screen and audio, an agent must not silently install the app, approve macOS permissions, enable capture, or claim setup succeeded without checking the real local connection.

Approach

Keep Agent Native as the single source of truth for Rewind's instructions, privacy boundaries, and local connection setup. The public BuilderIO/skills repository receives an exact generated copy for discovery, while both advertised Agent Native installers converge on Core's fail-closed setup flow.

The skill may offer to open the official Clips download page after the user agrees. Native installation, Gatekeeper approval, macOS capture permissions, and enabling Rewind remain human-controlled. Setup is complete only when the local Screen Memory store exists, the skill and MCP configuration are installed together, and screen_memory_status succeeds.

What changed

Export the canonical Rewind skill so BuilderIO/skills can mirror it without maintaining a second copy by hand.
Delegate @agent-native/skills add --skill rewind to Core's complete local Screen Memory installer.
Reject --no-mcp, remote MCP URLs, and missing-store setup before writing either the skill or agent configuration.
Add consent-gated first-run guidance for installing Clips Desktop and repairing the local connection.
Cover Codex, Claude Code, and Cursor configuration paths.
Notify the public catalog through both the legacy and new sync events during the companion-repository transition. The legacy event is sent first so either merge order remains safe.

Safety and operations

Rewind remains disabled by default. This change does not install Clips, grant macOS permissions, enable capture, inspect app-data folders, or upload local screen-memory media.
A failed preflight leaves no prose-only skill or partial MCP configuration behind.
There are no schema migrations, backfills, credential changes, or destructive data operations.
The public mirror is generated one way from Agent Native; its human README remains a public-repository overlay.
Rolling back these package changes restores the previous installer behavior but does not alter any existing Clips capture data or settings.

Verification

Passed: 69 focused Core skill tests proved atomic Codex installation, missing-store and --no-mcp rejection, consent guidance, and Cursor/Claude Code configuration.
Passed: 34 standalone installer tests and the @agent-native/skills typecheck proved Rewind delegates to Core and preserves CLI arguments and errors.
Passed: the canonical/public equality check proved the generated Rewind SKILL.md matches its Agent Native source.
Passed: all required checks on head 57e81e745—Build, Typecheck, Fast tests, Core integration, Content DB/parity, Plan E2E, and lint/format.
Passed: independent technical review, including the preflight write-order fix and the dual-event transition. The final automated review reports no remaining issue.
Skipped with reason: Framework Compute was unavailable because its remote Mac was offline; fresh GitHub CI supplied the composed build and typecheck evidence instead.
Blocked: the frozen clean-profile macOS journey could not run because the available Mac already has Clips installed, no branch-built signed Clips artifact was available, and the branch CLI source fallback exited with spawn tsx ENOENT. H1–H10 must still be rerun with a clean profile and runnable branch-built CLI before merge. Existing Clips state, permissions, configuration, and Screen Memory data were not touched.

Review focus

Does every Rewind installer either produce the skill and local MCP connection together or fail before writing either one?
Are the native-app, Gatekeeper, permission, and capture-enablement boundaries explicit enough that an agent cannot mistake guidance for consent?
Does the generated-mirror contract keep Agent Native canonical while preserving the public README overlay?
Does dual dispatch make either companion-PR merge order safe without accepting untrusted repository input?

Companion PR

Public catalog and documentation: BuilderIO/skills#54

github-actions · 2026-07-23T12:05:41Z

Here's a visual recap of what changed:

Open the full interactive recap

builder-io-integration · 2026-07-23T12:12:39Z

⚠️ Review Agent ran into a problem and couldn't finish reviewing the latest commit.

We've been automatically notified and are looking into it. Push a new commit to re-trigger the review, or contact support@builder.io if this keeps happening.

Error ID: 69c68efb9173487194670e1e0fb6dabe

…kill-sync

builder-io-integration

Builder reviewed your changes and found 1 potential issue 🟡

Review Details

Incremental Code Review Summary

PR #2345 updates the Rewind public-skill publication flow and keeps the installer centered on Core's local Clips Screen Memory setup. The latest code preserves the useful fail-closed behavior: Rewind rejects disconnected MCP modes, checks for the local store before writing skill or agent configuration, and documents explicit user consent for opening Clips and enabling capture. The CLI delegation and client-specific coverage remain sound.

This is a standard-risk change because it alters shared CLI installation behavior and cross-repository synchronization. One new integration issue was confirmed in the latest state: the producer now emits agent-native-public-skills-updated, but the current BuilderIO/skills repository only declares a repository_dispatch listener for agent-native-plan-skills-updated. GitHub accepts the dispatch successfully even when no workflow handles it, so the new event can silently fail to mirror Rewind unless the companion listener is landed or the event is changed to one the receiver handles.

✅ Good patterns: preflight-before-write ordering, explicit privacy and native-permission boundaries, canonical Core ownership of MCP setup, and tests covering the new failure paths.

🧪 Browser testing: Skipped — PR only modifies CLI logic, skill content, tests, workflow configuration, and release metadata; it has no user-facing browser impact.

builder-io-integration · 2026-07-24T04:14:14Z

            -f "client_payload[sourceSha]=${{ github.sha }}" \
            -f "client_payload[sourceRunUrl]=${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+
+          gh api repos/BuilderIO/skills/dispatches \


🟡 Dispatch target has no listener for the new public-skill event

The added agent-native-public-skills-updated dispatch is currently a no-op: the current BuilderIO/skills repository only declares a repository_dispatch listener for agent-native-plan-skills-updated. GitHub accepts repository-dispatch event names without a matching workflow, so this step succeeds while never mirroring Rewind. Add or land the corresponding downstream listener and sync logic before emitting this event, or dispatch an event that an existing receiver handles.

Additional Info

Verified against the current BuilderIO/skills default branch via GitHub API: only ci.yml and update-agent-native-plan-skills.yml exist, and the latter listens only for agent-native-plan-skills-updated.

…kill-sync

builder-io-integration

Builder reviewed your changes and found 1 potential issue 🟡

Review Details

Incremental Code Review Summary

The latest commit adds lazy installation-ID creation to both CLI telemetry implementations so failed Rewind preflights do not create telemetry state merely by constructing a telemetry client. The change also adds coverage for that behavior, while the existing Rewind installer and public synchronization changes remain otherwise unchanged. The unresolved public dispatch comment was intentionally not reposted.

This is a standard-risk change because the PR modifies shared CLI routing, telemetry initialization, and local MCP installation semantics. One new medium-severity issue remains: the Rewind preflight exits early for --no-mcp and --mcp-url, so a multi-skill invocation can install an earlier skill before Rewind reaches its incompatible-flag rejection. That violates the stated fail-before-writes guarantee for invalid multi-selection requests.

✅ Good patterns: lazy telemetry initialization avoids unnecessary local state on failed commands, the new test directly verifies no installation ID is created, and focused Core/skills test suites pass.

🧪 Browser testing: Skipped — PR only modifies CLI logic, skill content, tests, workflow configuration, and release metadata; it has no user-facing browser impact.

builder-io-integration · 2026-07-24T16:43:02Z

+  if (
+    parsed.command !== "add" ||
+    parsed.dryRun ||
+    !parsed.mcp ||
+    parsed.mcpUrl
+  ) {
+    return undefined;
+  }


🟡 Preflight Rewind when its required MCP is disabled

runSkills() uses this preflight before iterating selected targets, but the guard returns for --no-mcp and --mcp-url. A multi-skill invocation such as skills add --skill assets --skill rewind --no-mcp --client codex --yes can therefore install Assets first, then reach Rewind's incompatible-flag rejection and fail after writing files. Check Rewind selection and reject incompatible flags in the early preflight before target iteration.

Additional Info

The existing direct Rewind checks in addAgentNativeSkill occur after target routing and cannot protect earlier selections in a multi-skill invocation.

builder-io-integration

Builder reviewed your changes and found 2 potential issues 🟡

Review Details

Incremental Code Review Summary

The latest commit adds rollback snapshots around Rewind’s skill/configuration writes and restores prior files when MCP setup fails. The rollback path is covered for Codex and Claude Code, and the existing open comments were respected: the public dispatch issue and the --no-mcp preflight comment were not reposted or resolved.

This remains a standard-risk change because it affects shared CLI installation, telemetry, and local MCP configuration. Two new medium-severity issues remain: supported Rewind aliases are not consistently recognized by telemetry routing, and the standalone skills package delegates only the literal rewind name. As a result, equivalent aliases can create telemetry before preflight or trigger an unnecessary public-catalog fetch before Core performs local setup.

✅ Good patterns: snapshot/restore is scoped to Rewind paths, rollback is attempted on MCP failures, existing files are restored in tests, and successful Rewind completion telemetry is delayed until MCP registration succeeds.

🧪 Browser testing: Skipped — PR only modifies CLI logic, telemetry, skill content, tests, workflow configuration, and release metadata; it has no user-facing browser impact.

builder-io-integration · 2026-07-24T16:54:42Z

+  const explicitlyTargetsRewind = args.some(
+    (arg, index) =>
+      arg === "rewind" ||


🟡 Defer Rewind telemetry for all supported aliases

skills.ts recognizes screen-memory, clips-rewind, and agent-native-rewind as Rewind aliases, and preflightRewindStore normalizes them before rejecting an unavailable local store. This routing check only recognizes the literal rewind, so agent-native skills add screen-memory ... executes cli.run tracking before preflight; createCliTelemetry.track() can create ~/.agent-native/installation-id and send telemetry for an equivalent failed Rewind install. Normalize the positional and --skill values through the same alias mapping or cover all supported aliases.

Additional Info

Confirmed against BUILT_IN_APP_SKILL_ALIASES in packages/core/src/cli/skills.ts and the new preflight path.

builder-io-integration · 2026-07-24T16:54:42Z

+function isCoreDelegatedSkill(skillName: string): boolean {
+  // Rewind uses Core's local Screen Memory installer, not the standalone
+  // package's hosted MCP descriptor path.
+  return skillName === "rewind" || Boolean(resolveAppForSkill(skillName));


🟡 Recognize Rewind aliases when delegating standalone installs

Core accepts screen-memory, clips-rewind, and agent-native-rewind as Rewind aliases, but the standalone installer only treats the literal rewind as core-delegated here. @agent-native/skills add screen-memory ... can therefore materialize/fetch the public BuilderIO/skills catalog before Core is invoked, making the supported alias depend on an unrelated network operation and potentially fail offline before local-store preflight. Share Core’s alias normalization or maintain the complete alias set, with delegation coverage for each alias.

Additional Info

Confirmed against BUILT_IN_APP_SKILL_ALIASES in packages/core/src/cli/skills.ts; isCoreDelegatedSkill currently checks only skillName === "rewind".

3mdistal added 3 commits July 23, 2026 07:09

Sync Rewind into the public skills catalog

f2c1c2a

Guide Rewind users through Clips setup

6cab953

Preflight Rewind before writing skill files

706ef11

This comment has been minimized.

Sign in to view

3mdistal mentioned this pull request Jul 23, 2026

Add Rewind to the public skills catalog BuilderIO/skills#54

Merged

This comment has been minimized.

Sign in to view

This comment was marked as outdated.

Sign in to view

Keep legacy skill sync dispatch during transition

82c5542

This comment has been minimized.

Sign in to view

Prioritize legacy skill sync dispatch

57e81e7

This comment has been minimized.

Sign in to view

This comment was marked as outdated.

Sign in to view

3mdistal changed the title ~~Publish Rewind through the public skills catalog~~ Publish Rewind with complete local setup Jul 23, 2026

3mdistal requested a review from steve8708 July 23, 2026 15:52

steve8708 approved these changes Jul 23, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into codex/rewind-public-s…

6d2bfe7

…kill-sync

builder-io-integration Bot reviewed Jul 24, 2026

View reviewed changes

3mdistal added 2 commits July 24, 2026 00:17

fix(cli): reject Rewind before local writes

7531abd

fix(cli): preflight Rewind skill flags

33f710b

This comment has been minimized.

Sign in to view

This comment was marked as outdated.

Sign in to view

3mdistal added 3 commits July 24, 2026 12:30

Merge remote-tracking branch 'origin/main' into codex/rewind-public-s…

c693ed5

…kill-sync

test: preserve rewind preflight telemetry invariant

456514b

fix: defer cli identity writes until telemetry events

5ccceac

This comment was marked as outdated.

Sign in to view

fix: preflight rewind before cli telemetry

e95ad07

builder-io-integration Bot reviewed Jul 24, 2026

View reviewed changes

fix: roll back partial rewind setup

e961c31

builder-io-integration Bot reviewed Jul 24, 2026

View reviewed changes

Uh oh!

Conversation

3mdistal commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Approach

What changed

Safety and operations

Verification

Review focus

Companion PR

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

github-actions Bot commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

builder-io-integration Bot commented Jul 23, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment was marked as outdated.

Uh oh!

builder-io-integration Bot left a comment

Choose a reason for hiding this comment

Incremental Code Review Summary

Uh oh!

builder-io-integration Bot Jul 24, 2026

Choose a reason for hiding this comment

🟡 Dispatch target has no listener for the new public-skill event

Uh oh!

This comment has been minimized.

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

builder-io-integration Bot left a comment

Choose a reason for hiding this comment

Incremental Code Review Summary

Uh oh!

builder-io-integration Bot Jul 24, 2026

Choose a reason for hiding this comment

🟡 Preflight Rewind when its required MCP is disabled

Uh oh!

builder-io-integration Bot left a comment

Choose a reason for hiding this comment

Incremental Code Review Summary

Uh oh!

builder-io-integration Bot Jul 24, 2026

Choose a reason for hiding this comment

🟡 Defer Rewind telemetry for all supported aliases

Uh oh!

builder-io-integration Bot Jul 24, 2026

Choose a reason for hiding this comment

🟡 Recognize Rewind aliases when delegating standalone installs

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

3mdistal commented Jul 23, 2026 •

edited

Loading

github-actions Bot commented Jul 23, 2026 •

edited

Loading