Skip to main content

Never Answer the Same Question Twice

Building a self-learning helpdesk inside Slack with Switch (peopledesk )

Updated 9 min readMarkdown
Never Answer the Same Question Twice

The Short Version

  • The problem: Repetitive questions about leave and VPNs bury real work, and approvals get lost in threads with no clear owner.
  • What I built: PeopleDesk, an HR and IT helpdesk agent that lives in a Slack channel. It answers from a knowledge base, routes tickets to humans, and drafts a new article every time a problem gets solved.
  • The core rule: The agent never acts in isolation. Permissions follow identity. Employees can't approve their own leave, non-helpers can't resolve tickets, and sensitive topics go straight to a human.
  • The stack: Switch, OpenCode, Docker, the Slack API, and Wispr Flow.

The Monday Morning Problem

Every team has the same Monday.

Someone asks how many sick leaves they get. Someone's VPN is down again. A leave request is buried in a thread and nobody is sure who's allowed to approve it.

The answers exist, but they live in documents nobody opens. The approvals live in chat with no owner.

Ticketing portals don't fix this because they pull people out of where they already talk. Regular Slack bots don't fix it either, because they have no structured state, no identity checks, and no permission boundaries.

So I built an agent that sits in the channel, answers from a knowledge base, opens a ticket when it's stuck, routes it to the right person, and gets smarter every time a human solves something.

What PeopleDesk Does

Architecture

Slack Channel
     |
     v
Switch (Room + Identity)
     |
     v
OpenCode Agent
  AGENTS.md | team.json | kb/*.md | tickets | requests

Key Features

1. Answers with sources

It replies from a Markdown knowledge base and names the exact article. It never invents policies, dates, or amounts.

2. Routes tickets

If the answer isn't in the knowledge base, it opens a ticket and tags the right person by topic, HR or IT.

3. Enforces permissions

Only the assigned helper can resolve a ticket. Only an employee's manager can approve their leave. Nobody can approve their own request.

4. Learns from humans

When a helper resolves a ticket, the agent drafts a new article. Once the helper approves it, the next person gets an instant answer.

5. Knows when to step back

Resignations, salary disputes, and legal questions go straight to a human instead of getting an AI guess.

6. Stays auditable

Helpers can edit articles, employees can flag outdated info, and managers can run a nudge command to recap open tasks.


Why Switch Is the Heart of It

The hackathon's question is simple: Would this project stop working without Switch?

For PeopleDesk, yes, for three reasons.

1. A Channel Becomes a Room

Humans and the agent read the same thread, so the agent behaves like a teammate instead of a detached bot.

2. Real Identity

Switch hands the agent every message along with the sender's authenticated handle.

That's what makes permission boundaries possible. When someone tries to self-approve or close another person's ticket, the agent checks the handle and says no.

3. No Plumbing

Register the agent once in the Switch Console, invite it into a channel, and your team can use it right away.

Without Switch, I'd be building Slack WebSocket listeners, user token mapping, identity middleware, and thread state tracking.

With it, the agent's rules are the product.


How It Works

There's no backend server and no database.

Switch invokes the agent as an OpenCode session on each message event, and the agent's folder is its memory.

Project Structure

File What it's for
AGENTS.md Operating rules and permission boundaries
team.json Helpers, managers, and the topics they own
kb/*.md The knowledge base, version-controlled Markdown
tickets.json Ticket state and lifecycle
requests.json Approval workflows

Build It Yourself

1. Install Docker and Switch Console

Install and start Docker Desktop, then download Switch Console and create a new local server instance.

2. Create the Slack App

Go to the Slack App Directory, choose:

Create New App → From an App Manifest

Pick your test workspace, and paste the standard Switch Slack manifest.

One thing to change: Remove the agent_view blocks and the assistant:write scope.

Declaring the app as a generic Slack Assistant can restrict guest permissions and force unwanted DM thread behavior.

3. Collect Your Credentials

Keep these in a local .env file and never commit it.

  • App-level token: Under Basic Information → App-Level Tokens, with the connections:write scope. Starts with xapp-.
  • Bot token: Under Install App → Bot User OAuth Token. Starts with xoxb-.
  • Workspace ID: From your browser URL (app.slack.com/client/T.../C...). Starts with T.

4. Connect Slack in Switch Console

Go to:

Server → Home → Messaging Apps → Connect Slack

  1. Enter a service name.
  2. Paste both tokens.
  3. When asked about account assignment, choose This is me.

On a free Slack plan, turn Agent name autocomplete off, since it needs a paid tier. People can still trigger the agent by typing its full name.

5. Create the Room

Make a channel like #peopledesk-test and run:

/invite @Agent Switch

It should appear under Your Rooms in the Console.

6. Set Up the Agent Folder

mkdir -p peopledesk-agent/kb
cd peopledesk-agent

touch AGENTS.md team.json tickets.json requests.json

echo "[]" > tickets.json
echo "[]" > requests.json

Then fill in team.json with your people:

team.json

{
  "people": [
    {
      "handle": "thomasjoshua466",
      "display": "Joshua",
      "role": "hr-manager",
      "handles_topics": ["hr", "leave", "payroll"],
      "manages": ["*"]
    },
    {
      "handle": "thomasjoshua098",
      "display": "Bob",
      "role": "it-admin",
      "handles_topics": ["it", "equipment", "vpn", "wifi"]
    }
  ]
}

Add a few starter articles to kb/, like:

  • leave-policy.md
  • wifi-vpn.md

Leave out some topics on purpose, such as health insurance or work-from-home rules, so you can watch the learning loop work live.

7. Register the Agent

In Switch Console, under Your Agents, click Add Agent and set:

Setting Value
Name peopledesk.joshua
Provider OpenCode
Directory Path to peopledesk-agent
Execution mode Auto mode on
Bypass permissions Off
Access control Include workspace members under Who can talk to your agent

8. Invite It and Map the Handles

In your channel, run:

!invite-agent @peopledesk.joshua

Then ask it to list the room's participants and copy the exact handles into team.json.

That's what gives you identity control from the start.


The Brain: AGENTS.md

To keep the model fast and predictable, I wrote the rules as short numbered lines instead of long prose.

1. KNOWLEDGE FIRST:
   Always query kb/*.md before answering.
   Always cite the exact source file.

2. STICK TO FACTS:
   Never speculate on policy, compensation,
   or company dates.

3. CLARIFICATION:
   Ask at most ONE clarifying question per interaction
   before taking action.

4. TICKET CREATION:
   If kb/*.md lacks an answer, create an entry
   in tickets.json and tag the matching handle
   from team.json.

5. PERMISSION RULES:
   - Only the assigned helper handle can mark
     a ticket as "resolved".
   - Only the designated manager handle can
     approve/decline entries in requests.json.
   - Requesters can NEVER self-approve or
     self-resolve their own submissions.

6. LEARNING LOOP:
   When a helper resolves a ticket, draft a new
   .md document in kb/ and await approval
   from that helper.

7. SENSITIVE ESCALATION:
   Instantly escalate resignations, legal queries,
   or pay disputes directly to the HR manager.

8. CONCISE REPLIES:
   Keep all Slack output between 1 to 4 lines maximum.

Seeing It Work

I tested with three personas:

  • Alice: Employee
  • Bob: IT admin
  • Joshua: HR manager

The boundaries held every time.

1. The Learning Loop

Alice:

"What health insurance plan do we have?"

PeopleDesk:

No record in the knowledge base. Created ticket T-002 and tagged @Joshua (HR).

Joshua:

Resolves the ticket with the policy terms.

The agent drafts kb/health-insurance.md, and Joshua replies:

"Approve"

Alice, the next day:

"What health insurance do we have?"

PeopleDesk:

"We provide Comprehensive Healthcare Plan B (Source: kb/health-insurance.md)."

2. Permission Refusals

Alice writes:

Resolved T-002

PeopleDesk:

"Refused. Only assigned helper (@Joshua) can resolve Ticket T-002."


Joshua tries to resolve an IT ticket assigned to Bob.

PeopleDesk:

"Refused. Ticket T-004 is assigned to IT Admin (@Bob)."

3. Self-Approval Block

Alice requests leave for Dec 20–24, then types:

Approve request R-001

PeopleDesk:

"Refused. Requesters cannot approve their own requests. Awaiting action from Manager (@Joshua)."


Lessons and Gotchas

1. Identity Uses Handles, Not Display Names

Display names change. Switch relies on the underlying handle (like thomasjoshua466), so always list the participants first before defining roles.

2. Use State Machines, Not Timers

Switch agents run on events and have no built-in cron.

For stalled tickets, I added a manual nudge command that scans tickets.json for open items and pings their owners.

3. Threads Trigger the Agent

In local Switch setups, replies in a thread trigger the agent without an @mention.

Keep threads focused, or turn on !follow-ups off for side discussions.

4. Keep JSON Writes Small

Since local JSON files are the datastore, tell the agent to append selectively instead of rewriting whole files.

It keeps responses fast.


Built by Voice

I wrote most of the prompt rules and documentation with Wispr Flow, speaking instead of typing.


What's Next?

  • Private approvals: Moving sensitive pay and leave approvals into 1:1 agent DMs.
  • Scheduled reminders: Using external webhooks or Slack Workflow Builder for periodic ticket rollups.
  • New verticals: Adapting the template for university support desks and medical clinics.

Try It Yourself

No comments yet. Be the first to comment.