arizuko › products › Helpdesk › setup

Helpdesk setup

You can make a new group from the product, or add the product to a group that you already have. Both ways put the same files in the same places.

One placement rule serves both ways, so a product means the same thing however you apply it. Only the skill moves: the product ships it at skills/<name>/, and it goes to .claude/skills/<name>/, where the agent reads it.

The product needs an instance and one channel

A running instance, from getting started.
One channel adapter, so that support messages reach the agent. Slack is the usual channel for a support queue.
Nothing more. The product ships no sidecar, no image extension and no external credential.

group add makes a new group with the product and its route

The Slack JID names the workspace, the kind and the channel. Send /chatid in the channel to get it.

arizuko group -i <instance> add slack:T012ABCD/channel/C0SUPPORT acme/support --product helpdesk
arizuko route -i <instance> list

ID  SEQ  MATCH                            TARGET
1   0    room=T012ABCD/channel/C0SUPPORT  acme/support

The command records the selection of the product for acme/support in the installed_packages resource. The next arizuko package sync writes the group/ files of the product into groups/acme/support/ and replaces any edit of them. group add also writes the route, so every message in that Slack channel reaches the acme/support agent.

To add a second channel, add a second group. To add a webhook or a public chat link, make a route token, as webhooks and chat link show. All of these inputs reach the same folder and the same agent.

package add selects a product for an existing group

A group can run several products. Select each one for the group, then sync:

arizuko package add -i <instance> -g acme/support ant/examples/helpdesk
arizuko package sync -i <instance>

An escalation to an agent is a delegation

The product escalates billing and account questions. An escalation to a person is a message. An escalation to another agent is a delegation. Make the billing group first, because nothing makes it for you:

arizuko group -i <instance> add slack:T012ABCD/channel/C0BILLING acme/billing

The support agent then calls delegate_group with the billing folder and the request. The billing agent runs its own turn, in its own guest, with its own grants and its own egress allowlist. It is a peer, not a subroutine.

The delegating agent needs a grant. role:member does not hold delegate_group, so an operator must grant it to the support folder, with a scope that covers acme/billing. Until then, the agent says that it cannot escalate. That is the correct failure.

A route selects one destination for each message. Use delegation to bring the billing agent into the same issue. Routing explains how routes are matched.

One optional variable names the escalation target

The product declares one optional variable for the escalation target.

HELPDESK_ESCALATION_CHANNEL=acme/billing

The facts folder holds what your team promises

facts/sla.md ships with one line, so the shape is clear. Replace it with what your team promises, and add one file for each topic, for example the refund window, the supported versions and the escalation rota. The agent answers from these files. It escalates every question that the files do not answer.

The facts/ files of the product are examples, not package files, so arizuko package sync never rewrites them. Copy them once from the repository checkout:

cp -r ant/examples/helpdesk/facts /srv/data/arizuko_<instance>/groups/acme/support/

A billing question must escalate

arizuko send -i <instance> acme/support "I was charged twice for March, ticket 4417" --wait

A correct answer escalates, does not resolve, and quotes the ticket ID. If the agent offers a refund, check that the helpdesk package is selected and its manual is installed.

Four files tune the agent

Voice: Edit group/PERSONA.md in the package source and run arizuko package sync.
Rules: Edit the package source's CLAUDE.md and run arizuko package sync. The combined manual is mounted read-only in the guest.
Triage classes: Edit the package source's skills/triage/SKILL.md and run arizuko package sync. The installed skill is mounted read-only in the guest.
A skill to turn off: Put a .disabled file in the directory of the skill.