Session: Cursor + Paper + Grok App Builder workflow (Ion Wake, 2026-08-23)

First-party session log fetched from the Orca share https://share.onorca.dev/a/BUEVHFdLiORG. Readable body served at https://content.orcausercontent.dev/usercontent/BUEVHFdLiORG/artifact.html. Filename on the share: 2026-08-23-cursor-paper-grok-workflow.md. This is a session log (Paul + Cursor, Ion Wake / pmcclelland/ion-wake, 2026-08-23), not a wiki page.

Summary

The load-bearing discovery: Grok App Builder and Cursor do not share a skill-discovery path. Grok Build auto-lists .grok/skills/ (especially design-ui for overlay/HUD). Cursor, Cursor Cloud Agents, and Grok Bot coding agents auto-list .cursor/skills/, .agents/skills/, and user skill dirs — not .grok/skills/. AGENTS.md in the repo tells agents to consult Grok skills; it does not inject the skill bodies.

The workflow that fell out:

1. Design in Cursor + Paper Desktop (same session must see Paper, git, and the running app).
2. Non-visual engine work can go to a coding agent that cannot see Paper.
3. Expose .grok/skills into git as .cursor/skills so Cloud / Grok Bot clones load the same UI doctrine.
4. Keep the delta small. Paper can hold chrome that must never land in the app. Copy-only asks stay copy-only.

Cursor + Paper + Grok App Builder — personal project workflow

First-party notes from a Cursor session on Ion Wake (pmcclelland/ion-wake) on 2026-08-23. Written so Brain can ingest later into threads/artificial-intelligence (AI coding tools / practitioner workflows). This is a session log, not a wiki page.

Harness map

Do not collapse these four into one “Grok on Cursor” blob.

Grok Build advantages that still hold: opinionated playable bar, skill triggers (design-ui, building-games, controls), isolation, preview contract. Cursor advantages: git, Paper, local debug, Grok Bot / cloud handoff.

Design loop (Paper + Cursor)

Worked on Ion Wake overlay screens (title, play HUD, over, scores).

1. Open a Paper file (here: ionwake).
2. code-to-design — pull live tokens/chrome onto the canvas. Match src/styles.css (instrument black #07080c, steel type, Oxanium + Figtree). Do not invent neon arcade.
3. Iterate visually in Paper.
4. design-to-code in a session that can see Paper and the repo. Implement only the requested delta.
5. Verify in the running game (desktop + mobile). Paper-only chrome (iOS status bar, decorative ship stand-in) stays in Paper.

Failure mode this session: first design-to-code pass restyled layout/tokens. The ask was copy. Reverted layout; kept copy: High Scores, IONWAKE, Save Score. Shipped as 99b4bff.

Paper is the visual source of truth. A coding agent without Paper will invent layout if asked to “match the artboard.”

Skill loading — what actually works

Grok doctrine (still the UI source of truth)

Repo path: .grok/skills/. Overlay / HUD / Paper / CSS → read design-ui first (references/refined-ui.md, typography.md, surfaces.md, animations.md). Games with chrome also load building-games. WASD / vehicle / flight → controls. auth / neon only per AGENTS.md §0.5. Do not call imagine_* unless those tools are listed.

What Cursor injects vs what it must Read

• Cursor available_skills in this session: Cursor built-ins, plugins (Paper, Vercel, …), ~/.cursor/skills, ~/.claude/skills, ~/.agents/skills. Not .grok/skills.
• AGENTS.md is always-on and instructs consulting Grok skills. Without a Read, the agent restyles from memory or Paper skills alone.
• This session did Read design-ui for the Paper pass — that is why the canvas used instrument-black tokens.

Wiring shipped 2026-08-23 (95d1206 on ion-wake main)

In the repo (Cloud / Grok Bot consumers):

• .cursor/skills → symlink ../.grok/skills (git mode 120000)
• .cursor/rules/grok-design-ui.mdc — alwaysApply; gate on .grok/skills/ existing; force Read of design-ui before overlay work

On this Mac (installer + local routing; not in git):

• ~/.cursor/rules/grok-design-ui.mdc — alwaysApply, same gate. Does not follow Cloud Agents.
• ~/.cursor/skills/grok-app-builder-skills — routing table when .grok/skills exists
• ~/.cursor/skills/link-grok-skills — /link-grok-skills: run scripts/link-grok-skills.sh, then commit only .cursor/skills and the rule. If .cursor/skills already exists as a directory, add per-skill symlinks instead of replacing it. Do not push unless asked.

After clone of a fresh App Builder repo: invoke /link-grok-skills, commit, push. Then Cloud / Grok Bot coding agents on that repo auto-list Grok skills.

The installer skill itself is not on the Cloud VM unless copied there or committed. Cloud agents consume the result in git, not the Mac installer.

Operating checklist (personal App Builder projects)

1. Design / HUD / copy: Cursor + Paper, session that can see both. Open .grok/skills/design-ui (or rely on .cursor/skills/design-ui once linked).
2. If the Paper delta is copy, change copy only.
3. Physics / scoring / persistence / refactors: coding agent without Paper is fine.
4. New App Builder checkout: /link-grok-skills → commit .cursor/ → push so Cloud / Grok Bot get the pack.
5. Do not send “make it match Paper” to Grok App Builder (no Paper, no git) or to a Paper-blind coder.
6. Account Cursor Settings → Rules (user rules) are the account-synced channel Cloud Agents are documented to inherit. ~/.cursor/rules is machine-local and currently not loaded by cloud rule-walk.

Suggested Brain ingest

Target: threads/artificial-intelligence (practitioner workflows; already has cursor and vibe-coding-app-builders).

Possible wiki atoms (for ingest to create or extend, not created here):

• Entity: Grok App Builder — chat + preview sandbox; .grok/skills; AGENTS.md sandbox contract; not git/Paper.
• Entity: Grok Bot — xAI teammate on Cursor infra; coding handoff to Cloud Agents.
• Entity: Paper Desktop — design canvas + MCP; code-to-design / design-to-code; must share a session with the repo.
• Concept: agent skill discovery paths — .grok/skills vs .cursor/skills vs ~/.cursor/rules vs account User Rules vs Cloud /workspace walk.
• Concept: Paper-as-source-of-truth with tight deltas — overlay documentation vs restyle; Paper-only chrome must not ship.
• Mechanism: expose Grok skills to Cursor via repo symlink — .cursor/skills → .grok/skills plus alwaysApply rule; /link-grok-skills as the clone-time installer.

Related existing pages: cursor, vibe-coding-app-builders, ai-coding-tool-landscape-2026.

Provenance

• Repo: https://github.com/pmcclelland/ion-wake
• Commits this session: 99b4bff (overlay copy), 95d1206 (.cursor/skills + rule)
• Paper file: ionwake (https://app.paper.design/file/01M0QMYAQHZ94VA5CA7FR3QC7K/1-0)
• Cursor Cloud rules/skills behavior: Cursor docs (cloud agent best practices; skills directories); forum confirmation that ~/.cursor/rules is not loaded because discovery walks up from /workspace
• Grok Bot: xAI “Introducing Grok Bot” (teammate, own cloud computer, Cursor Pro+/Ultra among access paths)