Build Discord agent gateway for natural-language service workflows

[michaelmwu]

Goal

Make the Discord bot smart enough to accept natural-language English commands and use skills / MCP servers to modify our services safely. The first concrete target should be a task-management workflow, then expand toward service changes through PR-based automation.

Proposed architecture

Keep the Discord bot thin:

Discord command/message
  -> bot auth/context resolver
  -> agent orchestrator
  -> deterministic permission gate
  -> skills / MCP tool registry
  -> service APIs / GitHub / task service / worker jobs
  -> audit log + user-visible result

The LLM should interpret English, propose structured plans, and choose likely tools. It must not make authorization decisions. Backend policy should own identity, scopes, approvals, resource checks, audit logs, and execution.

Example user flow

User says:

Create a task for Sarah to update the onboarding docs by Friday and link it to project Atlas.

The agent proposes a frozen structured action:

{
  "intent": "create_task",
  "tool": "task_management.create_task",
  "arguments": {
    "assignee": "sarah",
    "title": "Update onboarding docs",
    "due_date": "2026-05-15",
    "project": "Atlas"
  },
  "risk": "low"
}

The deterministic permission layer then authorizes or blocks the call.

Model usage guidance

Use stronger reasoning models selectively:

• understanding messy English requests
• resolving ambiguity
• planning multi-step work
• choosing between skills/tools
• generating code/service changes
• drafting PRs

Use smaller/faster models for simple classification, obvious field extraction, simple task creation, and summaries.

Do not use any model as the source of truth for permissions.

Permission model

Implement layered controls:

• identity resolution from Discord user/guild/channel to internal user/org/project context
• capability-based scopes such as task:create, task:update, task:assign, github:pr:create, deploy:request
• tool-level authorization before every tool call
• resource-level checks for project/task/org access
• risk-based confirmation and approval gates
• immutable audit logging for attempted and executed actions
• separate read tools from write tools
• no raw service credentials exposed to the model
• treat retrieved task/docs/comments/issues as untrusted content

Initial MVP

1. Add an agent gateway endpoint behind the Discord bot.
2. Support English task-management commands only.
3. Add read-only task/project lookup tools.
4. Add create/update task tools.
5. Add deterministic authorization and resource checks.
6. Add confirmation flow for writes.
7. Audit every attempted tool call.
8. Exclude production deploys, secret access, and arbitrary shell execution.

Follow-up direction

After task workflows are stable, support service modification through GitHub PR workflows:

"Add a retry setting to the worker"
  -> agent drafts plan
  -> creates branch
  -> edits code
  -> runs tests
  -> opens PR
  -> human reviews

Prefer PR-based changes over direct mutation for service changes.

Proposed subissues

• Add Discord agent gateway and natural-language command routing #259
• Add deterministic permissions and approval policy for agent tools #258
• Create MCP and skill tool registry with risk metadata #263
• Build task-management MCP tools and natural-language workflow #260
• Add confirmation UX and immutable audit logging for agent actions #261
• Implement model routing for simple versus reasoning-heavy agent workflows #262

[michaelmwu]

Triage update after PR #264: closed #258, #261, #262, and #263 as completed, and #259 was already closed by the PR. Keeping this parent open for now because #260 still needs a durable/canonical task backend rather than the current in-memory MVP task store.