project-init 0.3.0__py3-none-any.whl

project_init/templates/base/dot_claude/scripts/monitor_pr.sh

@@ -0,0 +1,270 @@
+#!/bin/bash
+# Wait for all CI checks on a PR, then optionally merge.
+# Only prints failures or the final pass line — no per-refresh noise.
+# Requires: gh, python3 (stdlib only — no jq dependency).
+#
+# Usage:
+#   .claude/scripts/monitor_pr.sh <pr-number> [--merge] [--review-cycle N] [--no-review]
+#
+# --merge: squash-merge and delete branch automatically when all checks pass.
+# --review-cycle N: current review fix cycle count (0-based, default 0).
+#   When N >= MAX_REVIEW_CYCLES and review/decision is still failing or pending,
+#   force-merges with --admin.
+# --no-review: skip all review waiting and admin-merge after CI passes.
+#   Use ONLY for solo-dev PRs where no human reviewer will ever respond.
+#   Do NOT use to avoid addressing legitimate review feedback.
+#
+# Full lifecycle for agents:
+#   1. .claude/scripts/monitor_pr.sh <n> --merge
+#   2. Exit 2 -> review comments printed -> read and address them, push
+#   3. Re-run with --review-cycle 1
+#   4. Exit 2 again -> address remaining comments, push
+#   5. Re-run with --review-cycle 2 -> admin-merge fires if still blocked
+#
+# Review cycle policy:
+#   Two fix cycles are required before admin-merge is allowed. This ensures
+#   review feedback (including Copilot comments) is read and addressed at
+#   least once before force-merging.
+
+set -euo pipefail
+
+PR_NUMBER="${1:-}"
+MODE="${2:-}"
+REVIEW_CYCLE=0
+MAX_REVIEW_CYCLES=2
+NO_REVIEW=0
+
+if [ -z "$PR_NUMBER" ]; then
+  echo "Usage: monitor_pr.sh <pr-number> [--merge] [--review-cycle N] [--no-review]" >&2
+  exit 1
+fi
+
+if [ -n "$MODE" ] && [ "$MODE" != "--merge" ]; then
+  echo "Unknown option: $MODE" >&2
+  exit 2
+fi
+
+# Parse remaining flags (order-independent after position 2).
+# Shift past <pr-number> and optional --merge; remaining args are flags.
+shift 1  # drop PR_NUMBER
+[ "$MODE" = "--merge" ] && shift 1  # drop --merge if present
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --review-cycle)   REVIEW_CYCLE="${2:-0}"; shift 2 ;;
+    --review-cycle=*) REVIEW_CYCLE="${1#*=}"; shift ;;
+    --no-review)      NO_REVIEW=1; shift ;;
+    *) echo "Unknown option: $1" >&2; exit 2 ;;
+  esac
+done
+
+_count_pending() {
+  echo "$1" | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+# Exclude review/decision; it is a derived commit status that only appears
+# after a review event. We detect review state directly via reviewDecision.
+print(sum(1 for c in data if c.get('name') != 'review/decision' and c.get('state') in ('PENDING', 'IN_PROGRESS', 'EXPECTED')))
+"
+}
+
+_print_failures() {
+  echo "$1" | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+bad = [
+    c for c in data
+    if c.get('name') != 'review/decision'
+    and (
+        c.get('bucket') in ('fail', 'cancel')
+        or c.get('state') in ('FAILURE', 'CANCELLED', 'TIMED_OUT', 'ERROR')
+    )
+]
+for c in bad:
+    print(f\"  {c['name']}: {c.get('state') or c.get('bucket')}\")
+sys.exit(len(bad))
+"
+}
+
+# Print review feedback — inline comments first, falls back to full PR comments view.
+_print_review_comments() {
+  local inline
+  inline=$(
+    gh api "repos/{owner}/{repo}/pulls/$PR_NUMBER/comments" \
+      --jq '.[] | "  \(.path):\(.line // "?") [\(.user.login)]\n  \(.body)\n"' \
+      2>/dev/null || true
+  )
+  if [ -n "$inline" ]; then
+    printf '%s\n' "$inline"
+  else
+    gh pr view "$PR_NUMBER" --comments 2>/dev/null || true
+  fi
+  echo "  Full PR: $(gh pr view "$PR_NUMBER" --json url -q '.url' 2>/dev/null || true)"
+}
+
+_run_gh() {
+  local output
+  local status
+
+  set +e
+  output=$(GH_PROMPT_DISABLED=1 gh "$@" 2>&1)
+  status=$?
+  set -e
+
+  if [ -n "$output" ]; then
+    printf '%s\n' "$output" | grep -v "^$" || true
+  fi
+
+  return "$status"
+}
+
+_admin_merge() {
+  if _run_gh pr merge "$PR_NUMBER" --squash --delete-branch --admin; then
+    echo "Merged PR #$PR_NUMBER (admin)"
+  else
+    echo "ERROR: admin merge failed for PR #$PR_NUMBER" >&2
+    return 1
+  fi
+}
+
+# Query the PR's aggregate review decision directly — source of truth regardless
+# of whether the review/decision commit status has been posted yet.
+# Returns: APPROVED | CHANGES_REQUESTED | REVIEW_REQUIRED | (empty = no review policy)
+# Returns UNKNOWN on API failure — callers must treat this as fail-closed.
+_get_review_decision() {
+  gh pr view "$PR_NUMBER" --json reviewDecision -q '.reviewDecision // ""' 2>/dev/null || echo "UNKNOWN"
+}
+
+# Check if any review activity exists (COMMENTED, APPROVED, or CHANGES_REQUESTED).
+# Bot reviewers like Codex post COMMENTED reviews that don't change reviewDecision,
+# so we use this as an early exit signal from the wait loop.
+_has_review_activity() {
+  local count
+  count=$(gh pr view "$PR_NUMBER" --json reviews -q '.reviews | length' 2>/dev/null) || count=0
+  [ "$count" -gt 0 ]
+}
+
+# --- Wait for all CI checks (excludes review/decision commit status) ---
+# Guard: if checks haven't registered yet (empty list), keep polling.
+# An empty list is indistinguishable from "all done" without this guard,
+# which caused premature merges before CI even started.
+while true; do
+  CHECKS=$(gh pr checks "$PR_NUMBER" --json name,state,bucket 2>/dev/null) || CHECKS="[]"
+  CHECK_COUNT=$(echo "$CHECKS" | python3 -c "import json,sys; print(len(json.load(sys.stdin)))")
+  [ "$CHECK_COUNT" -eq 0 ] && { sleep 10; continue; }
+  PENDING=$(_count_pending "$CHECKS")
+  [ "$PENDING" -eq 0 ] && break
+  sleep 10
+done
+
+FAIL_CODE=0
+_print_failures "$CHECKS" || FAIL_CODE=$?
+
+if [ "$FAIL_CODE" -gt 0 ]; then
+  echo "CI failed on PR #$PR_NUMBER — fix the issues, push, then re-run this script."
+  exit 1
+fi
+
+# --no-review: explicit bypass — skip review gate entirely after CI passes.
+# Use only for solo-dev PRs where no reviewer will ever respond.
+if [ "$NO_REVIEW" -eq 1 ] && [ "$MODE" = "--merge" ]; then
+  echo "PR #$PR_NUMBER: CI passed. --no-review specified — skipping review gate."
+  _admin_merge; exit 0
+fi
+
+# --- Wait up to 6 min for a reviewer to act ---
+# Query reviewDecision directly so this works before review-status.yml creates
+# the derived review/decision commit status.
+REVIEW_TIMEOUT=360
+REVIEW_ELAPSED=0
+REVIEW_DECISION=$(_get_review_decision)
+if [ "$MODE" = "--merge" ] && [ "$REVIEW_CYCLE" -ge "$MAX_REVIEW_CYCLES" ] && [ "$REVIEW_DECISION" = "REVIEW_REQUIRED" ]; then
+  echo "Max review cycles ($MAX_REVIEW_CYCLES) reached — skipping reviewer wait and force-merging with admin override."
+  _admin_merge; exit 0
+fi
+
+if [ "$REVIEW_DECISION" = "REVIEW_REQUIRED" ] || [ "$REVIEW_DECISION" = "UNKNOWN" ]; then
+  echo "Waiting for reviewer (up to ${REVIEW_TIMEOUT}s, polling every 30s) — reviewDecision: ${REVIEW_DECISION}"
+fi
+while { [ "$REVIEW_DECISION" = "REVIEW_REQUIRED" ] || [ "$REVIEW_DECISION" = "UNKNOWN" ]; } && [ "$REVIEW_ELAPSED" -lt "$REVIEW_TIMEOUT" ]; do
+  sleep 30
+  REVIEW_ELAPSED=$((REVIEW_ELAPSED + 30))
+  REVIEW_DECISION=$(_get_review_decision)
+  echo "  [${REVIEW_ELAPSED}s/${REVIEW_TIMEOUT}s] reviewDecision: ${REVIEW_DECISION:-none}"
+  # Early exit: if any review activity exists (even COMMENTED), stop waiting.
+  # Bot reviewers like Codex post comments without changing reviewDecision.
+  if [ "$REVIEW_DECISION" = "REVIEW_REQUIRED" ] && _has_review_activity; then
+    echo "  Review comments detected — proceeding without waiting for formal approval."
+    break
+  fi
+  CHECKS=$(gh pr checks "$PR_NUMBER" --json name,state,bucket 2>/dev/null) || CHECKS="[]"
+done
+
+if [ "$REVIEW_DECISION" = "UNKNOWN" ]; then
+  echo "ERROR: could not fetch reviewDecision for PR #$PR_NUMBER — cannot verify review state." >&2
+  exit 2
+fi
+
+if [ "$REVIEW_DECISION" = "CHANGES_REQUESTED" ]; then
+  echo "Review/decision failed on PR #$PR_NUMBER (cycle $REVIEW_CYCLE/$MAX_REVIEW_CYCLES):"
+  _print_review_comments
+
+  if [ "$MODE" = "--merge" ]; then
+    if [ "$REVIEW_CYCLE" -ge "$MAX_REVIEW_CYCLES" ]; then
+      echo "Max review cycles ($MAX_REVIEW_CYCLES) reached — force-merging with admin override."
+      _admin_merge; exit 0
+    else
+      NEXT=$((REVIEW_CYCLE + 1))
+      echo "Address the comments above, push your changes, then re-run:"
+      echo "  .claude/scripts/monitor_pr.sh $PR_NUMBER --merge --review-cycle $NEXT"
+      exit 2
+    fi
+  fi
+  exit 1
+fi
+
+if [ "$REVIEW_DECISION" = "REVIEW_REQUIRED" ]; then
+  echo "PR #$PR_NUMBER: review/decision still pending after ${REVIEW_TIMEOUT}s — no reviewer has acted."
+  echo "  Full PR: $(gh pr view "$PR_NUMBER" --json url -q '.url' 2>/dev/null || true)"
+
+  if [ "$MODE" = "--merge" ]; then
+    if [ "$REVIEW_CYCLE" -ge "$MAX_REVIEW_CYCLES" ]; then
+      echo "Max review cycles ($MAX_REVIEW_CYCLES) reached — force-merging with admin override."
+      _admin_merge; exit 0
+    else
+      NEXT=$((REVIEW_CYCLE + 1))
+      echo "Request a review or wait for a reviewer, then re-run:"
+      echo "  .claude/scripts/monitor_pr.sh $PR_NUMBER --merge --review-cycle $NEXT"
+      exit 2
+    fi
+  fi
+  exit 1
+fi
+
+PR_URL=$(gh pr view "$PR_NUMBER" --json url -q '.url')
+echo "PR #$PR_NUMBER passed: $PR_URL"
+
+if [ "$MODE" = "--merge" ]; then
+  MERGE_STATE=$(gh pr view "$PR_NUMBER" --json mergeStateStatus -q '.mergeStateStatus' 2>/dev/null || echo "UNKNOWN")
+
+  if [ "$MERGE_STATE" = "CLEAN" ] || [ "$MERGE_STATE" = "UNSTABLE" ]; then
+    if _run_gh pr merge "$PR_NUMBER" --squash --delete-branch; then
+      echo "Merged PR #$PR_NUMBER"
+    else
+      echo "ERROR: merge failed for PR #$PR_NUMBER" >&2
+      exit 1
+    fi
+  elif [ "$MERGE_STATE" = "BLOCKED" ]; then
+    echo "PR is blocked by review protection — merging with admin override."
+    _admin_merge
+  else
+    if ! _run_gh pr merge "$PR_NUMBER" --squash --delete-branch; then
+      if ! _run_gh pr merge "$PR_NUMBER" --squash --delete-branch --auto; then
+        echo "ERROR: could not merge or enable auto-merge for PR #$PR_NUMBER" >&2
+        exit 1
+      fi
+      echo "Auto-merge enabled for PR #$PR_NUMBER — will merge once all requirements are met."
+    else
+      echo "Merged PR #$PR_NUMBER"
+    fi
+  fi
+fi

project_init/templates/base/dot_claude/scripts/promote_review.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+# Thin shim — actual logic lives in .claude/hooks/dag_workflow.py.
+exec python3 "$(dirname "$0")/../hooks/dag_workflow.py" promote "$@"

project_init/templates/base/dot_claude/scripts/push_branch.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+# Thin shim — actual logic lives in .claude/hooks/dag_workflow.py.
+# Kept under .claude/scripts/ so existing skill paths and agent muscle
+# memory keep working.
+exec python3 "$(dirname "$0")/../hooks/dag_workflow.py" push "$@"

project_init/templates/base/dot_claude/scripts/push_wiki.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# push_wiki.sh — clone the GitHub wiki, update Home.md, and push.
+# Usage: push_wiki.sh <repo-slug> <wiki-source-file>
+#   repo-slug       e.g. owner/repo-name
+#   wiki-source-file  path to the markdown file to write as Home.md
+#
+# The guard allowlists this script so it is not blocked by the git-push rule.
+
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+  echo "Usage: push_wiki.sh <repo-slug> <wiki-source-file>" >&2
+  exit 1
+fi
+
+REPO_SLUG="$1"
+SOURCE_FILE="$2"
+WIKI_DIR="$(mktemp -d)"
+trap 'rm -rf "$WIKI_DIR"' EXIT
+
+echo "Cloning wiki for $REPO_SLUG..."
+git clone "https://github.com/${REPO_SLUG}.wiki.git" "$WIKI_DIR"
+
+cp "$SOURCE_FILE" "$WIKI_DIR/Home.md"
+
+cd "$WIKI_DIR"
+git add Home.md
+if git diff --cached --quiet; then
+  echo "Wiki already up to date."
+  exit 0
+fi
+git commit -m "Update Home page"
+git push
+echo "Wiki updated."

project_init/templates/base/dot_claude/scripts/setup_github.sh

@@ -0,0 +1,219 @@
+#!/bin/bash
+# Configure or check GitHub repository governance for the scaffolded workflow.
+#
+# Usage: setup_github.sh [branch] [--protect]
+#   --protect  apply baseline branch protection to the default branch
+#              (require CI green, require PR review, block force-push).
+#              Idempotent: the PUT endpoint replaces the existing config.
+#
+# Requires: gh and admin permission on the repository.
+
+set -euo pipefail
+
+BRANCH="main"
+PROTECT=0
+for arg in "$@"; do
+  case "$arg" in
+    --protect) PROTECT=1 ;;
+    --*) echo "Unknown option: $arg" >&2; exit 1 ;;
+    *) BRANCH="$arg" ;;
+  esac
+done
+
+if ! gh auth status >/dev/null 2>&1; then
+  echo "ERROR: gh is not authenticated. Run gh auth login first." >&2
+  exit 1
+fi
+
+REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
+OWNER=${REPO%/*}
+NAME=${REPO#*/}
+
+echo "Configuring GitHub governance for $REPO ($BRANCH)"
+# Default endpoint: repos/$OWNER/$NAME/branches/main/protection
+
+if [ "$PROTECT" = 1 ]; then
+PROTECTION=$(mktemp)
+trap 'rm -f "$PROTECTION"' EXIT
+
+# Contexts must match the scaffolded workflows ("<workflow> / <job name>").
+# "CI / Integration tests" is omitted on purpose — that job is documented as
+# user-adjustable; add it here once your integration suite is stable.
+cat > "$PROTECTION" <<'JSON'
+{
+  "required_status_checks": {
+    "strict": true,
+    "contexts": [
+      "CI / Lint and test",
+      "CI / Secret scan (gitleaks)",
+      "Validate PR / Check PR title, branch, and linked issue",
+      "review/decision"
+    ]
+  },
+  "enforce_admins": false,
+  "required_pull_request_reviews": {
+    "required_approving_review_count": 1,
+    "dismiss_stale_reviews": true,
+    "require_code_owner_reviews": false,
+    "require_last_push_approval": false
+  },
+  "restrictions": null,
+  "required_conversation_resolution": true,
+  "allow_force_pushes": false,
+  "allow_deletions": false
+}
+JSON
+
+if gh api "repos/$OWNER/$NAME/branches/$BRANCH/protection" -X PUT --input "$PROTECTION" >/dev/null; then
+  echo "Branch protection applied to $BRANCH"
+else
+  echo "WARNING: could not apply branch protection. Check admin permissions and repository plan." >&2
+fi
+else
+  echo "Skipping branch protection (pass --protect to apply: require CI green, require review, block force-push)"
+fi
+
+if gh api "repos/$OWNER/$NAME/code-review-settings" -X PUT -f copilot_code_review_enabled=true >/dev/null 2>&1; then
+  echo "Copilot code review enabled"
+else
+  echo "WARNING: Enable Copilot code review manually if your plan supports it:" >&2
+  echo "  https://github.com/$OWNER/$NAME/settings/code_review" >&2
+fi
+
+# --- GitHub Project board field provisioning ---
+# Creates the single-select metadata fields used by board-automation.yml.
+# Requires a token with 'project' scope (set PROJECT_TOKEN env var, or ensure
+# gh auth token has project scope). Skips fields that already exist.
+echo ""
+echo "Provisioning GitHub Project board fields..."
+
+PROJECT_NUMBER="${PROJECT_NUMBER:-1}"
+
+# Use PROJECT_TOKEN if set, otherwise fall through to default gh auth
+if [ -n "${PROJECT_TOKEN:-}" ]; then
+  export GH_TOKEN="$PROJECT_TOKEN"
+fi
+
+PROJECT_DATA=$(gh api graphql -f query='
+  query($owner: String!, $number: Int!) {
+    user(login: $owner) {
+      projectV2(number: $number) {
+        id
+        fields(first: 50) { nodes { ... on ProjectV2SingleSelectField { name } } }
+      }
+    }
+    organization(login: $owner) {
+      projectV2(number: $number) {
+        id
+        fields(first: 50) { nodes { ... on ProjectV2SingleSelectField { name } } }
+      }
+    }
+  }' -f owner="$OWNER" -F number="$PROJECT_NUMBER" 2>/dev/null || echo '{}')
+
+PROJECT_ID=$(echo "$PROJECT_DATA" | jq -r \
+  '(.data.user.projectV2 // .data.organization.projectV2 // {}).id // empty')
+
+if [ -z "$PROJECT_ID" ]; then
+  echo "WARNING: Project #$PROJECT_NUMBER not found for $REPO." >&2
+  echo "  Ensure PROJECT_TOKEN has 'project' scope, or create these fields manually:" >&2
+  echo "  • Priority     — options: high, medium, low" >&2
+  echo "  • Size         — options: XS, S, M, L, XL" >&2
+  echo "  • Agent ready  — options: Yes, No" >&2
+  echo "  • Confidence   — options: high, medium, low, unknown" >&2
+  echo "  • Type         — options: feature, bug, chore, documentation, test" >&2
+  echo "  Settings: https://github.com/users/$OWNER/projects/$PROJECT_NUMBER/settings/fields" >&2
+else
+  EXISTING_FIELDS=$(echo "$PROJECT_DATA" | jq -r \
+    '((.data.user.projectV2 // .data.organization.projectV2).fields.nodes // [])[] | .name // empty')
+
+  ensure_single_select_field() {
+    local field_name="$1"
+    local mutation="$2"
+    if printf '%s\n' "$EXISTING_FIELDS" | grep -Fxq "$field_name"; then
+      echo "  '$field_name' already exists — skipping"
+      return 0
+    fi
+    if gh api graphql -f query="$mutation" -f projectId="$PROJECT_ID" >/dev/null 2>&1; then
+      echo "  Created '$field_name'"
+    else
+      # Repo: $REPO  Project: #$PROJECT_NUMBER
+      echo "  WARNING: could not create '$field_name' for $REPO — add it manually:" >&2
+      echo "    https://github.com/users/$OWNER/projects/$PROJECT_NUMBER/settings/fields" >&2
+    fi
+  }
+
+  ensure_single_select_field "Priority" '
+    mutation($projectId: ID!) {
+      createProjectV2Field(input: {
+        projectId: $projectId
+        dataType: SINGLE_SELECT
+        name: "Priority"
+        singleSelectOptions: [
+          { name: "high",   color: RED,    description: "" }
+          { name: "medium", color: YELLOW, description: "" }
+          { name: "low",    color: GRAY,   description: "" }
+        ]
+      }) { projectV2Field { ... on ProjectV2SingleSelectField { id } } }
+    }'
+
+  ensure_single_select_field "Size" '
+    mutation($projectId: ID!) {
+      createProjectV2Field(input: {
+        projectId: $projectId
+        dataType: SINGLE_SELECT
+        name: "Size"
+        singleSelectOptions: [
+          { name: "XS", color: BLUE,   description: "" }
+          { name: "S",  color: GREEN,  description: "" }
+          { name: "M",  color: YELLOW, description: "" }
+          { name: "L",  color: ORANGE, description: "" }
+          { name: "XL", color: RED,    description: "" }
+        ]
+      }) { projectV2Field { ... on ProjectV2SingleSelectField { id } } }
+    }'
+
+  ensure_single_select_field "Agent ready" '
+    mutation($projectId: ID!) {
+      createProjectV2Field(input: {
+        projectId: $projectId
+        dataType: SINGLE_SELECT
+        name: "Agent ready"
+        singleSelectOptions: [
+          { name: "Yes", color: GREEN, description: "" }
+          { name: "No",  color: GRAY,  description: "" }
+        ]
+      }) { projectV2Field { ... on ProjectV2SingleSelectField { id } } }
+    }'
+
+  ensure_single_select_field "Confidence" '
+    mutation($projectId: ID!) {
+      createProjectV2Field(input: {
+        projectId: $projectId
+        dataType: SINGLE_SELECT
+        name: "Confidence"
+        singleSelectOptions: [
+          { name: "high",    color: GREEN,  description: "" }
+          { name: "medium",  color: YELLOW, description: "" }
+          { name: "low",     color: ORANGE, description: "" }
+          { name: "unknown", color: GRAY,   description: "" }
+        ]
+      }) { projectV2Field { ... on ProjectV2SingleSelectField { id } } }
+    }'
+
+  ensure_single_select_field "Type" '
+    mutation($projectId: ID!) {
+      createProjectV2Field(input: {
+        projectId: $projectId
+        dataType: SINGLE_SELECT
+        name: "Type"
+        singleSelectOptions: [
+          { name: "feature",       color: BLUE,   description: "" }
+          { name: "bug",           color: RED,    description: "" }
+          { name: "chore",         color: GRAY,   description: "" }
+          { name: "documentation", color: PURPLE, description: "" }
+          { name: "test",          color: YELLOW, description: "" }
+        ]
+      }) { projectV2Field { ... on ProjectV2SingleSelectField { id } } }
+    }'
+fi
+

project_init/templates/base/dot_claude/scripts/start_issue.sh

@@ -0,0 +1,134 @@
+#!/bin/bash
+# Start work on a GitHub issue: create branch, push, and open a draft PR.
+#
+# Usage:
+#   .claude/scripts/start_issue.sh <issue-number> <type>
+#
+# Types: feat  fix  chore  docs  test
+#
+# Composable with create_issue.sh:
+#   .claude/scripts/create_issue.sh feat "Add OAuth login" | xargs -I{} .claude/scripts/start_issue.sh {} feat
+
+set -euo pipefail
+
+VALID_TYPES="feat fix chore docs test"
+
+usage() {
+  echo "Usage: start_issue.sh <issue-number> <type>"
+  echo ""
+  echo "Types: $VALID_TYPES"
+  echo ""
+  echo "Examples:"
+  echo "  start_issue.sh 42 feat"
+  echo "  start_issue.sh 99 fix"
+  exit 1
+}
+
+# --- Validate args ---
+if [ $# -lt 2 ]; then
+  usage
+fi
+
+ISSUE_NUMBER="$1"
+TYPE="$2"
+
+if ! echo "$VALID_TYPES" | grep -qw "$TYPE"; then
+  echo "ERROR: invalid type '$TYPE'. Valid types: $VALID_TYPES" >&2
+  exit 1
+fi
+
+if ! [[ "$ISSUE_NUMBER" =~ ^[0-9]+$ ]]; then
+  echo "ERROR: issue number must be numeric, got '$ISSUE_NUMBER'" >&2
+  exit 1
+fi
+
+# --- Resolve project key / abbreviation ---
+# Set PROJECT_KEY env var, add `project_key: PI` to .claude/config.yaml,
+# or let the script derive one from the repository directory name.
+derive_project_key() {
+  if [ -n "${PROJECT_KEY:-}" ]; then
+    echo "$PROJECT_KEY"
+    return
+  fi
+
+  local configured=""
+  configured=$(grep '^[[:space:]]*project_key:' .claude/config.yaml 2>/dev/null \
+    | head -n 1 \
+    | cut -d: -f2- \
+    | sed 's/#.*$//' \
+    | tr -d '[:space:]"' \
+    | tr -d "'" || true)
+  if [ -n "$configured" ]; then
+    echo "$configured"
+    return
+  fi
+
+  local repo_name=""
+  repo_name=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
+  echo "$repo_name" \
+    | tr '[:lower:]' '[:upper:]' \
+    | tr -cs 'A-Z0-9' '\n' \
+    | awk 'NF { printf substr($0, 1, 1) }' \
+    | cut -c1-10
+}
+
+PROJECT_KEY=$(derive_project_key)
+PROJECT_KEY=$(echo "$PROJECT_KEY" | tr '[:lower:]' '[:upper:]' | tr -cd 'A-Z0-9')
+if [ -z "$PROJECT_KEY" ]; then
+  PROJECT_KEY="PROJ"
+fi
+
+# --- Fetch issue title ---
+ISSUE_TITLE=$(gh issue view "$ISSUE_NUMBER" --json title -q '.title' 2>/dev/null)
+if [ -z "$ISSUE_TITLE" ]; then
+  echo "ERROR: issue #$ISSUE_NUMBER not found" >&2
+  exit 1
+fi
+
+ISSUE_REF="${PROJECT_KEY}-${ISSUE_NUMBER}"
+
+# --- Derive branch name: <issue_type>/<project_abbr>-<issue_number>-<kebab-slug>, max 80 chars total ---
+# Matches convention: feat/PI-42-add-oauth-login, fix/API-99-null-pointer
+# Strip leading [type] prefix from issue title if present (e.g. "[feat] Add OAuth" -> "Add OAuth")
+CLEAN_TITLE=$(echo "$ISSUE_TITLE" | sed 's/^\[[^]]*\] *//')
+SLUG=$(echo "$CLEAN_TITLE" \
+  | tr '[:upper:]' '[:lower:]' \
+  | tr -cs 'a-z0-9' '-' \
+  | sed 's/^-//;s/-$//')
+PREFIX="${ISSUE_REF}-"
+MAX_SLUG=$(( 80 - ${#TYPE} - 1 - ${#PREFIX} ))  # -1 for the /
+if [ "$MAX_SLUG" -lt 12 ]; then
+  MAX_SLUG=12
+fi
+SLUG="${SLUG:0:$MAX_SLUG}"
+SLUG="${SLUG%-}"   # trim trailing dash if truncated mid-word
+BRANCH="${TYPE}/${PREFIX}${SLUG}"
+
+echo "Branch: $BRANCH"
+
+# --- Guard: already on this branch or it already exists ---
+CURRENT=$(git branch --show-current)
+if [ "$CURRENT" = "$BRANCH" ]; then
+  echo "Already on branch $BRANCH"
+elif git show-ref --verify --quiet "refs/heads/$BRANCH"; then
+  echo "Branch $BRANCH already exists - switching"
+  git checkout "$BRANCH"
+else
+  git checkout -b "$BRANCH"
+fi
+
+# --- Push and set upstream (retry + remote-SHA verification) ---
+.claude/scripts/push_branch.sh "$BRANCH"
+
+# --- Open draft PR ---
+# Conventional Commits with issue key as scope (ADR-006)
+PR_TITLE="${TYPE}(${ISSUE_REF}): ${CLEAN_TITLE}"
+PR_BODY="Closes #${ISSUE_NUMBER}"
+
+PR_URL=$(gh pr create \
+  --draft \
+  --title "$PR_TITLE" \
+  --body "$PR_BODY")
+
+echo "Draft PR: $PR_URL"
+