feat(skills): add afk-sleep-work skill for autonomous unattended execution

README.md

@@ -10,6 +10,7 @@ A collection of public, reusable agent skills, cheatsheets, and operational work
 | :--- | :--- |
 | **[`coding-dev.md`](skills-public/coding-dev.md)** | Standing rules for all code work: maximum linter/compiler strictness, never filtering build output, reuse-before-reinvent dependency ordering, file/function size limits, test & regression discipline, verification gates, scope control, commit hygiene, and honest reporting. |
 | **[`cli-tooling.md`](skills-public/cli-tooling.md)** | Using command-line tools correctly: reading the help tree instead of guessing flags, preferring an existing CLI over an ad-hoc script, non-interactive invocation, machine-readable output formats, orienting on prior work before starting, script placement & symlinking, and care around destructive commands. |
+| **[`afk-sleep-work.md`](skills-public/afk-sleep-work.md)** | Operating unattended and autonomously: continuous forward momentum, avoiding polling traps and deadlocks, host preservation and resource budgeting (disk, packages, processes), isolated tool provisioning, avoiding "last breath" traps on token/quota exhaustion, bypassing or driving GUI launchers, and wake-up checkpoints. |
 
 ### 🔤 Per-Language Rules ([`code-languages/`](skills-public/code-languages/))
 

afk-sleep-work.md

@@ -0,0 +1,296 @@
+---
+name: afk-sleep-work
+description: >-
+  Use this skill when the user indicates they will be away, AFK, or sleeping, grants broad autonomous
+  execution authority, asks the agent to work continuously until tokens or objectives are exhausted,
+  or delegates multi-phase tasks requiring unattended orchestration, safe tool provisioning, avoiding
+  polling traps, respecting token/subscription margins (the "last breath" rule), and bypassing or driving GUI launchers.
+---
+
+# Unattended & Autonomous Execution (AFK / Sleep Work)
+
+How to operate safely, productively, and continuously when the user steps away and delegates
+broad execution authority to the agent.
+
+When a user says they will be AFK or going to sleep, they are relinquishing the interactive
+feedback loop. Every decision, recovery, tool installation, and verification gate must be
+orchestrated autonomously until the goal is achieved or budget limits are reached.
+
+---
+
+## 1. The Autonomous Execution Contract
+
+When working unattended, the agent assumes full responsibility for forward momentum and system
+preservation. Three primary rules govern this mode:
+
+1. **Keep Moving Forward:** Do not stop to ask clarifying questions about minor ambiguities or
+   blockers that can be resolved through investigation, trial hypotheses, or alternative strategies.
+2. **First, Do No Harm:** Broad authority is **not** permission to degrade the host, saturate
+   resources, clobber system packages, or risk data loss.
+3. **Leave a Transparent Audit Trail:** When the user returns, they must be able to inspect an
+   orderly checkpoint detailing what was done, what succeeded, what failed, and where state currently sits.
+
+---
+
+## 2. Trap Avoidance: Loops, Timeouts & Interactive Prompts
+
+The most common failure mode during unattended execution is getting wedged in a blocking state,
+consuming time or tokens without making progress.
+
+### Never write polling wait loops
+
+> [!CAUTION]
+> **Strictly forbidden:** Never run `while`, `until`, or sleep polling loops in shell commands
+> (see [`code-languages/bash.md` §3](skills-public/code-languages/bash.md)).
+> An unattended loop that never satisfies its exit condition hangs the session indefinitely.
+
+- **Use built-in blocking or notification mechanisms:** Prefer CLI flags like `--wait`,
+  `--no-detach`, or dedicated background task status notifications over manual polling.
+- **Enforce hard timeouts:** Every long-running, external, or uncertain command must be wrapped
+  in a timeout:
+  ```bash
+  timeout 300s my-command --batch
+  ```
+  If a process exceeds its expected runtime, terminate it, record the timeout, and inspect logs.
+
+### Non-interactive flags are mandatory
+
+Commands that pause for user confirmation (`[y/N]`) will stall indefinitely when the user is away:
+
+- Always supply non-interactive switches: `-y`, `--yes`, `--non-interactive`, `--batch`,
+  `--headless`, or environment flags like `CI=1` and `DEBIAN_FRONTEND=noninteractive`.
+- Consult [`cli-tooling.md` §2](skills-public/cli-tooling.md) before invoking unfamiliar tools to ensure
+  targets and arguments are explicitly declared rather than prompted.
+
+### Bounded retries with hypothesis variation
+
+If an automated build, test, or patch fails:
+- **Do not retry the exact same failing command** hoping for a different outcome.
+- Limit automated retries on any single problem to a fixed ceiling (e.g. 3 attempts).
+- Each retry **must test a distinct hypothesis** (different compiler flag, altered configuration,
+  corrected dependency path, or alternative implementation strategy).
+- If 3 successive attempts fail, abandon that branch, record the detailed diagnostic log, and
+  pivot to an alternative route or proceed to the next independent task.
+
+---
+
+## 3. Host Safety & Resource Budgets ("Do No Harm")
+
+Unattended access requires strict operational discipline to ensure the machine remains stable,
+responsive, and intact.
+
+### Storage & disk preservation
+
+Running out of disk space can corrupt databases, break desktop sessions, and crash background daemons.
+
+- **Check free space first:** Run `df -h <target_path>` before downloading large archives,
+  compiling large codebases, or unpacking toolchains.
+- **Never saturate drives:** Ensure at least 15–20% of disk space remains free on the root and
+  working filesystems.
+- **Clean intermediate artifacts:** Delete downloaded archive files (`.tar.gz`, `.zip`, `.iso`),
+  temporary unpack directories, and oversized intermediate build caches once installation or
+  verification is complete.
+- **Log rotation and dump bounds:** Prevent automated runs from generating unbounded log files or
+  gigabyte-scale core dumps.
+
+### OS and system package integrity
+
+- **Never mutate or override host system packages:** Do not execute blanket system package manager
+  upgrades or installs (`sudo dnf install`, `sudo apt-get upgrade`, `pacman -Syu`) that replace
+  host libraries, alter desktop drivers, or conflict with system-level package trees.
+- **Isolate in containers or user space:**
+  - Prefer dedicated build containers, chroots, or isolated environments (such as
+    [`distrobox-buildbox-dev.md`](skills-private/distrobox-buildbox-dev.md), Docker, or Podman) for
+    compilers, toolchains, and experimental packages.
+  - For user-level binaries, install into user-scoped paths (`~/.local/bin/`, `~/.local/share/`,
+    or project-local virtual environments).
+  - Never run arbitrary third-party build scripts with elevated root privileges unless explicitly
+    demanded by the architecture and verified safe.
+
+### Process and lifecycle safety
+
+- **Strictly prohibited operations:**
+  - Never invoke `shutdown`, `reboot`, `systemctl poweroff`, or `init 0/6`.
+  - Never kill the host desktop session, display server (`wayland`, `xorg`), or user window manager.
+  - Never issue broad `pkill` or `killall` commands with generic names (e.g. `pkill python` or
+    `killall node`) that might terminate the agent itself, IDE sidecars, or unrelated user processes.
+  - Always target specific PIDs or match full command lines (`pkill -f ...`).
+
+### CPU, memory, and bandwidth etiquette
+
+- **Do not saturate all CPU cores:** When invoking multi-threaded builds (`make`, `ninja`, `cargo`),
+  cap jobs to `$(nproc --ignore=2)` or use `nice -n 10` to avoid starving interactive desktop
+  responsiveness or audio subsystems.
+- **Monitor memory footprints:** For heavy memory operations (e.g. large reverse engineering suites,
+  AST parsing, heavy link steps), monitor RAM with `free -m` and kill runaway tasks before triggering
+  the kernel OOM killer.
+
+---
+
+## 4. Tool & Dependency Provisioning in Isolation
+
+Autonomous work often demands tools not yet present on the system (e.g. decompilers, disassemblers,
+symbol analyzers, cross-compilers, or profiling utilities).
+
+### Check existence before fetching
+
+Always verify if a tool or functional equivalent is already available in `$PATH`, in an existing
+container, or in user directories before attempting to download:
+
+```bash
+command -v <tool> || which <tool>
+```
+
+### Preferred provisioning hierarchy
+
+When a missing utility or dependency is required:
+
+1. **Local Project / Toolchains:** Look for existing scripts or submodule toolchains inside the repo.
+2. **Isolated Build Containers:** Run or install the tool within a development container or
+   Distrobox instance, keeping the host clean.
+3. **Self-Contained User-Space Binaries:** Download official prebuilt standalone binaries, AppImages,
+   or portable zip releases into `~/.local/bin/` or a project scratch folder.
+4. **Isolated Package Managers:** Use language-specific or user-space package managers (`cargo install`,
+   `pip install --user`, `npm install --no-save`, `go install`) scoped to non-root directories.
+
+### Headless & scriptable mode over GUI
+
+When using heavyweight tools that typically feature GUIs (such as Ghidra, IDA, Wireshark, or
+debuggers):
+
+- **Always prioritize headless/CLI mode:** Use headless batch scripts, CLI entrypoints, or
+  Python/Java/Lua automation APIs rather than starting graphical interfaces.
+  - *Example (Ghidra):* Run `analyzeHeadless <project_dir> <project_name> -import <binary> -postScript <script.py>`
+    rather than launching the Swing GUI.
+  - *Example (Network/Packets):* Use `tshark` or `tcpdump` instead of launching GUI Wireshark.
+  - *Example (Debugging):* Run `gdb -batch -ex ...` or `lldb --batch -o ...`.
+
+---
+
+## 5. Launchers & GUI Automation: Bypassing vs. Driving
+
+Complex applications, game engines, and test suites often wrap their executables behind splash
+launchers, web views, or login modals. When running unattended, handle them systematically.
+
+```
+┌────────────────────────────────────────────────────────┐
+│ 1. Direct Executable Bypass (Preferred)                │
+│    Inspect process args, run child binary directly     │
+└───────────────────────────┬────────────────────────────┘
+                            │ (if blocked by DRM / IPC)
+┌───────────────────────────▼────────────────────────────┐
+│ 2. Command-Line Arguments & Flags                      │
+│    Search for -nosplash, -nolauncher, --skip-intro     │
+└───────────────────────────┬────────────────────────────┘
+                            │ (if GUI invocation mandatory)
+┌───────────────────────────▼────────────────────────────┐
+│ 3. Autonomous GUI Driving                              │
+│    Locate window, simulate inputs, verify state change │
+└────────────────────────────────────────────────────────┘
+```
+
+### Hierarchy of execution
+
+1. **Direct Executable Bypass (Highest Priority):**
+   Launchers are usually thin wrappers around the real core engine or binary.
+   - Run the launcher once or inspect its script / configuration files to identify the real child
+     binary and its working directory.
+   - Inspect active processes (`ps aux | grep -i <app>` or `wmic process` under Wine/Windows) to
+     extract the exact command line and parameters passed from the launcher to the target process.
+   - Execute the target binary directly with those extracted parameters, bypassing the launcher UI
+     completely.
+
+2. **Command-Line & Config Flags:**
+   If the launcher must be invoked, look for flags that suppress interactive prompts:
+   - Common bypass switches: `-nosplash`, `-nolauncher`, `-autostart`, `-batch`, `-silent`, `--skip-login`.
+   - Configuration files: Check configuration `.ini`, `.json`, or `.xml` files to toggle
+     `SkipLauncher=true` or set auto-connect / auto-load options.
+
+3. **Driving the GUI (Fallback):**
+   If the launcher cannot be bypassed and requires a click or keyboard event to proceed:
+   - Identify the window using available window management or GUI automation tools
+     (e.g. `xdotool`, `ydotool`, or desktop MCP tools).
+   - Capture a screenshot or window dump to verify geometry and interactive button states.
+   - Dispatch the required input sequence (e.g. Enter, Space, or target coordinate click).
+   - **Immediately verify state transition:** Confirm the launcher window closes or the child
+     process spawns. Never assume input succeeded without checking process lists or window titles.
+   - Protect with a hard timeout so that an unexpected modal dialog does not block execution forever.
+
+---
+
+## 6. Token & Subscription Exhaustion (The "Last Breath" Rule)
+
+In unattended sessions, the execution lifecycle is bounded by context window size, agent token
+budgets, subscription quotas, or harness timeouts. How the session winds down determines whether
+the run is a success or leaves a broken system.
+
+### Watch for approaching limits
+
+Track execution consumption and context density where possible:
+- If context length grows high or the harness signals approaching token/turn caps, prioritize
+  winding down over starting new initiatives.
+- If rate limits, credit caps, or subscription tier resets are anticipated, prepare state so that
+  execution can pause cleanly and recover without corruption.
+
+### Never start fragile tasks in your "last breath"
+
+> [!CAUTION]
+> **The "Last Breath" Trap:** Never initiate an open-ended, non-atomic, or high-risk mutating
+> operation when token budget, context window, or subscription quota are nearly exhausted.
+
+Rushing into a complex task with only a few turns or tokens remaining guarantees failure. If the
+harness cuts execution off mid-flight — or freezes the agent until quota resets hours later —
+unfinished work leaves the environment in a broken, unusable state:
+- **Corrupted source trees:** Half-applied multi-file refactors that leave syntax errors and broken builds.
+- **Dangling locks:** Incomplete package installs holding `/var/lib/dpkg/lock`, active git index
+  locks (`.git/index.lock`), or held database transactions.
+- **Uncommitted state:** Unfinished rebases, stashes, or uncommitted modifications that confuse
+  subsequent runs or the user.
+- **Zombie processes:** Orphaned background build daemons, open sockets, or runaway test loops
+  consuming host memory.
+
+### The Controlled Landing protocol
+
+When budget, tokens, or turns drop below a comfortable margin (or when an operation cannot be
+guaranteed to finish and verify within the remaining budget):
+
+1. **Stop scope expansion:** Refuse new goals, refactors, or dependency upgrades.
+2. **Finish or roll back atomic units:** Complete the immediate atomic file edit or roll it back
+   cleanly (`git checkout -- <file>`) so the repository remains in a compiling, testable state.
+3. **Terminate ephemeral processes:** Kill all background test runners, scratch servers, and
+   temporary debuggers.
+4. **Run verification gates:** Confirm `git status` is clean or staged cleanly, and the build passes.
+5. **Commit atomic progress:** Commit completed, verified units with conventional commit messages so
+   progress is never lost if the session terminates abruptly.
+6. **Write the recovery checkpoint:** Explicitly document the exact resume instructions, active
+   hypotheses, and next planned action in the status artifact so either the user or the next agent
+   turn can resume seamlessly.
+
+---
+
+## 7. Checkpointing & The "Wake-Up" Audit Trail
+
+Because the user is not present to monitor intermediate chatter, keep a consolidated record of
+progress.
+
+### Write a live status checkpoint
+
+Maintain a dedicated status file (e.g. `PROGRESS.md`, `AFK_WORK_LOG.md`, or a persistent artifact)
+updated after every major milestone. The document should contain:
+
+| Section | Contents |
+| :--- | :--- |
+| **Objective** | The original task and current operational phase. |
+| **Completed Work** | Bulleted list of concrete accomplishments (code written, tests passing, tools configured). |
+| **Current State** | Active branch, git commit hash, build status, running daemons or services. |
+| **Findings & Discoveries** | Key technical observations, reversed structs, discovered bugs, or API quirks. |
+| **Obstacles & Fallbacks** | Blockers encountered, strategies that failed (with brief reasons), and how the agent pivoted. |
+| **Harness / Budget State** | Token/quota state, whether work halted due to task completion or approaching budget limits. |
+| **Immediate Next Steps** | Exact command line or file target where the next session should pick up. |
+
+### Clean exit on budget exhaustion
+
+When tokens, context, or scheduled runtime run out:
+- Ensure the controlled landing steps above have been executed.
+- Output a concise, unambiguous final summary pointing directly to the written checkpoint so the
+  user has immediate clarity upon waking up or returning.