Simplify Athena operator architecture
This commit is contained in:
Mikei386
@@ -1,155 +1,62 @@
|
||||
---
|
||||
name: athena-operator
|
||||
description: Operate and extend the Athena AI platform safely.
|
||||
description: Understand, operate and extend the Athena AI host.
|
||||
license: MIT
|
||||
metadata:
|
||||
hermes:
|
||||
version: 0.2.0
|
||||
author: Michael Roll, Hermes Agent
|
||||
platforms: [linux, macos, windows]
|
||||
tags: [athena, operations, docker, mcp, models, recovery]
|
||||
related_skills: []
|
||||
version: 1.0.0
|
||||
author: Michael Roll
|
||||
platforms: [linux]
|
||||
tags: [athena, docker, mcp, models, recovery]
|
||||
---
|
||||
|
||||
# Athena Operator Skill
|
||||
# Athena Operator
|
||||
|
||||
Operate, diagnose, extend, and recover the Athena AI platform through its
|
||||
platform-context and operator MCPs. Keep durable truth in the versioned Athena
|
||||
repository and use live measurements only as evidence of current state.
|
||||
Use this skill for work on Athena itself: Docker, MCPs, models, profiles,
|
||||
Hermes, OpenWebUI, TTS, STT, image generation, Git and recovery.
|
||||
|
||||
## When to Use
|
||||
## Start
|
||||
|
||||
- Use for Athena, MikeAI, Docker-stack, router, inference-profile, model,
|
||||
benchmark, MCP, Hermes, Open WebUI, TTS, STT, image, Git-deploy, and recovery
|
||||
work on the Athena host.
|
||||
- Use when a user asks how Athena is built or whether an Athena component is
|
||||
running, configured, documented, reproducible, or recoverable.
|
||||
- Do not use as the primary tool for Home Assistant, Unraid, Sonarr, Radarr,
|
||||
Navidrome, or GitHub data when their specialist MCP is available.
|
||||
1. Read `ATHENA.md` through Athena Platform Context. It is the normal source
|
||||
of architectural truth.
|
||||
2. Call `athena_operator_inspect` once for the affected area.
|
||||
3. Search for the concrete source file, then read only the required lines.
|
||||
|
||||
## Prerequisites
|
||||
Do not rediscover the complete platform for every task. Do not read entire
|
||||
large files when a bounded section is enough. Do not guess file paths.
|
||||
|
||||
- Require `Athena Plattformwissen` for architecture and versioned knowledge.
|
||||
- Require `Athena Operator` for live host inspection and execution.
|
||||
- Treat missing or failed tools as missing evidence. Never invent state,
|
||||
output, files, logs, or completed actions.
|
||||
- Never request, reveal, copy into chat, or commit secret values.
|
||||
## Change
|
||||
|
||||
## Tool Selection
|
||||
When the user has clearly requested a change, use `athena_operator_change` to
|
||||
apply the smallest durable change. The operator owns the Git worktree and
|
||||
deployment access; do not clone another repository or request another SSH key.
|
||||
|
||||
1. Identify the target system before calling a tool.
|
||||
2. For Athena itself, begin with `athena_operator_inspect`. Use
|
||||
`athena_get_overview` when architectural context is needed.
|
||||
3. For external services, prefer the narrow specialist MCP. Use
|
||||
`athena_get_external_services` before planning a duplicate service.
|
||||
4. Use `athena_operator_search_source` and `athena_operator_read_source` for
|
||||
deployed code. Use `athena_search_knowledge` and `athena_read_source` for
|
||||
documentation. Do not guess paths or configuration.
|
||||
5. Use `athena_operator_terminal` as the broad Athena escape hatch only when a
|
||||
structured tool is too narrow. Keep commands focused and outputs bounded.
|
||||
Afterwards run focused checks, verify the affected service, commit and push.
|
||||
Create a recovery kit after the complete change works, not after every
|
||||
intermediate edit.
|
||||
|
||||
## Procedure
|
||||
For a new MCP, normally change only its server code, Dockerfile, MCP Compose
|
||||
service, env example, client registration and a focused test. Reuse an existing
|
||||
backend instead of installing a duplicate service.
|
||||
|
||||
1. **Establish evidence.** Inspect only the relevant live subject and read the
|
||||
smallest authoritative source section. Completion: runtime facts and source
|
||||
facts are separately identified.
|
||||
2. **Check drift.** Compare live state with versioned source and current
|
||||
reference documentation. Completion: any mismatch is named before changes.
|
||||
3. **Protect the active workload.** Check jobs and active containers. Do not
|
||||
restart, recreate, switch profiles, alter shared configuration, or consume
|
||||
required GPU capacity while an important request or benchmark is active.
|
||||
Completion: work is either proven idle or the change is staged only.
|
||||
4. **Plan rollback.** Name the files, services, validation, rollback artifact,
|
||||
and expected user-visible effect. Completion: rollback is possible without
|
||||
relying on chat history.
|
||||
5. **Change the source of truth.** Modify repository sources, not only a live
|
||||
container. Prefer `athena_operator_prepare`; show its full preview and stop
|
||||
for the exact user confirmation before `athena_operator_execute`.
|
||||
Prefer `patch_update` with a small unified diff and the current file SHA for
|
||||
ordinary edits. Use `file_update` only for new files or intentional complete
|
||||
replacements. Never clone the repository in
|
||||
the Hermes sandbox and never request or copy an SSH key; the Operator owns
|
||||
the canonical worktree and its deploy credentials.
|
||||
Completion: the approved ticket matches the intended content.
|
||||
6. **Deploy narrowly.** Change only named services. Never restart the entire
|
||||
stack merely to activate one component. Completion: unrelated containers
|
||||
and the active inference request remain undisturbed.
|
||||
7. **Verify behavior.** Run syntax/config checks, focused tests, service health,
|
||||
and one bounded functional test. A running container alone is not proof.
|
||||
Completion: expected behavior and rollback path are both verified.
|
||||
8. **Close the maintenance loop.** For a normal MCP delivery, prefer one
|
||||
confirmed `mcp_release`; it applies the reviewed patches, runs checks,
|
||||
deploys only named services, synchronizes OpenWebUI, publishes selected
|
||||
paths and creates recovery. Use separate operations only for diagnosis or a
|
||||
deliberately partial workflow. Otherwise update relevant docs, publish only the
|
||||
explicitly selected changed paths with `git_publish`, create a newer
|
||||
recovery bundle, then check maintenance status.
|
||||
Completion: source commit, deployed state, docs, and recovery agree.
|
||||
## Tool discipline
|
||||
|
||||
## Compact MCP Release Recipe
|
||||
- One failed path may be corrected once. Repeated `file not found`, permission
|
||||
or circuit-breaker responses mean stop and report the exact blocker.
|
||||
- Keep search and terminal output bounded.
|
||||
- Prefer specialist MCPs for Home Assistant, Unraid, ARR, Navidrome and other
|
||||
external systems.
|
||||
- A healthy container is not proof; perform one bounded functional check.
|
||||
- Never claim a write, deploy, commit, push or recovery succeeded without its
|
||||
actual result.
|
||||
|
||||
Use this route for a new self-written MCP. Do not rediscover the platform file
|
||||
by file.
|
||||
## Remote-host boundary
|
||||
|
||||
1. Inspect Athena once and check the service catalogue so an existing backend
|
||||
is reused rather than duplicated.
|
||||
2. Treat an already reviewed artifact in an approved staging directory as an
|
||||
input. Calculate its SHA once and pass it to `mcp_release.imports`; never
|
||||
reproduce a long staged source file in chat or a `file_update` payload.
|
||||
3. Patch only the actual integration sources: `platform/mcp/compose.yaml`, the
|
||||
managed Hermes config in `platform/hermes/config.yaml`, OpenWebUI's
|
||||
versioned connector sync/seed, the env example, tests and relevant docs.
|
||||
4. Set `hermes_sync: true` when the managed Hermes MCP list changes and
|
||||
`openwebui_sync: true` when OpenWebUI's connector list changes. Neither sync
|
||||
restarts Hermes, Router, Qwen, WireGuard, or the complete stack.
|
||||
5. Do not add a VPN port or edit WireGuard for an ordinary in-stack MCP. Hermes
|
||||
and OpenWebUI use Docker DNS on the private tool network. Add external VPN
|
||||
publication only when the user explicitly asks for access by outside MCP
|
||||
clients.
|
||||
6. One `mcp_release` should import/patch, test, deploy only the named MCP,
|
||||
synchronize clients, publish selected paths and create recovery. Then verify
|
||||
handshake plus one bounded non-writing function.
|
||||
Never shut down or reboot Athena and never change its SSH, LAN, WireGuard,
|
||||
firewall, boot, kernel, partition or mount configuration unless the user gives
|
||||
a separate explicit current instruction. Do not restart Router, Qwen, Hermes
|
||||
or the whole stack merely to deploy one component.
|
||||
|
||||
A tool-call budget that ends "at a checkpoint" means: report a compact status,
|
||||
then continue the same approved task with a fresh budget. It does not mean
|
||||
abandon the requested implementation after reconnaissance.
|
||||
|
||||
## Persistent Versus Temporary Work
|
||||
|
||||
- "Use" a missing helper for one task: place it in a task-specific temporary
|
||||
location or ephemeral container and remove it afterward.
|
||||
- "Install", "add", "deploy", or "make permanent": implement it in repository
|
||||
source, documentation, installation flow, and recovery.
|
||||
- Do not create a second backend merely because an existing service is stopped,
|
||||
inaccessible, or absent from one tool catalogue.
|
||||
|
||||
## Remote-Safety Boundary
|
||||
|
||||
- Athena has no physical console or KVM. Never attempt power control or changes
|
||||
to Athena SSH, LAN, WireGuard, firewall, boot, kernel, drivers, mounts, or
|
||||
partitions through this workflow.
|
||||
- Do not stop or restart the WireGuard gateway as a side effect of ordinary
|
||||
deployment. Bind user services to the VPN path; keep them unavailable from
|
||||
the university LAN.
|
||||
- Inside the trusted VPN, normal service communication and Internet access are
|
||||
allowed. Do not add extra egress restrictions unless the user requests them.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Profile names are not simultaneous models; exactly one text profile is active.
|
||||
- A profile switch can terminate active generation and invalidate prompt cache.
|
||||
- A healthy container can still expose the wrong model, route, or tool set.
|
||||
- `/opt/mike-ai/stack` is deployed source, not automatically the canonical Git
|
||||
worktree. Use `patch_update` for compact edits and `mcp_release` for the
|
||||
complete MCP lifecycle. Do not reconstruct whole Compose or installer files
|
||||
for a small change.
|
||||
- New skills are loaded at the next Hermes session; absence in the current
|
||||
session is expected.
|
||||
|
||||
## Verification
|
||||
|
||||
- State the tools that supplied each important live claim.
|
||||
- List every modified source file and every deployed service.
|
||||
- Report focused test and health results, not vague success language.
|
||||
- If Git publication or recovery creation is incomplete, call it unfinished
|
||||
maintenance rather than declaring the task fully complete.
|
||||
Temporary helpers belong under `/tmp` or in an ephemeral container. Permanent
|
||||
software belongs in the Git-managed stack. Secrets stay under `/etc/mike-ai`
|
||||
and must not be committed or printed.
|
||||
|
||||
Reference in New Issue
Block a user