snappy-go

One job: turn a free-form prompt into a running snappy-os background agent that fires every 10 minutes via cron until max_ticks is reached or /snappy-stop <name> is invoked. Multiple agents can run in parallel (cap SNAPPY_AGENT_CONCURRENCY, default 3) - each one is a row in state/agents/<name>.json.

Usage

/snappy-go "Keep going, close all remaining gaps"              # name defaults to "default"
/snappy-go content-miner "Mine pod transcripts for pull quotes" 40
/snappy-go                                                      # bare → interview mode

Steps

Mode A - argument given

1. Parse args. Two shapes are accepted for back-compat:

• <prompt> [max_ticks] - no name → implicit name="default"
• <name> <prompt> [max_ticks] - explicit name (any token without

spaces that starts the message) If the first token matches an existing agent id OR looks like a short alphanumeric slug ([a-z0-9][a-z0-9-]{1,39}), treat it as the name. Otherwise treat everything as prompt and use default.

1. Run:

   bash ~/projects/snappy-os/state/bin/agents/go.sh <name> "<prompt>" [max_ticks]

(Back-compat: go.sh "<prompt>" [max_ticks] without a name also works - routes to name=default.)

1. Read back state/agents/<name>.json and confirm status=running,

prompt=<prompt>, max_ticks=<n>.

1. Tell the operator:

• name + the prompt (truncated to 80 chars)
• cadence (every 10 min) and cap (max_ticks × 10 min ≈ N hours)
• how to stop: /snappy-stop <name>
• how to see them all: /snappy-list
• where to watch: byline 🤖 row + tail -f /tmp/snappy-agent-<name>.log

Mode B - no argument (interview mode)

When /snappy-go is invoked bare, you MUST NOT just print status. You MUST use the AskUserQuestion tool to run an intelligent interview keyed to the current system state. Do not print the questions as markdown - use the actual tool so the operator gets the native multiple-choice UI.

Gather context FIRST (single bash, parallel where possible):

cd ~/projects/snappy-os

# Currently running agents (multi-agent era)
npx tsx state/bin/agents/ctl.ts list 2>/dev/null

# Open p0/p1 rows (area + sev + age)
jq -r 'select((.status//"open")!="resolved") | select((.sev//.severity//"")|ascii_downcase|test("^p[01]$")) | [(.sev//.severity), .area] | @tsv' state/log/breakage-report.ndjson | sort -u

# Recurring-area patterns from pid-trends
npx tsx state/lint/pid-trends.ts 2>&1 | tail -5

# Graduation-ripe skills (≥10 runs, still prose)
jq -r '.skill' state/log/evals.ndjson | sort | uniq -c | sort -rn | head -10

Then call AskUserQuestion with 2-4 dynamic questions derived from that context. Each option should cite a real number or area from the context (e.g. "worker-stale-program has opened 4 times in 7 days"), not a generic menu item. Example frame:

• Q1: pick the agent to start OR manage - list already-running agents

with pause/resume/stop as options + a "new agent" option.

• Q2: if "new", name the specific recurring row + its count, offers

fix-at-source vs patch-symptom vs regen-brief.

• Q3: graduation-ripe skills + their run counts.
• Q4: autonomy mode - full autopilot / co-pilot / stop-loop.

After the user answers, synthesize a directive prompt + pick a name from their selections and run Mode A with those.

Never print the questions as text. Always use AskUserQuestion. If the tool is not available in the current session, load it with ToolSearch({query: "select:AskUserQuestion"}) first.

Why

A scheduled background agent is the snappy-os version of "keep working while I sleep." The byline becomes the play/stop indicator; this skill is the play button. Multiple agents let the operator run "mine content" AND "draft Ray update" in parallel without one stomping on the other.

Eval

Shape-gate (verified by the invoking agent - go.sh is a thin wrapper, the agent that ran the slash command is responsible for the eval row per CONSTITUTION invariant #4):

• state/agents/<name>.json has status=running after invocation.
• prompt is non-empty.
• max_ticks > 0.
• state/log/agents.ndjson gained a {action:"go", id:<name>} row (written by ctl.ts).

Score = 1 if all four pass; else 0. The agent appends to state/log/evals.ndjson via score() with skill: "snappy-go", verb: "set", supplying its own actor_session_id and a separate auditor_session_id.

Gotchas

• Per-agent lockfile at /tmp/snappy-agent-<name>.lock; a long-running

tick will cause subsequent ticks for that agent to no-op until it releases.

• Concurrency is capped by SNAPPY_AGENT_CONCURRENCY (default 3). If 3

agents are running and you start a 4th, it is written to disk but ticks skip it until one of the three finishes.

• max_ticks is the hard ceiling. Set low for expensive directives.
• The agent runs with --dangerously-skip-permissions. The system

prompt forbids destructive operations (no rm -rf, no force-push, no DROP). Pushes are allowed if the work warrants them.

• /snappy-stop <name> deletes that agent's file. state/log/agents.ndjson

is the history log. To "pause and resume later," use /snappy-pause.

• Agents are machine-local. A Mac Mini agent is invisible to the MBP's

byline and vice versa (see /snappy-list gotchas).

Rubric

criteria:
  - name: agent_state_file_written
    kind: deterministic
    check: "After invocation, 'state/agents/<name>.json' exists and contains '{\"status\": \"running\"}'."
  - name: agent_prompt_and_ticks_valid
    kind: deterministic
    check: "The 'prompt' field in 'state/agents/<name>.json' is non-empty and 'max_ticks' is greater than 0."
  - name: log_entry_created
    kind: deterministic
    check: "A new row with '{\"action\": \"go\", \"id\": \"<name>\"}' is appended to 'state/log/agents.ndjson'."
  - name: interview_mode_tool_use
    kind: judge
    check: "If no arguments are provided, the skill exclusively uses the AskUserQuestion tool for interaction and does not print questions as raw text."
  - name: user_feedback_completeness
    kind: judge
    check: "When arguments are given, the skill informs the operator about the agent's name, truncated prompt, cadence, stop method, list method, and watch location."

go - loader

Per-turn rules for the go skill. Full reference: state/skills/go/SKILL.md. Do not skip these.

Critical Rules

• The cron tick is gated on the lockfile /tmp/claude-cron-directive.lock;
• Bare /snappy-go (no argument) = interview mode. You MUST call the

AskUserQuestion tool with 2-4 questions whose options are derived from live system context (open p0/p1, pid-trends, graduation candidates, current directive). Printing the questions as markdown text is FORBIDDEN - the operator gets the native picker or nothing. If AskUserQuestion isn't loaded, ToolSearch({query: "select:AskUserQuestion"}) first.

• Option labels must cite real numbers/areas from the context (e.g.

"worker-stale-program - opened 4× in 7d"), never generic choices.

Commands

| ui dashboard | state/skills/go/resources/ui.openui | |invoke: see state/skills/go/SKILL.md Steps section |eval log: state/log/evals.ndjson (skill: "go")

Self-Test

An agent reading this should correctly:

1. [ ] Know which lib/bin artifact backs this skill (or that it is prose-only)
2. [ ] Know what to write to state/log/evals.ndjson after invoking
3. [ ] Know the eval mode (auto / shape / manual) from the .md frontmatter

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] go: <what was missing>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] go: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/go/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.