arizuko › howto › Build a product

build a product

A product is a package with workspace identity and initial facts. Select it for a group with arizuko package add -g FOLDER.

The helpdesk template supplies a working example

ant/examples/helpdesk/ supplies a persona, operating rules, example facts, a triage skill and evaluation cases. Its manifest is:

name: helpdesk
brand: Helpdesk
tagline: Triage inbound support, answer what it can, escalate what it cannot.
env:
  HELPDESK_ESCALATION_CHANNEL:
    hint: Folder that billing/account escalations are routed to

Directory contents supply skills. The manifest declares name, optional brand and tagline, and environment requirements. The manifest defines this one package. It never selects a package.

The operator selects a package for a group

arizuko package add -g FOLDER ant/examples/helpdesk
arizuko package sync

add installs the package and records the selection in the installed_packages resource. sync installs every selected package again. Use -i/--instance NAME for another configured instance. Relative sources resolve under HOST_APP_DIR. The group must exist, and the files of a group in groups/FOLDER/ are not a selection.

group add -p helpdesk writes the same selection row for the new folder, and the files arrive on the next package sync. create -p helpdesk records the product as ARIZUKO_DEFAULT_PRODUCT in .env; the first boot of routd writes the same selection row for main.

Package assets and workspace files have different owners

Skills, native hooks, tools and manuals remain in the installed package. The renderer projects selected assets read-only into each guest. Core comes first, then packages in the order the operator added them. A later package overrides an earlier package on the same skill, hook, tool or group/ path, and package sync prints one line for each override.

Put the persona and other workspace files that nobody edits under group/. Each package sync writes them at the same relative paths and replaces any edit by the agent. The turn settings carry the advisory deny rule Edit(~/<path>) for each such file. A file that exists and that no package installed stops the command unless you pass -f. A file that a package stops shipping is removed. Package documentation stays with the source. Ship a file that the operator or the agent must edit, such as facts/, beside group/ and tell the operator to copy it once. group/.claude/settings.json merges by key: two packages that set the same key refuse the sync, and a key already in the group file stays.

Build tools with the package install command

An optional install string runs on the host as the invoking operator, from the source directory. PREFIX names the installed package directory; place executables in $PREFIX/bin/. They run inside the group at /usr/local/bin/. Agent turns run no host installer.

Hook scripts live in hooks/; native configuration lives in .claude/settings.json or .codex/hooks.json. The package reference lists guest paths and service constraints.

Ship tests with the workspace

Keep product evaluation cases beside the source. Verify task behavior in an isolated instance; package installation alone cannot prove that an agent follows instructions. The helpdesk fixture demonstrates refusal and escalation cases.

Check that package sync restores a group/ file after an edit, that package rm removes the files of the package, and that packaged tools execute through their standard guest paths.

Resource rows belong to instance packages

A group package cannot install service fragments or resource rows. Configure connectors, grants and scheduled tasks through their owning resources. A skills-only environment requirement is a setup hint; scoped credentials belong in group secrets.

Source: helpdesk template, package guide, package reference.