thepopebot 1.2.76-beta.2 → 1.2.76-beta.21

package/setup/lib/telegram.mjs

@@ -1,72 +1,11 @@
-import { randomBytes } from 'crypto';
-
-/**
- * Generate a verification code for Telegram chat ID capture
- */
-export function generateVerificationCode() {
-  return 'verify-' + randomBytes(4).toString('hex');
-}
-
-/**
- * Register a Telegram webhook
- */
-export async function setTelegramWebhook(botToken, webhookUrl, secretToken = null) {
-  // Delete first — Telegram ignores secret_token changes if the URL is unchanged
-  await deleteTelegramWebhook(botToken);
-
-  const body = { url: webhookUrl };
-  if (secretToken) {
-    body.secret_token = secretToken;
-  }
-
-  const response = await fetch(
-    `https://api.telegram.org/bot${botToken}/setWebhook`,
-    {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(body),
-    }
-  );
-
-  const result = await response.json();
-  return result;
-}
-
-/**
- * Get current webhook info
- */
-export async function getTelegramWebhookInfo(botToken) {
-  const response = await fetch(`https://api.telegram.org/bot${botToken}/getWebhookInfo`);
-  const result = await response.json();
-  return result;
-}
-
-/**
- * Delete existing webhook
- */
-export async function deleteTelegramWebhook(botToken) {
-  const response = await fetch(`https://api.telegram.org/bot${botToken}/deleteWebhook`, {
-    method: 'POST',
-  });
-  const result = await response.json();
-  return result;
-}
-
-/**
- * Validate bot token by calling getMe
- */
-export async function validateBotToken(botToken) {
-  try {
-    const response = await fetch(`https://api.telegram.org/bot${botToken}/getMe`);
-    const result = await response.json();
-    if (result.ok) {
-      return { valid: true, botInfo: result.result };
-    }
-    return { valid: false, error: result.description };
-  } catch (error) {
-    return { valid: false, error: error.message };
-  }
-}
+// Re-export Telegram API helpers from the package (single source of truth).
+// The CLI setup wizard shares these helpers with the admin UI server actions.
+export {
+  validateBotToken,
+  setTelegramWebhook,
+  getTelegramWebhookInfo,
+  deleteTelegramWebhook,
+} from '../../lib/tools/telegram.js';
 
 /**
  * Get BotFather URL for creating a new bot

package/templates/.env.example

@@ -29,9 +29,6 @@ TELEGRAM_BOT_TOKEN=
 # Secret for validating Telegram webhooks (generate with: openssl rand -hex 32)
 TELEGRAM_WEBHOOK_SECRET=
 
-# Verification code for getting your chat ID (e.g., verify-abc12345)
-TELEGRAM_VERIFICATION=
-
 # Secret for GitHub Actions webhook auth (must match GH_WEBHOOK_SECRET secret)
 GH_WEBHOOK_SECRET=
 
@@ -50,10 +47,6 @@ ASSEMBLYAI_API_KEY=
 # LLM model name override (optional, provider-specific default if unset)
 # LLM_MODEL=
 
-# Default Telegram chat ID for scheduled notifications
-# Get this by messaging your bot and checking the webhook logs, or use @userinfobot
-TELEGRAM_CHAT_ID=
-
 # Let's Encrypt email for automatic SSL (docker-compose only, optional)
 # If not set, Traefik uses a self-signed certificate
 # LETSENCRYPT_EMAIL=

package/templates/.github/workflows/rebuild-event-handler.yml

@@ -71,7 +71,7 @@ jobs:
       - name: Reload (no version change)
         if: steps.pull.outputs.status == 'RELOAD'
         run: |
-          docker exec thepopebot-event-handler npx pm2 reload all
+          docker exec thepopebot-event-handler gosu coding-agent pm2 reload all
 
       - name: Pull new image and restart container
         if: steps.pull.outputs.status == 'VERSION_CHANGED'

package/templates/.gitignore.template

@@ -11,11 +11,9 @@
 # Playwright MCP
 .playwright-mcp/
 
-# Pi system prompt (generated at runtime from SOUL.md)
+# Pi system prompt (generated at runtime)
 .pi/SYSTEM.md
 
-# Dynamically activated skills (created at container runtime, not user config)
-skills/active/agent-job-secrets
 
 # Database
 /data/

package/templates/CLAUDE.md

@@ -11,7 +11,7 @@ This directory contains files that get copied into user projects when they run `
 
 ## What belongs here
 
-- **Agent job config**: `agent-job/SOUL.md`, `agent-job/CRONS.json`, etc.
+- **Agent job config**: `agent-job/SYSTEM.md`, `agent-job/CRONS.json`, etc.
 - **Event handler config**: `event-handler/agent-chat/SYSTEM.md`, `event-handler/TRIGGERS.json`, etc.
 - **GitHub Actions workflows**: `.github/workflows/`
 - **Docker compose**: `docker-compose.yml`

package/templates/CLAUDE.md.template

@@ -4,10 +4,11 @@ This is a [thepopebot](https://github.com/stephengpope/thepopebot) project.
 
 ## Directories
 
-- **`agent-job/`** — Agent job configuration: system prompts (`SOUL.md`, `SYSTEM.md`), heartbeat prompt, and cron schedules (`CRONS.json`).
+- **`agent-job/`** — Agent job configuration: system prompt (`SYSTEM.md`), heartbeat prompt, and cron schedules (`CRONS.json`).
+- **`coding-workspace/`** — Optional system prompt (`SYSTEM.md`) for code mode workspaces. Empty by default.
 - **`agents/`** — Custom agent definitions. Each subdirectory defines an agent (see Managing Agents below).
 - **`event-handler/`** — Event handler configuration: chat system prompts, trigger definitions (`TRIGGERS.json`), cluster templates, and LiteLLM proxy config.
-- **`skills/library/`** — Skill plugins. Activate by symlinking into `skills/active/`.
+- **`skills/`** — Skill plugins. Each subdirectory with a `SKILL.md` is an active skill.
 - **`data/`** — Runtime data (SQLite database, cluster state). Not checked into git.
 - **`logs/`** — Agent job logs, organized by job ID. Not checked into git.
 
@@ -19,16 +20,37 @@ This is a [thepopebot](https://github.com/stephengpope/thepopebot) project.
 
 ## Managed Files
 
-Some files are auto-synced by `npx thepopebot init` and will be overwritten on upgrade. Do not edit these:
+Some files are auto-synced by `npx thepopebot init` and will be overwritten on every init/upgrade. Do not edit these:
 
 - `.github/workflows/` — CI/CD workflows
 - `docker-compose.yml`
 - `.dockerignore`
 - `.gitignore`
-- `agent-job/CLAUDE.md`
-- `agents/CLAUDE.md`
-- `event-handler/CLAUDE.md`
-- `skills/CLAUDE.md`
+
+The `CLAUDE.md` files scattered through the project tree (e.g. `agent-job/CLAUDE.md`, `agents/CLAUDE.md`, `event-handler/CLAUDE.md`, `skills/CLAUDE.md`) are scaffolded by `init` from `*.template` sources but are **not** in the managed-paths list — they will not be overwritten if you have edited them. Run `npx thepopebot reset <path>` to restore one to its template default, or `npx thepopebot diff <path>` to see your local changes.
+
+## Agent Scoping
+
+Agents can be scoped to subdirectories within the repository. When a chat is launched with a scope (e.g., `agents/gary-vee`), the coding agent runs with that directory as its working directory.
+
+### Directory Structure
+
+```
+agents/
+  gary-vee/
+    CLAUDE.md         ← agent-specific context (optional)
+    SYSTEM.md         ← agent-specific system prompt (optional)
+    skills/           ← agent-specific skills (optional, overrides root skills/)
+      agent-job-secrets → ../../../skills/agent-job-secrets  (symlink)
+      custom-skill/
+```
+
+### How Scoping Works
+
+- **Working directory** — The agent's cwd is set to the scoped directory. It still has access to the full repo.
+- **Skills** — If the scoped directory has a `skills/` folder, those skills are used. If not, the root `skills/` folder is used as a fallback. Sub-agent skills can symlink back to root skills they need.
+- **CLAUDE.md** — The coding agent automatically picks up `.claude/` and `CLAUDE.md` files relative to its working directory.
+- **Default scope** — When no scope is selected, the agent runs from the repository root with root-level skills.
 
 ## Agents
 

package/templates/agent-job/CLAUDE.md.template

@@ -4,8 +4,7 @@ This directory contains your agent job configuration files — system prompts, s
 
 ## Files
 
-- **`SOUL.md`** — Agent personality, identity, and values. Included in every agent job system prompt.
-- **`SYSTEM.md`** — Runtime environment documentation injected into the agent's context.
+- **`SYSTEM.md`** — Agent system prompt: identity, runtime environment, and instructions. Rendered with full template support (`{{skills}}`, `{{datetime}}`, file includes).
 - **`HEARTBEAT.md`** — Prompt for the agent's periodic heartbeat cron job.
 - **`CRONS.json`** — Scheduled job definitions, loaded at server startup.
 
@@ -27,7 +26,10 @@ There are three action types:
 }
 ```
 
-Optional: add `"llm_provider"` and `"llm_model"` to override the default LLM for that job.
+Optional fields:
+- `"scope"` (e.g. `"agents/my-agent"`) — routes the cron to a scoped agent. Its `SYSTEM.md`, skills directory, and working directory all switch to that subdirectory. See `agents/CLAUDE.md` for the full pattern.
+- `"agent_backend"` (e.g. `"claude-code"`, `"codex-cli"`, `"gemini-cli"`, `"pi"`, `"opencode"`, `"kimi-cli"`) — pick which coding agent runs the job, overriding the default set in Admin > Event Handler > Coding Agents.
+- `"llm_model"` — override the model used within the selected coding agent (provider is implicit in the agent).
 
 **`command`** — Runs a shell command on the event handler (working directory: project root).
 

package/templates/agent-job/CRONS.json

@@ -12,5 +12,21 @@
     "type": "command",
     "command": "echo \"pong!\"",
     "enabled": true
+  },
+  {
+    "name": "scoped-agent-example",
+    "schedule": "0 9 * * *",
+    "type": "agent",
+    "job": "Read jobs/daily-check.md and complete it.",
+    "scope": "agents/my-agent",
+    "enabled": false
+  },
+  {
+    "name": "agent-backend-override-example",
+    "schedule": "0 10 * * *",
+    "type": "agent",
+    "job": "Summarize open pull requests.",
+    "agent_backend": "codex-cli",
+    "enabled": false
   }
 ]

package/templates/agent-job/SYSTEM.md

@@ -1,31 +1,29 @@
 # Agent Job Environment
 
-You are an autonomous AI agent running inside a Docker container on thepopebot.
+You are an autonomous AI agent running inside a Docker container on thepopebot. You approach tasks methodically — plan before acting, favor simplicity, and prioritize quality over speed.
 
 ## Runtime Environment
 
 Your workspace is `/home/coding-agent/workspace` — a live git repository.
 
 ## Temporary Files
-Use `/home/coding-agent/workspace/.tmp/` for working files — downloads, screenshots, intermediate data, scripts, generated files. `/home/coding-agent/workspace/.tmp/` is gitignored and nothing there gets committed. If a tool downloads a file, save it to `/home/coding-agent/workspace/.tmp/` and reference it directly.
+Use `/tmp` for working files — downloads, screenshots, intermediate data, scripts, generated files. If a tool downloads a file, save it to `/tmp` and reference it directly.
 
-**DO NOT USE** `/tmp` because that will leak and waste disk space from writing extra layers to the container.
-
-Everything in the workspace is automatically committed and pushed when your job finishes. You do not control this. Be intentional about what you put here — **any file you create, move, or download into the workspace WILL be committed.**
+Everything in the workspace `/home/coding-agent/workspace` is automatically committed and pushed when your job finishes. You do not control this. Be intentional about what you put here — **any file you create, move, or download into the workspace WILL be committed.**
 
 ## Directory Layout
 
 - `agents/` — Agent definitions. Each subdirectory defines an agent with its own prompts.
-- `agent-job/` — Runtime config: system prompts (`SOUL.md`, `SYSTEM.md`), cron schedules (`CRONS.json`), heartbeat prompt.
+- `agent-job/` — Runtime config: system prompt (`SYSTEM.md`), cron schedules (`CRONS.json`), heartbeat prompt.
 - `event-handler/` — Event handler config. Do not edit — managed by the event handler.
-- `skills/library/` — Skill plugins. Active skills are symlinked into `skills/active/`.
+- `skills/` — Skill plugins. Each subdirectory with a `SKILL.md` is an active skill.
 - `data/`, `logs/` — Runtime data and job logs.
 
 ## What You Can Edit
 
 - `agent-job/CRONS.json` — Add, remove, or change scheduled jobs
 - `agents/` — Create or remove agent definitions
-- `skills/active/` — Activate or deactivate skills via symlinks
+- `skills/` — Add or remove skill directories
 - Agent prompt files (`.md`) in `agent-job/` and `agents/`
 - Reports and output files
 
@@ -35,17 +33,24 @@ Everything in the workspace is automatically committed and pushed when your job
 - `docker-compose.yml`, `.dockerignore`, `.gitignore` — Managed infrastructure files
 - `.env` — Environment secrets
 
+## Agent Scoping
+
+Agents can be scoped to subdirectories under `agents/`. When scoped, the agent's working directory is set to that subdirectory (e.g., `agents/gary-vee/`). The full repo is still accessible.
+
+- **Skills fallback** — If the scoped directory has a `skills/` folder, those are used. Otherwise, the root `skills/` folder applies. Sub-agents can symlink individual skills from root: `skills/agent-job-secrets → ../../../skills/agent-job-secrets`.
+- **No skills folder needed** — If you don't create a `skills/` directory in the agent scope, it inherits all root skills automatically.
+
 ## Self-Modification
 
-**Add an agent** — Create `agents/<name>/` with a `jobs/` subfolder, add a cron entry in `agent-job/CRONS.json` pointing to the prompt file, update `agents/CLAUDE.md` to document it, update root `CLAUDE.md` to reflect the new agent.
+**Add an agent** — Create `agents/<name>/` with an optional `CLAUDE.md`, `SYSTEM.md`, and `skills/` directory. Add a cron entry in `agent-job/CRONS.json` if it runs on a schedule. Update `agents/CLAUDE.md` and root `CLAUDE.md`.
 
 **Remove an agent** — Delete the `agents/<name>/` folder, remove its cron entries, update `agents/CLAUDE.md` and root `CLAUDE.md`.
 
 **Change a schedule** — Edit `agent-job/CRONS.json` (cron expressions, enable/disable).
 
-**Activate a skill** — Symlink from `skills/library/<name>/` into `skills/active/`, update root `CLAUDE.md`.
+**Add a skill** — Create a directory in `skills/` with a `SKILL.md`, update root `CLAUDE.md`.
 
-**Deactivate a skill** — Remove the symlink from `skills/active/`, update root `CLAUDE.md`.
+**Remove a skill** — Delete the directory from `skills/`, update root `CLAUDE.md`.
 
 **Keep CLAUDE.md files current** — When you change the structure of the instance (add/remove agents, change schedules, activate skills), update the root `CLAUDE.md` and any affected folder-level `CLAUDE.md` files so the next agent has an accurate picture.
 

package/templates/agents/CLAUDE.md.template

@@ -2,15 +2,22 @@
 
 ## Adding an Agent
 
-Each subdirectory defines an agent. Create a folder with a `SYSTEM.md` file:
+Each subdirectory defines an agent. At minimum create a folder with a `SYSTEM.md` file:
 
 ```
 agents/
 └── my-agent/
-    └── SYSTEM.md        # System prompt — identity, instructions, constraints
+    ├── SYSTEM.md        # System prompt — identity, instructions, constraints (required)
+    ├── CLAUDE.md        # Optional — guidance for AI assistants editing this agent's files
+    ├── skills/          # Optional — agent-specific skills (overrides root skills/ for this scope)
+    └── jobs/            # Optional — reusable task prompts referenced from CRONS.json
 ```
 
-`SYSTEM.md` is the agent's system prompt. Write it in markdown addressed to the agent (e.g. "You are a code reviewer...").
+`SYSTEM.md` is the agent's system prompt. Write it in markdown addressed to the agent (e.g. "You are a code reviewer..."). `CLAUDE.md` (if present) is read by AI assistants working in this directory — use it for non-obvious context only.
+
+**Skills resolution**: when a job runs with `scope: "agents/my-agent"`, the runtime checks `agents/my-agent/skills/` first; missing skills fall back to root `skills/`. To override a built-in skill for one agent, drop a same-named SKILL.md under that agent's `skills/`.
+
+> **Important:** `agents/<name>/SYSTEM.md` **replaces** `agent-job/SYSTEM.md` when the agent is scoped — it doesn't extend it. Use `agent-job/SYSTEM.md` as a starting template and adapt it: keep the runtime environment notes, the `/tmp` scratch directive, and add the `{{skills}}` token if you want skill descriptions injected. Then add the agent's identity-specific instructions on top.
 
 For agents with multiple complex tasks, add a `jobs/` subfolder:
 
@@ -25,29 +32,22 @@ agents/
 
 ## Scheduling
 
-Add a cron entry in `agent-job/CRONS.json`:
+Add a cron entry in `agent-job/CRONS.json` with a `scope` field pointing at the agent:
 
 ```json
 {
-  "name": "my-agent-daily",
-  "schedule": "0 9 * * *",
+  "name": "my-agent-weekly-report",
+  "schedule": "0 9 * * 1",
   "type": "agent",
-  "job": "Read agents/my-agent/SYSTEM.md and follow the instructions there.",
+  "scope": "agents/my-agent",
+  "job": "Follow the instructions in jobs/weekly-report.md",
   "enabled": true
 }
 ```
 
-For job-specific prompts, chain the reads:
+`scope` activates the agent's identity (`SYSTEM.md`), skills, and working directory — the cron runs as the scoped agent, not from the repo root. `job` is the task prompt the agent receives.
 
-```json
-{
-  "name": "my-agent-report",
-  "schedule": "0 9 * * 1",
-  "type": "agent",
-  "job": "Read agents/my-agent/SYSTEM.md for context, then read agents/my-agent/prompts/weekly-report.md and complete that task.",
-  "enabled": true
-}
-```
+For reusable tasks, write the prompt as markdown in `agents/<name>/jobs/<task>.md` and reference it from `job` — the agent's working directory is the scoped folder, so the relative path resolves. For one-off tasks, write the prompt inline.
 
 ## Removing an Agent
 

package/templates/coding-workspace/CLAUDE.md.template

@@ -0,0 +1,7 @@
+# coding-workspace/ — Code Mode System Prompt
+
+Optional system prompt for code mode workspaces. Edit `SYSTEM.md` to customize the coding agent's behavior when working on your repos.
+
+## Files
+
+- **`SYSTEM.md`** — System prompt for code mode. Empty by default — the coding agent uses its built-in prompt. Add content here to append custom instructions. Supports `{{skills}}`, `{{datetime}}`, and `{{ file.md }}` includes.

package/templates/data/CLAUDE.md.template

@@ -1,5 +1,5 @@
 # Data Directory
 
-Runtime data including the SQLite database (`thepopebot.sqlite`) and cluster state. Created automatically on server start.
+Runtime data including the SQLite database (`db/thepopebot.sqlite`) and cluster state. Created automatically on server start. Override the DB path with `DATABASE_PATH` in `.env`.
 
 Not checked into git.

package/templates/docker-compose.custom.yml

@@ -46,6 +46,7 @@ services:
     volumes:
       - .:/project
       - ./agent-job:/app/agent-job
+      - ./agents:/app/agents
       - ./event-handler:/app/event-handler
       - ./skills:/app/skills
       - ./.env:/app/.env

package/templates/docker-compose.yml

@@ -19,6 +19,7 @@ services:
     volumes:
       - .:/project
       - ./agent-job:/app/agent-job
+      - ./agents:/app/agents
       - ./event-handler:/app/event-handler
       - ./skills:/app/skills
       - ./.env:/app/.env

package/templates/event-handler/CLAUDE.md.template

@@ -0,0 +1,79 @@
+# event-handler/ — Event Handler Configuration
+
+This directory holds configuration for the event handler: webhook triggers, chat system prompts, cluster role definitions, LiteLLM proxy routing, and the job-summary prompt. Edit these to shape how your handler reacts to events.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `TRIGGERS.json` | Webhook trigger definitions — fires actions when matching paths receive HTTP requests |
+| `agent-chat/SYSTEM.md` | System prompt for the chat agent (default chat mode) |
+| `code-chat/SYSTEM.md` | System prompt for code mode chat (workspace-aware) |
+| `clusters/SYSTEM.md` | System prompt prepended to every cluster worker |
+| `clusters/ROLE.md` | Role-template snippet referenced by cluster role definitions |
+| `litellm/main.yaml` | LiteLLM proxy config — routes Claude Code through other providers |
+| `SUMMARY.md` | System prompt for the auto-summary that runs after agent jobs complete |
+
+## TRIGGERS.json
+
+JSON array of webhook trigger definitions. Loaded at server boot by `lib/triggers.js`.
+
+```json
+{
+  "name": "review-github-event",
+  "watch_path": "/github/webhook",
+  "actions": [
+    { "type": "agent", "job": "Summarize this GitHub event:\n{{body}}" }
+  ],
+  "enabled": true
+}
+```
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `name` | Yes | Unique within the file |
+| `watch_path` | Yes | Path to match (`/github/webhook`, `/webhook`, custom paths) |
+| `actions` | Yes | Array — runs in order, fire-and-forget after auth |
+| `enabled` | No | Defaults `true`. Set `false` to keep the entry but skip it |
+
+### Action types
+
+Three types — `agent`, `command`, `webhook`. `agent` accepts optional `scope`, `agent_backend`, `llm_model` overrides:
+
+```json
+{ "type": "agent", "job": "Process: {{body}}", "scope": "agents/triage", "agent_backend": "claude-code", "llm_model": "claude-sonnet-4-5-20250929" }
+{ "type": "command", "command": "echo 'webhook received: {{body}}' >> logs/webhook.log" }
+{ "type": "webhook", "url": "https://example.com/hook", "method": "POST", "headers": {}, "vars": { "source": "github" } }
+```
+
+`scope` resolves to a directory under `agents/` (see `agents/CLAUDE.md`). The agent runs with that directory as its working dir, picks up its `SYSTEM.md`, and uses the skills under `agents/<scope>/skills/` falling back to root `skills/`.
+
+### Template tokens (in `job` and `command` strings)
+
+`{{body}}`, `{{body.field}}`, `{{query}}`, `{{query.field}}`, `{{headers}}`, `{{headers.field}}`. Tokens are expanded when the trigger fires.
+
+## Chat System Prompts
+
+`agent-chat/SYSTEM.md` and `code-chat/SYSTEM.md` are the system prompts injected into chat sessions. They support `{{include path/to/file.md}}`, `{{datetime}}`, and `{{skills}}` variables (resolved by `lib/utils/render-md.js`).
+
+- **Agent chat** (`agent-chat/`) — default chat mode. Workspace-agnostic.
+- **Code chat** (`code-chat/`) — code-mode chat. Knows about the active code workspace, repo, branch, and feature branch.
+
+Both can be scoped: a chat tied to a workspace with `scope: "agents/foo"` will load `agents/foo/SYSTEM.md` instead of these defaults.
+
+## Cluster Configuration
+
+`clusters/SYSTEM.md` is prepended to every cluster worker's system prompt. `clusters/ROLE.md` is a reusable role-template snippet that individual cluster role definitions can reference. Cluster behavior is configured in the Admin UI; these files supply the prompt context.
+
+## LiteLLM Proxy
+
+`litellm/main.yaml` is read by the optional LiteLLM sidecar (`docker-compose.litellm.yml`). It routes Claude Code's Anthropic-protocol calls to other providers (OpenAI, Gemini, custom OpenAI-compatible endpoints). Edit when you want to use Claude Code with a non-Anthropic backend. Refer to [LiteLLM docs](https://docs.litellm.ai/) for the schema.
+
+## Summary Prompt
+
+`SUMMARY.md` is the prompt for the helper LLM call that auto-summarizes agent job results (PR link, status, files changed). Tweak its tone or formatting here.
+
+## Notes
+
+- These files are user-owned — edits are preserved across `thepopebot upgrade`.
+- The Admin UI (`/admin/event-handler/`) configures runtime defaults (LLM provider, coding agent backend, OAuth tokens). Trigger-level `agent_backend` / `llm_model` overrides those defaults.

package/templates/event-handler/TRIGGERS.json

@@ -48,10 +48,26 @@
     "enabled": false
   },
   {
-    "name": "review-with-openai",
+    "name": "review-with-model-override",
     "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" }
+      { "type": "agent", "job": "Review the GitHub event and summarize what happened:\n{{body}}", "llm_model": "claude-opus-4-7" }
+    ],
+    "enabled": false
+  },
+  {
+    "name": "review-with-codex",
+    "watch_path": "/github/webhook",
+    "actions": [
+      { "type": "agent", "job": "Review the GitHub event and summarize what happened:\n{{body}}", "agent_backend": "codex-cli" }
+    ],
+    "enabled": false
+  },
+  {
+    "name": "scoped-webhook-agent",
+    "watch_path": "/webhook",
+    "actions": [
+      { "type": "agent", "job": "A webhook was received. Read jobs/handle-webhook.md and complete it using the payload:\n{{body}}", "scope": "agents/my-agent" }
     ],
     "enabled": false
   }

package/templates/skills/CLAUDE.md.template

@@ -1,14 +1,14 @@
 # skills/ — Agent Skills
 
-Skills are lightweight plugins that extend agent abilities. Each skill lives in `skills/library/<skill-name>/` and is activated by symlinking into `skills/active/`.
+Skills are lightweight plugins that extend agent abilities. Each skill lives in `skills/<skill-name>/`.
 
 ## How Skills Work
 
-1. **Discovery** — The system scans `skills/active/` for directories containing `SKILL.md`.
+1. **Discovery** — The system scans `skills/` for directories containing `SKILL.md`.
 2. **Frontmatter loaded** — The `description` from YAML frontmatter is included in the system prompt under "Active skills" (via the `{{skills}}` template variable).
 3. **Full SKILL.md read on demand** — When the agent decides to use a skill, it reads the full `SKILL.md` for detailed usage instructions.
 
-Both Pi and Claude Code discover skills from the same `skills/active/` directory (via `.pi/skills` and `.claude/skills` symlink bridges).
+All coding agents discover skills from the same `skills/` directory (via `.pi/skills`, `.claude/skills`, etc. symlink bridges).
 
 ## Conventions
 
@@ -48,12 +48,12 @@ description: One sentence describing what the skill does and when to use it.
 ## Usage
 
 ```bash
-skills/library/skill-name/script.sh <args>
+skills/skill-name/script.sh <args>
 ```
 ```
 
 - The `description` field appears in the system prompt — keep it concise and action-oriented.
-- Use project-root-relative paths in documentation (e.g., `skills/library/skill-name/script.sh`).
+- Use project-root-relative paths in documentation (e.g., `skills/skill-name/script.sh`).
 
 ### Skill Structure
 
@@ -67,27 +67,26 @@ If a skill needs an API key, add it via the admin UI (Settings > Agent Jobs > Se
 
 ### Activation & Deactivation
 
-```bash
-# Activate
-ln -s ../library/skill-name skills/active/skill-name
+Skills are active when present in the `skills/` directory. To deactivate, remove or move the skill directory out.
 
-# Deactivate
-rm skills/active/skill-name
-```
+All coding agents discover skills from the same `skills/` directory via symlink bridges created by `npx thepopebot init`:
 
-The `skills/active/` directory is shared by both agent backends via symlink bridges:
-- `.claude/skills → skills/active`
-- `.pi/skills → skills/active`
+- `.claude/skills → ../skills` (Claude Code)
+- `.pi/skills → ../skills` (Pi)
+- `.codex/skills → ../skills` (Codex CLI)
+- `.gemini/skills → ../skills` (Gemini CLI)
+- `.kimi/skills → ../skills` (Kimi CLI)
+- `.agents/skills → ../skills` (OpenCode and other plugin-style agents)
 
 ## Creating a Skill
 
 ### Simple bash skill (most common)
 
 ```bash
-mkdir skills/library/my-skill
+mkdir skills/my-skill
 ```
 
-**skills/library/my-skill/SKILL.md:**
+**skills/my-skill/SKILL.md:**
 ```markdown
 ---
 name: my-skill
@@ -101,11 +100,11 @@ Requires MY_API_KEY environment variable.
 
 ## Usage
 ```bash
-skills/library/my-skill/run.sh <args>
+skills/my-skill/run.sh <args>
 ```
 ```
 
-**skills/library/my-skill/run.sh:**
+**skills/my-skill/run.sh:**
 ```bash
 #!/bin/bash
 set -euo pipefail
@@ -115,10 +114,9 @@ if [ -z "$MY_API_KEY" ]; then echo "Error: MY_API_KEY not set"; exit 1; fi
 # ... skill logic
 ```
 
-Then make it executable and activate:
+Then make it executable:
 ```bash
-chmod +x skills/library/my-skill/run.sh
-ln -s ../library/my-skill skills/active/my-skill
+chmod +x skills/my-skill/run.sh
 ```
 
 ### Node.js skill
@@ -131,4 +129,4 @@ Always build AND test a skill in the same job. Tell the agent to test with real
 
 ## Default Skills
 
-Check `skills/library/` for available built-in skills. Activate any you need by symlinking into `skills/active/`.
+Check `skills/` for available built-in skills (e.g., `agent-job-secrets`, `playwright-cli`).

package/templates/skills/{library/agent-job-secrets → agent-job-secrets}/SKILL.md

@@ -7,10 +7,10 @@ description: List and retrieve agent secrets. Plain secrets are also available a
 
 ```bash
 # List available secret keys (fetches current list from server)
-node skills/library/agent-job-secrets/agent-job-secrets.js
+node skills/agent-job-secrets/agent-job-secrets.js
 
 # Get a secret value (OAuth credentials are auto-refreshed)
-node skills/library/agent-job-secrets/agent-job-secrets.js get MY_CREDENTIALS
+node skills/agent-job-secrets/agent-job-secrets.js get MY_CREDENTIALS
 ```
 
 ## Notes