Chat console: Discord bridge for the ask→plan→implement flow

[gingur]

Ask

Add a mobile-friendly chat console over the existing GitHub agent flow, using Discord as the frontend and a Cloudflare Worker as the bridge. Chat is a mirror/remote-control of GitHub — all AI turns keep running through claude.plan / claude.implement on the Claude Max subscription; the bridge itself does no LLM work (no consumption-billed chat AI like Claude Tag).

Why Discord (decided during design)

• Free (Slack's free tier hides history; Slack Lists / Claude Tag need paid Slack + consumption billing).
• Real threads, good mobile apps and push notifications.
• Bots are first-class and webhook-friendly for a CF Worker bridge.

Interaction model (sketch, planner to refine)

• #general channel = pre-planning: operator messages are triaged; when an idea firms up, the bridge files a GitHub ask issue (which then follows the normal assign → plan → panel cycle).
• Channel per ask issue: created when the ask is filed; issue comments (bot summaries, panels, failure reports) mirror into the channel; operator replies in the channel post back as issue comments, which claude.wake already turns into agent turns.
• Thread per task (sub-issue): implement-turn summaries and PR links mirror into the task's thread.
• Action panels: mirrored as Discord components (buttons) where possible; a tap performs the same checkbox tick / comment on GitHub — GitHub stays the source of truth for state.

Constraints

• GitHub remains the single source of truth; the bridge is stateless where possible (reconcile from GitHub, same philosophy as the agent prompts).
• Bridge = Cloudflare Worker (webhooks from GitHub + Discord interactions endpoint); deploy via devkit's own cf.worker.* workflows.
• Credentials (Discord bot token, GitHub webhook secret) live in Infisical, fetched via OIDC.
• No new AI billing surface: any LLM step happens inside the existing claude.* workflows on the Max token.

[gingur-bot]

Plan

Ask (restated): Add a mobile-friendly chat console over the existing GitHub agent flow: Discord as the frontend, a Cloudflare Worker as the bridge. Discord is a mirror/remote-control — GitHub stays the source of truth, all AI turns keep running through claude.plan / claude.implement on the Max subscription, and the bridge does no LLM work. Channel per ask issue, thread per task, action panels surfaced as tappable buttons, operator replies flowing back as issue comments that claude.wake already turns into agent turns.

Current state:

• The agent flow is entirely comment/label/assignment-driven on GitHub: .github/workflows/claude.wake.yml turns operator comments and panel-checkbox ticks into bot assignments; .github/workflows/claude.plan.yml / claude.implement.yml run the turns; actions/claude.handoff/action.yml posts/sweeps action panels (identified by an HTML-comment marker, defined in that file's marker= line). This means the bridge needs zero changes to the agent workflows — anything that posts a comment as the operator, or edits a bot panel comment to tick a box, drives turns exactly like the GitHub UI does.
• Worker deploy infra already exists and is reusable: .github/workflows/cf.worker.deploy.yml (takes cwd, builds, fetches CF creds from Infisical via OIDC, deploys with --env), actions/cf.worker.deploy/, actions/infisical.secrets.fetch/, node.verify.yml for CI (also takes cwd). Nothing pushes runtime worker secrets yet — that's a small gap to fill.
• devkit itself is a library repo (workflows/actions/configs) with one self-caller precedent (.github/workflows/scan.yml). There is no app code in the repo today.

Verified platform constraint (shapes the whole design): Discord does not deliver regular channel messages over HTTP webhooks — its outgoing Webhook Events cover only a narrow event set, and MESSAGE_CREATE requires a persistent Gateway websocket (Discord webhook-events docs). What does arrive over plain HTTP is the Interactions endpoint: slash commands, buttons, select menus, and modals (Discord's official Cloudflare Workers sample). A Gateway connection from a Worker means a 24/7-active Durable Object (paid plan, stateful) — against the free/stateless constraints.

Approach: v1 is interaction-driven: every operator input is a slash command, a button tap, or a modal — all pure HTTP, statelessly verifiable (Ed25519), free-tier. Concretely, the sketch's "type in #general and get triaged" becomes /ask (opens a title+body modal → files the ask issue and assigns the bot); replying in an ask channel becomes a 💬 Reply button on every mirrored comment (opens a modal) or /reply; panel checkboxes become one button per option. On mobile that's: push notification → open channel → tap button → type in modal → done. A Gateway/Durable-Object listener for free-text chat is a possible later enhancement, not v1.

Key decisions (each seriously considered the other way):

1. Bridge code lives in this repo at apps/discord.bridge/, as a standalone package (own package.json + lockfile, not a pnpm workspace conversion). Rejected: a separate repo — task issues filed here can only be implemented by PRs here; a new repo would need its own agent wiring before any work could start. Rejected: Durable-Object Gateway bot — paid, stateful, more moving parts.
2. The bridge acts on GitHub as the operator via a fine-grained PAT (issues read/write on this repo) stored in Infisical. Comments post as gingur (author_association OWNER → wake's created-gate passes) and panel edits have sender ≠ bot with the comment still bot-authored (wake's edited-gate passes). Rejected: a GitHub App or second machine user — their comments have no OWNER/MEMBER/COLLABORATOR association, so wake would ignore them without loosening its trust gate.
3. Stateless mapping by naming convention: ask issue N ↔ text channel ask-<N> (topic = issue URL), task issue M ↔ thread task-<M> inside the ask's channel. Both directions resolve with one Discord API lookup; no KV/DO/database. Rejected: KV mapping store — cache invalidation for no real win at this scale.
4. Runtime worker secrets are pushed at deploy time by an optional, backward-compatible extension to cf.worker.deploy.yml (wrangler secret bulk from the already-fetched Infisical env). Rejected: runtime Infisical fetch from the Worker — adds a hot-path dependency and another auth surface.

Not in v1 (noted for later asks): free-text capture via Gateway, multi-repo/org webhook fan-in, mirroring panel-defusal edits back onto already-posted Discord buttons beyond best-effort.

Proposed tasks

1. Scaffold the Discord bridge worker at apps/discord.bridge/

• Depends on: nothing

• Body:

  devkit is gaining a Discord↔GitHub bridge: a Cloudflare Worker that mirrors the repo's agent flow (ask issues, task sub-issues, action panels — see .github/workflows/claude.wake.yml and actions/claude.handoff/action.yml for how that flow works) into a Discord server, and turns Discord interactions back into GitHub issue activity. This task creates the app skeleton and its CI; mirroring logic and interaction handling land in follow-up tasks (Add rollback wrapper action for Workers Static Assets #2/POC: self-hosted GitHub Actions runner via Cloudflare Tunnel #3 of this plan) — build the skeleton so both bolt on cleanly.

  Create apps/discord.bridge/ as a standalone package (own package.json and pnpm-lock.yaml; do NOT convert the repo root into a pnpm workspace — cf.worker.deploy.yml and node.verify.yml run pnpm install --frozen-lockfile inside their cwd input):

  • package.json: private, "type": "module", scripts lint, typecheck, test (node.verify defaults), build (can be a no-op true — wrangler bundles TS itself), devDeps: typescript, vitest, wrangler, eslint/prettier reusing configs/ from the repo root (see root package.json exports for the paths). Add .nvmrc and packageManager so actions/node.setup resolves versions.
  • wrangler.toml: worker name discord-bridge, main = "src/index.ts", a current compatibility_date, and an [env.production] block (the reusable deploy workflow always passes --env; see CLAUDE.md → wrangler.toml). Non-secret config as [vars]: DISCORD_PUBLIC_KEY, DISCORD_APP_ID, DISCORD_GUILD_ID, DISCORD_OPERATOR_ID, GITHUB_REPO (e.g. gingur/devkit), GITHUB_BOT (e.g. gingur-bot). Secrets (DISCORD_BOT_TOKEN, GH_WEBHOOK_SECRET, GH_OPERATOR_PAT) are NOT in the file — they arrive via wrangler secret (deploy wiring is a separate task).
  • src/index.ts: a plain fetch-handler router (no framework needed) with three routes:
    • POST /discord — Discord interactions endpoint. Verify the Ed25519 signature (X-Signature-Ed25519 / X-Signature-Timestamp against DISCORD_PUBLIC_KEY, WebCrypto Ed25519 or the discord-interactions npm package); invalid → 401. Handle interaction type PING → respond {"type": 1} (PONG). Other interaction types: dispatch to a stub module (src/interactions.ts) that returns an ephemeral "not implemented yet" message.
    • POST /github — GitHub webhook endpoint. Verify X-Hub-Signature-256 HMAC-SHA256 against GH_WEBHOOK_SECRET (constant-time compare); invalid → 401. Valid → dispatch to a stub module (src/mirror.ts) that no-ops and returns 202.
    • GET /healthz → 200 ok. Everything else → 404.
  • Vitest tests: valid/invalid Ed25519 signature (generate a keypair in the test), PING→PONG shape, valid/invalid HMAC, route 404s.
  • CI caller: .github/workflows/verify.yml in this repo (follow the existing self-caller precedent .github/workflows/scan.yml), on: pull_request with a paths: filter for apps/discord.bridge/**, calling gingur/devkit/.github/workflows/node.verify.yml@main with cwd: apps/discord.bridge. Per CLAUDE.md's runner-routing policy, PR-triggered CI stays GitHub-hosted — pass no runner input.

  Follow CLAUDE.md conventions throughout (naming tiers, natural errors over defensive guards).

  Acceptance criteria

  • pnpm lint, pnpm typecheck, pnpm test all pass in apps/discord.bridge/.
  • Tests cover: signed PING returns type-1 PONG; tampered Discord signature → 401; bad GitHub HMAC → 401; /healthz → 200.
  • verify.yml triggers on a PR touching apps/discord.bridge/** and passes.
  • No secrets in any committed file (the pre-commit/CI Infisical scan stays green).

2. Bridge: mirror GitHub → Discord (channels, threads, comments, panels)

• Depends on: 1

• Body:

  Builds on the apps/discord.bridge/ worker skeleton (routes, signature verification, and a no-op src/mirror.ts already exist). This task implements the GitHub-webhook → Discord mirroring so the repo's agent flow (see .github/workflows/claude.wake.yml, .github/workflows/claude.plan.yml, actions/claude.handoff/action.yml) is readable and actionable from Discord. Config available in env: DISCORD_BOT_TOKEN (secret), DISCORD_GUILD_ID, GITHUB_REPO, GITHUB_BOT.

  Mapping is stateless, by naming convention: ask issue N ↔ guild text channel ask-<N> (channel topic = the issue URL), task issue M ↔ thread named task-<M> inside its parent ask's channel. Resolve by listing guild channels / active threads via the Discord REST API — no KV or database. All Discord REST calls use the bot token (Authorization: Bot …).

  Handle these webhook deliveries on POST /github (events: issues, issue_comment; ignore everything else with 202):

  • issues / action labeled with label claude-ask (this is how every ask enrolls — see the Enroll step in .github/workflows/claude.plan.yml): ensure channel ask-<N> exists (idempotent: look up by name first — webhook redeliveries must not duplicate), under a category named asks (create the category if missing). Set the topic to the issue URL and post a header message with the issue title, a body excerpt, and the link.
  • issues / action opened where the issue has label claude-task: resolve the parent ask via the GraphQL parent field on the issue (sub-issue relationship); if there is no parent or no ask-<N> channel, skip silently. Otherwise create (idempotently, look up first) a thread named task-<M> in that channel with a header message (title + link).
  • issue_comment / action created on an issue labeled claude-ask or claude-task: mirror into the mapped channel/thread — author login, body, and a link back to the comment. Respect Discord limits (content 2000 chars / embed description 4096): truncate with an ellipsis, the link always survives. Attach a 💬 Reply button (custom_id = reply:<issueNumber>) to every mirrored comment. If the comment body contains the live action-panel marker (the exact HTML-comment string in the marker= line of actions/claude.handoff/action.yml), additionally parse its checkbox lines (- [ ] **Label** — …) and render one button per option, custom_id = tick:<commentId>:<lineIndex>, labeled with the bold text. Button handlers are the next task — just render them here.
  • issue_comment / action edited where the comment is a defused panel (marker changed to its :done variant — see the defusal convention in the same action file): best-effort, find the mirrored Discord message (scan recent channel messages for one whose components carry that commentId in a custom_id) and edit it to remove the option buttons. If not found, do nothing.
  • issues / action closed on a claude-ask issue: post a closing note in the channel and move the channel to a category named archive (create if missing).

  Keep handlers thin and testable: pure functions from (webhook payload, env) → list of Discord REST requests, exercised in Vitest with fixture payloads and a mocked fetch. Natural-error philosophy per CLAUDE.md: let Discord API errors surface (log + 500), don't pre-validate what can't be wrong.

  Acceptance criteria

  • Vitest fixtures for each bullet above assert the exact Discord REST calls (method, path, body shape), including: idempotent channel/thread creation on redelivery, comment truncation at Discord limits, panel-comment → one button per checkbox line plus Reply, and non-enrolled issues (no claude-ask/claude-task label) producing zero Discord calls.
  • HMAC verification still enforced on every /github request (existing tests keep passing).
  • pnpm lint / typecheck / test pass in apps/discord.bridge/.

3. Bridge: Discord → GitHub (slash commands, buttons, modals)

• Depends on: 1, 2

• Body:

  Builds on apps/discord.bridge/ (worker skeleton with verified POST /discord interactions endpoint; task 2 established the naming conventions: channel ask-<N> ↔ ask issue, thread task-<M> ↔ task issue, button custom_ids reply:<issueNumber> and tick:<commentId>:<lineIndex>). This task implements the interaction handlers in src/interactions.ts so the operator can drive the GitHub agent flow entirely from Discord.

  All GitHub writes use GH_OPERATOR_PAT from env — a fine-grained PAT of the human operator. This is deliberate: comments must be authored by a user whose author_association is OWNER/MEMBER/COLLABORATOR, and panel-tick edits must have a sender different from GITHUB_BOT, or .github/workflows/claude.wake.yml (read its if: gate) will not start a turn.

  Authorization: every interaction first checks the invoking user id against DISCORD_OPERATOR_ID; anyone else gets an ephemeral refusal (flags 64) and no GitHub call.

  Handlers:

  • /ask slash command → respond with a modal (type 9): short title input + paragraph body input. On modal submit: create an issue in GITHUB_REPO (title, body) via the PAT, then assign GITHUB_BOT to it (assignment is what starts the planning turn — see .github/workflows/claude.plan.yml on: issues: [assigned]). Respond ephemerally with the issue link. The ask channel then appears automatically via the task-2 mirror when the plan workflow labels the issue claude-ask.
  • /reply <text> slash command (a required string option), usable in an ask-<N> channel or task-<M> thread: resolve the issue number from the channel/thread name (outside a mapped channel → ephemeral error), post <text> as an issue comment via the PAT, respond ephemerally with the comment link. Note in the runbook-facing help text that a [hold] prefix works exactly as on GitHub (comment without waking a turn — see the wake gate).
  • reply:<issueNumber> button → open the same reply modal (multi-line paragraph input); on submit, post the comment to that issue.
  • tick:<commentId>:<lineIndex> button → GET the comment via the PAT; verify it still contains the live action-panel marker (the exact string in the marker= line of actions/claude.handoff/action.yml — the :done variant means the panel was consumed: respond ephemerally "panel already closed/stale" and stop). Flip that line's leading - [ ] to - [x] and PATCH the comment body. This mirrors a checkbox tick 1:1, so multi-select panels keep their GitHub semantics: each option is its own button and the Submit option is just another button the operator taps last (wake only arms a multi-select once Submit is ticked). Respond ephemerally confirming which option was ticked.
  • Any GitHub round-trip that could exceed Discord's 3-second interaction deadline: use a deferred response (type 5, ephemeral) and edit the followup when done.

  Keep handlers pure/testable as in task 2 (interaction payload + env → GitHub REST requests), tested in Vitest with signed interaction fixtures and mocked fetch.

  Acceptance criteria

  • Vitest coverage: /ask modal submit → issue create + bot assign (in that order); /reply and reply-modal → correct POST …/issues/<n>/comments; tick button → GET + PATCH with exactly one checkbox flipped and the rest of the body byte-identical; tick on a :done panel → no PATCH; non-operator user id → no GitHub call and an ephemeral refusal; unmapped channel /reply → ephemeral error.
  • pnpm lint / typecheck / test pass in apps/discord.bridge/.

4. Bridge: command-registration script + setup runbook

• Depends on: 3

• Body:

  apps/discord.bridge/ (Cloudflare Worker bridging Discord ↔ this repo's GitHub agent flow) has interaction handlers for /ask and /reply (see src/interactions.ts) but Discord only offers slash commands that have been registered with the API, and a human setting the system up needs one document that covers every manual step. Two deliverables:

  1. apps/discord.bridge/scripts/register.ts — idempotent bulk-overwrite registration of the guild commands (PUT /applications/{DISCORD_APP_ID}/guilds/{DISCORD_GUILD_ID}/commands with the full command array: /ask, /reply with its required string option). Reads DISCORD_APP_ID, DISCORD_GUILD_ID, DISCORD_BOT_TOKEN from process env; run manually via a pnpm register script (document running it under infisical run so the token never touches disk). Node script, no Worker runtime needed.
  2. apps/discord.bridge/README.md — the complete setup runbook, in this order:
     • Create the Discord server, the application + bot (developer portal), which privileged intents are needed (none), the bot invite with permissions: Manage Channels, Manage Threads, Send Messages, Embed Links, Read Message History.
     • Where each config value comes from (public key, app id, guild id, operator user id) and where it goes (wrangler.toml [vars]).
     • Infisical: the secret names (DISCORD_BOT_TOKEN, GH_WEBHOOK_SECRET, GH_OPERATOR_PAT) and that they live in the same Infisical folder the deploy workflow fetches (see CLAUDE.md → Credentials & OIDC; exact path/project per this repo's deploy caller).
     • The operator PAT: fine-grained, this repo only, permission Issues read/write — and WHY it must be a human collaborator's PAT (the wake workflow's trust gate on author_association; cite .github/workflows/claude.wake.yml).
     • GitHub webhook: repo settings → webhook to https://<worker-host>/github, content type application/json, secret = GH_WEBHOOK_SECRET, events: Issues + Issue comments only.
     • Discord interactions endpoint: set https://<worker-host>/discord in the developer portal AFTER the first deploy (Discord verifies with a signed PING).
     • Run pnpm register to publish the slash commands.
     • Usage + limitations: /ask files an ask issue and starts planning; channel per ask, thread per task; buttons mirror action panels; /reply or the 💬 button to comment; [hold] prefix to comment without starting a turn; and prominently: free-text messages typed into channels are NOT seen by the bridge (Discord only delivers slash commands/buttons/modals over HTTP; reading messages needs a persistent Gateway connection, deliberately out of scope — link https://docs.discord.com/developers/events/webhook-events).

  Acceptance criteria

  • pnpm register performs a single bulk PUT with both commands and is safe to re-run.
  • README covers every bullet above; a reader can go from nothing to a working bridge without consulting any other document except CLAUDE.md.
  • pnpm lint / typecheck / test still pass.

5. Deploy wiring: runtime secret push + bridge deploy caller

• Depends on: 1 (parallel with 2–4)

• Body:

  Two related changes so apps/discord.bridge/ (a Cloudflare Worker in this repo) deploys through devkit's own reusable workflows, including its runtime secrets — nothing pushes worker secrets today.

  1. Extend .github/workflows/cf.worker.deploy.yml with an optional input secrets (string, default ''): space-separated names of env vars to push to the deployed worker as runtime secrets. When non-empty, after the Deploy step, build a JSON object of those names/values from the job env (they exist because infisical.secrets.fetch exported them) and pipe it to wrangler secret bulk in inputs.cwd, with the same --env / --name targeting and CLOUDFLARE_API_TOKEN/CLOUDFLARE_ACCOUNT_ID credentials the deploy used (mirror how actions/cf.worker.deploy/ invokes wrangler — keep the two invocations consistent). Empty input = no new step runs → fully backward-compatible for existing consumers. Follow CLAUDE.md (thin workflow glue; if the logic is more than a short step, extract a composite actions/cf.worker.secrets/ — judgement call, one concern either way; natural errors: let wrangler fail loudly if a named var is absent).
  2. Add the bridge's deploy caller .github/workflows/deploy.yml in this repo (self-caller precedent: .github/workflows/scan.yml): on: push to main with paths: apps/discord.bridge/** and the workflow file itself; single job calling gingur/devkit/.github/workflows/cf.worker.deploy.yml@main with cwd: apps/discord.bridge, env: production, secrets: 'DISCORD_BOT_TOKEN GH_WEBHOOK_SECRET GH_OPERATOR_PAT', runner: ${{ vars.RUNNER }} (push-to-main is operator-gated, so the local runner is allowed per CLAUDE.md → Self-hosted runner routing), and the Infisical inputs (infisicalIdentity: ${{ vars.INFISICAL_IDENTITY }}, project/env/path matching where the CF creds AND the three bridge secrets live — one fetch, one path; align the path with the runbook in apps/discord.bridge/README.md if it exists by then, else document the chosen path in the workflow comments). Permissions: contents: read, id-token: write, pull-requests: write (the deploy workflow records the version on the source PR).

  Acceptance criteria

  • cf.worker.deploy.yml with secrets unset produces an execution plan identical to today (no new step runs); with secrets set, exactly one wrangler secret bulk invocation receives all named values, and no secret value is ever echoed to the log.
  • deploy.yml triggers only on main-branch pushes touching the bridge app or itself, and passes all required inputs listed above.
  • actionlint (or careful YAML review if actionlint is unavailable) passes on both workflows.

To approve: tick Approve on the action panel below (it is posted automatically after this comment — do not add your own checkboxes here).
To change: just reply — any comment starts a revise turn automatically.

---

This turn: studied the agent workflows (claude.wake / claude.plan / claude.handoff), the cf.worker.* deploy surface, and verified the Discord platform constraint that drives the design (no free-text messages over HTTP — interactions only). Posted this plan; created nothing yet.
Need from you: tick Approve to materialize these 5 tasks as sub-issues, or reply with corrections (e.g. if you want the Gateway/free-text path in v1 after all, or a different home for the bridge code).

[gingur-bot]

🎛️ Your move

Ticking the box is the only way to approve. Any reply is discussion — it starts a revise/answer turn automatically. Prefix a comment with [hold] to comment without starting a turn.

(panel closed)

[gingur-bot]

I've reviewed some of the plan, but honestly it was too big to grok all in one read. out of the box, I want to support multiple repos, so is there a way to create a channel or something per repo so all commands are relative? the UX, when prompting questions, approval, or when I want to reply via text, all should be in scope and would love some screen shots of any existing workflows/presentation of these items already supported by discord.

[gingur]

Operator note: the comment above signed gingur-bot was actually me replying from the wrong account — treat it as operator feedback. Restating it so it's properly attributed:

I've reviewed some of the plan, but honestly it was too big to grok all in one read. Out of the box, I want to support multiple repos — is there a way to create a channel (or something) per repo so all commands are relative? The UX for prompting questions, approvals, and my text replies should all be in scope, and I'd love screenshots of any existing Discord workflows/presentation patterns for these.

Also: the revised plan must be readable on a phone in a couple of minutes — summarize at the top, push detail into the task bodies.

[gingur-bot]

Plan (v2)

Changed from v1: ① multi-repo is now built in — one Discord category per repo, and every command is relative to where you type it; ② added a UX walkthrough with real Discord screenshots (questions, approvals, text replies); ③ restructured for phone reading — task details are collapsed below.

Ask (restated): a mobile chat console over the existing GitHub agent flow — Discord frontend, Cloudflare Worker bridge, GitHub stays the source of truth, all AI turns stay on the Max-billed claude.plan/claude.implement workflows, the bridge does no LLM work. Now explicitly multi-repo from day one.

Current state: the agent flow is entirely comment/label-driven (.github/workflows/claude.wake.yml, claude.plan.yml, claude.implement.yml, actions/claude.handoff/action.yml) so the bridge needs zero changes to the agent workflows. Worker deploy infra exists (cf.worker.deploy.yml + composites); the only infra gap is pushing runtime worker secrets (task 5). No app code in the repo today.

Server layout — one category per repo

▾ DEVKIT                    ← category = repo (auto-created on its first ask)
   # general                ← type /ask here to file an ask in gingur/devkit
   # ask-75                 ← channel per ask issue; agent comments mirror here
      ↳ 🧵 task-81          ← thread per task sub-issue (implement summaries, PR links)
▾ OTHER-REPO
   # general
   # ask-12

• Commands are relative: /ask or /reply typed anywhere under a repo's category acts on that repo — no repo argument to remember. Buttons carry their repo internally, so taps are unambiguous too.
• Enrolling a repo = point its GitHub webhook at the worker + grant the PAT access (2 minutes, documented in the runbook). Its category and #general appear automatically on the first ask. Closed asks move to a per-repo archive category.
• Mapping is stateless/naming-based (rebuilt from Discord+GitHub on every event, no database) — same reconcile philosophy as the agent prompts.

The UX, in screenshots (official Discord docs imagery)

1 · Filing an ask / replying — slash commands. Type / and the bot's commands pop up with descriptions. This is /ask (file a new ask issue) and /reply (comment on the mapped issue):

2 · Typing text — modals. /ask and every 💬 Reply button open a pop-up form (title + multi-line body, up to 4000 chars). On submit the bridge files the issue / posts your comment on GitHub as you, so claude.wake starts a turn exactly as if you'd typed on github.com:

3 · Approvals & questions — buttons under the mirrored comment. When I post a plan + Approve panel (or a choices menu) on GitHub, the mirrored Discord message renders one button per checkbox option plus 💬 Reply. A tap ticks the real checkbox on GitHub; consumed panels get their buttons removed:

⚠️ One honest limitation: Discord only delivers slash commands, buttons, and modals over plain HTTP — free-text typed directly into a channel never reaches the bridge (reading messages needs a persistent Gateway socket → a paid, stateful Durable Object). So every text entry goes through /reply or a 💬 button+modal. A Gateway listener for true free-text chat is a possible later ask, deliberately not v1.

Key decisions (unchanged from v1 unless noted)

• Bridge code lives in this repo at apps/discord.bridge/ (standalone package; separate repo rejected — tasks filed here must be implementable here).
• Interactions-only over HTTP: free tier, stateless, Ed25519-verified (Discord's official CF Workers pattern).
• The bridge writes to GitHub with your fine-grained PAT (Issues read/write on enrolled repos) so comments/ticks pass claude.wake's author_association trust gate. A GitHub App/second bot was rejected — wake would ignore it.
• New for multi-repo: repo resolved from the webhook payload inbound, and from the channel's parent category (anchored by #general's topic = repo URL) outbound; button ids carry owner/repo. One webhook per enrolled repo, same worker URL + secret.
• Runtime worker secrets pushed at deploy time via a small, optional, backward-compatible secrets input on cf.worker.deploy.yml.

Proposed tasks (5 — details collapsed, tap to expand)

1. Scaffold the Discord bridge worker at apps/discord.bridge/

• Depends on: nothing
• Body:

Full task body

devkit is gaining a Discord↔GitHub bridge: a Cloudflare Worker that mirrors the agent flow of multiple GitHub repos (ask issues, task sub-issues, action panels — see .github/workflows/claude.wake.yml and actions/claude.handoff/action.yml for how that flow works) into one Discord server, and turns Discord interactions back into GitHub issue activity. This task creates the app skeleton and its CI; mirroring logic and interaction handling land in follow-up tasks — build the skeleton so both bolt on cleanly.

Create apps/discord.bridge/ as a standalone package (own package.json and pnpm-lock.yaml; do NOT convert the repo root into a pnpm workspace — cf.worker.deploy.yml and node.verify.yml run pnpm install --frozen-lockfile inside their cwd input):

• package.json: private, "type": "module", scripts lint, typecheck, test (node.verify defaults), build (can be a no-op true — wrangler bundles TS itself), devDeps: typescript, vitest, wrangler, eslint/prettier reusing configs/ from the repo root (see root package.json exports for the paths). Add .nvmrc and packageManager so actions/node.setup resolves versions.
• wrangler.toml: worker name discord-bridge, main = "src/index.ts", a current compatibility_date, and an [env.production] block (the reusable deploy workflow always passes --env; see CLAUDE.md → wrangler.toml). Non-secret config as [vars]: DISCORD_PUBLIC_KEY, DISCORD_APP_ID, DISCORD_GUILD_ID, DISCORD_OPERATOR_ID, GITHUB_BOT (e.g. gingur-bot). There is deliberately NO per-repo config var — the bridge is multi-repo and resolves the repo from each GitHub webhook payload / Discord channel context (later tasks). Secrets (DISCORD_BOT_TOKEN, GH_WEBHOOK_SECRET, GH_OPERATOR_PAT) are NOT in the file — they arrive via wrangler secret (deploy wiring is a separate task).
• src/index.ts: a plain fetch-handler router (no framework needed) with three routes:
  • POST /discord — Discord interactions endpoint. Verify the Ed25519 signature (X-Signature-Ed25519 / X-Signature-Timestamp against DISCORD_PUBLIC_KEY, WebCrypto Ed25519 or the discord-interactions npm package); invalid → 401. Handle interaction type PING → respond {"type": 1} (PONG). Other interaction types: dispatch to a stub module (src/interactions.ts) that returns an ephemeral "not implemented yet" message.
  • POST /github — GitHub webhook endpoint. Verify X-Hub-Signature-256 HMAC-SHA256 against GH_WEBHOOK_SECRET (constant-time compare); invalid → 401. Valid → dispatch to a stub module (src/mirror.ts) that no-ops and returns 202.
  • GET /healthz → 200 ok. Everything else → 404.
• Vitest tests: valid/invalid Ed25519 signature (generate a keypair in the test), PING→PONG shape, valid/invalid HMAC, route 404s.
• CI caller: .github/workflows/verify.yml in this repo (follow the existing self-caller precedent .github/workflows/scan.yml), on: pull_request with a paths: filter for apps/discord.bridge/**, calling gingur/devkit/.github/workflows/node.verify.yml@main with cwd: apps/discord.bridge. Per CLAUDE.md's runner-routing policy, PR-triggered CI stays GitHub-hosted — pass no runner input.

Follow CLAUDE.md conventions throughout (naming tiers, natural errors over defensive guards).

Acceptance criteria

• pnpm lint, pnpm typecheck, pnpm test all pass in apps/discord.bridge/.
• Tests cover: signed PING returns type-1 PONG; tampered Discord signature → 401; bad GitHub HMAC → 401; /healthz → 200.
• verify.yml triggers on a PR touching apps/discord.bridge/** and passes.
• No secrets in any committed file (the pre-commit/CI Infisical scan stays green).

2. Bridge: mirror GitHub → Discord (repo categories, ask channels, task threads, panels)

• Depends on: 1
• Body:

Full task body

Builds on the apps/discord.bridge/ worker skeleton (routes, signature verification, and a no-op src/mirror.ts already exist). This task implements the GitHub-webhook → Discord mirroring so the agent flow of any enrolled repo (see .github/workflows/claude.wake.yml, claude.plan.yml, actions/claude.handoff/action.yml) is readable and actionable from Discord. Config available in env: DISCORD_BOT_TOKEN (secret), DISCORD_GUILD_ID, GITHUB_BOT. There is no per-repo config: enrolled repos are exactly those whose webhooks point at this worker.

Multi-repo mapping — stateless, by naming convention:

• Repo ↔ category. Every webhook payload carries repository.full_name. The repo's home is a guild category containing a #general text channel whose topic is the repo URL (https://github.com/<owner>/<repo>) — that topic is the authoritative anchor; the category's display name is the repo name (fall back to <owner>-<repo> only if that name is already taken by a different repo's category). Resolve by listing guild channels and matching the topic; if absent, create category + #general (set the topic, post a one-line welcome naming the repo). This makes enrollment automatic: the first relevant webhook from a new repo materializes its category.
• Ask issue N ↔ text channel ask-<N> inside its repo's category (channel topic = issue URL). Issue numbers repeat across repos, so every lookup is scoped to the repo's category — never search channel names guild-wide.
• Task issue M ↔ thread named task-<M> inside its parent ask's channel.
• No KV or database — resolve via Discord REST (list channels / active threads) per event. All Discord REST calls use the bot token (Authorization: Bot …).

Handle these webhook deliveries on POST /github (events: issues, issue_comment; ignore everything else with 202):

• issues / action labeled with label claude-ask (this is how every ask enrolls — see the Enroll step in .github/workflows/claude.plan.yml): ensure the repo's category exists (above), then ensure channel ask-<N> in it (idempotent: look up by name within the category first — webhook redeliveries must not duplicate). Set the topic to the issue URL and post a header message with the issue title, a body excerpt, and the link.
• issues / action opened where the issue has label claude-task: resolve the parent ask via the GraphQL parent field on the issue (sub-issue relationship); if there is no parent or no ask-<N> channel in that repo's category, skip silently. Otherwise create (idempotently, look up first) a thread named task-<M> in that channel with a header message (title + link).
• issue_comment / action created on an issue labeled claude-ask or claude-task: mirror into the mapped channel/thread — author login, body, and a link back to the comment. Respect Discord limits (content 2000 chars / embed description 4096): truncate with an ellipsis, the link always survives. Attach a 💬 Reply button (custom_id = reply:<owner>/<repo>:<issueNumber>) to every mirrored comment. If the comment body contains the live action-panel marker (the exact HTML-comment string in the marker= line of actions/claude.handoff/action.yml), additionally parse its checkbox lines (- [ ] **Label** — …) and render one button per option, custom_id = tick:<owner>/<repo>:<commentId>:<lineIndex>, labeled with the bold text (Discord allows 100 chars per custom_id — these fit; keep them compact anyway). Button handlers are the next task — just render them here.
• issue_comment / action edited where the comment is a defused panel (marker changed to its :done variant — see the defusal convention in the same action file): best-effort, find the mirrored Discord message (scan recent channel messages for one whose components carry that commentId in a custom_id) and edit it to remove the option buttons. If not found, do nothing.
• issues / action closed on a claude-ask issue: post a closing note in the channel and move the channel to the repo's archive category, named <repo>-archive (create if missing).

Keep handlers thin and testable: pure functions from (webhook payload, env) → list of Discord REST requests, exercised in Vitest with fixture payloads and a mocked fetch. Natural-error philosophy per CLAUDE.md: let Discord API errors surface (log + 500), don't pre-validate what can't be wrong.

Acceptance criteria

• Vitest fixtures for each bullet above assert the exact Discord REST calls (method, path, body shape), including: auto-creation of a new repo's category+#general on its first ask; two different repos with the same issue number mapping to channels in different categories; idempotent channel/thread creation on redelivery; comment truncation at Discord limits; panel-comment → one button per checkbox line plus Reply, with owner/repo embedded in every custom_id; non-enrolled issues (no claude-ask/claude-task label) producing zero Discord calls.
• HMAC verification still enforced on every /github request (existing tests keep passing).
• pnpm lint / typecheck / test pass in apps/discord.bridge/.

3. Bridge: Discord → GitHub (repo-relative slash commands, buttons, modals)

• Depends on: 1, 2
• Body:

Full task body

Builds on apps/discord.bridge/ (worker skeleton with verified POST /discord interactions endpoint; task 2 established the multi-repo naming conventions: category ↔ repo anchored by #general's topic = repo URL, channel ask-<N> ↔ ask issue, thread task-<M> ↔ task issue, button custom_ids reply:<owner>/<repo>:<issueNumber> and tick:<owner>/<repo>:<commentId>:<lineIndex>). This task implements the interaction handlers in src/interactions.ts so the operator can drive the GitHub agent flow of every enrolled repo entirely from Discord.

Repo resolution is contextual — commands are relative to where they're typed:

• Slash commands: resolve the invoking channel's parent category, then that category's #general topic → owner/repo. Invoked outside any repo category → ephemeral error explaining to use a repo's channels.
• Buttons: the repo is embedded in the custom_id — no lookup needed.

All GitHub writes use GH_OPERATOR_PAT from env — a fine-grained PAT of the human operator granted Issues read/write on every enrolled repo. This is deliberate: comments must be authored by a user whose author_association is OWNER/MEMBER/COLLABORATOR, and panel-tick edits must have a sender different from GITHUB_BOT, or .github/workflows/claude.wake.yml (read its if: gate) will not start a turn.

Authorization: every interaction first checks the invoking user id against DISCORD_OPERATOR_ID; anyone else gets an ephemeral refusal (flags 64) and no GitHub call.

Handlers:

• /ask slash command → respond with a modal (type 9): short title input + paragraph body input. On modal submit: create an issue in the repo resolved from the invoking channel (title, body) via the PAT, then assign GITHUB_BOT to it (assignment is what starts the planning turn — see claude.plan.yml on: issues: [assigned]; the target repo is expected to have the claude agent workflows wired — if not, the natural failure is simply that no turn starts). Respond ephemerally with the issue link. The ask channel then appears automatically via the task-2 mirror when the plan workflow labels the issue claude-ask.
• /reply <text> slash command (a required string option), usable in an ask-<N> channel or task-<M> thread: resolve repo from the category and issue number from the channel/thread name (outside a mapped channel → ephemeral error), post <text> as an issue comment via the PAT, respond ephemerally with the comment link. Note in the runbook-facing help text that a [hold] prefix works exactly as on GitHub (comment without waking a turn — see the wake gate).
• reply:<owner>/<repo>:<issueNumber> button → open a reply modal (multi-line paragraph input); on submit, post the comment to that issue in that repo.
• tick:<owner>/<repo>:<commentId>:<lineIndex> button → GET the comment via the PAT; verify it still contains the live action-panel marker (the exact string in the marker= line of actions/claude.handoff/action.yml — the :done variant means the panel was consumed: respond ephemerally "panel already closed/stale" and stop). Flip that line's leading - [ ] to - [x] and PATCH the comment body. This mirrors a checkbox tick 1:1, so multi-select panels keep their GitHub semantics: each option is its own button and the Submit option is just another button the operator taps last (wake only arms a multi-select once Submit is ticked). Respond ephemerally confirming which option was ticked.
• Any GitHub round-trip that could exceed Discord's 3-second interaction deadline: use a deferred response (type 5, ephemeral) and edit the followup when done.

Keep handlers pure/testable as in task 2 (interaction payload + env → GitHub REST requests), tested in Vitest with signed interaction fixtures and mocked fetch.

Acceptance criteria

• Vitest coverage: /ask modal submit in a repo category → issue create in that repo + bot assign (in that order); /ask outside any repo category → ephemeral error, no GitHub call; /reply and reply-modal → correct POST /repos/<owner>/<repo>/issues/<n>/comments for the channel's repo; tick button → GET + PATCH with exactly one checkbox flipped and the rest of the body byte-identical; tick on a :done panel → no PATCH; non-operator user id → no GitHub call and an ephemeral refusal.
• pnpm lint / typecheck / test pass in apps/discord.bridge/.

4. Bridge: command-registration script + setup & enrollment runbook

• Depends on: 3
• Body:

Full task body

apps/discord.bridge/ (Cloudflare Worker bridging Discord ↔ the GitHub agent flow of multiple enrolled repos) has interaction handlers for /ask and /reply (see src/interactions.ts), but Discord only offers slash commands that have been registered with the API, and a human setting the system up needs one document covering every manual step. Two deliverables:

1. apps/discord.bridge/scripts/register.ts — idempotent bulk-overwrite registration of the guild commands (PUT /applications/{DISCORD_APP_ID}/guilds/{DISCORD_GUILD_ID}/commands with the full command array: /ask, /reply with its required string option). Registration is guild-level and repo-agnostic — run once, works for every enrolled repo. Reads DISCORD_APP_ID, DISCORD_GUILD_ID, DISCORD_BOT_TOKEN from process env; run manually via a pnpm register script (document running it under infisical run so the token never touches disk). Node script, no Worker runtime needed.
2. apps/discord.bridge/README.md — the complete setup runbook, in this order:
   • Create the Discord server, the application + bot (developer portal), which privileged intents are needed (none), the bot invite with permissions: Manage Channels, Manage Threads, Send Messages, Embed Links, Read Message History.
   • Where each config value comes from (public key, app id, guild id, operator user id) and where it goes (wrangler.toml [vars]).
   • Infisical: the secret names (DISCORD_BOT_TOKEN, GH_WEBHOOK_SECRET, GH_OPERATOR_PAT) and that they live in the same Infisical folder the deploy workflow fetches (see CLAUDE.md → Credentials & OIDC; exact path/project per this repo's deploy caller).
   • The operator PAT: fine-grained, permission Issues read/write, repo selection = every enrolled repo — and WHY it must be a human collaborator's PAT (the wake workflow's trust gate on author_association; cite .github/workflows/claude.wake.yml).
   • Enrolling a repo (its own section — this is the multi-repo on-ramp, repeat per repo): ① add a repo webhook → https://<worker-host>/github, content type application/json, secret = GH_WEBHOOK_SECRET, events: Issues + Issue comments only; ② add the repo to the PAT's repository access; ③ the repo must have the claude agent workflows wired (plan/implement/wake); ④ nothing to configure on Discord — the repo's category and #general appear on its first ask.
   • Discord interactions endpoint: set https://<worker-host>/discord in the developer portal AFTER the first deploy (Discord verifies with a signed PING).
   • Run pnpm register to publish the slash commands.
   • Usage + limitations: /ask in a repo's channels files an ask there and starts planning; category per repo, channel per ask, thread per task; buttons mirror action panels; /reply or the 💬 button to comment; [hold] prefix to comment without starting a turn; and prominently: free-text messages typed into channels are NOT seen by the bridge (Discord only delivers slash commands/buttons/modals over HTTP; reading messages needs a persistent Gateway connection, deliberately out of scope — link https://docs.discord.com/developers/events/webhook-events).

Acceptance criteria

• pnpm register performs a single bulk PUT with both commands and is safe to re-run.
• README covers every bullet above, including the per-repo enrollment section; a reader can go from nothing to a working multi-repo bridge without consulting any other document except CLAUDE.md.
• pnpm lint / typecheck / test still pass.

5. Deploy wiring: runtime secret push + bridge deploy caller

• Depends on: 1 (parallel with 2–4)
• Body:

Full task body

Two related changes so apps/discord.bridge/ (a Cloudflare Worker in this repo) deploys through devkit's own reusable workflows, including its runtime secrets — nothing pushes worker secrets today.

1. Extend .github/workflows/cf.worker.deploy.yml with an optional input secrets (string, default ''): space-separated names of env vars to push to the deployed worker as runtime secrets. When non-empty, after the Deploy step, build a JSON object of those names/values from the job env (they exist because infisical.secrets.fetch exported them) and pipe it to wrangler secret bulk in inputs.cwd, with the same --env / --name targeting and CLOUDFLARE_API_TOKEN/CLOUDFLARE_ACCOUNT_ID credentials the deploy used (mirror how actions/cf.worker.deploy/ invokes wrangler — keep the two invocations consistent). Empty input = no new step runs → fully backward-compatible for existing consumers. Follow CLAUDE.md (thin workflow glue; if the logic is more than a short step, extract a composite actions/cf.worker.secrets/ — judgement call, one concern either way; natural errors: let wrangler fail loudly if a named var is absent).
2. Add the bridge's deploy caller .github/workflows/deploy.yml in this repo (self-caller precedent: .github/workflows/scan.yml): on: push to main with paths: apps/discord.bridge/** and the workflow file itself; single job calling gingur/devkit/.github/workflows/cf.worker.deploy.yml@main with cwd: apps/discord.bridge, env: production, secrets: 'DISCORD_BOT_TOKEN GH_WEBHOOK_SECRET GH_OPERATOR_PAT', runner: ${{ vars.RUNNER }} (push-to-main is operator-gated, so the local runner is allowed per CLAUDE.md → Self-hosted runner routing), and the Infisical inputs (infisicalIdentity: ${{ vars.INFISICAL_IDENTITY }}, project/env/path matching where the CF creds AND the three bridge secrets live — one fetch, one path; align the path with the runbook in apps/discord.bridge/README.md if it exists by then, else document the chosen path in the workflow comments). Permissions: contents: read, id-token: write, pull-requests: write (the deploy workflow records the version on the source PR).

Acceptance criteria

• cf.worker.deploy.yml with secrets unset produces an execution plan identical to today (no new step runs); with secrets set, exactly one wrangler secret bulk invocation receives all named values, and no secret value is ever echoed to the log.
• deploy.yml triggers only on main-branch pushes touching the bridge app or itself, and passes all required inputs listed above.
• actionlint (or careful YAML review if actionlint is unavailable) passes on both workflows.

To approve: tick Approve on the action panel below (posted automatically after this comment).
To change: just reply — any comment starts a revise turn automatically.

---

This turn: revised the plan per your feedback — multi-repo is now core (category per repo, #general per repo for /ask, repo-relative commands, per-repo webhook enrollment, repo baked into button ids), added the screenshot UX walkthrough (slash commands, modals, buttons — with the honest free-text limitation), and collapsed task bodies so the summary reads on a phone. All 5 task bodies updated accordingly; nothing created yet.
Need from you: tick Approve to materialize the 5 tasks, or reply with more corrections — e.g. if the modal-only text entry (no free-text channel chat in v1) changes your mind about anything.

[gingur-bot]

🎛️ Your move

Ticking the box is the only way to approve. Any reply is discussion — it starts a revise/answer turn automatically. Prefix a comment with [hold] to comment without starting a turn.

(panel closed)

[gingur]

Operator decision — the bridge's home changes: build it into gingur/hooks, not a new Cloudflare Worker and not apps/discord.bridge/ here. hooks is our single webhook service by design (Nitro + Hono on Bun behind hooks.gingur.com, HMAC verification for GitHub and future providers, delivery dedup in Neon, a pg-boss job queue). Revise the plan (v3) accordingly:

• GitHub → Discord mirroring consumes GitHub events through hooks' existing verified/deduped pipeline and runs as pg-boss jobs (at-least-once delivery to Discord, retries for free). No new webhook surface.
• Discord → GitHub is a new provider route in hooks: Discord's interactions endpoint (Ed25519 signature verification, 3-second ack deadline — use deferred responses + a pg-boss job for the actual GitHub write).
• Drop the CF Worker/wrangler/cf.worker.deploy tasks entirely; the deploy story is hooks' own (it runs on the box behind the tunnel).
• Availability trade accepted: box down ⇒ console down; the GitHub-native panel/reply flow stays the always-on fallback.
• Enrollment is its own task (likely task 1): gingur-bot collaborator access on gingur/hooks, the caller workflows installed there, a per-repo Infisical OIDC identity/binding (the existing one is bound to repo:gingur/devkit only), and the repo's secrets under the hooks Infisical path.
• Where tasks live: implementation tasks must be filed in gingur/hooks (they're implementable only there). If you cannot create issues in that repo this turn, say so in the plan and file only the enrollment task here — the rest materialize after enrollment.

Keep v2's multi-repo model (category per repo, relative commands), the operator-PAT trust decision, and the phone-readable format.