@harbinger-ai/harbinger 0.1.0

package/templates/config/HEARTBEAT.md

@@ -0,0 +1,3 @@
+# Heartbeat Tasks
+
+Get the local weather for Claremont, CA and put it in /job/WEATHER.txt

package/templates/config/JOB_SUMMARY.md

@@ -0,0 +1,130 @@
+# Job Summary Bot
+
+You convert job result data into concise, scannable summaries. Adjust detail based on outcome: **less detail on success**, **more detail on failure or struggles**.
+
+## Output Rules
+
+- On success, lead with a short celebration using the short version of the actual job ID.
+- On failure (status is failure, cancelled, or timed_out), lead with a failure notice.
+- The job description should be a hyperlink to the PR on GitHub (or the run URL if no PR exists).
+- If the status is not closed/merged, prompt the reader to review it, with "Pull Request" as a hyperlink to the PR.
+- List changed files using dashes only (not bullets, **not** a link or clickable), with no explanations next to files.
+- Do not include `/logs` in the file list.
+
+## Output Format
+
+```
+Nice! <short_job_id> completed!
+
+Job: <job description as hyperlink to PR>
+Status: <status>
+
+Changes:
+- /folder/file1
+- /folder/file2
+
+Steps:
+- <what the agent did, chronologically>
+
+Went well:
+- <optional — only if something notable>
+
+Struggled with:
+- <optional — only if the agent hit difficulties>
+```
+
+### Section Rules
+
+**Steps** (always shown):
+- Up to 10 bullet points, fewer is fine — only include meaningful steps
+- Chronological order of what the agent actually did
+- Brief, action-oriented language (e.g., "Updated login flow", "Fixed 2 failing tests")
+- Skip trivial steps like reading files, thinking, or navigating — focus on actions taken
+
+**Went well** (optional — omit entirely if nothing notable):
+- 1-3 brief bullets on what worked smoothly or was done cleverly
+- Only include when there's something genuinely worth calling out
+
+**Struggled with** (optional — omit entirely if clean run):
+- 1-3 brief bullets on difficulties, retries, or workarounds
+- More detail on failure, less on success
+
+## Examples
+
+Successful run:
+
+Nice! a1b2c3d completed!
+
+Job: [Update auth module](https://github.com/org/repo/pull/42)
+Status: ✅ Merged
+
+Changes:
+- /src/auth/login.ts
+- /src/auth/utils.ts
+
+Steps:
+- Analyzed the existing auth module structure
+- Created new OAuth provider config
+- Updated login flow to use new provider
+- Ran tests and fixed 2 failing assertions
+- Cleaned up unused imports
+
+
+Open PR needing review:
+
+Nice! a1b2c3d completed!
+
+Job: [Fix pagination bug](https://github.com/org/repo/pull/43)
+Status: ⏳ Open — please review the [Pull Request](https://github.com/org/repo/pull/43)
+
+Changes:
+- /src/components/table.tsx
+
+Steps:
+- Identified off-by-one error in pagination logic
+- Patched the index calculation
+- Verified fix against edge cases
+
+
+Run with struggles:
+
+Nice! a1b2c3d completed!
+
+Job: [Add PDF export](https://github.com/org/repo/pull/44)
+Status: ✅ Merged
+
+Changes:
+- /src/export/pdf.ts
+- /package.json
+
+Steps:
+- Researched PDF generation libraries
+- Attempted jsPDF but hit rendering issues
+- Switched to puppeteer-based approach
+- Installed dependencies and configured headless Chrome
+- Implemented PDF export endpoint
+- Added tests
+
+Went well:
+- Final puppeteer implementation produces clean, well-formatted PDFs
+
+Struggled with:
+- Took several attempts to find a library that worked in the container environment
+
+
+Failed run (no PR):
+
+Job a1b2c3d failed!
+
+Job: [Add PDF export](https://github.com/org/repo/runs/12345)
+Status: ❌ Failed
+
+Steps:
+- Cloned repo and analyzed task requirements
+- Started implementing PDF export
+- Hit dependency installation errors
+- Attempted 3 different libraries without success
+
+Struggled with:
+- Could not resolve puppeteer dependencies in the container environment
+- Ran out of retries after 3 failed installation attempts

package/templates/config/MCP_SERVERS.json

@@ -0,0 +1 @@
+[]

package/templates/config/SKILL_BUILDING_GUIDE.md

@@ -0,0 +1,90 @@
+# Skill Building Guide
+
+## What is a skill?
+
+Skills are lightweight wrappers that extend agent abilities. They live in `skills/<skill-name>/` and are activated by symlinking into `skills/active/`. Both Pi and Claude Code discover skills from the same shared directory.
+
+## Skill structure
+
+- **`SKILL.md`** (required) — YAML frontmatter + markdown documentation
+- **Scripts** (optional) — prefer bash (.sh) for simplicity
+- **`package.json`** (optional) — only if Node.js dependencies are truly needed
+
+## SKILL.md format
+
+The `description` from frontmatter appears in the system prompt under "Active skills."
+Use project-root-relative paths in documentation (e.g., `skills/<skill-name>/script.sh`).
+
+```
+---
+name: skill-name-in-kebab-case
+description: One sentence describing what the skill does and when to use it.
+---
+
+# Skill Name
+
+## Usage
+
+```bash
+skills/skill-name/script.sh <args>
+```
+```
+
+## Example: Simple bash skill (most common pattern)
+
+The built-in `transcribe` skill — a SKILL.md and a single bash script:
+
+**skills/transcribe/SKILL.md:**
+```
+---
+name: transcribe
+description: Speech-to-text transcription using Groq Whisper API. Supports m4a, mp3, wav, ogg, flac, webm.
+---
+
+# Transcribe
+
+Speech-to-text using Groq Whisper API.
+
+## Setup
+Requires GROQ_API_KEY environment variable.
+
+## Usage
+```bash
+skills/transcribe/transcribe.sh <audio-file>
+```
+```
+
+**skills/transcribe/transcribe.sh:**
+```bash
+#!/bin/bash
+if [ -z "$1" ]; then echo "Usage: transcribe.sh <audio-file>"; exit 1; fi
+if [ -z "$GROQ_API_KEY" ]; then echo "Error: GROQ_API_KEY not set"; exit 1; fi
+curl -s -X POST "https://api.groq.com/openai/v1/audio/transcriptions" \
+  -H "Authorization: Bearer $GROQ_API_KEY" \
+  -F "file=@${1}" \
+  -F "model=whisper-large-v3-turbo" \
+  -F "response_format=text"
+```
+
+## Example: Skill with Node.js dependencies
+
+The built-in `brave-search` skill uses Node.js for HTML parsing (jsdom, readability, turndown). It has a `package.json` and `.js` scripts. Dependencies are installed automatically in Docker. Use this pattern only when bash + curl isn't sufficient.
+
+## Activation
+
+After creating skill files, symlink to activate:
+```bash
+ln -s ../skill-name skills/active/skill-name
+```
+
+## Always build AND test in the same job
+
+Tell the agent to test the skill with real input after creating it and fix any issues before committing. Don't create untested skills.
+
+## Credential setup
+
+If a skill needs an API key, the user should set it up BEFORE the job runs:
+- `npx thepopebot set-agent-llm-secret <KEY_NAME> <value>` — creates a GitHub secret with `AGENT_LLM_` prefix, exposed as an env var in the Docker container
+- The value is stored exactly as provided, no transformation needed
+- Also add to `.env` for local development
+- Keys can be rotated later with the same command

package/templates/config/SOUL.md

@@ -0,0 +1,17 @@
+# thepopebot Soul
+
+## Identity
+
+You are a diligent and capable AI worker. You approach tasks with focus, patience, and craftsmanship.
+
+## Personality Traits
+
+- **Methodical**: You work through problems systematically, step by step
+- **Reliable**: You follow through on commitments and complete what I start
+- **Curious**: You explore and learn from the codebase I work with
+- **Working Style**: You prefer to plan before acting
+
+## Values
+
+- **Quality over speed**: Better to do it right than do it twice
+- **Simplicity**: The simplest solution that works is usually best

package/templates/config/TRIGGERS.json

@@ -0,0 +1,58 @@
+[
+  {
+    "name": "on-github-event",
+    "watch_path": "/github/webhook",
+    "actions": [
+      { "type": "command", "command": "echo 'github webhook fired'" }
+    ],
+    "enabled": false
+  },
+  {
+    "name": "on-webhook-log",
+    "watch_path": "/webhook",
+    "actions": [
+      { "type": "command", "command": "echo 'webhook received: {{body}}'" }
+    ],
+    "enabled": false
+  },
+  {
+    "name": "review-github-event",
+    "watch_path": "/github/webhook",
+    "actions": [
+      { "type": "agent", "job": "A GitHub event occurred. Review the payload and summarize what happened:\n{{body}}" }
+    ],
+    "enabled": false
+  },
+  {
+    "name": "react-to-webhook",
+    "watch_path": "/webhook",
+    "actions": [
+      { "type": "agent", "job": "A webhook was received. Analyze the payload and decide if any action is needed:\n{{body}}" }
+    ],
+    "enabled": false
+  },
+  {
+    "name": "forward-github",
+    "watch_path": "/github/webhook",
+    "actions": [
+      { "type": "webhook", "url": "https://example.com/hook", "method": "POST", "vars": { "source": "github" } }
+    ],
+    "enabled": false
+  },
+  {
+    "name": "forward-webhook",
+    "watch_path": "/webhook",
+    "actions": [
+      { "type": "webhook", "url": "https://example.com/hook", "method": "POST", "vars": { "source": "webhook" } }
+    ],
+    "enabled": false
+  },
+  {
+    "name": "review-with-openai",
+    "watch_path": "/github/webhook",
+    "actions": [
+      { "type": "agent", "job": "Review the GitHub event and summarize what happened:\n{{body}}", "llm_provider": "openai", "llm_model": "gpt-4o" }
+    ],
+    "enabled": false
+  }
+]

package/templates/docker/event-handler/Dockerfile

@@ -0,0 +1,20 @@
+FROM node:22-bookworm-slim
+
+RUN apt-get update && apt-get install -y curl git python3 make g++ && \
+    curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+      | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg && \
+    echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+      | tee /etc/apt/sources.list.d/github-cli.list > /dev/null && \
+    apt-get update && apt-get install -y gh && \
+    rm -rf /var/lib/apt/lists/*
+RUN npm install -g pm2
+
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN npm install --omit=dev && \
+    npm install --no-save thepopebot@$(node -p "require('./package.json').version")
+
+COPY /templates/docker/event-handler/ecosystem.config.cjs /opt/ecosystem.config.cjs
+
+EXPOSE 80
+CMD ["pm2-runtime", "/opt/ecosystem.config.cjs"]

package/templates/docker/event-handler/ecosystem.config.cjs

@@ -0,0 +1,8 @@
+module.exports = {
+  apps: [{
+    name: 'next',
+    script: 'node_modules/.bin/next',
+    args: 'start -p 80',
+    kill_timeout: 120000,
+  }]
+};

package/templates/docker/job-claude-code/Dockerfile

@@ -0,0 +1,34 @@
+FROM node:22-bookworm-slim
+
+RUN apt-get update && apt-get install -y \
+    git \
+    jq \
+    curl \
+    procps \
+    libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 \
+    libcups2 libdrm2 libdbus-1-3 libxkbcommon0 \
+    libatspi2.0-0 libxcomposite1 libxdamage1 libxfixes3 \
+    libxrandr2 libgbm1 libasound2 libpango-1.0-0 libcairo2 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install GitHub CLI
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
+    && apt-get update && apt-get install -y gh \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN npm install -g @anthropic-ai/claude-code
+
+# Claude Code refuses --dangerously-skip-permissions as root.
+# Create a non-root user and give it ownership of /job.
+RUN useradd -m -s /bin/bash agent \
+    && mkdir -p /job \
+    && chown agent:agent /job
+
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+USER agent
+WORKDIR /job
+
+ENTRYPOINT ["/entrypoint.sh"]

package/templates/docker/job-claude-code/entrypoint.sh

@@ -0,0 +1,139 @@
+#!/bin/bash
+set -e
+
+# Extract job ID from branch name (job/uuid -> uuid), fallback to random UUID
+if [[ "$BRANCH" == job/* ]]; then
+    JOB_ID="${BRANCH#job/}"
+else
+    JOB_ID=$(cat /proc/sys/kernel/random/uuid)
+fi
+echo "Job ID: ${JOB_ID}"
+
+# Export SECRETS (JSON) as flat env vars (GH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN, etc.)
+if [ -n "$SECRETS" ]; then
+    eval $(echo "$SECRETS" | jq -r 'to_entries | .[] | "export \(.key)=\(.value | @sh)"')
+fi
+
+# Export LLM_SECRETS (JSON) as flat env vars
+if [ -n "$LLM_SECRETS" ]; then
+    eval $(echo "$LLM_SECRETS" | jq -r 'to_entries | .[] | "export \(.key)=\(.value | @sh)"')
+fi
+
+# Unset ANTHROPIC_API_KEY so Claude Code uses the OAuth token.
+# If both are set, Claude Code prioritizes API key (billing to API credits)
+# which defeats the purpose. The API key is for the event handler, not here.
+unset ANTHROPIC_API_KEY
+
+# Git setup - derive identity from GitHub token
+gh auth setup-git
+GH_USER_JSON=$(gh api user -q '{name: .name, login: .login, email: .email, id: .id}')
+GH_USER_NAME=$(echo "$GH_USER_JSON" | jq -r '.name // .login')
+GH_USER_EMAIL=$(echo "$GH_USER_JSON" | jq -r '.email // "\(.id)+\(.login)@users.noreply.github.com"')
+git config --global user.name "$GH_USER_NAME"
+git config --global user.email "$GH_USER_EMAIL"
+
+# Clone branch
+if [ -n "$REPO_URL" ]; then
+    git clone --single-branch --branch "$BRANCH" --depth 1 "$REPO_URL" /job
+else
+    echo "No REPO_URL provided"
+fi
+
+cd /job
+
+# Install npm deps for active skills (native deps need correct Linux arch)
+for skill_dir in /job/skills/active/*/; do
+    if [ -f "${skill_dir}package.json" ]; then
+        echo "Installing skill deps: $(basename "$skill_dir")"
+        (cd "$skill_dir" && npm install --omit=dev --no-package-lock)
+    fi
+done
+
+# Start Chrome if puppeteer installed it (needed by browser-tools skill)
+CHROME_PID=""
+CHROME_BIN=$(find /home/agent/.cache/puppeteer -name "chrome" -type f 2>/dev/null | head -1)
+if [ -n "$CHROME_BIN" ]; then
+    $CHROME_BIN --headless --no-sandbox --disable-gpu --remote-debugging-port=9222 2>/dev/null &
+    CHROME_PID=$!
+    sleep 2
+fi
+
+# Setup logs
+LOG_DIR="/job/logs/${JOB_ID}"
+mkdir -p "${LOG_DIR}"
+
+# Build system prompt from config MD files
+SYSTEM_PROMPT_FILE="${LOG_DIR}/system-prompt.md"
+SYSTEM_FILES=("SOUL.md" "AGENT.md")
+> "$SYSTEM_PROMPT_FILE"
+for i in "${!SYSTEM_FILES[@]}"; do
+    cat "/job/config/${SYSTEM_FILES[$i]}" >> "$SYSTEM_PROMPT_FILE"
+    if [ "$i" -lt $((${#SYSTEM_FILES[@]} - 1)) ]; then
+        echo -e "\n\n" >> "$SYSTEM_PROMPT_FILE"
+    fi
+done
+
+# Resolve {{datetime}} variable in system prompt
+sed -i "s/{{datetime}}/$(date -u +"%Y-%m-%dT%H:%M:%SZ")/g" "$SYSTEM_PROMPT_FILE"
+
+# Read job metadata from job.config.json
+JOB_CONFIG="/job/logs/${JOB_ID}/job.config.json"
+TITLE=$(jq -r '.title // empty' "$JOB_CONFIG")
+JOB_DESCRIPTION=$(jq -r '.job // empty' "$JOB_CONFIG")
+
+PROMPT="
+
+# Your Job
+
+${JOB_DESCRIPTION}"
+
+# Build --model flag if LLM_MODEL is set
+MODEL_FLAG=""
+if [ -n "$LLM_MODEL" ]; then
+    MODEL_FLAG="--model $LLM_MODEL"
+fi
+
+# Run Claude Code — capture exit code instead of letting set -e kill the script
+# stream-json gives the full conversation trace (thinking, tool calls, results)
+# similar to Pi's .jsonl session logs
+set +e
+claude -p "$PROMPT" \
+    $MODEL_FLAG \
+    --append-system-prompt-file "$SYSTEM_PROMPT_FILE" \
+    --dangerously-skip-permissions \
+    --verbose \
+    --output-format stream-json \
+    > "${LOG_DIR}/claude-session.jsonl" 2>"${LOG_DIR}/claude-stderr.log"
+AGENT_EXIT=$?
+
+# Commit based on outcome
+if [ $AGENT_EXIT -ne 0 ]; then
+    # Claude Code failed — only commit session logs, not partial code changes
+    git reset || true
+    git add -f "${LOG_DIR}"
+    git commit -m "🤖 Agent Job: ${TITLE} (failed)" || true
+else
+    # Claude Code succeeded — commit everything
+    git add -A
+    git add -f "${LOG_DIR}"
+    git commit -m "🤖 Agent Job: ${TITLE}" || true
+fi
+
+git push origin
+set -e
+
+# Cleanup Chrome
+if [ -n "$CHROME_PID" ]; then
+    kill $CHROME_PID 2>/dev/null || true
+fi
+
+# Create PR (auto-merge handled by GitHub Actions workflow)
+gh pr create --title "🤖 Agent Job: ${TITLE}" --body "${JOB_DESCRIPTION}" --base main || true
+
+# Re-raise failure so the workflow reports it
+if [ $AGENT_EXIT -ne 0 ]; then
+    echo "Claude Code exited with code ${AGENT_EXIT}"
+    exit $AGENT_EXIT
+fi
+
+echo "Done. Job ID: ${JOB_ID}"

package/templates/docker/job-pi-coding-agent/Dockerfile

@@ -0,0 +1,44 @@
+FROM node:22-bookworm-slim
+
+RUN apt-get update && apt-get install -y \
+    git \
+    jq \
+    curl \
+    procps \
+    # Chrome/Chromium dependencies
+    libnss3 \
+    libnspr4 \
+    libatk1.0-0 \
+    libatk-bridge2.0-0 \
+    libcups2 \
+    libdrm2 \
+    libdbus-1-3 \
+    libxkbcommon0 \
+    libatspi2.0-0 \
+    libxcomposite1 \
+    libxdamage1 \
+    libxfixes3 \
+    libxrandr2 \
+    libgbm1 \
+    libasound2 \
+    libpango-1.0-0 \
+    libcairo2 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install GitHub CLI
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
+    && apt-get update && apt-get install -y gh \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN npm install -g @mariozechner/pi-coding-agent
+
+# Create Pi config directory (extension loaded from repo at runtime)
+RUN mkdir -p /root/.pi/agent
+
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+WORKDIR /job
+
+ENTRYPOINT ["/entrypoint.sh"]