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.

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 <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 — and it is linted the same way. This path is more exposed than the issue path: a one-line --desc becomes the entire specification the agent ever sees, so take its warnings seriously.

lint [file] — check a body without spawning anything

bash "$CLAUDE_SKILL_DIR/kc-issue.sh" lint path/to/draft.md   # or pipe on stdin

Touches no git, no GitHub, no worktree. Findings print on stderr, JSON on stdout; exits 1 on a blocker. Useful for sanity-checking a draft issue before filing it, and it's what lint_test.sh drives.

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.
• The lint warns, it never blocks. Default behaviour always proceeds. Set KC_ISSUE_STRICT=1 to make the script refuse to spawn when a blocker fires — it exits before creating the worktree, so nothing is spent. Leave it unset unless you want that guardrail.

  KC_ISSUE_STRICT=1 bash "$CLAUDE_SKILL_DIR/kc-issue.sh" <N>
  

• Lint runs at spawn time, not issue-creation time. That's deliberate: it's the cheaper place to catch the problem, and it also covers issues written before the lint existed.
• 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.