SpillwaveSolutions · RichardHightower · Mar 11, 2026
diff --git a/skills/agcron/managing-daemon/SKILL.md b/skills/agcron/managing-daemon/SKILL.md
@@ -0,0 +1,215 @@
+---
+name: managing-daemon
+description: >
+  Start, stop, and check the status of the agent-cron daemon.
+  Use when you need to manage the daemon lifecycle, check if
+  the daemon is running, or troubleshoot daemon startup issues.
+---
+
+# Managing the Agent Cron Daemon
+
+This skill instructs you, the AI agent, on how to help a user start, stop, and
+check the status of the agent-cron daemon. Follow each section as written.
+Always show raw CLI output first, then provide your conversational interpretation.
+
+## Before You Start
+
+Run the following command to confirm the `agcron` binary is installed:
+
+```bash
+which agcron
+```
+
+If the command prints a path (e.g., `/usr/local/bin/agcron`), the binary is
+available. Proceed to the section the user needs.
+
+If the command prints nothing or returns "not found", tell the user:
+
+> The `agcron` binary is not on your PATH. You need to install it first.
+> I can help you with that using the **installing-agcron** skill.
+
+Do not continue with any daemon operations until the binary is confirmed present.
+
+## Starting the Daemon
+
+**Requirements:** DAEM-01 (start), DAEM-04 (double-start prevention)
+
+### Step 1 — Check whether the daemon is already running
+
+Run:
+
+```bash
+agcron status
+```
+
+Show the complete output to the user.
+
+**If the output contains "Status: running":**
+
+Tell the user the daemon is already running. Extract the PID and uptime from the
+output and present them conversationally. For example:
+
+> The daemon is already running (PID 48201, uptime 3h 12m). No action needed.
+
+Do NOT attempt to start the daemon again. Ask if the user wants to do something
+else instead (check status details, stop, etc.).
+
+**If the output contains "Error: Daemon is not running" (exit code 69):**
+
+Proceed to Step 2.
+
+### Step 2 — Start the daemon
+
+Run:
+
+```bash
+agcron daemon -d
+```
+
+Show the complete output to the user.
+
+**Expected success output:** `Daemon started (backgrounded)`
+
+**If the output says "Daemon already running (PID N)":** This means a race
+condition occurred between your status check and start attempt. Tell the user the
+daemon is already running with that PID. Do not retry.
+
+### Step 3 — Verify the daemon started
+
+Run:
+
+```bash
+agcron status
+```
+
+Show the complete output to the user. Confirm the daemon is running by checking
+for "Status: running" in the output. Summarize the key fields:
+
+> The daemon started successfully. It is running as PID 48201 with N jobs loaded.
+> The next scheduled run is at HH:MM.
+
+If the status still shows the daemon is not running, tell the user the start
+failed and direct them to the Troubleshooting section.
+
+## Stopping the Daemon
+
+**Requirement:** DAEM-02
+
+### Step 1 — Check whether the daemon is running
+
+Run:
+
+```bash
+agcron status
+```
+
+Show the complete output to the user.
+
+If the output contains "Error: Daemon is not running", tell the user:
+
+> The daemon is not currently running, so there is nothing to stop.
+
+Do not attempt to stop it. Ask if they want to start it instead.
+
+### Step 2 — Stop the daemon
+
+If the daemon is running, run:
+
+```bash
+agcron stop
+```
+
+Show the complete output to the user.
+
+**Expected output sequence:**
+
+1. `Stopping daemon...` — the daemon received the shutdown signal.
+2. `Daemon stopped` — clean shutdown completed.
+
+**If the output contains "Warning: daemon may still be draining":** Tell the
+user that in-flight jobs are still completing. The daemon will exit once all
+running jobs finish or the shutdown timeout (default 30 seconds) is reached.
+Suggest waiting a moment and then checking status:
+
+```bash
+agcron status
+```
+
+### Step 3 — Confirm shutdown
+
+Run:
+
+```bash
+agcron status
+```
+
+Show the complete output to the user. Confirm that the daemon is no longer
+running:
+
+> The daemon has been stopped successfully.
+
+If it is still running, it may be draining in-flight jobs. Tell the user to wait
+and check again, or refer to the Troubleshooting section.
+
+## Checking Status
+
+**Requirement:** DAEM-03
+
+Run:
+
+```bash
+agcron status
+```
+
+Show the complete raw output to the user first. Then interpret the fields.
+
+### When the daemon is running
+
+The output includes these fields:
+
+| Field              | Meaning                                        |
+| ------------------ | ---------------------------------------------- |
+| Status             | `running` — daemon is active                   |
+| PID                | Process ID of the daemon                       |
+| Uptime             | How long the daemon has been running            |
+| Loaded Jobs        | Number of cron job definitions currently loaded |
+| Queue Depth        | Number of jobs waiting to execute               |
+| Next Scheduled Run | When the next job will fire                     |
+| Memory             | Current memory usage of the daemon process      |
+
+Provide a conversational summary. For example:
+
+> The daemon is healthy and running as PID 48201 (uptime 3h 12m). It has 5 jobs
+> loaded with none queued. The next scheduled run is at 14:30 UTC. Memory usage
+> is 12 MB.
+
+If queue depth is high relative to loaded jobs, note this:
+
+> Queue depth is 8 with only 3 jobs loaded. This may indicate jobs are backing
+> up. Check concurrency settings or job execution times.
+
+### When the daemon is not running
+
+The output will contain "Error: Daemon is not running" and the exit code will be
+69. Tell the user:
+
+> The daemon is not running. Would you like me to start it?
+
+## Troubleshooting
+
+If you encounter errors during any daemon operation, consult the troubleshooting
+guide for diagnosis and resolution steps:
+
+See [references/troubleshooting.md](references/troubleshooting.md)
+
+Common issues include permission errors on the socket file, stale socket files
+blocking startup, config parse errors, and daemons that hang during shutdown.
+The troubleshooting guide provides the exact error messages and fix steps for
+each case.
+
+## Reference Materials
+
+For the complete CLI command reference including all flags, environment
+variables, and expected outputs, see:
+
+[references/cli-commands.md](references/cli-commands.md)
diff --git a/skills/agcron/managing-daemon/references/cli-commands.md b/skills/agcron/managing-daemon/references/cli-commands.md
@@ -0,0 +1,150 @@
+# Agent Cron Daemon CLI Command Reference
+
+## agcron daemon -d
+
+Start the daemon in background (detached) mode.
+
+**Usage:**
+
+```bash
+agcron daemon -d
+```
+
+**Success output:**
+
+```
+Daemon started (backgrounded)
+```
+
+**Already running output:**
+
+```
+Daemon already running (PID 48201)
+```
+
+The daemon writes its PID to the configured PID file and opens a Unix domain
+socket for CLI communication.
+
+## agcron daemon
+
+Start the daemon in foreground mode. This is primarily useful during development
+or debugging, as log output goes directly to the terminal.
+
+**Usage:**
+
+```bash
+agcron daemon
+```
+
+The daemon runs in the foreground until interrupted. Press `Ctrl+C` to trigger a
+graceful shutdown (equivalent to `agcron stop`).
+
+## agcron status
+
+Show the current daemon status.
+
+**Usage:**
+
+```bash
+agcron status
+```
+
+**When running — output fields:**
+
+```
+Status: running
+PID: 48201
+Uptime: 3h 12m
+Loaded Jobs: 5
+Queue Depth: 0
+Next Scheduled Run: 2026-03-10 14:30:00 UTC
+Memory: 12 MB
+```
+
+| Field              | Description                                         |
+| ------------------ | --------------------------------------------------- |
+| Status             | `running` when the daemon is active                 |
+| PID                | Operating system process ID                         |
+| Uptime             | Duration since the daemon started                   |
+| Loaded Jobs        | Count of parsed cron job definitions from `.cron/jobs/` |
+| Queue Depth        | Number of jobs currently waiting to execute          |
+| Next Scheduled Run | Timestamp of the next job scheduled to fire          |
+| Memory             | Resident memory usage of the daemon process          |
+
+**When not running:**
+
+```
+Error: Daemon is not running
+```
+
+Exit code: `69` (EX_UNAVAILABLE).
+
+## agcron stop
+
+Gracefully shut down a running daemon.
+
+**Usage:**
+
+```bash
+agcron stop
+```
+
+**Output sequence:**
+
+```
+Stopping daemon...
+Daemon stopped
+```
+
+The stop command sends a shutdown signal via the Unix domain socket. The daemon
+will finish any in-flight jobs before exiting, up to the configured
+`shutdown_timeout_secs` (default: 30 seconds).
+
+**If jobs are still draining:**
+
+```
+Stopping daemon...
+Warning: daemon may still be draining
+```
+
+This means in-flight jobs have not yet completed. The daemon will exit once they
+finish or the shutdown timeout is reached.
+
+**If the daemon is not running:**
+
+```
+Error: Daemon is not running
+```
+
+## agcron --version
+
+Display the installed version of the agcron binary.
+
+**Usage:**
+
+```bash
+agcron --version
+```
+
+**Output:**
+
+```
+agcron 1.6.0
+```
+
+## Environment Variables
+
+| Variable             | Description                                    | Default                              |
+| -------------------- | ---------------------------------------------- | ------------------------------------ |
+| AGENT_CRON_CONFIG    | Path to the configuration file                 | `~/.config/agent-cron/config.toml`   |
+| AGENT_CRON_SOCKET    | Path to the Unix domain socket                 | `~/.config/agent-cron/agent-cron.sock` |
+| CRON_MAX_CONCURRENCY | Maximum concurrent job executions              | `4`                                  |
+| RUST_LOG             | Log level filter (e.g., `debug`, `info,agcron=trace`) | `info`                         |
+
+## Configuration File
+
+**Location:** `~/.config/agent-cron/config.toml`
+
+The daemon reads this file on startup. It defines managed project directories,
+concurrency limits, default adapters, and transport preferences. Changes to the
+config file require a daemon restart to take effect.