bridge-ship
Skill7 starsChanged 8 days agoMITView on GitHub
Use when a change to this repo needs to actually run — after editing anything under bridge/, or when the user says "restart the bridge", "is it live", "ship it", "go live", "rebuild the dashboard", or reports that a fix you already made isn't working. Covers the dashboard's ⟳ go-live button, the build/restart/verify loop, and the ways restarting from inside a bridge session kills your own turn.
In this repository27 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- accessibility-auditSkill
- algorithmic-artSkill
- api-docsSkill
- beautiful-shadowsSkill
- brainstormingSkill
- bridge-eyesSkill
- bridge-feature-sliceSkill
- bridge-worktreeSkill
- changelogSkill
- color-paletteSkill
- content-strategySkill
- design-firstSkill
- design-implementSkill
- design-reviewSkill
- design-tokensSkill
- emil-design-engSkill
- empty-statesSkill
- frontend-designSkill
- landing-pageSkill
- micro-interactionsSkill
- mystical-assistant-designSkill
- ogilvy-copywritingSkill
- onboarding-guideSkill
- typography-scaleSkill
- visual-style-presetsSkill
- writing-guidelinesSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 60
If mystical status showed no systemd line (hand-launched bridge), setsid is enough:
- Distinctive: line 70
Commit first — an uncommitted edit plus a restart is how work gets lost.
- Very specific: line 87
Don't kill a launchd bridge to stop it — KeepAlive relaunches a crash.
- Distinctive: line 132
Don't claim it works because the file changed.
- Very specific: line 149
After the session resumes: mystical status + one real check that the new behaviour is present.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Shipping a change to the running bridge
Committed is not live. The bridge process holds the code it was launched with. Python edits need a restart; web edits need a rebuild and a restart to be served. A user testing "your fix" against the old process is the single most expensive failure mode in this repo — it looks like the fix didn't work.
Usually: the user goes live, not you
The dashboard's right rail shows ⟳ above the changelog whenever this checkout holds
code that isn't running: a web app built before its latest change, or a bridge launched
before its latest Python (GET /local/live, bridge/selfupdate.py live()). Its card
rebuilds what's behind and restarts the bridge (REBUILD & RESTART), or waits for the
running turns to end (AFTER N TURNS).
So once your change is merged on master and the suite is green, don't ask when to ship and don't build or restart anything yourself. End your reply by saying it's on master and the user can press ⟳ on the right rail to go live, and name what that does (rebuilds the dashboard, restarts the bridge). Use the paths below only when the user asks you to ship it yourself, or isn't on the dashboard (a Telegram-origin session).
Before you touch anything: who is supervising?
mystical statussupervised systemd in the output means the user unit
(mystical-assistant.service) owns the process. That changes how you restart.
The trap: you are inside the thing you are restarting
A Claude session hosted by the bridge is a child of the bridge process and shares its cgroup:
cat /proc/self/cgroup # .../app.slice/mystical-assistant.serviceThe unit is KillMode=mixed: systemctl --user stop SIGTERMs the bridge, which
stops its own Claude children, then SIGKILLs every process left in the cgroup
once the bridge has exited. That includes your session — and it includes any
setsid child you spawn to do the restart, because setsid escapes the process
group, not the cgroup. Restart naively and you get: bridge stopped, restarter
dead, nothing comes back up.
Escape the cgroup with a transient unit:
systemd-run --user --quiet --collect --unit=bridge-restart-$$ \
bash -c 'sleep 2; systemctl --user restart mystical-assistant.service'If mystical status showed no systemd line (hand-launched bridge), setsid is
enough:
setsid bash -c 'sleep 2; mystical restart' >/dev/null 2>&1 &Either way your turn dies when the bridge goes down. That is expected and
recoverable: bridge/recovery.py claims orphaned turns at boot and resumes the
resumable ones with --resume and a "you were interrupted, continue" nudge.
Commit first — an uncommitted edit plus a restart is how work gets lost.
Tell the user before you do it. Losing the turn mid-conversation is surprising unless they asked for the restart.
macOS: launchd instead of systemd
mystical status showing supervised launchd means the LaunchAgent
cloud.ainurhq.mystical.bridge owns the bridge. There's no cgroup: launchd
kills the job's process group, which your session is in. But
mystical restart there is launchctl kickstart -k, and launchd itself does
the kill and the relaunch, so the restart lands even though your turn dies:
mystical restart # under launchd: safe to call from inside a sessionDon't kill a launchd bridge to stop it — KeepAlive relaunches a crash. Stop
is launchctl bootout (what mystical stop does). Hand-launched (no
supervised line) on a Mac: no setsid binary exists, so detach with
nohup bash -c 'sleep 2; mystical restart' >/dev/null 2>&1 &.
Mystical.app is a separate process and survives all of this. It's built from
a checkout (MysticalRepo in its Info.plist), so rebuild it with mystical app
from master after merging app changes; macos/probe.sh shows you what it shows.
Windows (WSL): Mystical.exe
Mystical.exe is a Windows process outside the bridge's cgroup, so a bridge
restart never touches it, and mystical app from inside a bridge session is
safe: windows/build.sh builds on the Windows side with dotnet.exe, quits the
running exe over its pipe, swaps the files in %LOCALAPPDATA%\Programs\Mystical
and reopens it. It's built from a checkout (mystical.json beside the exe names
it), so rebuild it with mystical app from master after merging app changes;
windows/probe.sh shows what it shows and windows/capture.sh what the screen
shows. Launch a Windows GUI exe from WSL with PowerShell's Start-Process,
never cmd.exe /c start — that one waits for its child and hangs your turn.
Web bundles
dist/ is git-ignored and nothing is committed, so a surface with no bundle
serves nothing — not a stale page, a 404.
mystical build # forces all three: dashboard, Mini App, sitemystical start builds only what looks stale (source newer than
dist/index.html), and reinstalls deps when package-lock.json is newer than
node_modules/.package-lock.json. Every vite build also stamps dist/.built with
the tree it was built from (the builtFrom plugin in each vite.config.ts); ⟳
diffs that against the checkout, so a bundle copied in from a worktree build
reads correctly too. Build output goes to
~/.bridge_state/mystical.log, not your terminal — read it there when a build
fails.
Building in a worktree does not work out of the box: worktrees have no
node_modules. Symlink the launch checkout's, build, then remove the symlink
(it is not gitignored at that path).
Verify it is actually live
Don't claim it works because the file changed. Pick the cheapest real check:
mystical status # process up, all three ports 2xx
curl -s 127.0.0.1:8790/local/state | head -c 300 # a route answering with new data
tail -30 ~/.bridge_state/mystical.log # start-up errorsFor frontend changes, look at the pixels — see the bridge-eyes skill.
Order of operations
python3 -m pytest tests/ -q— green before you restart anything.- Commit.
- Merged on master: tell the user to press ⟳ (above). Only when shipping it yourself:
mystical buildif anyweb/orsite/source changed.- Restart via the transient unit above; warn the user first.
- After the session resumes:
mystical status+ one real check that the new behaviour is present.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

