diff --git a/AGENTS.md b/AGENTS.md index 9225512..d0240d7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,14 +1,17 @@ # apsuflow-skills -This repository distributes one on-demand operator skill. The canonical derived -source is `/opt/repositories/apsuflow/SKILL.md`; keep -`skills/apsuflow/SKILL.md` byte-identical whenever applicable Apsuflow -requirements or observed CLI behavior change. +This separate repository owns and distributes one on-demand operator skill. +`skills/apsuflow/SKILL.md` is canonical. Keep the repo-local mirror at +`/opt/repositories/apsuflow/SKILL.md` byte-identical whenever applicable +Apsuflow requirements or observed CLI behavior change. -Do not add implementation guidance, project policy, release mechanics, or a -second skill unless it owns a distinct recurring decision with a non-overlapping -trigger. Apsuflow `REQUIREMENTS.md`, CLI help, tests, and signed release evidence -remain authoritative. +The skill owns administration judgment: infrastructure-as-code practice, +configuration, deployment, maintenance, diagnosis, backup/recovery, and explicit +refusals around direct database/runtime/network mutation. Do not add product +implementation guidance, release mechanics, or a second skill unless it owns a +distinct recurring decision with a non-overlapping trigger. Apsuflow +`REQUIREMENTS.md`, CLI help, tests, and signed release evidence remain +authoritative. Before handoff: diff --git a/skills/apsuflow/SKILL.md b/skills/apsuflow/SKILL.md index 40a7e0f..3824339 100644 --- a/skills/apsuflow/SKILL.md +++ b/skills/apsuflow/SKILL.md @@ -50,15 +50,34 @@ in the same change when applicable requirements or CLI behavior change. Application queues, message retries, DLQs, and workflow state belong in broker-backed workloads. +## Infrastructure as code is central + +Treat reviewed, version-controlled `.apsu` plus the selected context as the +source of production intent. Put workloads, provider pools, placement, routes, +health checks, resources, update policy, and sealed-name references there; keep +secret values and credentials outside Git. A production change starts as a +declaration diff, passes `fmt --check`, `validate`, and preferably `apply +--dry-run`, then applies that exact reviewed file set. Record its revision, +context, dry-run, and post-apply workload/route evidence. + +Do not create a second source of truth through hand-edited runtime state or an +uncommitted mystery file. A manual restart may be an emergency diagnostic action, +but the durable repair belongs in IaC and must converge after re-apply. If live +state cannot be reconstructed from the elected declaration, stop and reconcile +that drift before making another change. + ## Install and update Use only the exact stable tag and artifact named by `docs/getting-started.md`. Verify `SHA256SUMS` and its SSH signature before installing; never use a mutable -`latest` URL. Keep the previous executable until the new one passes `version`, -`doctor`, and workload verification. The first stable release has no predecessor -compatibility case; every later stable release must carry proved upgrade and -rollback evidence against its adjacent stable predecessor. Apsuflow is not -published to a Cargo registry. +`latest` URL. Keep the previous executable and state backup until the new one +passes `version`, `doctor`, workload diagnosis, and each operator-facing route. +For host-network workloads, confirm the old container released its host ports and +the successor is the sole running generation; repeated replacement failures are +a rollback signal, not a reason to mutate runtime state directly. The first +stable release has no predecessor compatibility case; every later stable release +must carry proved upgrade and rollback evidence against its adjacent stable +predecessor. Apsuflow is not published to a Cargo registry. ## Local operation @@ -216,12 +235,14 @@ must return through Apsuflow or stop with a precise blocker. ## Decision and refusal -1. Name the context and solo/cluster topology. -2. Validate `.apsu` inputs and secret references; run diff before apply. +1. Identify the elected IaC revision, exact file order, context, and topology. +2. Validate `.apsu` inputs and secret references; run diff or dry-run before apply. 3. Ask before prune, restore, promotion, force-leader, or billable/destructive provider actions. -4. Apply through CLI/API and prove the workload path. -5. Diagnose through public status, logs, and recovery controls. +4. Apply the exact reviewed declaration through CLI/API and prove convergence, + workload behavior, and operator-facing routes. +5. Diagnose drift through public status, logs, and recovery controls; repair the + declaration rather than the runtime. Do not invent built-in queues, DLQs, application TLS, HTTP hostname routing, or distributed storage; use contexts as namespaces; put values/templates in `.apsu`;