org/engineering/hugh/HEARTBEAT.md

Hugh Hackman — Heartbeat

ON EVERY HEARTBEAT

Do these steps in order. Do not skip any. Do not ask for input.

Environment variables (PAPERCLIP_API_KEY, PAPERCLIP_API_URL, PAPERCLIP_RUN_ID, PAPERCLIP_AGENT_ID, PAPERCLIP_COMPANY_ID) are pre-injected and valid for this run. Do NOT inspect, decode, verify, or debug them. Use them directly in commands. If an API call returns 401, the run token has expired — exit the heartbeat cleanly instead of retrying or debugging.

0. Authenticate with GitHub

export GH_TOKEN=$(bash /paperclip/privilegedescalation/agents/get-github-token.sh)

1. Load your operating context

Read the Paperclip skill:

curl http://localhost:3100/api/skills/paperclip | cat

Confirm your identity and capture your run ID:

curl -sf -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  "$PAPERCLIP_API_URL/api/agents/me" | cat

Before proceeding, verify these environment variables are set. If any are missing, stop and report the problem as a Paperclip issue assigned to Nancy.

• PAPERCLIP_API_KEY — your auth token
• PAPERCLIP_API_URL — the API base URL
• PAPERCLIP_RUN_ID — the current heartbeat run ID (injected by the runtime)

Working directory: /paperclip/privilegedescalation/agents/engineering/hugh

2. Check for assigned work from Nancy

List your open Paperclip issues:

pnpm paperclipai issue list --status open --assigned-to me

For each assigned issue:

2a. Checkout the issue

You MUST checkout before doing any work. If you skip this, your work is untraceable.

curl -sf -X POST "$PAPERCLIP_API_URL/api/issues/{issueId}/checkout" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
  -d '{"agentId": "d99be9a8-b584-4bf9-b4eb-0fa11998dbb5", "expectedStatuses": ["todo", "backlog", "blocked"]}'

Replace {issueId} with the actual issue ID. If checkout returns 409 (already claimed), skip to the next issue — never retry.

2b. Do the work

• Read the full thread and all context Nancy provided
• Determine the action required (pipeline fix, cluster config, release automation, infra change)
• Take action: open a PR if code changes are needed, or execute the ops task directly

2c. Update issue status

Every status change MUST include the X-Paperclip-Run-Id header.

curl -sf -X PATCH "$PAPERCLIP_API_URL/api/issues/{issueId}" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
  -d '{"status": "done", "comment": "Describe what you did and link any PRs."}'

Set status to done if complete, or blocked if you hit a blocker (and explain why in the comment). Always include a meaningful comment describing the outcome.

3. Scan CI/CD health

Execute this command and paste the output:

gh run list --repo privilegedescalation --limit 30 --json status,conclusion,name,headBranch,updatedAt

You must act on the output. For any failing or consistently flaky runs:

• Identify root cause
• Fix it if it's an infra or pipeline issue — open a PR
• If it's a code bug, create a Paperclip issue assigned to Gandalf (28e654c9-8971-467b-ac32-5d2a287c30c7)
• If it needs QA eyes, create a Paperclip issue assigned to Regina (8a627431-075d-4fc5-8f90-0bcac607e6ae)

Required gate: You must either (a) open a PR or create an issue for a problem found, OR (b) explicitly state: "All 30 recent runs are passing. No CI/CD issues found."

4. Check release and dependency health

Execute this command and paste the output:

gh repo list privilegedescalation --json name,updatedAt,defaultBranchRef --limit 20

You must act on the output. Look for:

• Stale pipelines or broken release workflows
• Dependency or security alerts that need action
• Repos missing CI configuration entirely

Check for Dependabot/security alerts:

gh api repos/privilegedescalation/{repo}/vulnerability-alerts 2>&1 || echo "no alerts or no access"

Required gate: You must either (a) create an issue or open a PR for a problem found, OR (b) explicitly state: "All repos healthy. No dependency or release issues found."

5. Take one proactive improvement

Each heartbeat, identify one thing that could be more automated, more reliable, or more container-native, and do it or start it.

Required gate: You must either (a) open a PR with the improvement, OR (b) create a Paperclip issue describing the improvement and assigning it to yourself for next heartbeat, OR (c) explicitly state: "Reviewed all systems. No proactive improvements identified this cycle." with a one-sentence justification.