go-process-cli

Files (29)

• AGENTS.md
• SKILL.md
• _template.md · assets/templates/
• metadata.json
• _sections.md · references/
• cli-execute-context-wires-signals.md · references/
• cli-flag-vs-cobra-by-shape.md · references/
• cli-rune-return-errors.md · references/
• cli-stdlib-subcommand-pattern.md · references/
• ctx-cancellable-wait.md · references/
• ctx-defer-cancel.md · references/
• ctx-explicit-argument.md · references/
• err-join-aggregate-workloads.md · references/
• err-run-function-for-deferred-cleanup.md · references/
• exec-cancel-sigterm-before-kill.md · references/
• exec-commandcontext-binds-lifetime.md · references/
• exec-exit-code-from-exiterror.md · references/
• exec-kill-process-group.md · references/
• exec-pipes-without-deadlock.md · references/
• sig-notify-context-for-shutdown.md · references/
• sig-second-signal-force-quit.md · references/
• state-atomic-pidfile.md · references/
• state-reap-children-wait.md · references/
• state-signal-zero-liveness.md · references/
• state-structured-slog-transitions.md · references/
• work-bound-concurrency.md · references/
• work-errgroup-fan-out.md · references/
• work-every-goroutine-has-exit.md · references/
• work-sender-closes-channel.md · references/

SKILL.md (first lines)

# Go Process-Management CLIs

> Make Go command-line tools that spawn, supervise, and shut down processes correctly — the part the stdlib makes easy to get subtly wrong.

## When to Apply

Reach for this skill when building or reviewing a Go CLI whose job is to *control other processes or concurrent workloads*: a daemon, a process supervisor, a job/worker runner, a deploy or migration tool, a test harness that shells out, or any program that must stop cleanly when an orchestrator says so. It targets **Go 1.22+** on **Unix-like systems** (Linux, macOS); a few rules note where Windows differs. It assumes you already know Go — it only corrects the specific defaults that go wrong in this domain.

## Categories

| # | Category | Prefix | What it covers |
|---|----------|--------|----------------|
| 1 | Signals & Graceful Shutdown | `sig` | Binding a context to SIGINT/SIGTERM; second-signal force-quit |
| 2 | Child Processes | `exec` | `os/exec` lifetime, graceful kill, process groups, pipes, exit codes |
| 3 | Concurrency & Workloads | `work` | errgroup fan-out, bounded concurrency, goroutine-leak discipline, channel ownership |
| 4 | Context Propagation | `ctx` | Explicit context args, `defer cancel()`, cancellable waits |
| 5 | Errors & Exit Codes | `err` | `run() error` for deferred cleanup, aggregating failures |
| 6 | CLI Framework & Flags | `cli` | stdlib `flag` vs cobra, `ExecuteContext`, `RunE`, subcommand patterns |
| 7 | Process State & Supervision | `state` | Liveness probes, atomic PID files, zombie reaping, structured logs |

## Quick Reference

The defaults this skill exists to correct:

- **`signal.NotifyContext(ctx, SIGINT, SIGTERM)`** — not a channel that only watches Ctrl-C. Orchestrators send SIGTERM.
- **`exec.CommandContext` + `cmd.Cancel`/`cmd.WaitDelay`** — plain `CommandContext` SIGKILLs children with no cleanup.
- **`Setpgid` + `kill(-pgid)`** — signalling the direct child orphans grandchildren (`sh -c`, `make`, `npm`).
- **`cmd.Output()`** for capture — reading a pipe after `Wait()` deadlocks.
- **`errgroup.WithContext` + `SetLimit(n)`** — a goroutine per task means a *process* per task: PID/FD exhaustion.
- **`ctx` as an argument** — never a struct field; **`defer cancel()`** on every derived context.
- **`select { case <-ticker.C: case <-ctx.Done(): }`** — `time.Sleep` makes shutdown wait out the interval.
- **`main → run() error → os.Exit(1)`** — `log.Fatal`/`os.Exit` deep in code skip every `defer`.
- **`proc.Signal(syscall.Signal(0))`** — `os.FindProcess` always succeeds on Unix; it never proves liveness.
- **`os.OpenFile(O_CREATE|O_EXCL)`** for PID files — check-then-create is a race; **`cmd.Wait()`** every child or it zombifies.

## How to Use

1. Identify which category your task falls under (see table above).
2. Read the relevant rule files in `references/` — each is a focused, self-contained pattern naming the wrong default it corrects.
3. Apply the pattern; follow the `Reference` link in each rule for the authoritative source.

Rules cross-link (e.g. graceful shutdown ties signals → context → child-process kill → cleanup), so follow the links when a task spans categories.

When extending this skill, copy `assets/templates/_template.md`: WHY first, one canonical example with realistic names, a foil only if the wrong way is a genuine trap.

## Source Authority

Every rule cites primary sources — the Go standard library reference on pkg.go.dev, the official Go blog (go.dev/blog), and the cobra documentation — chosen because they are maintainer-authored and version-current. No content farms, listicles, or undated tutorials.

## Related Skills

- `radical-simplification` — when a supervisor design has accreted accidental complexity.
- `unix-cli` / `cli-for-agents` — broader CLI ergonomics beyond process management.

From pproenca/dot-skills, MIT.

More from pproenca/dot-skills