Skills: add /scan-board JIRA board scanning skill

[rahmanunver]

Add /scan-board skill

Turns a Jira ticket into a ready-to-work worktree with a validated plan. Stops before writing code.

Why

Starting a ticket is the same six steps every time: open Jira, read it, figure out which repo it belongs to, make a branch, make a worktree, write a spec. This does all of it in one command, and because every ticket lands in its own worktree, several can be in flight at once without stepping on each other.

Usage

Command	What it does
/scan-board	lists your In Progress tickets, you pick one
/scan-board WC-1234	goes straight to that ticket
/scan-board Samuel	scans a teammate's board

One-time setup on first run: a Jira API token in your keychain. The skill walks you through it.

Example

▎ /scan-board

Your In Progress tickets:
WC-3516 Support-ticket Calendar year view drops the last week of December
WC-3402 Bug Combobox clears selection on blur

▎ WC-3516

Ticket WC-3516 — Calendar year view drops the last week of December
Repo web-widgets (component: calendar (widget))
Worktree ../worktrees/web-widgets-wc-3516
Branch wc-3516/year-view-last-week
Spec openspec/changes/fix-year-view-week-boundary/
Zendesk 1 linked ticket, not accessible from here paste any repro if you have one
Next /openspec-apply to implement

What it does not do

• No code, no commits, no pushes, planning only
• No Zendesk access. It only tells you linked tickets exist, so you know extra context is out there.
• Only asks you a question when the ticket is genuinely ambiguous. Otherwise it just reports and stops.

[github-actions]

AI Code Review

⚠️ Approved with suggestions — low-severity items only, safe to merge

---

What was reviewed

File	Change
.agents/skills/scan-board/SKILL.md	New skill definition for /scan-board — full Jira-to-worktree workflow
.agents/skills/README.md	Registry entry added for scan-board

Skipped (out of scope): dist/, pnpm-lock.yaml

All CI checks: could not retrieve status (permission prompt declined); no widget code changed so lint/unit/E2E are not applicable.

---

Findings

⚠️ Low — read flag syntax is zsh-only

File: .agents/skills/scan-board/SKILL.md line 57
Note: The token-setup step uses read -r -s "JIRA_TOKEN?Paste the full Jira token: " — the "var?prompt" form works in zsh but not in bash. If a developer's default shell (or any non-interactive shell invoked by an agent) is bash this silently sets JIRA_TOKEN to an empty string, producing an opaque 401 at the auth check.
Fix: Use the portable form:

printf 'Paste the full Jira token: '
read -r -s JIRA_TOKEN
printf '\n'

---

⚠️ Low — JIRA_SERVER sed expression is fragile on non-GNU sed

File: .agents/skills/scan-board/SKILL.md line 94
Note: The one-liner sed 's/.*"cloudId":"\([^"]*\)".*/\1/' relies on the entire JSON being on one line and on basic-regex capturing groups. macOS ships BSD sed where this works, but the expression is sensitive to whitespace in the JSON response. A more robust alternative:

curl -s https://mendix.atlassian.net/_edge/tenant_info | python3 -c "import sys,json; print(json.load(sys.stdin)['cloudId'])"

python3 is available on every macOS developer machine and handles pretty-printed or compact JSON equally.

---

⚠️ Low — worktree symlink fallback points at .claude/skills, not .agents/skills

File: .agents/skills/scan-board/SKILL.md line 227
Note: The fallback creates ln -s "$REPO/.claude/skills" "$WT/.claude/skills". In the current repo .claude/skills is itself a symlink to ../.agents/skills, so this resolves correctly — but only because that indirection already exists. If .claude/skills is ever removed or restructured, the fallback silently creates a dangling symlink. Pointing directly at the canonical location is more resilient:

ln -s "$REPO/.agents/skills" "$WT/.agents/skills"
# and optionally alias: ln -s "../.agents/skills" "$WT/.claude/skills"

---

Positives

• The prerequisite check sequence (skill → CLI → keychain) is front-loaded and explicit — agents can't accidentally skip a dependency and get a mysterious 401 later.
• The JIRA_SERVER explanation (site host vs. gateway host, why mendix.atlassian.net returns misleading 404s) is unusually thorough and will save significant debugging time for anyone who hits the gotcha.
• Token handling avoids echoing: read -s, unset JIRA_TOKEN after storing, and the explicit "Never echo the token" instruction on the failure path are all correct practices.
• The gate section has well-defined, non-overlapping trigger conditions — "A Zendesk badge count is never a trigger" prevents the guard from collapsing into an unconditional prompt on support tickets.
• The spec-validation gate ("every acceptance criterion must map to a task") closes the loop between planning and execution with a concrete completion criterion.