chief-clancy 0.1.0

package/src/commands/once.md

@@ -0,0 +1,13 @@
+# /clancy:once
+
+Pick up exactly one ticket from your Kanban board, implement it, commit, squash-merge, and stop.
+
+Good for:
+- Your first run — watch Clancy work before going AFK
+- Testing after changing .clancy/docs/ or CLAUDE.md
+- Debugging a specific ticket
+- When you only have time for one ticket
+
+@.claude/clancy/workflows/once.md
+
+Run one ticket as documented in the workflow above.

package/src/commands/review.md

@@ -0,0 +1,9 @@
+# /clancy:review
+
+Fetch the next ticket from the board and score it — returns a confidence score (0–100%) and actionable recommendations before you run.
+
+Does not implement anything. Read-only from Clancy's perspective, though it invokes Claude for analysis.
+
+@.claude/clancy/workflows/review.md
+
+Score the ticket as documented in the workflow above, including the full 7-criterion rubric and confidence bands.

package/src/commands/run.md

@@ -0,0 +1,11 @@
+# /clancy:run
+
+Run Clancy in loop mode — processes tickets from your Kanban board until the queue is empty or MAX_ITERATIONS is reached.
+
+Usage:
+  /clancy:run       — uses MAX_ITERATIONS from .clancy/.env (default 5)
+  /clancy:run 20    — overrides MAX_ITERATIONS to 20 for this session only
+
+@.claude/clancy/workflows/run.md
+
+Run the loop as documented in the workflow above. The numeric argument (if provided) is session-only and never written to .clancy/.env.

package/src/commands/settings.md

@@ -0,0 +1,7 @@
+# /clancy:settings
+
+View and change Clancy configuration without re-running init.
+
+@.claude/clancy/workflows/settings.md
+
+Run the settings workflow as documented above.

package/src/commands/status.md

@@ -0,0 +1,9 @@
+# /clancy:status
+
+Show the next tickets Clancy would pick up — read-only board check, no side effects.
+
+Fetches up to 3 tickets from the queue using the same query as /clancy:once, so what you see here is exactly what Clancy would run next.
+
+@.claude/clancy/workflows/status.md
+
+Show status as documented in the workflow above. Strictly read-only — no git operations, no file writes, no ticket claiming.

package/src/commands/uninstall.md

@@ -0,0 +1,5 @@
+/clancy:uninstall
+
+Remove Clancy's slash commands from this project or your global Claude Code installation.
+
+@.claude/clancy/workflows/uninstall.md

package/src/commands/update-docs.md

@@ -0,0 +1,9 @@
+# /clancy:update-docs
+
+Incrementally refresh .clancy/docs/ — re-runs only the agents covering areas that have changed since the last scan.
+
+Faster than a full map-codebase when you've made targeted changes (new dependency, design system update, new test strategy, etc.).
+
+@.claude/clancy/workflows/update-docs.md
+
+Run the incremental update as documented in the workflow above.

package/src/commands/update.md

@@ -0,0 +1,9 @@
+# /clancy:update
+
+Update Clancy itself to the latest version via npx and show what changed.
+
+This re-runs the installer, which copies the latest command files from the npm package into your .claude/commands/clancy/ directory. Your .clancy/ project folder (scripts, docs, progress log) is never touched.
+
+@.claude/clancy/workflows/update.md
+
+Run the update as documented in the workflow above.

package/src/templates/.env.example.github

@@ -0,0 +1,43 @@
+# Clancy — GitHub Issues configuration
+# Copy this file to .env and fill in your values.
+# Never commit .env to version control.
+
+# ─── GitHub Issues ────────────────────────────────────────────────────────────
+GITHUB_TOKEN=ghp_your-personal-access-token
+GITHUB_REPO=owner/repo-name
+
+# Optional: only pick up issues with this label (in addition to 'clancy').
+# Useful for mixed backlogs where not every issue is suitable for autonomous implementation.
+# Create the label in GitHub first, then add it to any issue you want Clancy to pick up.
+# CLANCY_LABEL=clancy
+
+# ─── Git ──────────────────────────────────────────────────────────────────────
+# Base integration branch. Clancy branches from here when an issue has no milestone.
+# When an issue has a milestone, Clancy auto-creates milestone/{slug} from this branch.
+CLANCY_BASE_BRANCH=main
+
+# ─── Loop ─────────────────────────────────────────────────────────────────────
+# Max tickets to process per /clancy:run session (default: 20)
+MAX_ITERATIONS=20
+
+# ─── Model ────────────────────────────────────────────────────────────────────
+# Claude model used for each ticket session. Leave unset to use the default.
+# Options: claude-opus-4-6 | claude-sonnet-4-6 | claude-haiku-4-5
+# CLANCY_MODEL=claude-sonnet-4-6
+
+# ─── Optional: Figma MCP ──────────────────────────────────────────────────────
+# Fetch design specs from Figma when a ticket has a Figma URL in its description
+# FIGMA_API_KEY=your-figma-api-key
+
+# ─── Optional: Playwright visual checks ───────────────────────────────────────
+# Run a visual check after implementing UI tickets
+# PLAYWRIGHT_ENABLED=true
+# PLAYWRIGHT_DEV_COMMAND="yarn dev"
+# PLAYWRIGHT_DEV_PORT=5173
+# PLAYWRIGHT_STORYBOOK_COMMAND="yarn storybook"
+# PLAYWRIGHT_STORYBOOK_PORT=6006
+# PLAYWRIGHT_STARTUP_WAIT=15
+
+# ─── Optional: Notifications ──────────────────────────────────────────────────
+# Webhook URL for Slack or Teams notifications on ticket completion
+# CLANCY_NOTIFY_WEBHOOK=https://hooks.slack.com/services/your/webhook/url

package/src/templates/.env.example.jira

@@ -0,0 +1,53 @@
+# Clancy — Jira configuration
+# Copy this file to .env and fill in your values.
+# Never commit .env to version control.
+
+# ─── Jira ─────────────────────────────────────────────────────────────────────
+JIRA_BASE_URL=https://your-org.atlassian.net
+JIRA_USER=your-email@example.com
+JIRA_API_TOKEN=your-api-token-from-id.atlassian.com
+JIRA_PROJECT_KEY=PROJ
+
+# Status name for "ready to be picked up" (default: To Do)
+# Must be quoted if the status name contains spaces (e.g. "Selected for Development")
+CLANCY_JQL_STATUS="To Do"
+
+# Set to any non-empty value to filter by open sprints (requires Jira Software)
+# Remove or leave empty if your project doesn't use sprints
+# CLANCY_JQL_SPRINT=true
+
+# Optional: only pick up tickets with this label. Recommended for mixed backlogs
+# where not every ticket is suitable for autonomous implementation (e.g. non-code tasks).
+# Create the label in Jira first, then add it to any ticket you want Clancy to pick up.
+# CLANCY_LABEL="clancy"
+
+# ─── Git ──────────────────────────────────────────────────────────────────────
+# Base integration branch. Clancy branches from here when a ticket has no parent epic.
+# When a ticket has a parent epic, Clancy auto-creates epic/{key} from this branch.
+CLANCY_BASE_BRANCH=main
+
+# ─── Loop ─────────────────────────────────────────────────────────────────────
+# Max tickets to process per /clancy:run session (default: 5)
+MAX_ITERATIONS=5
+
+# ─── Model ────────────────────────────────────────────────────────────────────
+# Claude model used for each ticket session. Leave unset to use the default.
+# Options: claude-opus-4-6 | claude-sonnet-4-6 | claude-haiku-4-5
+# CLANCY_MODEL=claude-sonnet-4-6
+
+# ─── Optional: Figma MCP ──────────────────────────────────────────────────────
+# Fetch design specs from Figma when a ticket has a Figma URL in its description
+# FIGMA_API_KEY=your-figma-api-key
+
+# ─── Optional: Playwright visual checks ───────────────────────────────────────
+# Run a visual check after implementing UI tickets
+# PLAYWRIGHT_ENABLED=true
+# PLAYWRIGHT_DEV_COMMAND="yarn dev"
+# PLAYWRIGHT_DEV_PORT=5173
+# PLAYWRIGHT_STORYBOOK_COMMAND="yarn storybook"
+# PLAYWRIGHT_STORYBOOK_PORT=6006
+# PLAYWRIGHT_STARTUP_WAIT=15
+
+# ─── Optional: Notifications ──────────────────────────────────────────────────
+# Webhook URL for Slack or Teams notifications on ticket completion
+# CLANCY_NOTIFY_WEBHOOK=https://hooks.slack.com/services/your/webhook/url

package/src/templates/.env.example.linear

@@ -0,0 +1,43 @@
+# Clancy — Linear configuration
+# Copy this file to .env and fill in your values.
+# Never commit .env to version control.
+
+# ─── Linear ───────────────────────────────────────────────────────────────────
+LINEAR_API_KEY=lin_api_your-personal-api-key
+LINEAR_TEAM_ID=your-team-uuid
+
+# Optional: only pick up issues with this label. Recommended for mixed backlogs
+# where not every issue is suitable for autonomous implementation (e.g. non-code tasks).
+# Create the label in Linear first, then add it to any issue you want Clancy to pick up.
+# CLANCY_LABEL=clancy
+
+# ─── Git ──────────────────────────────────────────────────────────────────────
+# Base integration branch. Clancy branches from here when an issue has no parent.
+# When an issue has a parent, Clancy auto-creates epic/{key} from this branch.
+CLANCY_BASE_BRANCH=main
+
+# ─── Loop ─────────────────────────────────────────────────────────────────────
+# Max tickets to process per /clancy:run session (default: 20)
+MAX_ITERATIONS=20
+
+# ─── Model ────────────────────────────────────────────────────────────────────
+# Claude model used for each ticket session. Leave unset to use the default.
+# Options: claude-opus-4-6 | claude-sonnet-4-6 | claude-haiku-4-5
+# CLANCY_MODEL=claude-sonnet-4-6
+
+# ─── Optional: Figma MCP ──────────────────────────────────────────────────────
+# Fetch design specs from Figma when a ticket has a Figma URL in its description
+# FIGMA_API_KEY=your-figma-api-key
+
+# ─── Optional: Playwright visual checks ───────────────────────────────────────
+# Run a visual check after implementing UI tickets
+# PLAYWRIGHT_ENABLED=true
+# PLAYWRIGHT_DEV_COMMAND="yarn dev"
+# PLAYWRIGHT_DEV_PORT=5173
+# PLAYWRIGHT_STORYBOOK_COMMAND="yarn storybook"
+# PLAYWRIGHT_STORYBOOK_PORT=6006
+# PLAYWRIGHT_STARTUP_WAIT=15
+
+# ─── Optional: Notifications ──────────────────────────────────────────────────
+# Webhook URL for Slack or Teams notifications on ticket completion
+# CLANCY_NOTIFY_WEBHOOK=https://hooks.slack.com/services/your/webhook/url

package/src/templates/CLAUDE.md

@@ -0,0 +1,69 @@
+<!-- clancy:start -->
+## Clancy
+
+This project uses Clancy for autonomous ticket-driven development.
+
+### Docs
+Before every run, read all docs in `.clancy/docs/`:
+- STACK.md — tech stack and dependencies
+- INTEGRATIONS.md — external services and APIs
+- ARCHITECTURE.md — system design and data flow
+- CONVENTIONS.md — code style and patterns
+- TESTING.md — test approach and coverage expectations
+- GIT.md — branching, commit format, merge strategy
+- DESIGN-SYSTEM.md — tokens, components, visual conventions
+- ACCESSIBILITY.md — WCAG requirements and ARIA patterns
+- DEFINITION-OF-DONE.md — checklist before marking a ticket complete
+- CONCERNS.md — known risks, tech debt, things to avoid
+
+### Executability check
+
+Before any git operation, branch creation, or code change — assess whether this ticket can be implemented entirely as a code change committed to this repo.
+
+**Skip the ticket** if it primarily requires any of the following — Clancy cannot do these:
+- **External system admin:** work in Google Analytics, Salesforce, HubSpot, the AWS console, app store dashboards, or any external platform not accessible through code
+- **Human process steps:** getting sign-off or approval, sending emails to customers, coordinating with people, scheduling meetings, making announcements to users
+- **Non-repo production ops:** deploying to production, rotating secrets in prod, scaling infrastructure — unless the task is purely about editing CI/CD config files that live in this repo
+- **Non-code deliverables:** writing runbooks, updating Confluence or wikis, creating presentations, documenting in external tools
+
+When in doubt: "Is the primary deliverable a code change committed to this repo?" — if yes, implement it; if no, skip it.
+
+**If skipping, do all four of these in order:**
+1. Output this exact line: `⚠ Skipping [TICKET-KEY]: {one-line reason}`
+2. Output this exact line: `Ticket skipped — update it to be codebase-only work, then re-run.`
+3. Append to `.clancy/progress.txt`: `YYYY-MM-DD HH:MM | TICKET-KEY | SKIPPED | {reason}`
+4. Stop. No branches, no file changes, no git operations.
+
+**If the ticket is codebase work**, proceed to implementation normally.
+
+### Git workflow
+- Read GIT.md before every run — follow its conventions exactly
+- Default (if GIT.md is silent): one feature branch per ticket `feature/{ticket-key-lowercase}`, squash merge into target branch, conventional commits `feat(TICKET-123): summary`
+- Target branch is auto-detected from the ticket: if it has a parent epic, Clancy branches from and merges into `epic/{epic-key}` (created from `CLANCY_BASE_BRANCH` if it doesn't exist); otherwise branches from `CLANCY_BASE_BRANCH` directly
+- Delete ticket branch locally after merge — never push deletes
+
+### Progress
+Log completed tickets to `.clancy/progress.txt`:
+`YYYY-MM-DD HH:MM | TICKET-KEY | Summary | DONE`
+
+### Design context
+When a ticket description contains a Figma URL, fetch design context before implementing.
+Use the three-tier approach in order:
+  1. Figma MCP: get_metadata → targeted get_design_context → get_screenshot (3 calls, best quality)
+  2. Figma REST API image export: parse file key + node ID from URL, fetch rendered PNG as vision input
+  3. Ticket image attachment: use any image attached to the ticket description as vision input
+Fetch once only — never return to Figma mid-session.
+Map all token values to CSS custom properties. Never use raw SVGs or hardcoded colours.
+Figma URL must come from the ticket description only — never from CLAUDE.md or other docs.
+
+### Visual checks
+After implementing a UI ticket, run a visual check before committing.
+Read .clancy/docs/PLAYWRIGHT.md to determine which server to use (Storybook or dev server).
+Apply the decision rule against this ticket's description — route/page/screen/layout → dev server,
+component/atom/molecule/organism/variant/story → Storybook, ambiguous → dev server default.
+Start the server using health check polling (not sleep). Navigate to the relevant route or story.
+Screenshot, assess visually, check console. Fix before committing if anything looks wrong.
+If a Figma design was fetched for this ticket, compare the screenshot directly against it — check layout, spacing, colours, typography, and component fidelity. Treat the Figma design as the source of truth.
+Kill by PID then sweep the port unconditionally — never leave a port open.
+Log result: YYYY-MM-DD HH:MM | TICKET-KEY | PLAYWRIGHT_PASS|FAIL | server-used
+<!-- clancy:end -->

package/src/templates/scripts/clancy-afk.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# Strict mode: exit on error (-e), undefined variables (-u), pipe failures (-o pipefail).
+# This means any command that fails will stop the script immediately rather than silently continuing.
+set -euo pipefail
+
+# ─── WHAT THIS SCRIPT DOES ─────────────────────────────────────────────────────
+#
+# Loop runner for Clancy. Calls clancy-once.sh repeatedly until:
+#   - No more tickets are found ("No tickets found", "All done", etc.)
+#   - A preflight check fails (output line starting with ✗)
+#   - MAX_ITERATIONS is reached
+#   - The user presses Ctrl+C
+#
+# This script does not know about boards. All board logic lives in clancy-once.sh,
+# which is always the runtime filename regardless of which board is configured.
+# /clancy:init copies the correct board variant as clancy-once.sh during setup.
+#
+# ───────────────────────────────────────────────────────────────────────────────
+
+# ─── PREFLIGHT ─────────────────────────────────────────────────────────────────
+
+command -v claude >/dev/null 2>&1 || {
+  echo "✗ claude CLI not found."
+  echo "  Install it: https://claude.ai/code"
+  exit 0
+}
+command -v jq >/dev/null 2>&1 || {
+  echo "✗ jq not found."
+  echo "  Install: brew install jq  (mac) | apt install jq  (linux)"
+  exit 0
+}
+command -v curl >/dev/null 2>&1 || {
+  echo "✗ curl not found. Install curl for your OS."
+  exit 0
+}
+
+[ -f .clancy/.env ] || {
+  echo "✗ .clancy/.env not found."
+  echo "  Copy .clancy/.env.example to .clancy/.env and fill in your credentials."
+  exit 0
+}
+# shellcheck source=/dev/null
+source .clancy/.env
+
+git rev-parse --git-dir >/dev/null 2>&1 || {
+  echo "✗ Not a git repository."
+  echo "  Clancy must be run from the root of a git project."
+  exit 0
+}
+
+# ─── END PREFLIGHT ─────────────────────────────────────────────────────────────
+
+MAX_ITERATIONS=${MAX_ITERATIONS:-5}
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# clancy-once.sh is always the runtime filename regardless of board.
+# /clancy:init copies the correct board variant as clancy-once.sh.
+ONCE_SCRIPT="$SCRIPT_DIR/clancy-once.sh"
+
+if [ ! -f "$ONCE_SCRIPT" ]; then
+  echo "✗ Script not found: $ONCE_SCRIPT"
+  echo "  Run /clancy:init to scaffold scripts."
+  exit 0
+fi
+
+echo "Starting Clancy — will process up to $MAX_ITERATIONS ticket(s). Ctrl+C to stop early."
+echo ""
+
+i=0
+while [ "$i" -lt "$MAX_ITERATIONS" ]; do
+  i=$((i + 1))
+  echo ""
+  echo "=== Iteration $i of $MAX_ITERATIONS ==="
+
+  # Run clancy-once.sh and stream its output live via tee.
+  # tee writes to both stdout (visible to user) and a temp file (for stop-condition checks).
+  # Without tee, output would be buffered in a variable and hidden during implementation.
+  TMPFILE=$(mktemp)
+  bash "$ONCE_SCRIPT" 2>&1 | tee "$TMPFILE"
+  OUTPUT=$(cat "$TMPFILE")
+  rm -f "$TMPFILE"
+
+  # Stop if no tickets remain
+  if echo "$OUTPUT" | grep -qE "No tickets found|No issues found|All done"; then
+    echo ""
+    echo "✓ Clancy finished — no more tickets."
+    exit 0
+  fi
+
+  # Stop if Claude skipped the ticket (not implementable from the codebase).
+  # Re-running would just fetch and skip the same ticket again — stop and let
+  # the user update the ticket or remove it from the queue before continuing.
+  if echo "$OUTPUT" | grep -q "Ticket skipped"; then
+    echo ""
+    echo "⚠ Clancy stopped — ticket was skipped (not implementable from the codebase)."
+    echo "  Update the ticket to focus on codebase work, then re-run."
+    exit 0
+  fi
+
+  # Stop if a preflight check failed (lines starting with ✗)
+  if echo "$OUTPUT" | grep -qE "^✗ "; then
+    echo ""
+    echo "✗ Clancy stopped — preflight check failed. See output above."
+    exit 0
+  fi
+
+  sleep 2
+done
+
+echo ""
+echo "Reached max iterations ($MAX_ITERATIONS). Run clancy-afk.sh again to continue."

package/src/templates/scripts/clancy-once-github.sh

@@ -0,0 +1,225 @@
+#!/usr/bin/env bash
+# Strict mode: exit on error (-e), undefined variables (-u), pipe failures (-o pipefail).
+# This means any command that fails will stop the script immediately rather than silently continuing.
+set -euo pipefail
+
+# ─── WHAT THIS SCRIPT DOES ─────────────────────────────────────────────────────
+#
+# Board: GitHub Issues
+#
+# 1. Preflight  — checks all required tools, credentials, and repo reachability
+# 2. Fetch      — pulls the next open issue with the 'clancy' label assigned to you
+# 3. Branch     — creates a feature branch from the issue's milestone branch (or base branch)
+# 4. Implement  — passes the issue to Claude Code, which reads .clancy/docs/ and implements it
+# 5. Merge      — squash-merges the feature branch back into the target branch
+# 6. Close      — marks the GitHub issue as closed via the API
+# 7. Log        — appends a completion entry to .clancy/progress.txt
+#
+# This script is run once per issue. The loop is handled by clancy-afk.sh.
+#
+# NOTE: GitHub's /issues endpoint returns pull requests too. This script filters
+# them out by checking for the presence of the 'pull_request' key in each result.
+#
+# NOTE: Failures use exit 0, not exit 1. This is intentional — clancy-afk.sh
+# detects stop conditions by reading script output rather than exit codes, so a
+# non-zero exit would be treated as an unexpected crash rather than a clean stop.
+#
+# ───────────────────────────────────────────────────────────────────────────────
+
+# ─── PREFLIGHT ─────────────────────────────────────────────────────────────────
+
+command -v claude >/dev/null 2>&1 || {
+  echo "✗ claude CLI not found."
+  echo "  Install it: https://claude.ai/code"
+  exit 0
+}
+command -v jq >/dev/null 2>&1 || {
+  echo "✗ jq not found."
+  echo "  Install: brew install jq  (mac) | apt install jq  (linux)"
+  exit 0
+}
+command -v curl >/dev/null 2>&1 || {
+  echo "✗ curl not found. Install curl for your OS."
+  exit 0
+}
+
+[ -f .clancy/.env ] || {
+  echo "✗ .clancy/.env not found."
+  echo "  Copy .clancy/.env.example to .clancy/.env and fill in your credentials."
+  echo "  Then run: /clancy:init"
+  exit 0
+}
+# shellcheck source=/dev/null
+source .clancy/.env
+
+git rev-parse --git-dir >/dev/null 2>&1 || {
+  echo "✗ Not a git repository."
+  echo "  Clancy must be run from the root of a git project."
+  exit 0
+}
+
+if ! git diff --quiet || ! git diff --cached --quiet; then
+  echo "⚠ Working directory has uncommitted changes."
+  echo "  Consider stashing or committing first to avoid confusion."
+fi
+
+[ -n "${GITHUB_TOKEN:-}"  ] || { echo "✗ GITHUB_TOKEN is not set in .clancy/.env";  exit 0; }
+[ -n "${GITHUB_REPO:-}"   ] || { echo "✗ GITHUB_REPO is not set in .clancy/.env";   exit 0; }
+
+# Validate GITHUB_REPO format — must be owner/repo with safe characters only
+if ! echo "$GITHUB_REPO" | grep -qE '^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$'; then
+  echo "✗ GITHUB_REPO format is invalid. Expected owner/repo (e.g. acme/my-app). Check GITHUB_REPO in .clancy/.env."
+  exit 0
+fi
+
+PING=$(curl -s -o /dev/null -w "%{http_code}" \
+  -H "Authorization: Bearer $GITHUB_TOKEN" \
+  -H "X-GitHub-Api-Version: 2022-11-28" \
+  "https://api.github.com/repos/$GITHUB_REPO")
+
+case "$PING" in
+  200) ;;
+  401) echo "✗ GitHub authentication failed. Check GITHUB_TOKEN in .clancy/.env."; exit 0 ;;
+  403) echo "✗ GitHub access denied. Your token may lack the repo scope."; exit 0 ;;
+  404) echo "✗ GitHub repo '$GITHUB_REPO' not found. Check GITHUB_REPO in .clancy/.env."; exit 0 ;;
+  000) echo "✗ Could not reach GitHub. Check your network."; exit 0 ;;
+  *)   echo "✗ GitHub returned unexpected status $PING. Check your config."; exit 0 ;;
+esac
+
+if [ "${PLAYWRIGHT_ENABLED:-}" = "true" ]; then
+  if lsof -ti:"${PLAYWRIGHT_DEV_PORT:-5173}" >/dev/null 2>&1; then
+    echo "⚠ Port ${PLAYWRIGHT_DEV_PORT:-5173} is already in use."
+    echo "  If visual checks fail, stop whatever is using the port first."
+  fi
+fi
+
+echo "✓ Preflight passed. Starting Clancy..."
+
+# ─── END PREFLIGHT ─────────────────────────────────────────────────────────────
+
+# ─── FETCH ISSUE ───────────────────────────────────────────────────────────────
+
+# Fetch open issues assigned to the authenticated user with the 'clancy' label.
+# GitHub's issues endpoint returns PRs too — filter them out by checking for pull_request key.
+# per_page=3 so we can find one real issue even if the first result(s) are PRs.
+RESPONSE=$(curl -s \
+  -H "Authorization: Bearer $GITHUB_TOKEN" \
+  -H "X-GitHub-Api-Version: 2022-11-28" \
+  "https://api.github.com/repos/$GITHUB_REPO/issues?state=open&assignee=@me&labels=clancy&per_page=3")
+
+# Verify response is an array before parsing (guards against error objects on rate limit / transient failure)
+if ! echo "$RESPONSE" | jq -e 'type == "array"' >/dev/null 2>&1; then
+  ERR_MSG=$(echo "$RESPONSE" | jq -r '.message // "Unexpected response"' 2>/dev/null || echo "Unexpected response")
+  echo "✗ GitHub API error: $ERR_MSG. Check GITHUB_TOKEN in .clancy/.env."
+  exit 0
+fi
+
+# Filter out PRs and take first real issue
+ISSUE=$(echo "$RESPONSE" | jq 'map(select(has("pull_request") | not)) | .[0]')
+
+if [ "$(echo "$ISSUE" | jq 'type')" = '"null"' ] || [ -z "$(echo "$ISSUE" | jq -r '.number // empty')" ]; then
+  echo "No issues found. All done!"
+  exit 0
+fi
+
+ISSUE_NUMBER=$(echo "$ISSUE" | jq -r '.number')
+TITLE=$(echo "$ISSUE" | jq -r '.title')
+BODY=$(echo "$ISSUE" | jq -r '.body // "No description"')
+MILESTONE=$(echo "$ISSUE" | jq -r '.milestone.title // "none"')
+
+BASE_BRANCH="${CLANCY_BASE_BRANCH:-main}"
+TICKET_BRANCH="feature/issue-${ISSUE_NUMBER}"
+
+# GitHub has no native epic concept — use milestone as the grouping signal.
+# If the issue has a milestone, branch from milestone/{slug} (creating it from
+# BASE_BRANCH if it doesn't exist yet). Otherwise branch from BASE_BRANCH directly.
+if [ "$MILESTONE" != "none" ]; then
+  MILESTONE_SLUG=$(echo "$MILESTONE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-')
+  TARGET_BRANCH="milestone/${MILESTONE_SLUG}"
+  git show-ref --verify --quiet "refs/heads/$TARGET_BRANCH" \
+    || git checkout -b "$TARGET_BRANCH" "$BASE_BRANCH"
+else
+  TARGET_BRANCH="$BASE_BRANCH"
+fi
+
+# ─── IMPLEMENT ─────────────────────────────────────────────────────────────────
+
+echo "Picking up: [#${ISSUE_NUMBER}] $TITLE"
+echo "Milestone: $MILESTONE | Target branch: $TARGET_BRANCH"
+
+git checkout "$TARGET_BRANCH"
+# -B creates the branch if it doesn't exist, or resets it to HEAD if it does.
+# This handles retries cleanly without failing on an already-existing branch.
+git checkout -B "$TICKET_BRANCH"
+
+PROMPT="You are implementing GitHub Issue #${ISSUE_NUMBER}.
+
+Title: $TITLE
+Milestone: $MILESTONE
+
+Description:
+$BODY
+
+Step 0 — Executability check (do this before any git or file operation):
+Read the issue title and description above. Can this issue be implemented entirely
+as a code change committed to this repo? Consult the 'Executability check' section of
+CLAUDE.md for the full list of skip conditions.
+
+If you must SKIP this issue:
+1. Output: ⚠ Skipping [#${ISSUE_NUMBER}]: {one-line reason}
+2. Output: Ticket skipped — update it to be codebase-only work, then re-run.
+3. Append to .clancy/progress.txt: YYYY-MM-DD HH:MM | #${ISSUE_NUMBER} | SKIPPED | {reason}
+4. Stop — no branches, no file changes, no git operations.
+
+If the issue IS implementable, continue:
+1. Read ALL docs in .clancy/docs/ — especially GIT.md for branching and commit conventions
+2. Follow the conventions in GIT.md exactly
+3. Implement the issue fully
+4. Commit your work following the conventions in GIT.md
+5. When done, confirm you are finished."
+
+CLAUDE_ARGS=(--dangerously-skip-permissions)
+[ -n "${CLANCY_MODEL:-}" ] && CLAUDE_ARGS+=(--model "$CLANCY_MODEL")
+echo "$PROMPT" | claude "${CLAUDE_ARGS[@]}"
+
+# ─── MERGE, CLOSE & LOG ────────────────────────────────────────────────────────
+
+# Squash all commits from the feature branch into a single commit on the target branch.
+git checkout "$TARGET_BRANCH"
+git merge --squash "$TICKET_BRANCH"
+if git diff --cached --quiet; then
+  echo "⚠ No changes staged after squash merge. Claude may not have committed any work."
+else
+  git commit -m "feat(#${ISSUE_NUMBER}): $TITLE"
+fi
+
+# Delete ticket branch locally
+git branch -d "$TICKET_BRANCH"
+
+# Close the issue — warn but don't fail if this doesn't go through
+CLOSE_HTTP=$(curl -s -o /dev/null -w "%{http_code}" -X PATCH \
+  -H "Authorization: Bearer $GITHUB_TOKEN" \
+  -H "X-GitHub-Api-Version: 2022-11-28" \
+  -H "Content-Type: application/json" \
+  "https://api.github.com/repos/$GITHUB_REPO/issues/${ISSUE_NUMBER}" \
+  -d '{"state": "closed"}')
+[ "$CLOSE_HTTP" = "200" ] || echo "⚠ Could not close issue #${ISSUE_NUMBER} (HTTP $CLOSE_HTTP). Close it manually on GitHub."
+
+# Log progress
+echo "$(date '+%Y-%m-%d %H:%M') | #${ISSUE_NUMBER} | $TITLE | DONE" >> .clancy/progress.txt
+
+echo "✓ #${ISSUE_NUMBER} complete."
+
+# Send completion notification if webhook is configured
+if [ -n "${CLANCY_NOTIFY_WEBHOOK:-}" ]; then
+  NOTIFY_MSG="✓ Clancy completed [#${ISSUE_NUMBER}] $TITLE"
+  if echo "$CLANCY_NOTIFY_WEBHOOK" | grep -q "hooks.slack.com"; then
+    curl -s -X POST "$CLANCY_NOTIFY_WEBHOOK" \
+      -H "Content-Type: application/json" \
+      -d "$(jq -n --arg text "$NOTIFY_MSG" '{"text": $text}')" >/dev/null 2>&1 || true
+  else
+    curl -s -X POST "$CLANCY_NOTIFY_WEBHOOK" \
+      -H "Content-Type: application/json" \
+      -d "$(jq -n --arg text "$NOTIFY_MSG" '{"type":"message","attachments":[{"contentType":"application/vnd.microsoft.card.adaptive","content":{"type":"AdaptiveCard","body":[{"type":"TextBlock","text":$text}]}}]}')" >/dev/null 2>&1 || true
+  fi
+fi