Run exactly one full executor cycle for one bead, isolated in a fresh git worktree cut from the latest epic branch (epic/<epic-bead-id>), and deliver it as a PR that targets that epic branch.
This is the preferred path when an epic has its own long-lived integration branch (so the epic can land in main as one merge), each child bead should ship as its own PR into that epic branch, and the main working tree has in-flight changes that must not be touched. No WIP commit, no branch switch in the main tree — all bead work happens in a sibling worktree that is created automatically and left in place after the PR opens, so the user can return to it for review comments, screenshots, or CI fixes. Removal is a separate manual step via the cleanup-worktree skill.
-
If the current repo is not initialized for Beads, stop and tell the user to run the template bootstrap script or at minimum bd init --prefix <prefix> plus the repo scaffolding steps.
-
Determine the target bead before touching anything:
- if the user supplied a bead id in the current request, use that bead
- if the user supplied freeform selector text, treat it as a selector or hint
- otherwise inspect
bd ready --json and choose the best ready bead autonomously
- preference order: a ready bead clearly related to the current repo context or recent planner discussion, else the highest-priority ready bead
- if the choice is ambiguous, ask before proceeding
- record the chosen bead id as
<BEAD_ID> (e.g. lexify-wyk) for the rest of the flow
-
Determine the parent epic bead for <BEAD_ID>:
- if the user supplied an epic id in the current request, use that epic
- otherwise inspect the bead's dependencies (
bd show <BEAD_ID> --json and/or bd dep list <BEAD_ID>) and look for a parent dep whose target bead has --type epic
- if multiple epic parents exist, ask the user which one to target
- if no epic parent exists, stop and tell the user this skill requires the bead to be parented under an epic (or have them pass the epic id explicitly)
- record the epic bead id as
<EPIC_BEAD_ID>
-
Record <EPIC_BRANCH> as epic/<EPIC_BEAD_ID> — no slug. Using just the bead id prevents duplicate branches when different sessions derive different slugs from the same epic title.
-
Derive <TASK_SLUG> from the bead title and record <BRANCH_NAME> as feat/<BEAD_ID>-<TASK_SLUG>:
- lowercase the title
- drop file extensions (
.tsx, .ts, .py, etc.) and leading punctuation around tokens (__root.tsx → root)
- replace any non-alphanumeric run with a single
-
- drop English filler words:
the, a, an, and, or, of, to, for, in, on, with, vs, via, plus low-signal trailing words like cleanup, update, changes, work
- preserve task identifier prefixes the title carries (e.g.
t9, m3, phase2)
- keep at most 4–5 meaningful tokens, joined with
-
- trim leading/trailing
-, collapse repeated -
- target ≤ 40 characters for the slug itself; truncate the last token if needed
- example: bead
lexify-wyk titled T9 — __root.tsx wiring + Home/LoggedOut swap + cleanup → <TASK_SLUG> is t9-root-wiring-swap and <BRANCH_NAME> is feat/lexify-wyk-t9-root-wiring-swap
- if the title is too generic to yield ≥ 2 meaningful tokens (e.g.
Fix bug), fall back to <BRANCH_NAME> = feat/<BEAD_ID> and note this in the final summary
-
Do not modify the main working tree. No dirty-state check, no WIP commit, no branch switch — it stays on whatever branch it is currently on. (Step 11 below reads git-ignored .env* files out of it to seed the worktree, but never writes to it.)
-
Resolve the epic branch. Try in this order:
git rev-parse --verify <EPIC_BRANCH> (local)git ls-remote --exit-code --heads origin <EPIC_BRANCH> (remote)- record whether the epic branch exists locally, only remotely, or not at all
- if it exists nowhere, this skill will create it from the latest default branch in step 9. Detect the default branch first: use
git symbolic-ref refs/remotes/origin/HEAD if present; otherwise fall back to main if it exists, else master. Record as <DEFAULT_BRANCH>. Note in the final summary that the epic branch was created.
-
Determine the worktree path. Always use just the bead id as the path suffix (no task slug) so paths stay short and predictable:
REPO_NAME=$(basename $(git rev-parse --show-toplevel))
WORKTREE_PATH="../${REPO_NAME}-feat-${BEAD_ID}"
-
Make sure the epic branch exists on origin so the worktree can be cut from it cleanly. Use whichever path matches step 7:
- exists on origin:
git fetch origin <EPIC_BRANCH>
- exists only locally: push it so the worktree can branch from
origin/<EPIC_BRANCH> (do not move the local ref):
git push -u origin <EPIC_BRANCH>:<EPIC_BRANCH>
git fetch origin <EPIC_BRANCH>
- does not exist anywhere: create it from the latest default branch without disturbing the main tree, then push it. Use a temporary worktree-free branch creation via
git branch (which does not touch the working tree):
git fetch origin <DEFAULT_BRANCH>
git branch <EPIC_BRANCH> origin/<DEFAULT_BRANCH>
git push -u origin <EPIC_BRANCH>
git fetch origin <EPIC_BRANCH>
-
Create the worktree on a new branch off the freshly fetched epic branch:
git worktree add <WORKTREE_PATH> -b <BRANCH_NAME> origin/<EPIC_BRANCH>
- If
<BRANCH_NAME> already exists locally, stop and ask the user whether to reuse, rename, or delete it.
- If
<WORKTREE_PATH> already exists on disk, stop and ask the user.
-
Seed git-ignored local env files into the worktree — REQUIRED before build-and-test. A fresh worktree checks out only tracked files, so git-ignored local config the build needs — .env.local, .env, and the rest of the .env* family — is absent, and build-and-test would otherwise run against a worktree with no environment. Do this up front and unconditionally; do NOT skip or defer it on the assumption that build-and-test will synthesize a default environment — seed first, then let build-and-test verify, regardless of whether you believe the build needs the env. Copy those files (and only those) from the main checkout into the worktree, preserving relative paths. Run this from the main checkout (<MAIN_ROOT> = its root, git rev-parse --show-toplevel); it reads from the main tree but never writes to it:
git -C <MAIN_ROOT> ls-files --others --ignored --exclude-standard --directory \
| grep -E '(^|/)\.env(\.[^/]*)?$' \
| while IFS= read -r f; do
mkdir -p "<WORKTREE_PATH>/$(dirname "$f")"
cp -p "<MAIN_ROOT>/$f" "<WORKTREE_PATH>/$f"
done
--directory collapses fully-ignored directories (node_modules/, dist/, .beads/, *.db) to a single entry so the grep skips them — only .env* files are copied, never dependencies or build output. cp -p preserves the source permissions (env files are often 600).- Always run the detection command; only treat this as a no-op when its actual output is empty. Never pre-judge that no
.env* files exist because the worktree looks build-ready (.env.example is tracked and proves nothing).
- This
.env* seed is the up-front, non-negotiable part. Separately, if build-and-test later fails because some other git-ignored config is missing (e.g. .dev.vars, a local service-account JSON), copy that one file the same way — but that reactive copy never replaces the up-front .env* seed above. Do not bulk-copy all ignored files.
-
Run the executor cycle for <BEAD_ID> — every step in order, operating inside <WORKTREE_PATH>:
beads-claimwriting-plans- implementation
systematic-debugging if blockedbuild-and-test — REQUIRED after implementation. Read the repo-local skill from the worktree (.claude/skills/build-and-test/SKILL.md for Claude sessions; .codex/skills/build-and-test/SKILL.md when running under Codex) and follow it. Do NOT skip this step.verification-before-completion (run the verification commands)requesting-code-review (dispatch the code-reviewer subagent; required, not optional)beads-close
-
If separate work is discovered, create follow-up beads during execution or before close. Keep this worktree scoped to <BEAD_ID> only.
-
If a blocker appears, update the current bead, summarize the blocker, and stop. Report the worktree path so the user can return to it. The worktree is never removed automatically — use the cleanup-worktree skill when ready to discard it.
-
If build/test fails and the fix is still in scope, return to implementation and retry.
-
After successful close, finalize the branch from within <WORKTREE_PATH> following the finishing-a-development-branch skill:
- verify clean tree and commits ahead of
<EPIC_BRANCH> (not main)
git push -u origin HEADgh pr create --base <EPIC_BRANCH> --title "<conventional-commit title>" --body "..." — the PR body must include both an Epic: <EPIC_BEAD_ID> line and a Bead: <BEAD_ID> reference line (e.g. Bead: lexify-a8m). The title follows conventional commits format (type(scope): description) with no bead id prefix.- report the PR URL
-
Stop with a concise summary: bead id, epic id, <EPIC_BRANCH> (PR base), <BRANCH_NAME>, PR URL, and the worktree path (so the user can cd back in for follow-up work). The main working tree was never modified. Note if the epic branch was created by this run. The worktree is left in place — use the cleanup-worktree skill to remove it once review comments, screenshots, and CI fixes are done.
