kc-issue

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,lint,lint_blockers}.

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.