feat(suggestions): permission gate + full loop for external contributors

pm-suggestions.yml:
- Write access → PM processes immediately
- No write access → tag @deepgram-devrel with needs:approval label; agent
  does nothing until devrel adds 'approved' label (re-triggers workflow)
- Bots silently skipped
- schedule/workflow_dispatch always pass (no user context)

engineer.md:
- PRs now include 'Closes #N' when queue issue originated from a public
  suggestion — GitHub closes the original issue on PR merge, notifying
  the contributor their request has been released

setup-labels.yml:
- Add needs:approval, approved, needs:clarification labels

Full contributor loop:
  Public opens issue → devrel adds 'approved' → PM queues it →
  Researcher + Engineer build it → PR merges → original issue closed
  with notification to contributor

Author: lukeocodes

.github/workflows/pm-suggestions.yml

@@ -5,6 +5,7 @@ on:
     types:
       - opened        # Every new issue, regardless of labels or format
       - reopened
+      - labeled       # Re-process when devrel adds 'approved' to external issues
   schedule:
     - cron: '47 * * * *'   # Hourly sweep to catch anything missed
   workflow_dispatch:
@@ -15,7 +16,6 @@ concurrency:
 
 jobs:
   run:
-    # Always run — PM reads the issue and decides what to do with it
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -32,7 +32,90 @@ jobs:
           git config user.name "examples-bot"
           git config user.email "noreply@deepgram.com"
 
+      # ── Permission gate ──────────────────────────────────────────────────
+      # Write access = act immediately.
+      # No write access = hold for devrel approval; don't run PM agent.
+      # Schedule/dispatch runs bypass the check (no user context).
+      - name: Check write permission
+        id: permission
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          EVENT="${{ github.event_name }}"
+          USERNAME="${{ github.event.issue.user.login }}"
+
+          # Schedule and dispatch runs always proceed
+          if [[ "$EVENT" == "schedule" || "$EVENT" == "workflow_dispatch" ]]; then
+            echo "gate=pass" >> $GITHUB_OUTPUT
+            echo "reason=scheduled" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          # If the 'approved' label was just added, treat as approved regardless of opener
+          LABEL="${{ github.event.label.name }}"
+          if [[ "$EVENT" == "issues" && "$LABEL" == "approved" ]]; then
+            echo "gate=pass" >> $GITHUB_OUTPUT
+            echo "reason=devrel-approved" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          # Check if the issue opener already has the 'approved' label (re-opened etc.)
+          HAS_APPROVED=$(gh issue view ${{ github.event.issue.number }} \
+            --repo ${{ github.repository }} \
+            --json labels --jq '[.labels[].name] | contains(["approved"])' 2>/dev/null || echo "false")
+          if [[ "$HAS_APPROVED" == "true" ]]; then
+            echo "gate=pass" >> $GITHUB_OUTPUT
+            echo "reason=already-approved" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          # Skip bots
+          if [[ "$USERNAME" == *"[bot]"* ]]; then
+            echo "gate=skip" >> $GITHUB_OUTPUT
+            echo "reason=bot" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          # Check write permission on this repo
+          PERM=$(gh api "repos/${{ github.repository }}/collaborators/${USERNAME}/permission" \
+            --jq '.permission' 2>/dev/null || echo "none")
+          echo "Permission for $USERNAME: $PERM"
+
+          if [[ "$PERM" == "write" || "$PERM" == "maintain" || "$PERM" == "admin" ]]; then
+            echo "gate=pass" >> $GITHUB_OUTPUT
+            echo "reason=has-write-access" >> $GITHUB_OUTPUT
+          else
+            echo "gate=hold" >> $GITHUB_OUTPUT
+            echo "reason=no-write-access" >> $GITHUB_OUTPUT
+            echo "username=$USERNAME" >> $GITHUB_OUTPUT
+          fi
+
+      # ── Hold: tag devrel for external suggestions ──────────────────────
+      - name: Hold for devrel approval
+        if: steps.permission.outputs.gate == 'hold'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          USERNAME="${{ steps.permission.outputs.username }}"
+          ISSUE="${{ github.event.issue.number }}"
+
+          # Only post once — skip if already held
+          ALREADY=$(gh issue view "$ISSUE" --repo ${{ github.repository }} \
+            --json labels --jq '[.labels[].name] | contains(["needs:approval"])' 2>/dev/null || echo "false")
+          if [[ "$ALREADY" == "true" ]]; then
+            echo "Already on hold — skipping duplicate comment"
+            exit 0
+          fi
+
+          gh issue edit "$ISSUE" --repo ${{ github.repository }} \
+            --add-label "needs:approval" 2>/dev/null || true
+
+          BODY="@deepgram-devrel — new suggestion from @${USERNAME} (no write access). Add the \`approved\` label to process it, or close to decline."
+          gh issue comment "$ISSUE" --repo ${{ github.repository }} --body "$BODY"
+
+      # ── Pass: run PM agent ────────────────────────────────────────────
       - name: Route issue
+        if: steps.permission.outputs.gate == 'pass'
         uses: anthropics/claude-code-action@beta
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
@@ -48,6 +131,7 @@ jobs:
             - Event: ${{ github.event_name }}
             - Issue number (if triggered by issue): ${{ github.event.issue.number }}
             - Repository: ${{ github.repository }}
+            - Trigger reason: ${{ steps.permission.outputs.reason }}
         env:
           KAPA_API_KEY: ${{ secrets.KAPA_API_KEY }}
           KAPA_PROJECT_ID: ${{ vars.KAPA_PROJECT_ID }}

.github/workflows/setup-labels.yml

@@ -38,6 +38,11 @@ jobs:
           create_label "queue:new-example"   "bfd4f2" "Queue: build a new example"
           create_label "queue:fix-example"   "bfd4f2" "Queue: fix a broken example"
 
+          # External suggestion approval labels
+          create_label "needs:approval"  "fbca04" "Waiting for devrel to approve external suggestion"
+          create_label "approved"        "0e8a16" "Approved by devrel — PM agent will process"
+          create_label "needs:clarification" "e4e669" "PM needs more info before acting"
+
           # Product labels
           create_label "product:stt"          "5319e7" "Speech-to-text"
           create_label "product:tts"          "5319e7" "Text-to-speech"

instructions/engineer.md

@@ -239,6 +239,15 @@ git add "examples/${NEXT}-${SLUG}/"
 git commit -m "feat(examples): add ${NEXT} — {description}"
 git push origin "$BRANCH"
 
+# Check if the queue issue has an origin issue to close when this PR merges.
+# The PM sets "Requested in #{N}" in the queue issue body for external suggestions.
+ORIGIN_ISSUE=""
+QUEUE_BODY=$(gh issue view {issue_number} --json body --jq '.body' 2>/dev/null || echo "")
+ORIGIN_NUM=$(echo "$QUEUE_BODY" | grep -oE 'Requested in #([0-9]+)' | grep -oE '[0-9]+' | head -1)
+if [ -n "$ORIGIN_NUM" ]; then
+  ORIGIN_ISSUE="Closes #${ORIGIN_NUM}"
+fi
+
 PR_URL=$(gh pr create \
   --title "[Example] ${NEXT} — {Title}" \
   --label "type:example,language:{lang},integration:{slug}" \
@@ -263,6 +272,8 @@ integrations: {integration-slug}
 ### Required secrets
 {vars beyond DEEPGRAM_API_KEY, or "None — only DEEPGRAM_API_KEY required"}
 
+${ORIGIN_ISSUE}
+
 ---
 *Built by Engineer on {date}*
 EOF

instructions/pm-suggestions.md

@@ -136,11 +136,27 @@ Requested in #{number}: {brief quote from original issue}
 {Any links from the original issue, or blank}
 
 ---
-*Queued by PM from #${number} on {date}*
+*Queued by PM from #{number} on {date}*
 EOF
 )"
 
-gh issue close {number} --comment "Queued as a new example. Tracking in #{new_issue_number}."
+# Get the new queue issue number
+NEW_ISSUE=$(gh issue list --repo ${{ github.repository }} \
+  --label "queue:new-example" --state open --limit 1 \
+  --json number --jq '.[0].number' 2>/dev/null)
+
+# Close the original suggestion with a friendly message
+# Note: use "closes #{PR_NUMBER}" in the PR body later so GitHub auto-closes
+# the original issue when the example PR merges — completing the full loop
+gh issue comment {number} --body "Thanks for the suggestion! 🎉
+
+I've queued this for the team. The Engineer will build the example and open a PR.
+I'll update this issue and close it when the example is released.
+
+Tracking: #{NEW_ISSUE}"
+
+# Don't close yet — leave it open so the contributor can track progress.
+# The PR body will include 'Closes #{number}' so GitHub closes it on merge.
 ```
 
 ---