// Work in an isolated git worktree for issues, features, or refactors. Use when the user asks to spin up a worktree, work in isolation, create an isolated branch, or says "worktree" in the context of starting work on something.
| name | worktree |
| description | Work in an isolated git worktree for issues, features, or refactors. Use when the user asks to spin up a worktree, work in isolation, create an isolated branch, or says "worktree" in the context of starting work on something. |
Work on a task in an isolated git worktree with its own Lookbook instance.
Use the EnterWorktree tool to create and switch into a worktree. Name it
after the task when possible:
EnterWorktree(name: "fix-button-hover")
This creates a worktree in .claude/worktrees/, creates a branch based on
HEAD, and switches your working directory into it.
Start Lookbook on the worktree's assigned port:
bin/worktree start
This daemonizes Lookbook + Tailwind and returns immediately. The port is deterministic (based on worktree name, range 4101-4600) and printed to stdout.
Print the URL for the user:
Lookbook → http://localhost:<port>/lookbook
Useful commands while working:
bin/worktree port # Show the assigned port
bin/worktree status # Check if services are running
bin/worktree stop # Stop services (do this at the end)
Work on the task. For component work, follow the contributing skill
(.claude/skills/contributing/SKILL.md) for conventions.
The worktree already has its own branch (created by EnterWorktree). Commit
to the current branch — do NOT create a new branch:
git add [specific files]
git commit -m "feat: description (#N)"
Run lint and tests before committing:
bundle exec standardrb --fix
bundle exec rake test
git push -u origin $(git branch --show-current)
Create the PR. Include Closes #N in the body if working on an issue:
gh pr create --title "<title>" --body "$(cat <<'EOF'
## Summary
- [what was done]
Closes #N
## Test plan
- [ ] Visual review in Lookbook
EOF
)"
Print the PR URL for the user.
Print the Lookbook URL so the user can review visually:
Lookbook → http://localhost:<port>/lookbook/inspect/kiso/<component>/playground
PR → https://github.com/steveclarke/kiso/pull/<number>
Stop Lookbook when the user is done reviewing:
bin/worktree stop
On session exit, Claude Code will prompt the user to keep or remove the worktree.
Build UIs with Kiso — accessible Rails UI components with Tailwind CSS theming. Use when creating interfaces, customizing themes, building forms, or composing page layouts in Rails + Hotwire apps.
Kiso component conventions and development workflow. Points to the right docs for building, reviewing, and shipping components.
Audit all documentation for staleness after code changes. Checks docs site, CLAUDE.md, skills references, contributing skill, agents, and project/ files. Use after completing a feature, merging a PR, or when asked to check docs.
Guide through releasing a new version of kiso. Use when cutting a release, publishing a new version, or running bin/release.
Build a Kiso component from scratch. Reads shadcn/Nuxt UI sources, creates theme module, ERB partials, Lookbook previews, docs, E2E tests. Use when building a new component or picking up where a previous attempt left off.
Review a Kiso component for quality and consistency. Runs the 12-point checklist against shadcn source, design system rules, and deliverables. Use on a PR, branch, or working directory.