feat: add arch-maintenance and arch-troubleshooting skills

refactor: rename dev-workflow skill to implementation-orchestrator
The name dev-workflow described a category, not what the skill does. It orchestrates implementation of already-planned tickets, so the new name says that. Skill dir, docs page, name field and openai display name are updated to match; validate-skill.sh moves with the dir and its paths are fixed for the new depth and engineering/ layout.
2026-09-22 17:52:48 -04:00 · 2026-08-30 13:40:27 -04:00 · 2026-08-30 12:44:20 -04:00
13 changed files with 372 additions and 35 deletions
@@ -34,6 +34,11 @@ Skills are grouped by invocation type. [User-invoked](docs/invocation.md) skills
 - [tmux-launch-agent](skills/misc/tmux-launch-agent/SKILL.md) — Fork a new agent CLI session into a new tmux window.
 - [visual-verification](skills/misc/visual-verification/SKILL.md) — Verify running desktop UI changes with screenshots and recordings.

+### Personal
+
+- [arch-maintenance](skills/personal/arch-maintenance/SKILL.md) — Keep an Arch/CachyOS system updated and healthy with status, check, and update workflows.
+- [arch-troubleshooting](skills/personal/arch-troubleshooting/SKILL.md) — Diagnose and repair Arch/CachyOS system problems.
+
 ### PKM

 - [conversation-summary](skills/pkm/conversation-summary/SKILL.md) — Save the current conversation as a report note in an Obsidian vault.
@@ -1,6 +1,6 @@
-# Pi development workflow skill
+# Pi implementation orchestrator skill

-`dev-workflow` implements already-planned tracker tickets from issue selection through isolated implementation worktrees, pull/merge requests, review, merge, and cleanup.
+`implementation-orchestrator` implements already-planned tracker tickets from issue selection through isolated implementation worktrees, pull/merge requests, review, merge, and cleanup.

 It supports:

@@ -40,10 +40,10 @@ Invoke it with an optional ticket ID or URL:

 ```text
 # Process only ticket 43
-/skill:dev-workflow 43
+/skill:implementation-orchestrator 43

 # Process all available tickets in the current repository
-/skill:dev-workflow
+/skill:implementation-orchestrator
 ```

 The ID must be a tracker issue/ticket, not a branch name, PR/MR ID, or session ID. With an ID, only that ticket is processed. With no ID, the skill considers all open tickets in the current repository.
@@ -1,26 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
-skill="$root/skills/dev-workflow/SKILL.md"
-shared_skill="$root/skills/forge-cli/SKILL.md"
-recipes=(
-	"$root/skills/forge-cli/references/tea.md"
-	"$root/skills/forge-cli/references/gh.md"
-	"$root/skills/forge-cli/references/glab.md"
-)
-
-[[ -f "$skill" && -f "$shared_skill" && -f "${recipes[0]}" && -f "${recipes[1]}" && -f "${recipes[2]}" ]] || {
-	echo 'Missing skill or reference file' >&2
-	exit 1
-}
-head -1 "$skill" | grep -qx -- '---'
-grep -q '^name: dev-workflow$' "$skill"
-grep -q '^description: ' "$skill"
-head -1 "$shared_skill" | grep -qx -- '---'
-grep -q '^name: forge-cli$' "$shared_skill"
-grep -q '^description: ' "$shared_skill"
-node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))' "$root/package.json"
-bash -n "$root/skills/forge-cli/scripts/detect-forge.sh"
-
-printf '%s\n' 'dev-workflow skill is valid'
@@ -1,12 +1,12 @@
 ---
-name: dev-workflow
-description: Implements ready-for-agent tracker tickets through isolated worktrees, pull requests, review, conflict resolution, and merge. Use after wayfinder and planning have produced tickets, when the user gives a ticket ID, asks to process available tickets, or asks to run the development workflow. Does not create planning tickets.
+name: implementation-orchestrator
+description: Implements ready-for-agent tracker tickets through isolated worktrees, pull requests, review, conflict resolution, and merge. Use after wayfinder and planning have produced tickets, with or without a ticket ID/URL; no ticket ID/URL means process available tickets. Does not create planning tickets.
 disable-model-invocation: true
 ---

-# Development workflow
+# Implementation orchestrator

-Use this skill only after the human-led wayfinder, plan, spec, and ticket phases. The optional argument is a **tracker ticket ID or URL**. With an argument, process only that ticket. With no argument, scope the run to all open tickets in the current repository. An ID means the forge's issue/ticket identifier, not a branch, session, or PR ID.
+Use this skill only after the human-led wayfinder, plan, spec, and ticket phases. **A tracker ticket ID or URL is optional. Without one, process all eligible open tickets in the current repository.** With an argument, process only that ticket. An ID means the forge's issue/ticket identifier, not a branch, session, or PR ID.

 ## Compose before acting

@@ -1,5 +1,5 @@
 interface:
-  display_name: "Development Workflow"
+  display_name: "Implementation Orchestrator"
  short_description: "Implements ready-for-agent tracker tickets through isolated worktrees"
 policy:
  allow_implicit_invocation: false
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../.." && pwd)"
+skill="$root/skills/engineering/implementation-orchestrator/SKILL.md"
+shared_skill="$root/skills/engineering/forge-cli/SKILL.md"
+recipes=(
+	"$root/skills/engineering/forge-cli/references/tea.md"
+	"$root/skills/engineering/forge-cli/references/gh.md"
+	"$root/skills/engineering/forge-cli/references/glab.md"
+)
+
+[[ -f "$skill" && -f "$shared_skill" && -f "${recipes[0]}" && -f "${recipes[1]}" && -f "${recipes[2]}" ]] || {
+	echo 'Missing skill or reference file' >&2
+	exit 1
+}
+head -1 "$skill" | grep -qx -- '---'
+grep -q '^name: implementation-orchestrator$' "$skill"
+grep -q '^description: ' "$skill"
+head -1 "$shared_skill" | grep -qx -- '---'
+grep -q '^name: forge-cli$' "$shared_skill"
+grep -q '^description: ' "$shared_skill"
+node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))' "$root/package.json"
+bash -n "$root/skills/engineering/forge-cli/scripts/detect-forge.sh"
+
+printf '%s\n' 'implementation-orchestrator skill is valid'
@@ -0,0 +1,8 @@
+# Personal Skills
+
+Skills tied to the user's own setup and not promoted as general-purpose workflows.
+
+## User-invoked
+
+- [arch-maintenance](arch-maintenance/SKILL.md) — Keep an Arch/CachyOS system updated and healthy with status, check, and update workflows.
+- [arch-troubleshooting](arch-troubleshooting/SKILL.md) — Diagnose and repair Arch/CachyOS system problems.
@@ -0,0 +1,50 @@
+---
+name: arch-maintenance
+description: Keep an Arch or CachyOS system updated and healthy with status, check, and update workflows.
+disable-model-invocation: true
+---
+
+# Arch Maintenance
+
+User-invoked only. Local machine. For diagnosing and fixing a broken system, use the `arch-troubleshooting` skill instead.
+
+## First move
+
+1. Read `../arch/references/safety.md` for distro detection, the safety contract, and redaction rules.
+2. Resolve `DOTFILES_ROOT` as described there.
+3. Run `bash ../arch/scripts/inspect-system.sh "$DOTFILES_ROOT"` for the read-only baseline.
+
+## Modes
+
+- `status` — baseline health report.
+- `check` — run `bash ../arch/scripts/check-system.sh "$DOTFILES_ROOT"`; report available updates, cache size, orphans, reboot need, and `.pacnew` files. No mutation.
+- `update` — full official update, then separately approved AUR and mise reconciliation.
+- `report` — save a redacted detailed report. Create `$HOME/.local/state/arch-system-management/reports/` and write `$(date +%Y-%m-%dT%H%M%S).md`.
+
+If the request is ambiguous, run `status` and ask which mode is wanted.
+
+## Update workflow
+
+1. Run the baseline, `check-system.sh`, and the pacman-lock checks from `../arch/references/safety.md`.
+2. Present the official update plan — exact command `sudo pacman -Syu`, affected scope, rollback, post-check — and obtain approval.
+3. Run `sudo pacman -Syu`; require exit 0.
+4. Verify: `pacman -Qkk` and a `find /etc -name '*.pacnew' -o -name '*.pacsave'` scan. Report `.pacnew` files for manual merge; never merge them automatically.
+5. Separately present AUR changes (`paru -Qua`); if approved, run `paru -Sua` (AUR only — the official update already ran) and verify.
+6. Separately present mise reconciliation; if approved, run `mise install` from `$DOTFILES_ROOT` and verify.
+7. Offer approved mise tasks individually; never run all tasks as a bundle.
+8. Check reboot need and failed units with `check-system.sh`.
+9. Append `timestamp, command, result, verification` to `$HOME/.local/state/arch-system-management/mutations.log` (no secrets).
+
+Declare success only after the post-checks pass. A reboot is a recommendation, never an implicit action.
+
+## Mise and dotfiles
+
+Read `../arch/references/mise.md` when the request concerns mise, dotfiles, or development tools.
+
+## Output
+
+1. detected system
+2. findings
+3. proposed next action
+4. approval needed, if any
+5. verification result
@@ -0,0 +1,41 @@
+---
+name: arch-troubleshooting
+description: Diagnose and repair Arch or CachyOS system problems.
+disable-model-invocation: true
+---
+
+# Arch Troubleshooting
+
+User-invoked only. Local machine. For routine maintenance and updates, use the `arch-maintenance` skill instead.
+
+## First move
+
+1. Read `../arch/references/safety.md` for distro detection, the safety contract, and redaction rules.
+2. Resolve `DOTFILES_ROOT` as described there.
+3. Run `bash ../arch/scripts/inspect-system.sh "$DOTFILES_ROOT"` for the read-only baseline before investigating.
+
+## Discipline
+
+Observe → rank causes → gather targeted evidence → propose → verify. Show ranked causes before testing any of them; proceed with the ranking if the user is away.
+
+- `diagnose <target>` — baseline plus targeted checks for `boot`, `packages`, `kernel`, `graphics`, `audio`, `network`, `storage`, or `services`.
+- `repair <target>` — propose a repair for package recovery, failed systemd units, initramfs regeneration, boot configuration, or network restart; apply only after approval and the safety contract.
+
+## Targeted evidence
+
+- boot/service: `journalctl -b` and `journalctl -b -1` for the relevant unit; `systemctl status <unit>`.
+- packages: transaction errors, lock ownership, sync state; never partial upgrades.
+- kernel: running vs installed kernel, initramfs presence, bootloader config.
+- graphics/audio/network: identify the active device, driver, service, and recent relevant journal entries before suggesting any change.
+
+## Repairs
+
+Each repair must state: observation, ranked cause, evidence, proposed change, reversibility, verification. Repairs are limited to reversible, scoped actions. After each approved repair, run its targeted verification and stop if it fails.
+
+## Output
+
+1. observation
+2. ranked causes with evidence
+3. proposed change
+4. approval needed
+5. verification result
@@ -0,0 +1,35 @@
+# Mise integration
+
+This machine uses mise for dotfile management and development tools.
+
+## Sources of truth
+
+- `$DOTFILES_ROOT/mise.toml` — dotfiles, bootstrap packages, setup tasks.
+- `$DOTFILES_ROOT/config/mise/config.toml` — mise tools and tasks.
+- `$DOTFILES_ROOT/packages/sjb-dev.packages` — pacman development packages.
+
+Prefer the configured owner: a tool in mise `[tools]` is reconciled with `mise install`; a package in `sjb-dev.packages` is checked with pacman. Duplicate installations are reported, never removed.
+
+## Read-only commands
+
+Run from the dotfiles root after verifying it contains `mise.toml`:
+
+```bash
+mise ls          # installed tools
+mise outdated    # tools behind their declared version
+mise tasks       # list tasks
+```
+
+## Mutations (approval required)
+
+```bash
+mise install     # reconcile declared tools — network + installs
+mise run <task>  # runs project tasks — may install plugins, edit config, enable services
+mise trust       # approve a config's executable settings — approve once, explicitly
+```
+
+Never run all tasks as a bundle; each needs its own approval. Never trust an arbitrary discovered project automatically.
+
+## Shell activation
+
+Bash and Fish configuration activate mise. When a mise-managed command is missing, check shell activation and `mise ls` before installing another copy.
@@ -0,0 +1,53 @@
+# Safety contract
+
+Shared by the arch-maintenance and arch-troubleshooting skills.
+
+## Distro detection
+
+Read `/etc/os-release`; use `ID` and `ID_LIKE`. Support Arch and CachyOS. On any other distro, stay read-only. Confirm `pacman` is available before any package operation.
+
+## DOTFILES_ROOT
+
+Set `DOTFILES_ROOT` to `$DOTFILES_ROOT` when it points to a directory containing `mise.toml`; otherwise `$HOME/.local/share/dotfiles` when it contains `mise.toml`. If neither, report it and treat mise checks as unavailable.
+
+## Read first, mutate second
+
+Before every mutation show: the exact command, affected scope, risk, rollback/recovery option, and the post-check. Wait for explicit approval.
+
+## Privilege
+
+Run as the normal user; use `sudo` only for the individual privileged command. Never store passwords or edit sudo policy.
+
+## Forbidden
+
+- `pacman -Sy` standalone (partial upgrade) — full updates are `sudo pacman -Syu` only
+- `--noconfirm`, `--force`, `--overwrite`, `-Rdd`
+- deleting `/var/lib/pacman/db.lck` without diagnosing
+- disk formatting, partitioning, filesystem repair, kernel removal, firewall/security disablement, destructive deletion
+
+## Pacman lock
+
+If `/var/lib/pacman/db.lck` exists or `pacman` errors with "unable to lock database":
+
+1. `pgrep -a pacman` and `pgrep -a paru` — is a package process active? If yes, wait for it; never kill it or delete the lock.
+2. If no process is active, the lock is stale. Report it and ask before removing it.
+
+## Config edits
+
+Create a backup, show a diff, get approval, then verify the result.
+
+## Backups
+
+Before risky work, detect snapshots/backups and warn when none exist. Do not create backup infrastructure automatically.
+
+## Failure
+
+If a mutation fails, stop mutations, preserve evidence, run only independent read-only checks, and report the exact failed command.
+
+## Verification
+
+Every mutation ends with the smallest check that fails if the change broke: exit code, then `pacman -Qkk` for package integrity, and a `find /etc -name '*.pacnew' -o -name '*.pacsave'` scan after upgrades. Report `.pacnew`/`.pacsave` files for manual merge; never merge them automatically.
+
+## Redaction
+
+Redact identity (usernames, hostnames), network identifiers (IP/MAC), storage serials/UUIDs, credentials, and environment values. Device paths and package/service names stay — they are diagnostic evidence.
@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+set -u
+
+section() {
+	printf '\n[%s]\n' "$1"
+}
+
+section "updates"
+if command -v checkupdates >/dev/null 2>&1; then
+	printf 'official_updates=%s\n' "$(checkupdates 2>/dev/null | wc -l)"
+else
+	printf 'checkupdates=unavailable (do not substitute pacman -Sy)\n'
+fi
+if command -v paru >/dev/null 2>&1; then
+	printf 'aur_updates=%s\n' "$(paru -Qua 2>/dev/null | wc -l)"
+else
+	printf 'paru=unavailable\n'
+fi
+
+section "cache"
+if [[ -d /var/cache/pacman/pkg ]]; then
+	du -sh /var/cache/pacman/pkg 2>/dev/null
+else
+	printf 'cache=unavailable\n'
+fi
+
+section "reboot-needed"
+# Compare the running kernel against its own installed package, not the newest
+# kernel in /usr/lib/modules (a fallback kernel can be newer without being booted).
+running="$(uname -r)"
+pkg=""
+for p in linux-cachyos linux-lts linux-zen linux; do
+	if pacman -Q "$p" >/dev/null 2>&1; then
+		pkg="$p"
+		break
+	fi
+done
+if [[ -n "$pkg" ]]; then
+	installed="$(pacman -Q "$pkg" | awk '{print $2}')"
+	# cachyos/lts/zen place the flavor after pkgrel: "7.2.5-1-cachyos" vs "7.2.5-1"
+	if [[ "$running" == "$installed"* ]]; then
+		printf 'reboot=not-needed (running=%s, %s=%s)\n' "$running" "$pkg" "$installed"
+	else
+		printf 'reboot=recommended (running=%s, %s=%s)\n' "$running" "$pkg" "$installed"
+	fi
+else
+	printf 'reboot=unknown\n'
+fi
+
+section "pacnew"
+found="$(find /etc -name '*.pacnew' -o -name '*.pacsave' 2>/dev/null || true)"
+if [[ -n "$found" ]]; then
+	printf '%s\n' "$found"
+else
+	printf 'pacnew=none\n'
+fi
+
+section "orphans"
+if command -v pacman >/dev/null 2>&1; then
+	printf 'orphan_candidates=%s\n' "$(pacman -Qdtq 2>/dev/null | wc -l)"
+fi
+
+section "failed-units"
+if command -v systemctl >/dev/null 2>&1; then
+	systemctl --failed --no-legend --plain 2>/dev/null || true
+fi
@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+set -u
+
+DOTFILES_ROOT="${1:-${DOTFILES_ROOT:-$HOME/.local/share/dotfiles}}"
+
+section() {
+	printf '\n[%s]\n' "$1"
+}
+
+section "system"
+if [[ -r /etc/os-release ]]; then
+	# shellcheck disable=SC1091
+	. /etc/os-release
+	printf 'name=%s\nid=%s\nid_like=%s\n' "${NAME:-unknown}" "${ID:-unknown}" "${ID_LIKE:-unknown}"
+else
+	printf 'os_release=unavailable\n'
+fi
+printf 'kernel=%s\narch=%s\n' "$(uname -r)" "$(uname -m)"
+
+section "package-manager"
+if command -v pacman >/dev/null 2>&1; then
+	printf 'pacman=%s\ninstalled_packages=%s\n' "$(command -v pacman)" "$(pacman -Qq 2>/dev/null | wc -l)"
+	orphans="$(pacman -Qdtq 2>/dev/null || true)"
+	if [[ -n "$orphans" ]]; then
+		printf 'orphan_candidates=%s\n' "$(printf '%s\n' "$orphans" | wc -l)"
+	else
+		printf 'orphan_candidates=0\n'
+	fi
+else
+	printf 'pacman=unavailable\n'
+fi
+
+section "services"
+if command -v systemctl >/dev/null 2>&1; then
+	failed="$(systemctl --failed --no-legend --plain 2>/dev/null || true)"
+	if [[ -n "$failed" ]]; then
+		printf '%s\n' "$failed"
+	else
+		printf 'failed_units=none\n'
+	fi
+else
+	printf 'systemctl=unavailable\n'
+fi
+
+section "storage"
+if command -v df >/dev/null 2>&1; then
+	df -hP / 2>/dev/null | tail -n 1
+else
+	printf 'df=unavailable\n'
+fi
+
+section "dotfiles-and-mise"
+if [[ -d "$DOTFILES_ROOT" && -f "$DOTFILES_ROOT/mise.toml" ]]; then
+	printf 'dotfiles_root=%s\n' "$DOTFILES_ROOT"
+	[[ -f "$DOTFILES_ROOT/config/mise/config.toml" ]] && printf 'mise_config=present\n' || printf 'mise_config=missing\n'
+	[[ -f "$DOTFILES_ROOT/packages/sjb-dev.packages" ]] && printf 'dev_packages=present\n' || printf 'dev_packages=missing\n'
+	if command -v mise >/dev/null 2>&1; then
+		printf 'mise=%s\n' "$(command -v mise)"
+		tools="$(cd "$DOTFILES_ROOT" && mise ls 2>/dev/null || true)"
+		if [[ -n "$tools" ]]; then
+			printf 'mise_installed_tools=%s\n' "$(printf '%s\n' "$tools" | grep -c .)"
+		else
+			printf 'mise_ls=failed\n'
+		fi
+	else
+		printf 'mise=unavailable\n'
+	fi
+else
+	printf 'dotfiles_root=not-found\n'
+fi
+
+section "optional-tools"
+for tool in paru checkupdates smartctl lsblk; do
+	if command -v "$tool" >/dev/null 2>&1; then
+		printf '%s=present\n' "$tool"
+	else
+		printf '%s=missing\n' "$tool"
+	fi
+done