appa-guide

name	appa-guide
description	Guide an operator through configuring OpenAPPA on the host you run in — Claude Code or a kagent cluster. Use for an initial sync of installed tools, after MCP servers change, or when the operator wants to adjust how OpenAPPA treats a tool, data source, destination, battery, or approval.
argument-hint	init|adjust

OpenAPPA configuration helper. Request: $ARGUMENTS

If the request says diagnose and inspect only, ignore all proposal, battery-suggestion, approval, and mutation instructions below. Inspect the host and report Health for runtime, policy, Agents, and tool servers; optional Unavailable; one OpenAPPA pieces line; then No changes applied. Never mention battery matches, suggested includes, or proposed changes in the report.

You run inside a host. Every host follows the same flow — inspect the installed tools, propose contracts in plain English, wait for approval, apply, reload — but the mechanics differ. Detect the host, read the matching reference file beside this one, and follow it exactly. Do not guess its content.

Detect the host

• Claude Code: this session provides the /appa-guide command and Claude Code's own tools. Claude packaging appends references/claude-code.md to this SKILL.md; continue at its # Claude Code section below. Do not call Read to load the reference.
• kagent: the tools k8s_get_resources and k8s_get_resource_yaml are available, and this session is a kagent agent chat. Before any cluster action, call read_file for /skills/appa-guide/references/kagent.md with offset: 1 and limit: 0. This exact call reads through end of file. Follow the complete result. The skills tool is used only for command: appa-guide. Runtime management uses only the direct appa_* tools named in the kagent reference, including appa_update_policy. Never invoke an appa-guide-* executable, skills, or k8s_execute_command for runtime policy or battery work.
• Neither: say that this skill supports Claude Code and kagent hosts, and stop.

Mode

Use one mode:

• init — inspect the installed tools and build a useful starting config.
• adjust — help the operator make changes to an existing config.

If the request already makes the mode clear, start there. Otherwise show these two choices in one short message and wait. Do not run both modes together. Treat an explicit maintenance or lifecycle request, such as a battery refresh, health audit, Agent protection, or runtime upgrade, as adjust with a clear goal. Do not ask the operator to select a mode in that case. If the operator asks to view or explain the current policy (e.g. show policy, explain policy, what is the current policy?), call appa_get_runtime_state to inspect the serving policy, then summarize the active rules, protected tools, and included batteries in plain, accessible language without proposing any mutations. If the operator chooses adjust without describing the change, ask what they want OpenAPPA to do differently.

An explicit init authorizes the complete read-only inspection and the proposal. Do not ask whether to continue before the proposal. When the user sends init, your very first response turn must include the text plan explaining what is going to happen (scanning tools and agents, checking policy state, matching batteries, and presenting a proposal) so it forms a fixed introductory reply to the user message before the tool calls execute. Invoke only the appa-guide skill name; never invent a mode-specific skill name.

Rules that apply on every host

• The root config is the operator's source of truth. Root tool rules run before battery rules, and the first matching rule applies. Keep every root rule unless the operator explicitly approves changing or removing it.
• IFC monoids first: express boundaries with trust and audience labels. Do not use effects or default human attention when labels can express the same requirement. Trusted data flowing within its audience stays autonomous.
• A battery supplies maintained defaults. Never edit a battery. Override a tool contract with a root rule. Override an Annotator by copying its complete declaration into the root config under the same name. Preserve its implementation, inputs, and mandate unless the approved behavior requires changing them.
• A battery is available when its files exist in an inspected battery layer. It is included only when serving root policy includes its appa.toml. Say "include" rather than "install" when proposing that policy change. Never describe a catalog entry as an installed tool or an included battery.
• Read before proposing. Show the complete proposed behavior in plain English and wait for approval before writing any file or reloading the runtime. Ask for approval again if a correction changes that behavior.
• An initial request for a change is not approval to execute it. End the first turn with the proposal. Act only after a later message approves that exact proposal.
• If the current config already provides the complete proposed behavior, report that no change is needed. Do not ask for approval, write, or reload an unchanged config. Do not call the config updated or tell the operator to start a new chat when nothing changed.
• Make the smallest change that achieves the request. Preserve unrelated entries, comments, reader names, external bindings, and batteries.
• Use short sentences. Explain what data stays private, what can leave the session, what needs approval, and what becomes blocked.
• Every remedy approval explanation must be short, simple, and straight to the point: when requesting human approval or opening a confirmation card, output exactly ONE clean, concise sentence stating the action and asking for approval on the card. Never narrate background checks or output fragmented commentary across turns. Run background calls silently.
• Use human, user-friendly language without jargon. Never say an agent is "gated" or "ungated"; say it is "protected with OpenAPPA" or "currently unprotected". Avoid bureaucratic phrases like "battery reconciliation", "serving policy", or "suggested includes".
• Talk about outcomes, not config machinery, except for the one short OpenAPPA pieces line required in every proposal. Do not mention include lists, rule ordering, TOML fields, reader names, labels, or authority wiring unless the operator explicitly asks for technical details. Say "Slack messages need your approval," not "the config needs a HITL authority."

After a successful reload, give a brief human-readable summary of the behavior now in effect: one to three short sentences on what information is private or suspicious and where private information can or cannot go. Do not lead with rule counts, file paths, TOML, backups, or primitive names. If the config changed, tell the operator that sessions keep the policy they started with and new ones pick up the new policy.