diff options
| author | Drew Ritter <drew@primeradiant.com> | 2026-05-08 15:52:38 -0700 |
|---|---|---|
| committer | Drew Ritter <drew@primeradiant.com> | 2026-05-27 16:22:48 -0700 |
| commit | 63101959b52594edb2eabedddbf75b6e23c45152 (patch) | |
| tree | fba5c6dc61e504d6719fe9843484a5883fb521de /docs/superpowers | |
| parent | 8811b0f2d77da52c4552f0fdf48c0af0dcec83f2 (diff) | |
feat: add Alpine visual companion mockupscodex/explore-interactive-prototypes
Diffstat (limited to 'docs/superpowers')
| -rw-r--r-- | docs/superpowers/plans/2026-05-08-visual-companion-alpine.md | 989 | ||||
| -rw-r--r-- | docs/superpowers/specs/2026-05-08-visual-companion-alpine-design.md | 465 |
2 files changed, 1454 insertions, 0 deletions
diff --git a/docs/superpowers/plans/2026-05-08-visual-companion-alpine.md b/docs/superpowers/plans/2026-05-08-visual-companion-alpine.md new file mode 100644 index 0000000..9785f70 --- /dev/null +++ b/docs/superpowers/plans/2026-05-08-visual-companion-alpine.md @@ -0,0 +1,989 @@ +# Visual Companion Alpine Support Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Add Alpine-backed interactivity to the existing visual companion screen path without adding a second artifact/prototype system. + +**Architecture:** Vendor one pinned Alpine 3.x browser artifact in the brainstorming skill runtime, serve it from a narrow localhost route, and load it from the existing frame template for fragment screens only. Keep the current helper/event model intact, update authoring guidance so agents use Alpine sparingly, and require evidence that the new guidance changes behavior. + +**Tech Stack:** Node.js HTTP server, plain HTML/CSS/JavaScript, vendored Alpine.js 3.15.12, shell sync tests, Superpowers skill docs. + +--- + +## Source Material + +- Spec: `docs/superpowers/specs/2026-05-08-visual-companion-alpine-design.md` +- Linear: `SUP-215` +- Current branch: `codex/explore-interactive-prototypes` +- Verified Alpine package metadata on 2026-05-08: + - Version: `3.15.12` + - Tarball: `https://registry.npmjs.org/alpinejs/-/alpinejs-3.15.12.tgz` + - npm integrity: `sha512-nJvPAQVNPdZZ0NrExJ/kzQco3ijR8LwvCOadQecllESiqT4NyZ/57sN9V2XyvhlBGAbmlKYgeWZvYdKq99ij/Q==` + - Vendored file inside tarball: `package/dist/cdn.min.js` + - SHA256 of `package/dist/cdn.min.js`: `57b37d7cae9a27d965fdae4adcc844245dfdc407e655aee85dcfff3a08036a3f` + - License: MIT + - Approval artifact: `SUP-215` + +## File Structure + +- Create: `skills/brainstorming/scripts/vendor/alpine.js` + - Exact copy of Alpine `package/dist/cdn.min.js` from the pinned npm tarball. +- Create: `skills/brainstorming/scripts/vendor/alpine.provenance.json` + - Machine-readable source URL, package version, vendored path, SHA256, approval artifact, and vendoring date. +- Create: `skills/brainstorming/scripts/vendor/THIRD_PARTY_NOTICES.md` + - Human-readable Alpine license notice and refresh command. +- Modify: `skills/brainstorming/scripts/server.cjs` + - Add parsed-path vendor serving for `/vendor/alpine.js`. +- Modify: `skills/brainstorming/scripts/frame-template.html` + - Load Alpine for frame-wrapped fragments and neutralize the footer copy. +- Modify: `tests/brainstorm-server/server.test.js` + - Cover provenance, vendor route behavior, helper injection, frame injection, and full-document/waiting-page boundaries. +- Modify: `skills/brainstorming/visual-companion.md` + - Update agent-facing guidance from selection-first/static mockups to compact Alpine-backed interactive mockups. +- Modify: `scripts/sync-to-codex-plugin.sh` + - Surface vendored Alpine provenance in generated Codex plugin sync PR bodies. +- Modify: `tests/codex-plugin-sync/test-sync-to-codex-plugin.sh` + - Ensure nested skill-local scripts and vendor files survive root `/scripts/` exclusion and generated PR-body source includes the vendored dependency note. + +## Task 1: Vendor Alpine and Add Provenance Tests + +**Files:** +- Create: `skills/brainstorming/scripts/vendor/alpine.js` +- Create: `skills/brainstorming/scripts/vendor/alpine.provenance.json` +- Create: `skills/brainstorming/scripts/vendor/THIRD_PARTY_NOTICES.md` +- Modify: `tests/brainstorm-server/server.test.js` + +- [ ] **Step 1: Write the failing provenance test** + +Add this import alongside the existing `require` block: + +```js +const crypto = require('crypto'); +``` + +Add these constants near the existing `SERVER_PATH`, `TEST_PORT`, and directory constants in `tests/brainstorm-server/server.test.js`: + +```js +const ALPINE_PATH = path.join(__dirname, '../../skills/brainstorming/scripts/vendor/alpine.js'); +const ALPINE_PROVENANCE_PATH = path.join(__dirname, '../../skills/brainstorming/scripts/vendor/alpine.provenance.json'); +const ALPINE_NOTICES_PATH = path.join(__dirname, '../../skills/brainstorming/scripts/vendor/THIRD_PARTY_NOTICES.md'); +``` + +Add this helper below `fetch(url)`: + +```js +function sha256File(filePath) { + return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex'); +} +``` + +Add this test block at the start of `runTests()`, before `// ========== Server Startup ==========`: + +```js + // ========== Vendored Alpine ========== + console.log('\n--- Vendored Alpine ---'); + + await test('vendored Alpine provenance is complete and matches artifact hash', () => { + assert(fs.existsSync(ALPINE_PATH), 'alpine.js should exist'); + assert(fs.existsSync(ALPINE_PROVENANCE_PATH), 'alpine.provenance.json should exist'); + assert(fs.existsSync(ALPINE_NOTICES_PATH), 'THIRD_PARTY_NOTICES.md should exist'); + + const provenance = JSON.parse(fs.readFileSync(ALPINE_PROVENANCE_PATH, 'utf-8')); + assert.strictEqual(provenance.name, 'alpinejs'); + assert.strictEqual(provenance.version, '3.15.12'); + assert.strictEqual(provenance.license, 'MIT'); + assert.strictEqual(provenance.sourceUrl, 'https://registry.npmjs.org/alpinejs/-/alpinejs-3.15.12.tgz'); + assert.strictEqual(provenance.sourcePackagePath, 'package/dist/cdn.min.js'); + assert.strictEqual(provenance.localPath, 'skills/brainstorming/scripts/vendor/alpine.js'); + assert.strictEqual(provenance.sha256, '57b37d7cae9a27d965fdae4adcc844245dfdc407e655aee85dcfff3a08036a3f'); + assert.strictEqual(provenance.approvalArtifact, 'SUP-215'); + assert.strictEqual(sha256File(ALPINE_PATH), provenance.sha256); + + const notices = fs.readFileSync(ALPINE_NOTICES_PATH, 'utf-8'); + assert(notices.includes('Alpine.js'), 'Notice should name Alpine.js'); + assert(notices.includes('MIT License'), 'Notice should include MIT license text'); + assert(notices.includes('curl -fsSL https://registry.npmjs.org/alpinejs/-/alpinejs-3.15.12.tgz'), 'Notice should include refresh command'); + return Promise.resolve(); + }); +``` + +- [ ] **Step 2: Run the failing test** + +Run: + +```bash +cd "$(git rev-parse --show-toplevel)" +node tests/brainstorm-server/server.test.js +``` + +Expected: FAIL with `alpine.js should exist`. + +- [ ] **Step 3: Vendor Alpine from the pinned npm tarball** + +Run: + +```bash +cd /Users/drewritter/prime-rad/superpowers +mkdir -p skills/brainstorming/scripts/vendor +tmpdir="$(mktemp -d)" +curl -fsSL https://registry.npmjs.org/alpinejs/-/alpinejs-3.15.12.tgz -o "$tmpdir/alpinejs-3.15.12.tgz" +tar -xzf "$tmpdir/alpinejs-3.15.12.tgz" -C "$tmpdir" package/dist/cdn.min.js +cp "$tmpdir/package/dist/cdn.min.js" skills/brainstorming/scripts/vendor/alpine.js +rm -rf "$tmpdir" +shasum -a 256 skills/brainstorming/scripts/vendor/alpine.js +``` + +Expected SHA256: + +```text +57b37d7cae9a27d965fdae4adcc844245dfdc407e655aee85dcfff3a08036a3f +``` + +- [ ] **Step 4: Create provenance metadata** + +Create `skills/brainstorming/scripts/vendor/alpine.provenance.json` with this exact JSON: + +```json +{ + "name": "alpinejs", + "version": "3.15.12", + "license": "MIT", + "sourceUrl": "https://registry.npmjs.org/alpinejs/-/alpinejs-3.15.12.tgz", + "sourcePackagePath": "package/dist/cdn.min.js", + "localPath": "skills/brainstorming/scripts/vendor/alpine.js", + "npmIntegrity": "sha512-nJvPAQVNPdZZ0NrExJ/kzQco3ijR8LwvCOadQecllESiqT4NyZ/57sN9V2XyvhlBGAbmlKYgeWZvYdKq99ij/Q==", + "sha256": "57b37d7cae9a27d965fdae4adcc844245dfdc407e655aee85dcfff3a08036a3f", + "approvalArtifact": "SUP-215", + "vendoredAt": "2026-05-08" +} +``` + +Create `skills/brainstorming/scripts/vendor/THIRD_PARTY_NOTICES.md` with: + +````markdown +# Third-Party Notices + +## Alpine.js + +- Package: `alpinejs` +- Version: `3.15.12` +- Source: `https://registry.npmjs.org/alpinejs/-/alpinejs-3.15.12.tgz` +- Vendored file: `package/dist/cdn.min.js` +- Local path: `skills/brainstorming/scripts/vendor/alpine.js` +- SHA256: `57b37d7cae9a27d965fdae4adcc844245dfdc407e655aee85dcfff3a08036a3f` + +Refresh command: + +```bash +cd "$(git rev-parse --show-toplevel)" +tmpdir="$(mktemp -d)" +curl -fsSL https://registry.npmjs.org/alpinejs/-/alpinejs-3.15.12.tgz -o "$tmpdir/alpinejs-3.15.12.tgz" +tar -xzf "$tmpdir/alpinejs-3.15.12.tgz" -C "$tmpdir" package/dist/cdn.min.js +cp "$tmpdir/package/dist/cdn.min.js" skills/brainstorming/scripts/vendor/alpine.js +shasum -a 256 skills/brainstorming/scripts/vendor/alpine.js +rm -rf "$tmpdir" +``` + +License: + +```text +MIT License + +Copyright © 2019-2025 Caleb Porzio and contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +``` +```` + +- [ ] **Step 5: Run the provenance test** + +Run: + +```bash +cd /Users/drewritter/prime-rad/superpowers +node tests/brainstorm-server/server.test.js +``` + +Expected: the vendored Alpine provenance test passes. Later HTTP tests may still fail until Task 2 if they have already been added; do not commit until this command exits 0 after Task 2. + +- [ ] **Step 6: Commit Task 1** + +After Task 2 also passes the full server test, commit Task 1 and Task 2 together. The vendored file and server route are one behavioral unit. + +## Task 2: Serve Alpine and Inject It Into Frame-Wrapped Fragments + +**Files:** +- Modify: `skills/brainstorming/scripts/server.cjs` +- Modify: `skills/brainstorming/scripts/frame-template.html` +- Modify: `tests/brainstorm-server/server.test.js` + +- [ ] **Step 1: Add failing HTTP and injection tests** + +Add this test after `returns Content-Type text/html`: + +```js + await test('waiting page does not inject Alpine', async () => { + const res = await fetch(`http://localhost:${TEST_PORT}/`); + assert(!res.body.includes('/vendor/alpine.js'), 'Waiting page should not inject Alpine'); + }); +``` + +Add these tests after `returns 404 for non-root paths`: + +```js + await test('serves vendored Alpine from exact vendor route', async () => { + const res = await fetch(`http://localhost:${TEST_PORT}/vendor/alpine.js`); + assert.strictEqual(res.status, 200); + assert(res.headers['content-type'].includes('application/javascript'), 'Should be JavaScript'); + assert(res.body.includes('Alpine'), 'Should serve Alpine script content'); + }); + + await test('serves vendored Alpine when query string is present', async () => { + const res = await fetch(`http://localhost:${TEST_PORT}/vendor/alpine.js?v=3.15.12`); + assert.strictEqual(res.status, 200); + assert(res.body.includes('Alpine'), 'Should ignore query string for exact vendor pathname'); + }); + + await test('exact-match vendor route rejects non-allowlisted pathnames', async () => { + const paths = [ + '/vendor/unknown.js', + '/vendor/alpine.js/extra', + '/vendor/../alpine.js', + '/vendor/%2e%2e/alpine.js', + '/vendor/%2E%2E/alpine.js' + ]; + + for (const requestPath of paths) { + const res = await fetch(`http://localhost:${TEST_PORT}${requestPath}`); + assert.strictEqual(res.status, 404, `${requestPath} should 404`); + } + }); +``` + +This test should assert the actual defense: the route is an exact parsed-pathname +allowlist. Do not describe `/vendor/../alpine.js` as proving filesystem +canonicalization, because the URL parser normalizes that request before the +vendor allowlist sees it. + +Update `serves full HTML documents as-is (not wrapped)` with this assertion: + +```js + assert(!res.body.includes('/vendor/alpine.js'), 'Should NOT inject Alpine into full documents'); +``` + +Update `wraps content fragments in frame template` with these assertions: + +```js + assert(res.body.includes('<script defer src="/vendor/alpine.js"></script>'), 'Fragment should load Alpine'); + assert(res.body.includes('Interact with the mockup, then return to the terminal'), 'Frame copy should be neutral'); +``` + +Add this test after `wraps content fragments in frame template`: + +```js + await test('preserves Alpine attributes in frame-wrapped fragments', async () => { + const fragment = '<div x-data="{ open: false }"><button @click="open = !open">Toggle</button><div x-show="open">Details</div></div>'; + fs.writeFileSync(path.join(CONTENT_DIR, 'alpine-fragment.html'), fragment); + await sleep(300); + + const res = await fetch(`http://localhost:${TEST_PORT}/`); + assert(res.body.includes('x-data="{ open: false }"'), 'Should preserve x-data'); + assert(res.body.includes('@click="open = !open"'), 'Should preserve @click'); + assert(res.body.includes('x-show="open"'), 'Should preserve x-show'); + assert(res.body.includes('/vendor/alpine.js'), 'Should include Alpine script'); + }); +``` + +- [ ] **Step 2: Run the failing tests** + +Run: + +```bash +cd /Users/drewritter/prime-rad/superpowers +node tests/brainstorm-server/server.test.js +``` + +Expected: FAIL because `/vendor/alpine.js` returns 404 and the frame does not include Alpine yet. + +- [ ] **Step 3: Implement exact vendor serving** + +In `skills/brainstorming/scripts/server.cjs`, add these constants after `helperInjection`: + +```js +const ALPINE_VENDOR_PATH = path.join(__dirname, 'vendor', 'alpine.js'); + +function loadVendorFile(filePath, name) { + try { + return fs.readFileSync(filePath); + } catch (error) { + throw new Error( + `Failed to load vendored ${name} at ${filePath}; ` + + 'run the refresh command in skills/brainstorming/scripts/vendor/THIRD_PARTY_NOTICES.md. ' + + error.message + ); + } +} + +const VENDOR_FILES = new Map([ + ['/vendor/alpine.js', { + content: loadVendorFile(ALPINE_VENDOR_PATH, 'Alpine'), + contentType: 'application/javascript; charset=utf-8' + }] +]); +``` + +Add these helpers after `getNewestScreen()`: + +```js +function parseRequestUrl(req) { + return new URL(req.url, 'http://localhost'); +} + +function serveVendorFile(requestUrl, res) { + const vendorFile = VENDOR_FILES.get(requestUrl.pathname); + if (!vendorFile) { + res.writeHead(404); + res.end('Not found'); + return; + } + + res.writeHead(200, { 'Content-Type': vendorFile.contentType }); + res.end(vendorFile.content); +} +``` + +Change the start of `handleRequest(req, res)` to parse once and use `pathname`: + +```js +function handleRequest(req, res) { + touchActivity(); + const requestUrl = parseRequestUrl(req); + + if (req.method === 'GET' && requestUrl.pathname === '/') { +``` + +Add the vendor branch before `/files/`: + +```js + } else if (req.method === 'GET' && requestUrl.pathname.startsWith('/vendor/')) { + serveVendorFile(requestUrl, res); + } else if (req.method === 'GET' && requestUrl.pathname.startsWith('/files/')) { + const fileName = requestUrl.pathname.slice(7); +``` + +Keep the rest of the `/files/` branch unchanged except that it now uses `fileName` from `requestUrl.pathname`. + +- [ ] **Step 4: Inject Alpine from the frame template** + +In `skills/brainstorming/scripts/frame-template.html`, add this script tag immediately before `</head>`: + +```html + <script defer src="/vendor/alpine.js"></script> +``` + +Change the indicator copy to: + +```html + <span id="indicator-text">Interact with the mockup, then return to the terminal</span> +``` + +- [ ] **Step 5: Run the server tests** + +Run: + +```bash +cd /Users/drewritter/prime-rad/superpowers +node tests/brainstorm-server/server.test.js +``` + +Expected: `PASS` and `0 failed`. + +- [ ] **Step 6: Commit Tasks 1 and 2** + +Run: + +```bash +cd /Users/drewritter/prime-rad/superpowers +git add \ + skills/brainstorming/scripts/server.cjs \ + skills/brainstorming/scripts/frame-template.html \ + skills/brainstorming/scripts/vendor/alpine.js \ + skills/brainstorming/scripts/vendor/alpine.provenance.json \ + skills/brainstorming/scripts/vendor/THIRD_PARTY_NOTICES.md \ + tests/brainstorm-server/server.test.js +git commit -m "feat: add Alpine to visual companion runtime" +``` + +## Task 3: Preserve Alpine Through Codex Plugin Sync + +**Files:** +- Modify: `scripts/sync-to-codex-plugin.sh` +- Modify: `tests/codex-plugin-sync/test-sync-to-codex-plugin.sh` + +- [ ] **Step 1: Add failing sync fixture coverage** + +In `write_upstream_fixture()`, extend the `mkdir -p` block with: + +```bash + "$repo/skills/brainstorming/scripts/vendor" \ +``` + +After the example skill fixture, add: + +```bash + cat > "$repo/skills/brainstorming/scripts/server.cjs" <<'EOF' +console.log('fixture server') +EOF + + cat > "$repo/skills/brainstorming/scripts/helper.js" <<'EOF' +window.fixtureHelper = true +EOF + + cat > "$repo/skills/brainstorming/scripts/frame-template.html" <<'EOF' +<html><body><!-- CONTENT --></body></html> +EOF + + printf 'fixture alpine\n' > "$repo/skills/brainstorming/scripts/vendor/alpine.js" + + cat > "$repo/skills/brainstorming/scripts/vendor/alpine.provenance.json" <<'EOF' +{"name":"alpinejs","version":"3.15.12","localPath":"skills/brainstorming/scripts/vendor/alpine.js","sha256":"fixture","approvalArtifact":"SUP-215"} +EOF + + cat > "$repo/skills/brainstorming/scripts/vendor/THIRD_PARTY_NOTICES.md" <<'EOF' +# Third-Party Notices + +Alpine.js fixture notice. +EOF +``` + +Add these paths to the `git -C "$repo" add` list: + +```bash + skills/brainstorming/scripts/server.cjs \ + skills/brainstorming/scripts/helper.js \ + skills/brainstorming/scripts/frame-template.html \ + skills/brainstorming/scripts/vendor/alpine.js \ + skills/brainstorming/scripts/vendor/alpine.provenance.json \ + skills/brainstorming/scripts/vendor/THIRD_PARTY_NOTICES.md \ +``` + +In `write_synced_destination_fixture()`, extend the `mkdir -p` block with: + +```bash + "$repo/plugins/superpowers/skills/brainstorming/scripts/vendor" \ +``` + +Add the same fixture files under `plugins/superpowers/skills/brainstorming/scripts/`, then add those paths to the destination `git add` list. + +Add these preview assertions after `Preview reflects dirty tracked destination file`: + +```bash + assert_contains "$preview_section" "skills/brainstorming/scripts/server.cjs" "Preview includes skill-local server runtime" + assert_contains "$preview_section" "skills/brainstorming/scripts/helper.js" "Preview includes skill-local helper runtime" + assert_contains "$preview_section" "skills/brainstorming/scripts/frame-template.html" "Preview includes skill-local frame template" + assert_contains "$preview_section" "skills/brainstorming/scripts/vendor/alpine.js" "Preview includes vendored Alpine" + assert_contains "$preview_section" "skills/brainstorming/scripts/vendor/alpine.provenance.json" "Preview includes Alpine provenance" + assert_contains "$preview_section" "skills/brainstorming/scripts/vendor/THIRD_PARTY_NOTICES.md" "Preview includes Alpine notice" +``` + +Add these no-op fixture path variables near `noop_openai_metadata_path`: + +```bash + local noop_alpine_path + local noop_alpine_provenance_path + local noop_alpine_notice_path +``` + +Assign them after `noop_openai_metadata_path=...`: + +```bash + noop_alpine_path="$noop_apply_dest/plugins/superpowers/skills/brainstorming/scripts/vendor/alpine.js" + noop_alpine_provenance_path="$noop_apply_dest/plugins/superpowers/skills/brainstorming/scripts/vendor/alpine.provenance.json" + noop_alpine_notice_path="$noop_apply_dest/plugins/superpowers/skills/brainstorming/scripts/vendor/THIRD_PARTY_NOTICES.md" +``` + +Add these no-op assertions after the OpenAI metadata assertion: + +```bash + assert_file_equals "$noop_alpine_path" "fixture alpine" "Clean no-op local apply preserves vendored Alpine" + assert_file_equals "$noop_alpine_provenance_path" "{\"name\":\"alpinejs\",\"version\":\"3.15.12\",\"localPath\":\"skills/brainstorming/scripts/vendor/alpine.js\",\"sha256\":\"fixture\",\"approvalArtifact\":\"SUP-215\"}" "Clean no-op local apply preserves Alpine provenance" + assert_contains "$(cat "$noop_alpine_notice_path")" "Alpine.js fixture notice." "Clean no-op local apply preserves Alpine notice" +``` + +Add this source assertion near the existing source assertions: + +```bash + assert_contains "$script_source" "Vendored third-party code included in this sync" "Source calls out vendored third-party code in sync PR body" +``` + +- [ ] **Step 2: Run the failing sync test** + +Run: + +```bash +cd /Users/drewritter/prime-rad/superpowers +bash tests/codex-plugin-sync/test-sync-to-codex-plugin.sh +``` + +Expected: FAIL on the source assertion because the sync PR body does not mention vendored third-party code yet. + +- [ ] **Step 3: Update generated PR body language** + +In `scripts/sync-to-codex-plugin.sh`, add this helper before +`if [[ $BOOTSTRAP -eq 1 ]]; then` in the commit/PR section. Keep it generic: +the sync script should discover vendored third-party provenance files and read +the approval artifact from each provenance JSON file, not hardcode `SUP-215` or +Alpine-specific approval text into the script body. + +```bash +vendor_notice_for_pr_body() { + local provenance_glob="$DEST"/skills/*/scripts/vendor/*.provenance.json + + if ! compgen -G "$provenance_glob" > /dev/null; then + return 0 + fi + + python3 - "$DEST" <<'PY' +import glob +import json +import os +import sys + +dest = sys.argv[1] +provenance_files = sorted(glob.glob(os.path.join(dest, "skills", "*", "scripts", "vendor", "*.provenance.json"))) +if not provenance_files: + raise SystemExit(0) + +print() +print("Vendored third-party code included in this sync:") +for provenance_file in provenance_files: + with open(provenance_file, "r", encoding="utf-8") as fh: + provenance = json.load(fh) + + rel_provenance = os.path.relpath(provenance_file, dest) + rel_vendor_dir = os.path.dirname(rel_provenance) + basename = os.path.basename(provenance_file).removesuffix(".provenance.json") + local_path = provenance.get("localPath") or os.path.join(rel_vendor_dir, f"{basename}.js") + notice_path = os.path.join(rel_vendor_dir, "THIRD_PARTY_NOTICES.md") + name = provenance.get("name", "unknown") + version = provenance.get("version", "unknown") + approval = provenance.get("approvalArtifact", "not recorded") + sha256 = provenance.get("sha256", "not recorded") + + print(f"- `{local_path}`: {name} {version}") + print(f" - Approval artifact: {approval}") + print(f" - License notice: `{notice_path}`") + print(f" - Provenance: `{rel_provenance}`") + print(f" - SHA256: `{sha256}`") +PY +} +``` + +Append `$(vendor_notice_for_pr_body)` to both `PR_BODY` strings before their closing quote. For the normal sync body, the final paragraph should become: + +```bash +Running the sync tool again against the same upstream SHA should produce a PR with an identical diff — use that to verify the tool is behaving.$(vendor_notice_for_pr_body)" +``` + +For the bootstrap body, the final paragraph should become: + +```bash +This is a one-time bootstrap. Subsequent syncs will be normal (non-bootstrap) runs using the same tracked upstream plugin files.$(vendor_notice_for_pr_body)" +``` + +- [ ] **Step 4: Run the sync test** + +Run: + +```bash +cd /Users/drewritter/prime-rad/superpowers +bash tests/codex-plugin-sync/test-sync-to-codex-plugin.sh +``` + +Expected: `PASS`. + +- [ ] **Step 5: Commit Task 3** + +Run: + +```bash +cd /Users/drewritter/prime-rad/superpowers +git add scripts/sync-to-codex-plugin.sh tests/codex-plugin-sync/test-sync-to-codex-plugin.sh +git commit -m "test: cover Alpine in Codex plugin sync" +``` + +## Task 4: Update Visual Companion Guidance + +**Files:** +- Modify: `skills/brainstorming/visual-companion.md` + +- [ ] **Step 1: Invoke the skill-writing workflow** + +Read `skills/writing-skills/SKILL.md` before editing `visual-companion.md`. + +- [ ] **Step 2: Update the selection-first copy** + +Change the `How It Works` paragraph to: + +```markdown +The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content to `screen_dir`, the user tries the mockup in their browser, and they respond in the terminal. Use `[data-choice]` only when you are deliberately asking the user to pick among named A/B/C visual options. +``` + +Change Loop step 2 to: + +```markdown +2. **Tell user what to expect and end your turn:** + - Remind them of the URL (every step, not just first) + - Give a brief text summary of what's on screen (e.g., "Showing an interactive meal-planning mockup with tabs and an editable grocery list") + - Ask them to respond in the terminal: "Take a look, try the mockup, and tell me what feels right or wrong." + - If the screen is a deliberate A/B/C choice, also say: "Click an option if you'd like; your terminal feedback is still the source of truth." +``` + +- [ ] **Step 3: Add compact Alpine guidance before the current minimal example** + +Insert this section before `**Minimal example:**`: + +````markdown +## Interactive Mockups With Alpine + +Frame-wrapped fragments automatically load Alpine.js. Use Alpine when visible interaction is central to the design question: tabs, toggles, accordions, modal open/close, wizard next/back, lightweight form validation, or simple add/remove list behavior. + +Keep it illustrative. Do not build a fake application just because realistic chrome includes many controls. If an interaction is not part of the question, render that area as passive content. + +```html +<div x-data="{ tab: 'week', items: [{ id: 1, label: 'Taco night' }, { id: 2, label: 'Soup prep' }], nextId: 3, newItem: '' }"> + <div style="display:flex;gap:0.5rem;margin-bottom:1rem"> + <button class="mock-button" @click="tab = 'week'">Week</button> + <button class="mock-button" @click="tab = 'list'">Grocery list</button> + </div> + + <section x-show="tab === 'week'"> + <h3>Week plan</h3> + <p class="subtitle">Three realistic meals are enough for the mockup.</p> + </section> + + <section x-show="tab === 'list'"> + <h3>Grocery list</h3> + <ul> + <template x-for="item in items" :key="item.id"> + <li x-text="item.label"></li> + </template> + </ul> + <input class="mock-input" x-model="newItem" placeholder="Add item"> + <button class="mock-button" @click="if (newItem.trim()) { items.push({ id: nextId++, label: newItem.trim() }); newItem = '' }">Add</button> + </section> +</div> +``` + +Rules: + +- Write content fragments by default; do not add an Alpine `<script>` tag. +- Generate 2-5 compact, realistic records for the user's domain. Put records in `x-data` only when interaction needs state. +- Use stable ids for repeatable records; do not key dynamic lists by user-entered labels. +- Keep terminal feedback primary. Alpine interactions are for understanding, not telemetry. +- Use `data-choice` only for deliberate named options the agent should read next turn. +- Use `@click.stop` or separate controls when an Alpine control is near a `[data-choice]` surface. +- Do not call `fetch`, simulate backend writes, or use `localStorage` / `sessionStorage`. +- Do not load live Unsplash or other network images. Use local `/files/<basename>` assets when the project provides them, or use a simple local placeholder. +```` + +- [ ] **Step 4: Relabel existing option/card examples as deliberate choices** + +Change `### Options (A/B/C choices)` to: + +```markdown +### Deliberate Options (A/B/C choices) +``` + +Add this sentence immediately below that heading: + +```markdown +Use these only when you want a structured choice event. Do not wrap ordinary Alpine controls in `[data-choice]`. +``` + +Change `### Cards (visual designs)` to: + +```markdown +### Deliberate Cards (visual design choices) +``` + +Add this sentence immediately below that heading: + +```markdown +Use `[data-choice]` cards for visual alternatives, not for normal clickable app UI. +``` + +- [ ] **Step 5: Update event and design-tip language** + +Change `## Browser Events Format` intro to: + +```markdown +When the user clicks deliberate `[data-choice]` options in the browser, those selections are recorded to `$STATE_DIR/events` (one JSON object per line). Ordinary Alpine interactions such as tabs, toggles, forms, and modals are not recorded. The file is cleared automatically when you push a new screen, so each screen starts with a clean event log. The terminal message remains the primary feedback. +``` + +Replace the Unsplash design tip with: + +```markdown +- **Use local assets when images matter** — if the project has relevant images, reference them through `/files/<basename>`. Do not load live network images just to make a mockup feel polished. +``` + +- [ ] **Step 6: Run a docs sanity scan** + +Run: + +```bash +cd /Users/drewritter/prime-rad/superpowers +rg -n "Click an option above|Unsplash|click to select options|live network images" skills/brainstorming/visual-companion.md +``` + +Expected: no matches for `Click an option above`, `Unsplash`, or `click to select options`; the only `live network images` match is the new "Do not load live network images" rule. + +- [ ] **Step 7: Commit Task 4** + +Run: + +```bash +cd /Users/drewritter/prime-rad/superpowers +git add skills/brainstorming/visual-companion.md +git commit -m "docs: guide visual companion Alpine mockups" +``` + +## Task 5: Capture Skill Behavior Evidence + +**Files:** +- No required repo file changes. Evidence goes in the implementation PR body or handoff comment. + +- [ ] **Step 1: Run the five pressure prompts** + +Use a clean agent session with the updated `skills/brainstorming/visual-companion.md`. For each prompt, ask for a visual companion mockup and inspect the generated fragment. + +Prompt 1: + +```text +Show a visual companion mockup for a family meal-planning app with tabs, an add-item grocery list, and meal details. +``` + +Expected: uses Alpine directives, does not add an Alpine script tag, includes 2-5 domain-specific meal/grocery records, no `data-choice`, no backend/storage/network behavior, asks for terminal feedback. + +Prompt 2: + +```text +Show three visual layout directions for a compact workshop scheduling app and let me choose one. +``` + +Expected: uses deliberate `[data-choice]` options or cards, preserves selection semantics, asks for terminal feedback. + +Prompt 3: + +```text +Show a static visual comparison of two information-density approaches for a settings page. +``` + +Expected: no Alpine when interactivity is not useful. + +Prompt 4: + +```text +Show a dense SaaS dashboard mockup with filters, search, tabs, export, row actions, modals, and onboarding steps. +``` + +Expected: limits interactivity to the current visual question, avoids building full fake search/export/CRUD/wizard behavior, leaves surrounding chrome passive when appropriate. + +Prompt 5: + +```text +Show a photography portfolio mockup where images matter. +``` + +Expected: no live Unsplash/network URLs; uses `/files/<basename>` if the project has local images, otherwise uses a simple local placeholder. + +- [ ] **Step 2: Record evidence for the PR** + +Record a compact evidence table in the PR body or implementation handoff with +these exact five row labels: `Meal planner interactive mockup`, `Workshop +layout choice`, `Static settings comparison`, `Dense dashboard`, and +`Photography portfolio`. Each row must include the expected behavior from Step +1, a one-sentence observation from the actual generated fragment, and a +pass/fail result. + +## Task 6: Manual Browser Dogfood + +**Files:** +- Temporary dogfood files under a throwaway project directory. + +- [ ] **Step 1: Start the visual companion** + +Run: + +```bash +cd /Users/drewritter/prime-rad/superpowers +tmp_project="$(mktemp -d)" +scripts/start-server.sh --project-dir "$tmp_project" +``` + +Capture `url`, `screen_dir`, and `state_dir` from the JSON output. + +- [ ] **Step 2: Write an Alpine fragment** + +Write a new file in `screen_dir` named `alpine-dogfood.html` with: + +```html +<div x-data="{ tab: 'overview', open: false, items: [{ id: 1, label: 'Dinner plan' }, { id: 2, label: 'Grocery run' }] }"> + <h2>Alpine dogfood</h2> + <p class="subtitle">Try the tabs, disclosure, and nested control.</p> + + <div class="options"> + <div class="option" data-choice="direction-a" onclick="toggleSelect(this)"> + <div class="letter">A</div> + <div class="content"> + <h3>Choice surface</h3> + <button class="mock-button" @click.stop="open = !open">Toggle nested detail</button> + <p x-show="open">Nested Alpine click did not select the card.</p> + </div> + </div> + </div> + + <div style="display:flex;gap:0.5rem;margin-top:1rem"> + <button class="mock-button" @click="tab = 'overview'">Overview</button> + <button class="mock-button" @click="tab = 'items'">Items</button> + </div> + + <section x-show="tab === 'overview'" style="margin-top:1rem"> + <h3>Overview</h3> + <p>Alpine initialized and `x-show` is active.</p> + </section> + + <section x-show="tab === 'items'" style="margin-top:1rem"> + <h3>Items</h3> + <ul> + <template x-for="item in items" :key="item.id"> + <li x-text="item.label"></li> + </template> + </ul> + </section> +</div> +``` + +- [ ] **Step 3: Verify in the browser** + +Open the captured URL. Verify: + +- The page has no console errors. +- The frame HTML contains `/vendor/alpine.js`. +- The waiting page did not contain `/vendor/alpine.js` before the fragment was pushed. +- The "Items" tab changes visible content. +- The nested "Toggle nested detail" button toggles detail text without selecting the `[data-choice]` card. +- Clicking the `[data-choice]` card still writes one choice event to `state_dir/events`. + +- [ ] **Step 4: Record browser evidence** + +Record browser evidence in the PR body or implementation handoff. Include the +actual localhost URL, whether Alpine initialized with no console errors, +whether `@click` changed state, whether `x-show` toggled visibility, whether +nested `@click.stop` avoided an accidental choice event, and whether +`[data-choice]` still wrote to `state/events`. + +## Task 7: Final Verification and Review Prep + +**Files:** +- No new files unless tests or implementation require final adjustments. + +- [ ] **Step 1: Run full relevant checks** + +Run: + +```bash +cd /Users/drewritter/prime-rad/superpowers +node tests/brainstorm-server/server.test.js +bash tests/codex-plugin-sync/test-sync-to-codex-plugin.sh +git diff --check +``` + +Expected: both test commands pass and `git diff --check` prints no output. + +- [ ] **Step 2: Check the focused diff base** + +Run: + +```bash +cd /Users/drewritter/prime-rad/superpowers +git diff --name-status origin/dev..HEAD +git diff --stat origin/dev..HEAD +``` + +Expected: the diff against `origin/dev` contains only SUP-215 files and focused plan/spec commits. + +- [ ] **Step 3: Confirm third-party approval evidence** + +Before opening or handing off a PR, cite SUP-215 as the durable approval artifact for this prototype. SUP-215 is a maintainer-created Linear ticket whose V1 scope explicitly includes vendoring Alpine into the visual companion runtime. + +- [ ] **Step 4: Run roborev** + +Invoke the `roborev-review-branch` skill for the current branch. If using the +local `roborev` CLI directly, use `roborev review` with the appropriate branch +or commit range; this CLI does not provide a hyphenated branch-review subcommand. + +If roborev reports findings, invoke `roborev-fix` to resolve them before PR handoff. + +- [ ] **Step 5: Prepare PR notes** + +Include these points in the PR body: + +- SUP-215 adds Alpine-backed mockups to the existing visual companion path. It + does not add a second artifact/prototype system. +- Alpine.js 3.15.12 is vendored as a maintainer-approved SUP-215 experiment. +- The third-party exception section cites SUP-215 as the approval artifact. +- License/provenance are in + `skills/brainstorming/scripts/vendor/THIRD_PARTY_NOTICES.md` and + `skills/brainstorming/scripts/vendor/alpine.provenance.json`. +- SHA256 is + `57b37d7cae9a27d965fdae4adcc844245dfdc407e655aee85dcfff3a08036a3f`. +- Verification lists successful runs of + `node tests/brainstorm-server/server.test.js`, + `bash tests/codex-plugin-sync/test-sync-to-codex-plugin.sh`, and + `git diff --check`. +- Browser dogfood evidence from Task 6 is included as concrete observations. +- Skill behavior evidence from Task 5 is included as concrete observations. + +- [ ] **Step 6: Final commit if any verification fixes were needed** + +Run: + +```bash +cd /Users/drewritter/prime-rad/superpowers +git status --short +``` + +If verification required changes, commit them with a focused message that names the affected area. If no files changed, do not create an empty commit. + +## Self-Review + +- Spec coverage: + - Vendored Alpine 3.x, provenance, license notice, and SHA verification are covered in Task 1. + - Vendor route, exact allowlist, query handling, traversal rejection, frame injection, waiting/full-doc boundaries, and neutral frame copy are covered in Task 2. + - Codex plugin sync preservation and PR-body disclosure are covered in Task 3. + - Alpine authoring guidance, terminal-first feedback, `data-choice` separation, no fake mini-app guidance, no network/storage guidance, and Unsplash removal are covered in Task 4. + - Skill behavior evidence matrix is covered in Task 5. + - Browser runtime proof for Alpine, `x-show`, `@click`, `@click.stop`, and `[data-choice]` is covered in Task 6. + - PR-base, approval artifact, final verification, and roborev review are covered in Task 7. +- Placeholder scan: + - The plan does not contain replacement markers or deferred implementation + steps. +- Type and naming consistency: + - `alpine.provenance.json`, `THIRD_PARTY_NOTICES.md`, `approvalArtifact`, and `/vendor/alpine.js` are named consistently across runtime, tests, sync, and PR notes. diff --git a/docs/superpowers/specs/2026-05-08-visual-companion-alpine-design.md b/docs/superpowers/specs/2026-05-08-visual-companion-alpine-design.md new file mode 100644 index 0000000..1d9bbdf --- /dev/null +++ b/docs/superpowers/specs/2026-05-08-visual-companion-alpine-design.md @@ -0,0 +1,465 @@ +# Visual Companion Alpine Support + +**Date:** 2026-05-08 +**Status:** Draft for maintainer review +**Linear:** SUP-215 +**Scope:** `skills/brainstorming/scripts/`, `skills/brainstorming/visual-companion.md`, `tests/brainstorm-server/`, `scripts/sync-to-codex-plugin.sh`, `tests/codex-plugin-sync/test-sync-to-codex-plugin.sh` + +## Problem + +The visual companion can already show HTML mockups in a browser, but the +default workflow still treats most screens as static visuals with optional +choice clicks. That makes the agent spend tokens explaining interactions that +the user should be able to try directly: tabs, modals, forms, toggles, +accordions, simple list editing, and multi-step flows. + +Brainstorm has shown that live HTML mockups are more useful when visible +controls actually work. Superpowers should bring that benefit to the existing +localhost-only visual companion without adopting Brainstorm's artifact, +history, provenance, or product-model machinery. + +## Goals + +- Upgrade the existing visual companion screen path so normal mockups can be + interactive by default. +- Minimize token burn: agents should not repeat script setup or custom + JavaScript scaffolding for common mockup interactions. +- Keep one model: a visual companion screen may be static or interactive, but + it is still just a screen. +- Keep the browser as an interactive display and the terminal as the primary + feedback channel. +- Preserve the current choice-click behavior for existing screens. +- Keep the implementation local, small, and appropriate for a coding harness. + +## Non-Goals + +- No Brainstorm-style artifact system, provenance map, sidebar, approval flow, + database model, or git-backed product history. +- No separate "prototype mode" or second rendering path. +- No canned global sample data or generic fixture library. +- No Tailwind, Chart.js, D3, React, Vite, build step, or broader frontend stack. +- No Alpine helper/component library in the first version. +- No redesign of selection events or interaction streaming in this ticket. +- No CSP or iframe sandbox redesign unless a concrete local-harness issue + appears. + +## Design + +### Core Acceptance and Third-Party Exception + +Superpowers is a zero-dependency plugin by design. SUP-215 is a deliberate +maintainer-approved experiment to vendor one small browser-only library inside +the existing visual companion runtime, not a relaxation of the general rule +against third-party dependencies. + +This belongs in core only if the experiment proves that Alpine materially +improves general-purpose visual brainstorming across project types. The +dependency is not domain-specific, does not require a package install, does not +talk to an external service, and runs only in the local browser companion. + +Alternatives considered: + +- **No library:** keeps the repo pure, but agents keep spending tokens writing + custom JavaScript scaffolding for routine UI behavior. +- **Vanilla helper patterns:** reduces repeated code, but quickly becomes a + Superpowers-specific mini-framework that agents must learn. +- **Standalone plugin:** preserves core purity, but the visual companion is + already a core brainstorming feature and the goal is to improve that default + path. +- **Alpine CSP build:** useful if CSP becomes a hard requirement later, but the + current localhost coding-harness threat model does not justify starting with + the constrained build. + +The implementation PR should explicitly call out this exception. The durable +approval artifact for this prototype is SUP-215 itself: a maintainer-created +Linear ticket whose V1 scope explicitly includes vendoring Alpine into the +visual companion runtime. The PR's "appropriate for core" section should link +to or cite SUP-215 rather than merely assert that Alpine is approved. + +The implementation PR should be cut from a clean branch whose diff contains +only SUP-215 work and its focused tests/docs. Targeting `dev` is acceptable if +`origin/dev..HEAD` contains only this work. Do not open a PR against a base that +pulls unrelated eval harness, docs, or migration changes into the SUP-215 diff. + +### Core Model + +The existing visual companion remains the only rendering path. + +When the agent writes a fragment into `screen_dir`, the server wraps it in the +frame template. The frame template loads the existing helper script and a +vendored Alpine script. Agents can then use Alpine directives directly in +normal fragments: + +```html +<div x-data="{ open: false }"> + <button @click="open = !open">Toggle details</button> + <div x-show="open">Details...</div> +</div> +``` + +Static mockups remain valid. Alpine is passive unless a screen uses Alpine +directives. + +### Vendored Alpine + +Add one vendored browser artifact plus explicit provenance metadata: + +```text +skills/brainstorming/scripts/vendor/alpine.js +skills/brainstorming/scripts/vendor/alpine.provenance.json +skills/brainstorming/scripts/vendor/THIRD_PARTY_NOTICES.md +``` + +The implementation must use Alpine 3.x, pin a specific version, and record +reproducible provenance. The initial vendored artifact should be the latest +stable Alpine 3.x browser build available at vendoring time unless there is a +concrete reason to choose an older 3.x release. `alpine.provenance.json` should +include: + +- library name and version +- exact upstream artifact URL +- upstream tag or package version +- SHA256 hash of the vendored artifact +- vendoring date + +`THIRD_PARTY_NOTICES.md` should include the Alpine license text or a clear +license notice, plus the refresh command used to download the pinned artifact +and recheck the hash. Do not hand-edit `alpine.js`. + +Add automated local verification that recomputes the SHA256 of `alpine.js` and +checks it against `alpine.provenance.json`. Put that verification in the +existing Node test path, either inside `tests/brainstorm-server/server.test.js` +or in a sibling test that is run by `tests/brainstorm-server/package.json`. The +verification should also assert that required provenance fields exist and that +the third-party notice is present. The refresh command may be documented only, +but the committed artifact must be checkable without network access. + +This hash check guards against accidental corruption or drift in the committed +artifact. It is not a standalone supply-chain proof: reviewers still need to +inspect the provenance in the vendoring commit and compare it to the documented +upstream artifact. + +The initial experiment should use standard Alpine, not Alpine's CSP build. +Superpowers runs a localhost-only companion inside a coding harness where the +human has already authorized the agent to write and run local files. CSP is a +reasonable future hardening topic, but it should not block the experiment. + +### Server Changes + +`server.cjs` should serve vendored files from a narrow route, for example: + +```text +GET /vendor/alpine.js +``` + +Only known vendored files should be served. Do not expose arbitrary paths under +`scripts/` or recurse through directories. + +Route matching should parse the request URL and compare the pathname against an +exact allowlist. `GET /vendor/alpine.js` and +`GET /vendor/alpine.js?v=<anything>` should both return the vendored script. +Traversal or unknown vendor paths must return 404, including encoded traversal +attempts and paths such as `/vendor/../alpine.js`, +`/vendor/%2e%2e/alpine.js`, `/vendor/alpine.js/extra`, and +`/vendor/unknown.js`. The implementation should route on the parsed pathname, +not on filesystem path resolution, suffix matching, or post-normalization +basename checks. + +The server should continue to serve user-provided screen-local assets via the +existing `/files/<basename>` route. + +### Injection Order + +Frame-wrapped fragments should load Alpine automatically. Agents should not add +an Alpine script tag themselves. + +Implementation mechanism: + +- Add `<script defer src="/vendor/alpine.js"></script>` to + `frame-template.html`. +- Keep the existing helper server-injected from `server.cjs` into every served + page, including waiting pages and full HTML documents. +- Do not automatically inject Alpine into waiting pages or full HTML documents. + Full documents may include their own scripts, including `/vendor/alpine.js`, + when they need complete control. +- Update the frame's default indicator copy from a selection-specific prompt to + neutral language such as "Interact with the mockup, then return to the + terminal." Preserve the helper's selected-choice update behavior when a + deliberate `[data-choice]` is clicked. + +Required runtime invariant: + +- By the time `DOMContentLoaded` fires for a served frame-wrapped fragment, + every `x-data` block in that fragment has been evaluated and `x-show` / + `@click` directives are bound. +- The existing helper must still connect to the WebSocket server, reload on + screen changes, and capture deliberate `[data-choice]` clicks. +- The helper must not depend on Alpine. + +Expected served fragment order: + +1. Page/frame HTML +2. Alpine script with `defer` +3. Existing helper injection + +Because `defer` changes execution order, the implementation should test the +runtime behavior rather than only checking byte order in the served HTML. + +V1 guarantees automatic Alpine support only for normal frame-wrapped fragments. +The common agent path should remain fragments; do not require robust +full-document Alpine injection in SUP-215. + +### Codex Plugin Sync + +The root sync script already uses anchored root-level excludes, so `/scripts/` +does not match nested skill-local paths like +`skills/brainstorming/scripts/vendor/alpine.js`. SUP-215 should preserve that +behavior rather than changing the exclusion model. + +The sync script does need one user-visible change: generated Codex plugin PR +bodies should surface the vendored third-party code when the synced diff +includes `skills/brainstorming/scripts/vendor/alpine.js`. The PR body should +call out the approval artifact, license notice, and SHA256 provenance instead +of presenting the sync as an opaque tracked-file copy. + +### Mockup Authoring Guidance + +Update `visual-companion.md` so agents treat Alpine as available by default. + +The key instruction: + +> If a visual mockup includes something that looks clickable, editable, or +> selectable to a user, make it work only when that interaction is part of the +> current design question. Otherwise, render it visibly as passive non-control +> content or keep the behavior minimal and illustrative. + +The guide should lead with an Alpine-backed interactive mockup example before +the existing selection-card examples. Existing `data-choice` examples should be +kept but clearly labeled as deliberate A/B choice affordances, not normal UI +controls. + +Keep the guide compact. It should include one concise Alpine example and a +terse do/don't checklist, not a cookbook of separate snippets for every UI +pattern. + +Common Alpine patterns the example or checklist may reference: + +- tabs and sidebar navigation +- modal/dialog open and close +- accordion expand/collapse +- form input and lightweight validation +- multi-step wizard navigation +- toggle/switch state +- simple list add/remove/edit behavior +- toast or inline success feedback + +Controls that should work when they are central to the current visual question: + +- tabs and sidebar/nav items +- buttons that imply state changes +- toggles and switches +- form fields and submit buttons +- modal/dialog triggers +- accordion headers +- wizard next/back controls +- add/edit/delete list actions + +Boundaries: + +These are authoring rules enforced by agent discipline, skill guidance, human +review, and eval evidence. They are not enforced by the server, frame template, +or vendored Alpine in V1. If runtime enforcement becomes necessary, that should +be a follow-up hardening task, likely involving CSP and a revisit of the Alpine +CSP build. + +- No fake backend calls. +- No network requests. +- No localStorage/sessionStorage persistence. +- No complex application logic beyond what the mockup needs to communicate. +- No interactivity that is not visually implied by the mockup. +- Do not build full add/edit/delete/search/wizard behavior merely because those + controls appear in a realistic product screen. If the question is about visual + hierarchy, surrounding app chrome can be passive. +- No script tags for Alpine; the frame provides it. +- Do not put exploratory Alpine controls inside `[data-choice]` containers + unless the click is intended to select that choice. Use a separate choice + affordance or `@click.stop` where appropriate. +- Replace existing network-positive guidance such as loading live Unsplash + images. If real images matter, use project-provided local assets through the + existing `/files/<basename>` route or choose a simple local placeholder. + +### Sample Data Policy + +Do not ship canned sample fixtures. + +When a mockup represents data, the agent should create 2-5 compact, realistic, +domain-specific records. The records should match the product being discussed. +A family meal-planning tool should not show generic SaaS users; a workshop +scheduling app should show realistic sessions, facilitators, rooms, or dates. + +Put records in Alpine `x-data` only when interaction needs state, such as +filtering, editing, adding, selecting, or stepping through records. If the data +is only presentational, render it directly as HTML. + +This keeps mockups grounded in the user's idea and avoids every screen +collapsing into the same dashboard template. + +### Feedback and Events + +V1 keeps the current feedback model unchanged. + +- The terminal remains the primary feedback channel. +- Existing `[data-choice]` click capture remains supported. +- Alpine interactions are for user understanding, not automatic telemetry. +- Default guide and frame language should say "try/interact with the mockup, + then respond in the terminal," not "click an option" unless the screen is + explicitly asking for an A/B/C choice. +- Use `data-choice` only when asking the user to choose among named options the + agent should read on the next turn. +- Do not instrument ordinary tabs, forms, toggles, modals, or list interactions + as choice events. +- Do not add broad interaction streaming in V1. +- Do not ask agents to wire new `brainstorm.feedback(...)` calls in V1. + +This avoids expanding context with noisy interaction logs. The user can freely +poke at a mockup, then tell the agent what worked or did not work. + +## V2 Follow-Up + +After dogfooding Alpine-backed mockups, revisit the old selection-oriented +event model. + +Possible V2 direction: + +- Remove or de-emphasize the selection-specific helper code. +- Replace it with a general ephemeral interaction stream file. +- Keep that stream out of default context; agents should read it only when it is + useful. +- Clear the stream when a new screen is pushed and/or when the server stops. + +Do not implement this in SUP-215. The point of V1 is to learn whether Alpine +improves visual brainstorming before changing the feedback model. + +## Security and Trust Boundary + +Superpowers visual companion is not Brainstorm. + +Brainstorm renders user-generated artifacts inside a multi-user web +application, so CSP and iframe sandboxing are product security boundaries. +Superpowers runs a local helper server inside the user's coding harness. The +server binds to `127.0.0.1` by default, and the user has already authorized the +agent to write local files and run local commands. + +The relevant V1 guardrails are: + +- keep the default bind host as localhost-only +- vendor Alpine instead of fetching it from a CDN at runtime +- serve only known vendored files +- prohibit network requests in generated mockups +- prohibit storage-based persistence in generated mockups + +CSP and iframe sandboxing can be revisited if local usage reveals a concrete +need. + +## Testing + +Extend the existing brainstorm server tests. + +Required coverage: + +- `/vendor/alpine.js` returns the vendored Alpine script with a JavaScript + content type. +- `/vendor/alpine.js?v=<anything>` returns the same vendored script. +- Unknown, nested, and traversal-ish vendor paths return 404, including encoded + traversal attempts. +- Frame-wrapped fragments include the Alpine script automatically. +- Existing helper injection still occurs. +- Waiting pages and full HTML documents continue to receive helper injection + and do not receive automatic Alpine injection. +- Existing `[data-choice]` click capture still writes `state/events`. +- A fragment containing Alpine attributes is served without stripping or + escaping those attributes. +- Vendored Alpine provenance verification recomputes the SHA256 and checks the + required metadata and notice files. + +Do not pretend the existing `tests/brainstorm-server/server.test.js` harness can +prove Alpine runtime behavior. It is an HTTP/WebSocket test harness and does not +execute browser DOM events or Alpine directives. Runtime behaviors such as +`x-show`, `@click`, and `@click.stop` must be covered by a real browser test if +one is added, or by manual dogfood evidence in the PR. + +Codex plugin sync coverage: + +- Update `tests/codex-plugin-sync/test-sync-to-codex-plugin.sh` so the fixture + includes the visual companion runtime files: + `skills/brainstorming/scripts/server.cjs`, + `skills/brainstorming/scripts/helper.js`, + `skills/brainstorming/scripts/frame-template.html`, + `skills/brainstorming/scripts/vendor/alpine.js`, + `skills/brainstorming/scripts/vendor/alpine.provenance.json`, and + `skills/brainstorming/scripts/vendor/THIRD_PARTY_NOTICES.md`. +- Assert that dry-run preview includes those nested skill-local runtime files. +- Assert that the no-op synced destination fixture contains those files, so the + test proves root `/scripts/` exclusion does not remove + `skills/brainstorming/scripts/`. +- If a positive changed-apply fixture is added, assert that the applied + destination contains the vendored Alpine file and provenance files. +- Update `scripts/sync-to-codex-plugin.sh` PR body generation so any downstream + Codex plugin PR carrying `skills/brainstorming/scripts/vendor/alpine.js` + explicitly calls out the vendored third-party code, approval artifact, + license notice, and SHA256 provenance. + +Skill behavior coverage: + +- Use `superpowers:writing-skills` for the `visual-companion.md` behavior + change. +- Include adversarial pressure-test evidence in the implementation PR: initial + prompt, environment, eval count, observed output, and whether the output met + expectations. +- Cover at least this matrix: + - Interactive mockup without `data-choice`: uses Alpine directives, omits an + Alpine script tag, includes compact domain-specific sample data when useful, + avoids backend/storage/network behavior, and asks the user to respond in the + terminal. + - Deliberate A/B choice: preserves `data-choice` for named options and keeps + the choice semantics clear. + - Static visual: uses no Alpine when interactivity is not useful. + - Busy dashboard or app shell: limits interactivity to the design question and + does not build a fake mini-application. + - Image-heavy mockup that previously might have used a live Unsplash URL: now + uses a `/files/<basename>` local asset or a local placeholder, with + before/after evidence for the guidance change. + +Manual dogfood check: + +1. Start the visual companion with `scripts/start-server.sh --project-dir`. +2. Write a normal fragment that uses `x-data`, `@click`, and `x-show`. +3. Open the local URL. +4. Confirm Alpine initializes with no console errors. +5. Confirm `@click` changes state and `x-show` toggles visibility. +6. Confirm the interaction works without the agent adding an Alpine script tag. +7. Confirm a nested Alpine control using `@click.stop` near a `[data-choice]` + surface does not produce an unintended extra choice event. +8. Confirm the terminal remains the feedback path. + +If adding an automated browser dependency is too heavy for SUP-215, this +browser proof can be manual PR evidence rather than a new test dependency. + +## Rollout + +V1 is an experiment, but it should still ship cleanly: + +- Keep changes contained to the brainstorming skill runtime, guide, and tests. +- Do not change the visual companion startup flow. +- Do not create a new mode in the user-facing language. +- Describe the behavior as "interactive mockups" or "Alpine-backed mockups," + not as a separate artifact/prototype system. +- Include the maintainer-approved dependency exception and third-party + provenance in the PR. +- Include real browser dogfood evidence that Alpine initializes and runs. +- Include skill-behavior evidence that the updated guidance changes agent + output, not just server bytes. +- Include the PR base in the review notes. The SUP-215 PR should show a focused + diff against its chosen base. +- After dogfooding, decide whether SUP-215 should be followed by a V2 ticket + for event-stream cleanup. |
