diff --git a/.claude/skills/help/SKILL.md b/.claude/skills/help/SKILL.md new file mode 100644 index 0000000..181c47e --- /dev/null +++ b/.claude/skills/help/SKILL.md @@ -0,0 +1,14 @@ +--- +name: help +description: Operator orientation - lists every skill available on this orchestrator with what it does and when to reach for it, grouped by purpose (status, weekly maintenance, host updates, tests, enrollment, recovery, reporting), plus a "what do you want to do?" guide for common situations. Read-only. Invoke as /help. +--- + +# help (thin wrapper) + +The canonical definition of this skill lives in the **opencode** position: + +**`.opencode/skills/help/SKILL.md`** + +Read that file for the full content. This `.claude/skills/` copy is kept as a +thin pointer for Claude Code compatibility; opencode loads the canonical +definition from `.opencode/skills/` directly. diff --git a/.opencode/skills/help/SKILL.md b/.opencode/skills/help/SKILL.md new file mode 100644 index 0000000..dc2cd9a --- /dev/null +++ b/.opencode/skills/help/SKILL.md @@ -0,0 +1,77 @@ +--- +name: help +description: Operator orientation - lists every skill available on this orchestrator with what it does and when to reach for it, grouped by purpose (status, weekly maintenance, host updates, tests, enrollment, recovery, reporting), plus a "what do you want to do?" guide for common situations. Read-only. Invoke as /help. +--- + +# help + +Orient the operator: what this orchestrator can do, via which skill, and what's sensible next. + +**First, enumerate the live roster** (skills get added — don't trust this file's list blindly): +``` +ls /srv/cc-ci-orch/.opencode/skills/ # canonical definitions (one dir per skill) +``` +For any skill not described below, read its `SKILL.md` frontmatter description and include it. +Then present the roster grouped as follows, and close with the situation guide. + +## The roster (curated descriptions — merge with the live listing) + +**Status & orientation** +- **/cc-ci-status** — the comprehensive read-only health/status check: weekly-run outcomes, + report publishing, stale tests, CVE-PR aging, host update recency, service health, bridge + `!testme` path. Ends `ALL HEALTHY` or prioritized findings each mapped to a skill. **Start + here when unsure.** +- **/help** — this orientation. + +**Weekly maintenance (recipes)** +- **/upgrade-all** — the weekly sweep: survey every `weekly` recipe, open verified upgrade PRs, + write the summary + report. Runs on a timer (`cc-ci-upgrade-all.timer`, Fri 02:00 UTC); + invoke manually to run it now. +- **/recipe-upgrade ** — the same pipeline for ONE recipe (plan → bump → verify green → + PR). `--with-tests` also fixes that recipe's stale test. +- **/recipe-report** — (re)generate the weekly report page for report.ci.commoninternet.net. + +**Tests** +- **/cc-ci-tests-update** — fleet-wide stale-test cleanup: find tests broken by legitimate + upstream changes, fix without weakening, verify, merge the test PRs. +- **/ci-test-review** — diagnose a specific red CI run: classify recipe bug vs stale test vs + CI-server bug, then fix on the right side. + +**cc-ci itself** +- **/cc-ci-server-update** — bump the CI **server** host's nixpkgs/sops-nix, deploy with + build → `nixos-rebuild test` → switch + health gate, PR merged on green. +- **/cc-ci-orchestrator-update** — same for **this** orchestrator host (self-update caveats). +- **/cc-ci-update** — both of the above plus /cc-ci-tests-update in one pass. +- **/ci-dev-workflow** — harness/CI-server development discipline (changing cc-ci itself). + +**Enrollment** +- **/recipe-enroll ** — add a NEW recipe to the maintained set end-to-end: mirror, + test suite, bridge + inventory enrollment, full-suite-green verification, bridge deploy. + +**Recovery** +- **hetzner-server-recovery** — when a Hetzner host is unreachable over SSH/tailscale: API + reboot, rescue mode, GRUB generation selection (submenu ids are `1>N`), console access. + +## "What do you want to do?" + +| Situation | Do this | +|---|---| +| "How is everything?" | `/cc-ci-status` | +| "Run the weekly upgrades now" | `/upgrade-all` (or `systemctl start cc-ci-upgrade-all.service`) | +| "Upgrade just " | `/recipe-upgrade ` | +| "The report site is stale/missing a week" | `/recipe-report` | +| "Tests are red because upstream changed" | `/cc-ci-tests-update` (fleet) or `/recipe-upgrade --with-tests` | +| "A CI run failed and I don't know why" | `/ci-test-review` | +| "Update the CI server OS/deps" | `/cc-ci-server-update` | +| "Update this orchestrator's OS/deps" | `/cc-ci-orchestrator-update` | +| "Add to what we maintain" | `/recipe-enroll ` | +| "A host is unreachable" | `hetzner-server-recovery` | +| "What needs my review?" | `/cc-ci-status` → its open-PR section lists CVE-urgent + ready-to-merge PRs | + +**Standing conventions** (all skills follow these): PRs are opened for visibility and merged +directly once verified (invocation = authorization) — except recipe upgrade PRs, which stay +operator-merged; `nixos-rebuild test` before any `switch`; never weaken a test; single-writer +branches; serialize deploy-heavy work on the shared swarm. + +If several things need doing, run `/cc-ci-status` first — its findings come pre-prioritized +with the skill to invoke for each.