assay-worktrees
Skill0 starsChanged 3 days agoApache-2.0View on GitHub
Isolate parallel work in the Assay repo using the Claude Code worktree layout. Use when starting a new bug/feature that should not collide with another running Claude session. Covers branch naming, worktree placement under .claude/worktrees, per-worktree uv setup, and cleanup.
- Reads credentials
In this repository10 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- assay-begin-fastSkill
- assay-beginSkill
- assay-end-fastSkill
- assay-endSkill
- assay-nextSkill
- assay-reportSkill
- prd-generatorSkill
- prd-interviewSkill
- tech-planSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
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
- Distinctive: line 16
Don't use this for one-off file edits that finish in a single session.
- Very specific: line 29
Verify ignore status any time: git check-ignore -v '.claude/worktrees/' (keep the trailing slash — a bare .claude/worktrees reports "not …
- Very specific: line 47
Prefer origin/master (shared truth.
- Very specific: line 73
No secrets/env files exist yet — the repo is docs-only.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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
Assay Worktree Workflow
When to Use
- Another Claude session is running on a different branch in Assay and you want to start a new bug/feature without colliding.
- You want to run two branches side by side.
- The primary checkout is dirty and switching branches would mix work.
Don't use this for one-off file edits that finish in a single session.
Layout — the official Claude Code pattern
Assay is a single repo. Worktrees live inside it at .claude/worktrees/<name>/.
.claude/worktrees/ is already in .gitignore.
/Users/aliz/dev/at/assay/ ← primary (master)
/Users/aliz/dev/at/assay/.claude/worktrees/bug-12/ ← bug #12 worktree
/Users/aliz/dev/at/assay/.claude/worktrees/feat-skill-ingest/Verify ignore status any time: git check-ignore -v '.claude/worktrees/' (keep the
trailing slash — a bare .claude/worktrees reports "not ignored" when the directory
doesn't exist yet, which is a false alarm, not a missing rule).
Branch naming convention
<type>/<id>/<owner> — owner is aliz. id is a GitHub issue number when there is
one, otherwise a short descriptive slug.
bug/12/alizfeat/skill-ingest/alizchore/pin-uv-version/aliz
Worktree dir name drops the slashes: <type>-<id> (e.g. bug-12, feat-skill-ingest).
The base branch is master
Assay's base branch is master. The remote is git@github.com:haqaliz/assay.git.
Prefer origin/master (shared truth; the local ref may be stale), falling back to
local master only if the remote ref isn't fetched:
git fetch origin master
git worktree add -b feat/skill-ingest/aliz .claude/worktrees/feat-skill-ingest origin/master
# fallback if the remote ref isn't fetched
git fetch origin master
git worktree add -b feat/skill-ingest/aliz .claude/worktrees/feat-skill-ingest origin/masterCreating a worktree
# from an existing branch you already pushed
git worktree add .claude/worktrees/feat-skill-ingest feat/skill-ingest/aliz
# via Claude Code's --worktree flag
claude --worktree feat-skill-ingestThe --worktree flag names the branch worktree-feat-skill-ingest, which won't match
your issue/slug naming — create the branch first, then git worktree add with it.
Auto-copying gitignored config (.worktreeinclude)
No secrets/env files exist yet — the repo is docs-only. Once a .env exists for BYOK
keys, create .worktreeinclude and list it, then copy manually for bare git worktree
add (the include only runs via claude --worktree):
cp .env .claude/worktrees/feat-skill-ingest/ # only once such a file existsNever copy captured sandbox traces, findings, or corpus cases between worktrees. They are run state tied to the run that produced them.
Per-worktree setup (Python core — uv)
cd .claude/worktrees/feat-skill-ingest
uv sync
uv run pytest
uv run assay --help⚠️ Greenfield caveat: no pyproject.toml, no uv.lock, no src/ yet. uv sync
fails until the Python core is scaffolded. If your work is the scaffolding, the
failing test comes first. Skip this section for docs-only work.
Switching between worktrees
git -C /Users/aliz/dev/at/assay worktree listCleaning up
git -C /Users/aliz/dev/at/assay worktree remove .claude/worktrees/feat-skill-ingest
git -C /Users/aliz/dev/at/assay branch -d feat/skill-ingest/alizCommon pitfalls
| Symptom | Cause | Fix |
invalid reference: origin/master | Remote not fetched, or doesn't exist yet | Branch from local master until a remote exists |
Branching from master | Assay's base branch is master | Use master |
| Worktree contents appear untracked in primary | .claude/worktrees/ not ignored | Already in .gitignore; verify with trailing slash |
uv sync fails: no pyproject.toml | Core not scaffolded (greenfield) | Expected — scaffold it test-first, or skip for docs-only work |
git worktree add fails: "already checked out" | Branch checked out elsewhere | git checkout master in the conflicting worktree, retry |
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.

