Kc Issue

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

This is the reliable entrypoint for per-issue work — on kube-coder or any other repository checked out in the workspace. It removes the two things that made ad-hoc worktree use flaky:

1. It branches from a freshly-fetched origin/<default branch>, never a stale local HEAD.
2. The agent is launched inside its own worktree, so it starts inside its isolation and physically cannot forget to use it.

Which repository: the git checkout you run the script from (any folder in it, or one of its worktrees), or KC_REPO_ROOT=/home/dev/<repo>; the GitHub repo is read from its origin remote (KC_REPO_SLUG=owner/repo overrides). From /home/dev itself it falls back to /home/dev/kube-coder.

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,mode,repo_root,repo,slug,base_ref,lint,lint_blockers}.

mode says who makes the worktree:

• server — this workspace's dashboard creates it when the Build launches (#701), so the Build is recorded with it: its Changes tab shows the diff and push command, and Settings → Worktrees lists it. worktree is where it will be; port is empty until launch.
• script — an older workspace: the script created the worktree itself.

Step 1b — surface the issue-body lint (#569). The script lints the body before the worktree exists, because the body is baked verbatim into the agent prompt: a thin issue silently produces a thin prompt, and the cost is paid before anyone can react. Findings arrive two ways — human-readable on stderr, and structured in the JSON's lint array ({severity,code,message}).

If lint is non-empty, show the user the findings before Step 3 — a short list, one per line. Then:

• lint_blockers > 0 (today: the needs-scoping label — the repo itself saying this isn't ready to implement): stop and ask whether to proceed. Spawning on a needs-scoping issue is almost always wrong, so this is the one case where you wait for an explicit yes.
• warnings only: mention them in one line and continue. A terse issue is sometimes genuinely fine and the operator knows it — the script warns, it never blocks, and the human makes the call.

Never edit or enrich the issue body to silence a warning; the lint reports, it doesn't rewrite.

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

cat <prompt_file>

Step 3 — launch the agent with mcp__dashboard__create_task:

• prompt = the full contents of prompt_file
• assistant = claude (default)
• with mode: "server":
  • workdir = repo_root
  • isolate = true ← this is what forces isolation
  • worktree_slug = slug (so re-running an issue continues its worktree)
  • base_ref = base_ref
• with mode: "script": workdir = the worktree path ← forces isolation

A 409 whose code is busy means an agent is already working this issue in that worktree — tell the user and offer its task instead of starting another.

Step 4 — confirm & report. Tell the user: the task id, and — from the worktree object in the response (server mode) or the JSON (script mode) — the branch, the worktree path and the preview port. Offer to show live output with mcp__dashboard__get_task; the Build's Changes tab is where they review the diff and copy the push command.