/adopt

description: Bootstrap an existing repo for ForgeDock — triage open issues, apply labels, suggest a starter milestone, and identify first /work-on candidates
argument-hint: "[--dry-run | --limit <N> | --milestone | --no-milestone]"
install: extras

/adopt — Repo Bootstrap & Backlog Triage

**Input**: $ARGUMENTS

You onboard an existing repo into the ForgeDock pipeline. Unlike `/forgedock-init` (which generates `forge.yaml`) and `/issue` (which creates new issues), `/adopt` operates on an existing backlog: scanning open issues, classifying them, applying category and priority labels, suggesting a starter milestone, and ranking the best `/work-on` first candidates.

Run `/adopt` once after `npx forgedock init` + `/forgedock-init` to make a legacy backlog pipeline-ready without touching the issues themselves.

**Agent model policy**: `model: "{DEFAULT_MODEL}"` — resolved from forge.yaml `agents.default_model`, else "sonnet" (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154. **NEVER use plan mode (EnterPlanMode).**

<!-- FORGE:SPEC_LOADED — adopt.md loaded and active. Agent is bound by this spec. -->

---

Argument Parsing

| Flag | Effect | |------|--------| | (none) | Full triage — scan issues, apply labels, suggest milestone, report candidates | | `--dry-run` | Classify and report but do NOT write any labels or create any milestone | | `--limit <N>` | Cap issue scan to the N most recently updated open issues (default: 200) | | `--milestone` | After labeling, automatically create the suggested starter milestone (no prompt) | | `--no-milestone` | Skip milestone suggestion entirely |

Parse `$ARGUMENTS`:

DRY_RUN=false
ISSUE_LIMIT=200
AUTO_MILESTONE=false
SKIP_MILESTONE=false

for arg in $ARGUMENTS; do
  case "$arg" in
    --dry-run)       DRY_RUN=true ;;
    --milestone)     AUTO_MILESTONE=true ;;
    --no-milestone)  SKIP_MILESTONE=true ;;
    --limit)         NEXT_IS_LIMIT=true ;;
    *)
      if [ "$NEXT_IS_LIMIT" = "true" ]; then
        ISSUE_LIMIT="$arg"
        NEXT_IS_LIMIT=false
      fi
      ;;
  esac
done

If `DRY_RUN=true`, prefix all actions with `[DRY RUN]` and skip all `gh label` writes and issue creation.

---

Config Resolution

Read `forge.yaml` at the project root to resolve all project-specific variables before running any commands:

CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
if [ ! -f "$CONFIG_FILE" ]; then
  echo "ERROR: forge.yaml not found."
  echo ""
  echo "Run first: npx forgedock init"
  echo "Then:      /forgedock-init"
  echo "Then:      /adopt"
  exit 1
fi

GH_REPO=$(yq '.project.owner + "/" + .project.repo' "$CONFIG_FILE")
GH_FLAG="-R $GH_REPO"
REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE")
STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE")
DEFAULT_BRANCH=$(yq '.branches.default' "$CONFIG_FILE")
PROJECT_BOARD_OWNER=$(yq '.project_board.owner // .project.owner' "$CONFIG_FILE")
PROJECT_NUMBER=$(yq '.project_board.project_number // empty' "$CONFIG_FILE" 2>/dev/null || echo "")
PROJECT_ID=$(yq '.project_board.project_id // empty' "$CONFIG_FILE" 2>/dev/null || echo "")

All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{STAGING_BRANCH}`, `{DEFAULT_BRANCH}`, `{PROJECT_BOARD_OWNER}`, `{PROJECT_NUMBER}`, and `{PROJECT_ID}` references below are populated from `forge.yaml`.

---

Phase 0: Prerequisites

0A: GitHub auth check

if ! gh auth status &>/dev/null; then
  echo "ERROR: GitHub CLI not authenticated. Run: gh auth login"
  exit 1
fi

0B: Ensure required labels exist

ForgeDock commands depend on canonical label names. Bootstrap them idempotently before any labeling.

echo "Checking ForgeDock labels on ${GH_REPO}..."
cd "$REPO_PATH" && npx forgedock labels setup --repo "$GH_REPO" 2>&1 | tail -5
echo "Labels ready."

If `npx forgedock labels setup` is unavailable (e.g. local dev install), fall back to verifying key labels exist and creating any that are missing:

# Fallback: verify a sample of key labels exist
MISSING_LABELS=""
for label in "priority:P0" "priority:P1" "priority:P2" "priority:P3" "workflow:investigating" "workflow:ready-to-build" "workflow:building" "workflow:in-review" "workflow:merged" "workflow:invalid" "needs-human"; do
  gh label list ${GH_FLAG} --json name --jq '.[].name' 2>/dev/null | grep -qx "$label" || MISSING_LABELS="$MISSING_LABELS $label"
done
if [ -n "$MISSING_LABELS" ]; then
  echo "WARNING: Missing labels:$MISSING_LABELS"
  echo "Run 'npx forgedock labels setup' from $REPO_PATH to create them."
fi

0C: Count open issues

TOTAL_OPEN=$(gh issue list ${GH_FLAG} --state open --limit 1 --json number --jq '. | length' 2>/dev/null || echo "0")
# More accurate count via API
TOTAL_OPEN=$(gh api "repos/${GH_REPO}/issues?state=open&per_page=1" -i 2>/dev/null \
  | grep -i "^link:" | grep -oE 'page=[0-9]+>; rel="last"' | grep -oE '[0-9]+' | tail -1 || echo "$TOTAL_OPEN")
echo "Open issues in ${GH_REPO}: ${TOTAL_OPEN}"
echo "Will process up to ${ISSUE_LIMIT} issues."

---

Phase 1: Issue Scan

1A: Fetch all open issues

echo "Fetching open issues..."
ALL_ISSUES=$(gh issue list ${GH_FLAG} \
  --state open \
  --limit "$ISSUE_LIMIT" \
  --json number,title,body,labels,createdAt,updatedAt \
  --jq '.[]')

1B: Split into already-adopted and legacy

An issue is "already pipeline-ready" if it has ANY `workflow:` label OR any `priority:` label already applied. These should be skipped — they were either created via `/issue` or previously adopted.

LEGACY_ISSUES=$(echo "$ALL_ISSUES" | jq -s '
  .[] | select(
    (.labels | map(.name) | any(startswith("workflow:") or startswith("priority:"))) | not
  )
')

ALREADY_READY=$(echo "$ALL_ISSUES" | jq -s '
  .[] | select(
    (.labels | map(.name) | any(startswith("workflow:") or startswith("priority:")))
  )
')

LEGACY_COUNT=$(echo "$LEGACY_ISSUES" | jq -s '. | length')
READY_COUNT=$(echo "$AL