snappy-stop

One job: stop the named background agent set by /snappy-go. Deletes state/agents/<name>.json so the byline 🤖 row for that agent drops on the next statusline render.

Usage

/snappy-stop                 # stops "default" (back-compat)
/snappy-stop content-miner   # stops the named agent

Steps

1. Resolve name: first argument if present, else default.
2. Run:

   bash ~/projects/snappy-os/state/bin/agents/stop.sh <name>

1. Confirm state/agents/<name>.json no longer exists (it is deleted on

stop, not flipped to status=stopped on disk - the history row in state/log/agents.ndjson records the stop).

1. Tell the operator:

• that the agent is stopped (no more ticks will fire for this id)
• how many ticks it ran (from the final history row)
• where the run logs are (/tmp/snappy-agent-<name>-*.log)
• the prompt is preserved in the go history row in

state/log/agents.ndjson for reference

Why

The byline stacks up to 3 🤖 rows for running agents. This skill is the "press the red square" affordance for one of them - without guessing at file paths or touching state/agents/ directly.

Eval

Shape-gate:

• state/agents/<name>.json is absent after invocation (or was already

absent, which is also a pass - idempotent stop).

• state/log/agents.ndjson gained a {action:"stop", id:<name>} row.

Score = 1 if both pass; else 0.

Gotchas

• A tick that is currently in-flight for that agent (its lockfile

/tmp/snappy-agent-<name>.lock is held) continues to completion; only future ticks are blocked. To kill an in-flight tick, identify the claude PID holding the lock and send SIGTERM.

• /snappy-pause <name> is the "halt without forgetting" alternative -

flips status to paused in the file; tick skips it; /snappy-resume flips it back.

• Stopping default when no agent named default exists prints a

no-such-agent error but is idempotent - no state change.

Rubric

criteria:
  - name: agent_json_deleted
    kind: deterministic
    check: "The file 'state/agents/<name>.json' must not exist after the skill execution."
  - name: stop_log_entry_added
    kind: deterministic
    check: "The 'state/log/agents.ndjson' file must contain a new JSON object with 'action: \"stop\"' and 'id: <name>'."
  - name: operator_message_completeness
    kind: judge
    check: "The skill's output message to the operator must inform that the agent is stopped, how many ticks it ran, and the location of its run logs."

snappy-stop - loader

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

Critical Rules

• A tick that is currently in-flight (lockfile present) continues to

Commands

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

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)] snappy-stop: <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)] snappy-stop: <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/snappy-stop/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.