Parallel CX session workflow + SETUP.md for new teammates by jorrit-stack · Pull Request #3 · stackblitz/Raycast-scripts

jorrit-stack · 2026-05-15T10:25:57Z

Summary

Bundles the new CX automation workflow (parallel Claude sessions per ticket, deep-dive escalation to the cx-agent Codespace) and a SETUP.md so any teammate can bootstrap the same stack.

What's in this PR

New: `open-cx-session.sh`

Spawn a fresh claude session per ticket in Warp / Terminal.app / Hyper. The session walks the standard CX workflow: pull Front context, query the bolt admin chat, check past conversations, apply policy from ~/.claude/CLAUDE.md, propose options for the human, draft a reply, run the bolt-qa-checker skill, post as a Front comment.

Trigger N times from Raycast → N parallel terminal tabs each working a different ticket.

Spawn-target switch via CX_TERMINAL:

Value	Mechanism	Notes
`Warp` (default)	Warp Launch Configurations (`~/.warp/launch_configurations/cx-session.yaml`)	Bypasses Agent Mode. No credits consumed regardless of Warp settings.
`Terminal`	Terminal.app `do script`	Most reliable; just needs Automation perm.
`Hyper`	Cmd+N keystroke + System Events	No agent interception.

claude binary auto-detection across Homebrew ARM/Intel + ~/.local/bin + PATH lookup, with CLAUDE_BIN env-var override.

New: `open-cx-deepdive.sh`

Skip admin chat and go straight to the CX agent Codespace. Wakes stackblitz/cx-agent via gh codespace start, pulls minimal Front context (email + subject) for the cnv_id, builds a primer prompt, copies it to the macOS pasteboard, and opens the Codespace's github.dev URL in the browser. Paste the primer into claude inside the Codespace to start the deep dive.

Path A (inline escalation from open-cx-session.sh) is handled via instructions in the recommended ~/.claude/CLAUDE.md — the local session asks before triggering this script on the user's confirmation.

Fix: `gh-cx-agent.sh` ssh argument order

The previous invocation passed the remote command as -c (which gh treats as the codespace name selector) and the codespace name as the positional command. Result:

getting full codespace details: HTTP 404: Not Found
(.../user/codespaces/cd%20/workspaces/cx-agent%20...)

gh was looking up a codespace literally named cd /workspaces/cx-agent && echo .... Swap to correct order: gh codespace ssh -c "$CODESPACE_NAME" "<remote command>".

Note: end-to-end usability still depends on adding sshd to the cx-agent devcontainer (separate PR opened on stackblitz/cx-agent).

New: `SETUP.md`

End-to-end bootstrap guide so a new teammate can stand up this stack from scratch:

Prereqs (macOS, Raycast, claude CLI, gh, node, jq, Chrome perms)
Bootstrap (clone, secrets, dependencies, Raycast registration, macOS permissions, smoke tests)
Picking a terminal (Warp / Terminal / Hyper)
Recommended ~/.claude/CLAUDE.md template — process-level only. Specific policy thresholds (live-session plan tier, goodwill amounts) stay personal/team-shared.
Workflow overview (Path A inline escalation; Path B direct deep-dive; parallel session pattern; memory feedback loop)
Troubleshooting table

Docs: README pointer

One-line pointer to SETUP.md at the top of README.md.

Dependencies

For open-cx-session.sh and open-cx-deepdive.sh to be useful end-to-end, the existing PR Add front-to-admin-chat: Front context → admin chat with prefilled query #2 (front-to-admin-chat) should land first. Without it the local Claude session can't pull Front + admin chat context as efficiently. The new scripts work standalone — they just call front-to-admin-chat/index.js if available.
For the one-shot gh-cx-agent.sh path to fully work, the matching PR on stackblitz/cx-agent (adds sshd feature) must merge and the Codespace must be rebuilt.

Test plan

bash open-cx-session.sh cnv_xxx opens a Warp tab via Launch Configurations (no Agent Mode interception, no credit consumption)
CX_TERMINAL=Terminal bash open-cx-session.sh cnv_xxx opens a single Terminal.app window
CX_TERMINAL=Hyper bash open-cx-session.sh cnv_xxx opens Hyper via keystroke (Agent permissions granted)
Spawned session reads ~/Documents/Raycast-scripts/cx-briefing/.env and authenticates Front + Linear + Slack
bash open-cx-deepdive.sh cnv_xxx wakes the cx-agent Codespace and opens https://<codespace>.github.dev/; primer is on clipboard
Verify the SETUP.md "Smoke tests" section runs cleanly on a fresh machine
Triggering 3+ open-cx-session.sh in quick succession produces 3+ independent terminal tabs

🤖 Generated with Claude Code

…args Bootstraps a parallel CX workstation workflow that any teammate can set up: open-cx-session.sh Spawn a fresh `claude` session per ticket in Warp / Terminal.app / Hyper. Loads a prompt that walks the standard CX workflow: pull customer context from Front, query the bolt admin chat, check past conversations, apply policy from ~/.claude/CLAUDE.md, propose options for the human, draft a reply, run the bolt-qa-checker skill, post as a Front comment for review. - Warp (default): uses Warp Launch Configurations (~/.warp/launch_configurations/cx-session.yaml). Bypasses Agent Mode entirely so no credits are consumed regardless of the user's Warp settings. - Terminal: native `do script` (most reliable; just needs Automation perm). - Hyper: keystroke via System Events. No agent interception. Auto-detects the `claude` binary across common locations (Homebrew ARM/Intel, ~/.local/bin) plus a CLAUDE_BIN env-var override. open-cx-deepdive.sh Path B in the workflow: skip admin chat and go straight to the CX agent Codespace (stackblitz/cx-agent). Wakes the Codespace, pulls minimal Front context for the cnv_id, builds a primer prompt with cnv_id / email / subject, copies it to the macOS pasteboard, and opens the Codespace's github.dev URL in the user's browser. The user pastes the primer into `claude` inside the Codespace to start the deep dive. Path A (inline escalation from open-cx-session.sh) is handled in ~/.claude/CLAUDE.md instructions — the local session asks before triggering open-cx-deepdive.sh on the user's confirmation. gh-cx-agent.sh Fix argument order on `gh codespace ssh`. The previous invocation passed the remote command as `-c` (treated as the codespace name selector) and the codespace name as the positional command — resulting in: getting full codespace details: HTTP 404: Not Found (.../user/codespaces/cd%20/workspaces/cx-agent%20...) Correct order: `-c CODESPACE_NAME` selects the codespace, the trailing positional is the remote command. Note: this only works end-to-end once stackblitz/cx-agent has sshd installed (separate PR opened against that repo). SETUP.md End-to-end bootstrap guide so a new teammate can stand up this stack: prereqs, secrets, Raycast registration, macOS permission grants, smoke tests, terminal selection, recommended ~/.claude/CLAUDE.md template, workflow overview, troubleshooting. Process-level guidance only — specific policy thresholds (live-session plan tier, goodwill amounts) stay in personal CLAUDE.md and team docs. README One-line pointer to SETUP.md at the top. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…P.md Makes the stack installable by another teammate. Previous SETUP.md was prereq-shaped; this turns it into a runnable bootstrap with concrete links, an opinionated workflow for skills + connectors + 1Password, and a copy-paste-able CLAUDE.md template. New files skills/bolt-qa-checker/SKILL.md skills/bolt-qa-checker/references/quality-rubric.md skills/empathy-tone-checker/SKILL.md Team's two custom CX skills committed at the repo root. Source of truth for the four-dimension rubric (Empathy & Communication, Ownership & Resolution, Technical Quality, Efficiency) and the phrase-level rewrite helper. Treat these as team-versioned — when the rubric calibrates, update here and re-run install-skills.sh everywhere. install-skills.sh Raycast-compatible installer. Copies each skill dir from this repo's skills/ into ~/.claude/skills/ so Claude Code picks them up automatically on every session start. Idempotent — re-run after pulling updates. CLAUDE.md.example Template ~/.claude/CLAUDE.md that a new teammate copies and edits. Personal bits use [PLACEHOLDERS]; universal content (tool stack, admin URLs, Bolt + Supabase staging guidance, agent picker change, Slack channels, English-only reply rule, draft-style rules) is pre-populated. Specific dollar/token thresholds intentionally deferred to team-level discussion rather than committed in plaintext. SETUP.md rewrite - Distinguish Claude Code CLI from Claude Desktop (only the CLI is required). - Reframe Notion / Slack / Linear as Claude connectors (MCP) rather than API keys. Linear/Slack keys in .env are now correctly marked optional — only consumed by customer-360's mention-scan, not the interactive workflow. - Add 1Password as the source for the shared Front API key and Stripe Keychain value (reference by item name, not deep link — repo is public). - Explicit per-key table (required/optional/where-from) instead of a prose paragraph. - Add Codespace creation step for cx-agent so first-time users land on their own Codespace rather than failing the deep-dive flow. - Updated troubleshooting and maintenance sections. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Warp's Launch Configurations path opens Warp on invocation but doesn't reliably execute the configured command in current testing (Warp lands in an empty shell with no error). Until that's worked out, switch the default spawn target to Terminal.app, which is verified working end-to-end via `do script`. Hyper remains the keystroke-based alternative. Warp branch stays in the script but is documented as experimental; set CX_TERMINAL=Warp to opt back in. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…ap script Previously the Terminal branch used osascript -> tell application Terminal -> do script. This requires Automation permission for the calling process (Raycast) to control Terminal.app — a permission most new users haven't granted, and when missing it fails silently (Terminal opens but receives no command = blank window). Switch to writing a self-cleaning bootstrap shell script to /tmp and handing it to `open -a Terminal`. `open` uses LaunchServices, not AppleScript, and doesn't need any per-app Automation permission. The bootstrap script: - cd's to the working directory - prints the [cx-session] bootstrap line for visibility - reads the prompt from the original /tmp/cx-session-prompt.XXX file - self-deletes both that prompt file and itself - execs into claude with the prompt Net effect: same UX, fewer required setup steps for new teammates, no more blank Terminal windows from Raycast. Hyper branch (keystroke automation) and Warp branch (Launch Configurations, experimental) unchanged. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

The `open -a Terminal <bootstrap-script>` approach didn't reliably execute the bootstrap script on Jorrit's Mac (Terminal opened blank). LaunchServices behavior for .sh files turns out to be too dependent on Terminal preferences and macOS version. Revert to the original osascript + `do script` approach. This requires the calling process (Raycast, your shell) to have Automation permission for Terminal in System Settings → Privacy & Security → Automation. Documented inline and in SETUP.md. For users who don't want to grant that permission, CX_TERMINAL=Hyper uses keystroke automation (different permission model — Accessibility for System Events instead of per-app Automation). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Terminal.app works via osascript do-script when the calling process has Automation permission, but Hyper is more reliably plug-and-play across fresh setups (Accessibility for System Events is broader and usually already granted for keystroke-using apps). Terminal remains a supported choice via CX_TERMINAL=Terminal. Warp stays experimental. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

install-skills.sh Previous version used `cp -R "$skill_dir" "$SKILLS_DST/"` where skill_dir ended with `/` (from the glob `*/`). On macOS that causes cp to copy the contents of the source directory, not the directory itself — so both skills ended up flattened into ~/.claude/skills/ (with SKILL.md from one overwriting SKILL.md from the other). Strip the trailing slash and use an explicit destination path per skill. After fix: ~/.claude/skills/bolt-qa-checker/SKILL.md ~/.claude/skills/bolt-qa-checker/references/quality-rubric.md ~/.claude/skills/empathy-tone-checker/SKILL.md open-cx-session.sh Prompt referenced `anthropic-skills:bolt-qa-checker` (a plugin namespace used by Claude Desktop when the skill ships as part of an anthropic-skills plugin). For user-level installs at ~/.claude/skills/<name>/, the bare name `bolt-qa-checker` is correct. Updated. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

joyict and others added 8 commits May 15, 2026 12:24

Merge remote-tracking branch 'stackblitz/main' into cx-session-and-setup

8cb85ab

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Parallel CX session workflow + SETUP.md for new teammates#3

Parallel CX session workflow + SETUP.md for new teammates#3
jorrit-stack wants to merge 8 commits into
mainfrom
cx-session-and-setup

jorrit-stack commented May 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jorrit-stack commented May 15, 2026

Summary

What's in this PR

New: open-cx-session.sh

New: open-cx-deepdive.sh

Fix: gh-cx-agent.sh ssh argument order

New: SETUP.md

Docs: README pointer

Dependencies

Test plan

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

New: `open-cx-session.sh`

New: `open-cx-deepdive.sh`

Fix: `gh-cx-agent.sh` ssh argument order

New: `SETUP.md`