kc-issue

name	kc-issue
description	Spin up an isolated agent to work a kube-coder issue. Given an issue number, creates a clean git worktree branched from a freshly-fetched origin/main, pulls the issue text, and launches a background Claude task that is BORN inside that worktree (workdir=worktree) so it cannot work in the shared clone. Use whenever the user wants to "work on issue N", "start an agent on issue N", or set up a per-issue worktree. Also lists issue worktrees and their task status.
user-invocable	true
allowed-tools	Bash, Read, mcp__dashboard__create_task, mcp__dashboard__list_tasks, mcp__dashboard__get_task
argument-hint	<issue-number> [--pr] | list | <slug> "free text"

kc-issue — one issue, one clean worktree, one agent

This is the reliable entrypoint for per-issue work on kube-coder. It removes the two things that made ad-hoc worktree use flaky:

1. It branches from a freshly-fetched origin/main, never a stale local HEAD.
2. It launches the agent with workdir = the worktree, so the agent starts inside its isolation and physically cannot forget to use it.

The heavy lifting is in kc-issue.sh next to this file. It does the git/fs part and prints JSON; you (the assistant) do the launch via create_task.

Do this when invoked

list — show existing issue worktrees + task status

bash "$CLAUDE_SKILL_DIR/kc-issue.sh" list

Then call mcp__dashboard__list_tasks and correlate by worktree/branch so the user sees which issues have a live agent.

<issue-number> (optionally --pr) — start an agent on an issue

Step 1 — create/reuse the worktree and get the prompt. If the user passed --pr (auto-open a PR when done), set KC_AUTO_PR=1:

# without --pr (default: preflight then STOP for review):
bash "$CLAUDE_SKILL_DIR/kc-issue.sh" <N>
# with --pr (preflight, push, open PR):
KC_AUTO_PR=1 bash "$CLAUDE_SKILL_DIR/kc-issue.sh" <N>

Capture the JSON it prints on stdout: {issue,title,url,worktree,branch,port,prompt_file,auto_pr}.

Step 2 — read the baked prompt (do NOT reconstruct it — use the file):

cat <worktree>/.kc-issue-prompt.md

Step 3 — launch the agent with mcp__dashboard__create_task:

• prompt = the full contents of .kc-issue-prompt.md
• workdir = the worktree path from the JSON ← this is what forces isolation
• assistant = claude (default)

Step 4 — confirm & report. Tell the user: the task id, the branch, the worktree path, and the preview port. Offer to show live output with mcp__dashboard__get_task. If they want to embed a preview once a dev server is up, use the port at /api/app-proxy/<port>/.

<slug> "free text" — ad-hoc (no GitHub issue)

Same flow; the description text is used in place of an issue body.

Notes & footguns

• The launched agent, not you, does the work. Your job is only to set up the worktree and launch. Don't start editing repo files in this chat.
• The agent runs inside the repo, so from its cwd the repo skills (worktree, kc-preflight, kc-ship-pr) ARE in scope — the baked prompt tells it to use them. (Those skills are NOT in scope for you at /home/dev, which is why this orchestration skill lives in the user-global skills dir.)
• Idempotent. Re-running for the same issue reuses the existing worktree + branch and rewrites the prompt; it won't clobber committed work.
• Cleanup when done (after the PR merges): remove the worktree dir but keep history via the repo's worktree helper:

  bash /home/dev/kube-coder/.claude/skills/worktree/worktree.sh rm issue-<N>
  git -C /home/dev/kube-coder branch -D kc/issue-<N>   # after merge only
  

• Disk. Each worktree gets its own node_modules/build output — keep only a handful live at once; tear down finished ones.

Parallel: several issues at once

Just invoke this once per issue. Each gets its own worktree, branch, port, and background task, so agents run truly in parallel without colliding. Use list to keep track.