chief-clancy 0.1.0

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

@@ -0,0 +1,252 @@
+#!/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: Linear
+#
+# 1. Preflight  — checks all required tools, credentials, and API reachability
+# 2. Fetch      — pulls the next unstarted issue assigned to you via GraphQL
+# 3. Branch     — creates a feature branch from the issue's parent 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. 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: Linear personal API keys do NOT use a "Bearer" prefix in the Authorization
+# header. OAuth access tokens do. This is correct per Linear's documentation.
+#
+# NOTE: state.type "unstarted" is a fixed enum value — it filters by state category,
+# not state name. This works regardless of what your team named their backlog column.
+#
+# 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 "${LINEAR_API_KEY:-}"  ] || { echo "✗ LINEAR_API_KEY is not set in .clancy/.env";  exit 0; }
+[ -n "${LINEAR_TEAM_ID:-}"  ] || { echo "✗ LINEAR_TEAM_ID is not set in .clancy/.env";  exit 0; }
+
+# Linear ping — verify API key with a minimal query
+# Note: personal API keys do NOT use a "Bearer" prefix — this is correct per Linear docs.
+# OAuth access tokens use "Bearer". Do not change this.
+PING_BODY=$(curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d '{"query": "{ viewer { id } }"}')
+
+echo "$PING_BODY" | jq -e '.data.viewer.id' >/dev/null 2>&1 || {
+  echo "✗ Linear authentication failed. Check LINEAR_API_KEY in .clancy/.env."; exit 0
+}
+
+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 one unstarted issue assigned to the current user on the configured team.
+# Note: personal API keys do NOT use "Bearer" prefix — this is intentional.
+#
+# GraphQL query (expanded for readability):
+#   viewer {
+#     assignedIssues(
+#       filter: {
+#         state: { type: { eq: "unstarted" } }   ← fixed enum, works regardless of column name
+#         team: { id: { eq: "$LINEAR_TEAM_ID" } }
+#         labels: { name: { eq: "$CLANCY_LABEL" } }  ← only if CLANCY_LABEL is set
+#       }
+#       first: 1
+#       orderBy: priority
+#     ) {
+#       nodes { id identifier title description parent { identifier title } }
+#     }
+#   }
+
+# Validate user-controlled values to prevent GraphQL injection.
+# Values are passed via GraphQL variables (JSON-encoded by jq) rather than string-interpolated.
+if ! echo "$LINEAR_TEAM_ID" | grep -qE '^[a-zA-Z0-9_-]+$'; then
+  echo "✗ LINEAR_TEAM_ID contains invalid characters. Check .clancy/.env."
+  exit 0
+fi
+if [ -n "${CLANCY_LABEL:-}" ] && ! echo "$CLANCY_LABEL" | grep -qE '^[a-zA-Z0-9 _-]+$'; then
+  echo "✗ CLANCY_LABEL contains invalid characters. Use only letters, numbers, spaces, hyphens, and underscores."
+  exit 0
+fi
+
+# Build request using GraphQL variables — values are JSON-encoded by jq, never interpolated into the query string.
+# The label filter clause is only added to the query when CLANCY_LABEL is set, since passing null would match nothing.
+if [ -n "${CLANCY_LABEL:-}" ]; then
+  REQUEST_BODY=$(jq -n \
+    --arg teamId "$LINEAR_TEAM_ID" \
+    --arg label "$CLANCY_LABEL" \
+    '{"query": "query($teamId: String!, $label: String) { viewer { assignedIssues(filter: { state: { type: { eq: \"unstarted\" } } team: { id: { eq: $teamId } } labels: { name: { eq: $label } } } first: 1 orderBy: priority) { nodes { id identifier title description parent { identifier title } } } } }", "variables": {"teamId": $teamId, "label": $label}}')
+else
+  REQUEST_BODY=$(jq -n \
+    --arg teamId "$LINEAR_TEAM_ID" \
+    '{"query": "query($teamId: String!) { viewer { assignedIssues(filter: { state: { type: { eq: \"unstarted\" } } team: { id: { eq: $teamId } } } first: 1 orderBy: priority) { nodes { id identifier title description parent { identifier title } } } } }", "variables": {"teamId": $teamId}}')
+fi
+
+RESPONSE=$(curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d "$REQUEST_BODY")
+
+# Check for API errors before parsing (rate limit, permission error, etc.)
+if ! echo "$RESPONSE" | jq -e '.data.viewer.assignedIssues' >/dev/null 2>&1; then
+  ERR_MSG=$(echo "$RESPONSE" | jq -r '.errors[0].message // "Unexpected response"' 2>/dev/null || echo "Unexpected response")
+  echo "✗ Linear API error: $ERR_MSG. Check LINEAR_API_KEY in .clancy/.env."
+  exit 0
+fi
+
+NODE_COUNT=$(echo "$RESPONSE" | jq '.data.viewer.assignedIssues.nodes | length')
+if [ "$NODE_COUNT" -eq 0 ]; then
+  echo "No issues found. All done!"
+  exit 0
+fi
+
+IDENTIFIER=$(echo "$RESPONSE" | jq -r '.data.viewer.assignedIssues.nodes[0].identifier')
+TITLE=$(echo "$RESPONSE" | jq -r '.data.viewer.assignedIssues.nodes[0].title')
+DESCRIPTION=$(echo "$RESPONSE" | jq -r '.data.viewer.assignedIssues.nodes[0].description // "No description"')
+PARENT_ID=$(echo "$RESPONSE" | jq -r '.data.viewer.assignedIssues.nodes[0].parent.identifier // "none"')
+PARENT_TITLE=$(echo "$RESPONSE" | jq -r '.data.viewer.assignedIssues.nodes[0].parent.title // ""')
+
+EPIC_INFO="${PARENT_ID}"
+if [ -n "$PARENT_TITLE" ] && [ "$PARENT_TITLE" != "null" ]; then
+  EPIC_INFO="${PARENT_ID} — ${PARENT_TITLE}"
+fi
+
+BASE_BRANCH="${CLANCY_BASE_BRANCH:-main}"
+TICKET_BRANCH="feature/$(echo "$IDENTIFIER" | tr '[:upper:]' '[:lower:]')"
+
+# Auto-detect target branch from ticket's parent.
+# If the issue has a parent, branch from epic/{parent-id} (creating it from
+# BASE_BRANCH if it doesn't exist yet). Otherwise branch from BASE_BRANCH directly.
+if [ "$PARENT_ID" != "none" ]; then
+  TARGET_BRANCH="epic/$(echo "$PARENT_ID" | tr '[:upper:]' '[:lower:]')"
+  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: [$IDENTIFIER] $TITLE"
+echo "Epic: $EPIC_INFO | 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 Linear issue $IDENTIFIER.
+
+Title: $TITLE
+Epic: $EPIC_INFO
+
+Description:
+$DESCRIPTION
+
+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 [$IDENTIFIER]: {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 | $IDENTIFIER | 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 & 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($IDENTIFIER): $TITLE"
+fi
+
+# Delete ticket branch locally
+git branch -d "$TICKET_BRANCH"
+
+# Log progress
+echo "$(date '+%Y-%m-%d %H:%M') | $IDENTIFIER | $TITLE | DONE" >> .clancy/progress.txt
+
+echo "✓ $IDENTIFIER complete."
+
+# Send completion notification if webhook is configured
+if [ -n "${CLANCY_NOTIFY_WEBHOOK:-}" ]; then
+  NOTIFY_MSG="✓ Clancy completed [$IDENTIFIER] $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

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

@@ -0,0 +1,259 @@
+#!/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: Jira
+#
+# 1. Preflight — checks all required tools, credentials, and board reachability
+# 2. Fetch    — pulls the next assigned "To Do" ticket from Jira (maxResults: 1)
+# 3. Branch   — creates a feature branch from the ticket's epic branch (or base branch)
+# 4. Implement — passes the ticket to Claude Code, which reads .clancy/docs/ and implements it
+# 5. Merge    — squash-merges the feature branch back into the target branch
+# 6. Log      — appends a completion entry to .clancy/progress.txt
+#
+# This script is run once per ticket. The loop is handled by clancy-afk.sh.
+#
+# NOTE: This file has no -jira suffix by design. /clancy:init copies the correct
+# board variant into the user's .clancy/ directory as clancy-once.sh regardless
+# of board. The board is determined by which template was copied, not the filename.
+#
+# 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 "${JIRA_BASE_URL:-}"    ] || { echo "✗ JIRA_BASE_URL is not set in .clancy/.env";    exit 0; }
+[ -n "${JIRA_USER:-}"        ] || { echo "✗ JIRA_USER is not set in .clancy/.env";        exit 0; }
+[ -n "${JIRA_API_TOKEN:-}"   ] || { echo "✗ JIRA_API_TOKEN is not set in .clancy/.env";   exit 0; }
+[ -n "${JIRA_PROJECT_KEY:-}" ] || { echo "✗ JIRA_PROJECT_KEY is not set in .clancy/.env"; exit 0; }
+if ! echo "$JIRA_PROJECT_KEY" | grep -qE '^[A-Z][A-Z0-9]+$'; then
+  echo "✗ JIRA_PROJECT_KEY format is invalid. Expected uppercase letters and numbers only (e.g. PROJ, ENG2). Check JIRA_PROJECT_KEY in .clancy/.env."
+  exit 0
+fi
+
+PING=$(curl -s -o /dev/null -w "%{http_code}" \
+  -u "$JIRA_USER:$JIRA_API_TOKEN" \
+  "$JIRA_BASE_URL/rest/api/3/project/$JIRA_PROJECT_KEY")
+
+case "$PING" in
+  200) ;;
+  401) echo "✗ Jira authentication failed. Check JIRA_USER and JIRA_API_TOKEN in .clancy/.env."; exit 0 ;;
+  403) echo "✗ Jira access denied. Your token may lack Browse Projects permission."; exit 0 ;;
+  404) echo "✗ Jira project '$JIRA_PROJECT_KEY' not found. Check JIRA_PROJECT_KEY in .clancy/.env."; exit 0 ;;
+  000) echo "✗ Could not reach Jira at $JIRA_BASE_URL. Check JIRA_BASE_URL and your network."; exit 0 ;;
+  *)   echo "✗ Jira 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 "  Clancy will attempt to start the dev server on this port."
+    echo "  If visual checks fail, stop whatever is using the port first."
+  fi
+fi
+
+echo "✓ Preflight passed. Starting Clancy..."
+
+# ─── END PREFLIGHT ─────────────────────────────────────────────────────────────
+
+# ─── FETCH TICKET ──────────────────────────────────────────────────────────────
+
+# Validate user-controlled values to prevent JQL injection.
+# JQL does not support parameterised queries, so we restrict to safe characters.
+if [ -n "${CLANCY_LABEL:-}" ] && ! echo "$CLANCY_LABEL" | grep -qE '^[a-zA-Z0-9 _-]+$'; then
+  echo "✗ CLANCY_LABEL contains invalid characters. Use only letters, numbers, spaces, hyphens, and underscores."
+  exit 0
+fi
+if ! echo "${CLANCY_JQL_STATUS:-To Do}" | grep -qE '^[a-zA-Z0-9 _-]+$'; then
+  echo "✗ CLANCY_JQL_STATUS contains invalid characters. Use only letters, numbers, spaces, hyphens, and underscores."
+  exit 0
+fi
+
+# Build JQL — sprint filter is optional (requires Jira Software license).
+# Uses the /rest/api/3/search/jql POST endpoint — the old GET /search was removed Aug 2025.
+# maxResults:1 is intentional — pick one ticket per run, never paginate.
+if [ -n "${CLANCY_JQL_SPRINT:-}" ]; then
+  SPRINT_CLAUSE="AND sprint in openSprints()"
+else
+  SPRINT_CLAUSE=""
+fi
+
+# Optional label filter — set CLANCY_LABEL in .env to only pick up tickets with that label.
+# Useful for mixed backlogs where not every ticket is suitable for autonomous implementation.
+if [ -n "${CLANCY_LABEL:-}" ]; then
+  LABEL_CLAUSE="AND labels = \"$CLANCY_LABEL\""
+else
+  LABEL_CLAUSE=""
+fi
+
+RESPONSE=$(curl -s \
+  -u "$JIRA_USER:$JIRA_API_TOKEN" \
+  -X POST \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  "$JIRA_BASE_URL/rest/api/3/search/jql" \
+  -d "{
+    \"jql\": \"project=$JIRA_PROJECT_KEY $SPRINT_CLAUSE $LABEL_CLAUSE AND assignee=currentUser() AND status=\\\"${CLANCY_JQL_STATUS:-To Do}\\\" ORDER BY priority ASC\",
+    \"maxResults\": 1,
+    \"fields\": [\"summary\", \"description\", \"issuelinks\", \"parent\", \"customfield_10014\"]
+  }")
+
+# New endpoint returns { "issues": [...], "isLast": bool } — no .total field
+ISSUE_COUNT=$(echo "$RESPONSE" | jq '.issues | length')
+if [ "$ISSUE_COUNT" -eq 0 ]; then
+  echo "No tickets found. All done!"
+  exit 0
+fi
+
+TICKET_KEY=$(echo "$RESPONSE" | jq -r '.issues[0].key')
+SUMMARY=$(echo "$RESPONSE" | jq -r '.issues[0].fields.summary')
+
+# Extract description via recursive ADF walk
+DESCRIPTION=$(echo "$RESPONSE" | jq -r '
+  .issues[0].fields.description
+  | .. | strings
+  | select(length > 0)
+  | . + "\n"
+' 2>/dev/null || echo "No description")
+
+# Extract epic — try parent first (next-gen), fall back to customfield_10014 (classic)
+EPIC_INFO=$(echo "$RESPONSE" | jq -r '
+  .issues[0].fields.parent.key // .issues[0].fields.customfield_10014 // "none"
+')
+
+# Extract blocking issue links
+BLOCKERS=$(echo "$RESPONSE" | jq -r '
+  [.issues[0].fields.issuelinks[]?
+    | select(.type.name == "Blocks" and .inwardIssue?)
+    | .inwardIssue.key]
+  | if length > 0 then "Blocked by: " + join(", ") else "None" end
+' 2>/dev/null || echo "None")
+
+BASE_BRANCH="${CLANCY_BASE_BRANCH:-main}"
+TICKET_BRANCH="feature/$(echo "$TICKET_KEY" | tr '[:upper:]' '[:lower:]')"
+
+# Auto-detect target branch from ticket's parent epic.
+# If the ticket has a parent epic, branch from epic/{epic-key} (creating it from
+# BASE_BRANCH if it doesn't exist yet). Otherwise branch from BASE_BRANCH directly.
+if [ "$EPIC_INFO" != "none" ]; then
+  TARGET_BRANCH="epic/$(echo "$EPIC_INFO" | tr '[:upper:]' '[:lower:]')"
+  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: [$TICKET_KEY] $SUMMARY"
+echo "Epic: $EPIC_INFO | Target branch: $TARGET_BRANCH | Blockers: $BLOCKERS"
+
+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 Jira ticket $TICKET_KEY.
+
+Summary: $SUMMARY
+Epic: $EPIC_INFO
+Blockers: $BLOCKERS
+
+Description:
+$DESCRIPTION
+
+Step 0 — Executability check (do this before any git or file operation):
+Read the ticket summary and description above. Can this ticket 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 ticket:
+1. Output: ⚠ Skipping [$TICKET_KEY]: {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 | $TICKET_KEY | SKIPPED | {reason}
+4. Stop — no branches, no file changes, no git operations.
+
+If the ticket 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 ticket 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 & 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($TICKET_KEY): $SUMMARY"
+fi
+
+# Delete ticket branch locally (never push deletes)
+git branch -d "$TICKET_BRANCH"
+
+# Log progress
+echo "$(date '+%Y-%m-%d %H:%M') | $TICKET_KEY | $SUMMARY | DONE" >> .clancy/progress.txt
+
+echo "✓ $TICKET_KEY complete."
+
+# Send completion notification if webhook is configured
+if [ -n "${CLANCY_NOTIFY_WEBHOOK:-}" ]; then
+  NOTIFY_MSG="✓ Clancy completed [$TICKET_KEY] $SUMMARY"
+  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

package/src/workflows/doctor.md

@@ -0,0 +1,115 @@
+## Update check
+
+Before doing anything else, check for updates:
+
+1. Run: `npm show chief-clancy version`
+2. Read the installed version from the Clancy `package.json`
+3. If a newer version exists, print: `ℹ Clancy v{current} → v{latest} available. Run /clancy:update to upgrade.` then continue normally.
+4. If already on latest, continue silently.
+5. If the npm check fails for any reason (offline, network error), continue silently. Never block on this.
+
+---
+
+# Clancy Doctor Workflow
+
+## Overview
+
+Diagnose your Clancy setup — test every configured integration and report what's working, what's broken, and how to fix it. Never modifies any files or state.
+
+---
+
+## Step 1 — Check install
+
+- Verify Clancy commands are installed (`.claude/commands/clancy/` or `~/.claude/commands/clancy/`)
+- Read installed version from `package.json` in the commands directory
+- Print: `✓ Clancy v{version} installed ({location})`
+
+---
+
+## Step 2 — Check prerequisites
+
+Test each required binary:
+
+| Binary | Check | Fix hint |
+|---|---|---|
+| `jq` | `command -v jq` | `brew install jq` / `apt install jq` |
+| `curl` | `command -v curl` | Install curl for your OS |
+| `git` | `command -v git` | Install git for your OS |
+
+Print `✓` or `✗` for each.
+
+---
+
+## Step 3 — Check project setup
+
+- `.clancy/` exists → `✓ .clancy/ found`
+- `.clancy/clancy-once.sh` exists and is executable → `✓ clancy-once.sh`
+- `.clancy/clancy-afk.sh` exists and is executable → `✓ clancy-afk.sh`
+- `.clancy/.env` exists → `✓ .clancy/.env found`
+- `.clancy/docs/` has non-empty files → `✓ codebase docs present ({N} files)`
+
+If `.clancy/` is missing: `✗ .clancy/ not found — run /clancy:init`
+If `.clancy/.env` is missing: `✗ .clancy/.env not found — run /clancy:init`
+
+---
+
+## Step 4 — Check board credentials
+
+Source `.clancy/.env` and detect which board is configured:
+
+**Jira** — if `JIRA_BASE_URL` is set:
+1. Check all required vars are non-empty: `JIRA_BASE_URL`, `JIRA_USER`, `JIRA_API_TOKEN`, `JIRA_PROJECT_KEY`
+2. Ping: `GET {JIRA_BASE_URL}/rest/api/3/project/{JIRA_PROJECT_KEY}` with basic auth
+3. Report HTTP status with specific guidance for each failure code
+
+**GitHub Issues** — if `GITHUB_TOKEN` is set:
+1. Check: `GITHUB_TOKEN`, `GITHUB_REPO`
+2. Ping: `GET https://api.github.com/repos/{GITHUB_REPO}` with bearer token
+3. Report status
+
+**Linear** — if `LINEAR_API_KEY` is set:
+1. Check: `LINEAR_API_KEY`, `LINEAR_TEAM_ID`
+2. Ping: `POST https://api.linear.app/graphql` with `{ viewer { id } }` — no Bearer prefix
+3. Report status
+
+---
+
+## Step 5 — Check optional integrations
+
+**Figma** — if `FIGMA_API_KEY` is set:
+- Call `GET https://api.figma.com/v1/me` with `X-Figma-Token: $FIGMA_API_KEY`
+- On success: print `✓ Figma connected — {email}`
+- On 403: print `✗ Figma authentication failed. Check FIGMA_API_KEY in .clancy/.env.`
+- Note: Figma's API does not expose plan information — check your plan at figma.com/settings
+
+**Playwright** — if `PLAYWRIGHT_ENABLED=true`:
+- Check `.clancy/docs/PLAYWRIGHT.md` exists
+- Verify `PLAYWRIGHT_DEV_COMMAND` and `PLAYWRIGHT_DEV_PORT` are set
+- Check port is not currently in use (just a status, not a blocker)
+
+**Notifications** — if `CLANCY_NOTIFY_WEBHOOK` is set:
+- Detect platform from URL (Slack/Teams)
+- Send a test ping: `"Clancy doctor — webhook test from {project dir}"`
+- Report success or failure
+
+---
+
+## Step 6 — Summary
+
+```
+Clancy doctor — {N} checks passed, {N} warnings, {N} failures
+
+✓ Clancy v0.1.0 installed (global)
+✓ jq, curl, git — all present
+✓ .clancy/ set up — 10 docs present
+✓ Jira connected — PROJ reachable
+✓ Figma connected — alex@example.com (check plan at figma.com/settings)
+✗ PLAYWRIGHT_STORYBOOK_PORT — not set in .clancy/.env
+
+Fix the ✗ items, then run /clancy:once to verify end-to-end.
+```
+
+If all checks pass:
+```
+All good. Run /clancy:once to pick up your first ticket.
+```