bikeindex/bike_index / .claude/skills/sandbox-test-setup
sandbox-test-setup
VerifiedBike Index Ruby + RSpec environment setup for each place this repo runs: a local macOS Conductor workspace, a spawned `.claude/worktrees/…` git worktree, and Claude Code's Linux web sandbox — getting `ruby`, `bundle`, `bin/lint`, a database, seeds, a dev server and a browser working there. **Read it before the first command in a spawned worktree**, which starts with `bin/workspace_setup` (without it `bin/env` hands back the main checkout's port, database and Redis). Read it whenever a session runs RSpec, `bundle` or `bin/lint`, needs a dev server or seeded data, or hits: a missing `.workspace_id` or `node_modules`, a `$BASE_URL` serving another branch, `Could not find 'bundler' (4.0.x)`, `command not found: rspec`, `uninitialized constant Pathname` or `undefined method 'intersect?' for Array` from a `bin/` script, `Sprockets::Rails::Helper::AssetNotFound`, `tailwind.css is not present`, `LoadError: Could not open library 'vips.so.42'`, `executable not found: "identify"`, or a Playwright browser-not-found, build-number mismatch, `Playwright::Error: timeout: expected float, got undefined` or `Running as root without --no-sandbox is not supported`. The fix is almost never a reinstall or a Gemfile edit — it's a PATH, an env var, or a service that isn't running.
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |