execute

Respond in the user's preferred language (detect from their recent messages, or fall back to the language setting in CLAUDE.md).

Read a plan, execute it fully. Execution is always automatic — never ask "proceed?" or "start?" during implementation. The user invoked execute; that IS the go-ahead.

Live Unity editing during execution: if a plan step needs to poke the live Unity Editor (inspect a component, modify a scene object, invoke a runtime method) instead of writing new C# code, consult shared/tykit-reference.md for the command map. Use tykit commands directly via the MCP tools (unity_query, unity_object, unity_assets, unity_physics) or direct HTTP (/ping, /health, /focus-unity for recovery). Only fall back to code-writing for changes that need version control or compile-time validation.

Arguments: $ARGUMENTS

• A file path to a plan/design document
• --no-worktree: skip worktree guard
• --auto: after completion, auto-select and run the next workflow step instead of asking the user (includes push — user should be aware)
• No arguments: detect the plan source from conversation or Docs/qq/

1. Worktree Guard (strict — do NOT bypass)

Worktree isolation is non-negotiable for /qq:execute. Executing a multi-step plan directly on a shared branch pollutes main, blocks parallel work, and makes rollback surgical instead of trivial. You MUST enter a worktree unless one of these three conditions is explicitly met:

1. You are already inside a git worktree (check with git rev-parse --show-toplevel — if it matches .git/worktrees/<name>/ in the output of git worktree list, you're in one). Skip to step 2.
2. The user passed --no-worktree as a literal flag in $ARGUMENTS. Not "semantically meant" — the exact token must be present. Agent-invented --no-worktree semantics is forbidden.
3. The plan is trivially small (≤ 3 steps touching ≤ 3 files, and no .cs compilation). For anything larger, you need a worktree.

Do NOT invent other bypass conditions. If you encounter an obstacle that seems to require skipping the worktree, fix the obstacle, don't skip the safety check. Common obstacles and their correct fixes:

Obstacle	❌ Wrong reaction	✅ Correct reaction
Plan file is untracked	"switching worktree loses plan → skip worktree"	git add <plan_file> && git commit -m "docs(plan): <slug>" → now plan is in git → enter worktree → plan is visible from worktree.
Uncommitted unrelated changes in working tree	"dirty tree → can't worktree → skip"	Commit them (if related to this plan) or stash them (if unrelated). Then enter worktree. If user wants to keep them dirty, they must pass --no-worktree explicitly.
Conversation has ephemeral state (open files, scratch edits)	"would lose context → skip"	Conversation state IS lost on worktree entry by design — that's the point of isolation. Re-load plan from disk in the new session. Do not skip for this reason.
EnterWorktree tool unavailable	"no tool → skip"	Fall back to ${CLAUDE_PLUGIN_ROOT}/bin/qq-worktree.py create --name <slug>, tell the user to reopen in the new path, and stop. Don't proceed in the main dir.

The procedure:

1. Verify plan is in git. If the plan file is untracked or has uncommitted changes:

   git status -- <plan_file>
   

   If dirty, commit it now:

   git add <plan_file>
   git commit -m "docs(plan): <slug> plan document"
   

   Announce: "Committed plan doc before entering worktree so it's accessible from the new worktree."

2. Capture source state BEFORE creating the worktree (required for verification in step 5):

   SOURCE_BRANCH=$(git rev-parse --abbrev-ref HEAD)
   SOURCE_HEAD=$(git rev-parse HEAD)
   echo "Source: $SOURCE_BRANCH @ $SOURCE_HEAD"
   

   Remember these — you'll verify the new worktree inherits them.

3. Derive a slug from the plan filename (lowercase, dashes, no extension).