Running Ruby + RSpec for Bike Index
Read the reference for the path you're in; the others don't apply.
| Path | Environment | Read |
|---|
/Users/…/conductor/workspaces/… | local macOS Conductor workspace | references/local-macos.md |
…/.claude/worktrees/… | spawned git worktree — set it up first, below | references/local-macos.md |
/home/user/bike_index ($CLAUDE_CODE_REMOTE=true) | Claude Code web sandbox | references/web-sandbox.md |
A spawned worktree sets itself up first
Before the first rspec, bundle, bin/lint, bin/env or dev server:
bin/workspace_setup --without_seeds
The SessionStart hook .claude/hooks/worktree-setup.sh runs this on a worktree's
first session, so a .workspace_id is usually already there. When it isn't, the
hook's output went to tmp/workspace_setup.log; read that, then run the command by hand.
When Claude Code removes the worktree, .claude/hooks/worktree-teardown.sh runs
bin/workspace_teardown to drop its databases, then git worktree remove. One with
uncommitted changes stays, databases and all.
It allocates an ID from the dev_workspaces registry, writes .workspace_id, and runs
bin/setup, which creates this workspace's databases and builds the CSS. Run bundle exec rails db:seed when you need records. node_modules starts as a clone of the root
checkout's, so npm install only fetches what this branch changed.
Never write .workspace_id yourself — bin/workspace_setup then skips allocation,
leaving an ID the registry never handed out. And skipping setup entirely silently falls
back to DEV_PORT=3042 and Redis db 0: the main checkout's port, database and cache —
and a bin/setup from there loads the schema over the main checkout's database.
Build the CSS (every environment)
AssetNotFound from any spec that renders the layout (an html request spec, any :js
spec) means app/assets/builds/tailwind.css is missing — a checkout where neither
bin/setup nor bin/dev has run. It isn't pre-existing; build it. The asset "email.css" is not present (anything rendering an email, including db:seed) is the
SCSS half:
bundle exec rails tailwindcss:build dartsass:build
A stale public/assets shadows your JavaScript
Any bin/turbo_tests or assets:precompile run leaves public/assets/.sprockets-manifest.json,
and the test environment serves controllers/**/*.js from it. So a :js spec runs the
old Stimulus controller and fails as if your change were wrong, while bin/dev works.
Confirm, then rm -rf public/assets (gitignored, no need to ask):
grep -o "controllers/[a-z_/]*controller[^\"]*" public/assets/.sprockets-manifest.json | head
Every :js spec failing in Playwright setup means node_modules lags the gem
playwright-ruby-client drives the playwright npm package, and a merge from main
bumps both together. Until npm install catches up, every :js example fails in
spec/support/capybara.rb with Playwright::Error: timeout: expected float, got undefined, which names neither version. Compare node -e 'console.log(require("playwright/package.json").version)' with package.json's pin,
then npm install && npx playwright install chromium.
Who starts bin/dev
Where a human works — a Conductor workspace, the main checkout — ask (AGENTS.md). In a
spawned worktree or the web sandbox, the checkout is yours: start it yourself.