refactor(stop): rewrite SKILL.md frontmatter/heading/prose for stop semantics (FW-13, FW-03)

- frontmatter description: 'Terminate...mark it terminated' → 'Stop...hard=terminated, stop options=stopped'
- heading: 'Multi-Agent Delete' → 'Multi-Agent Stop'
- tags: delete → stop
- state machine diagram: delete → stop
- prose: soft/hard delete → soft/hard stop throughout
- stop_session.sh: comments + echo 'delete complete' → 'stop complete'
- create/SKILL.md: companion list 'delete' → 'stop' (2 locations)
- preserved: status=terminated (valid YAML value), terminated_at field, --purge-conversation semantics
This commit is contained in:
2026-06-21 06:13:37 +00:00
parent 9334352924
commit 5af1387b5d
3 changed files with 26 additions and 26 deletions
@@ -22,7 +22,7 @@ metadata:
Spawn a new agent (`claude` or `agy`/antigravity-cli) in a **dedicated tmux session** for context-preserving long-running work. The tmux session is the *container*; the agent's session ID is *data* inside the container. **This skill creates the container + starts the agent — but does not resume an old conversation** (use `tmux-agent-orchestrate-resume` for that). Spawn a new agent (`claude` or `agy`/antigravity-cli) in a **dedicated tmux session** for context-preserving long-running work. The tmux session is the *container*; the agent's session ID is *data* inside the container. **This skill creates the container + starts the agent — but does not resume an old conversation** (use `tmux-agent-orchestrate-resume` for that).
For all agents: the tmux session name is produced by **`lib.sh::derive_session_name`** — the single source of truth shared by create/resume/delete/status/monitor (P0-A). The rule (verbatim from the function): For all agents: the tmux session name is produced by **`lib.sh::derive_session_name`** — the single source of truth shared by create/resume/stop/status/monitor (P0-A). The rule (verbatim from the function):
> slug = the **two trailing path components** of the absolute workspace, `_`→`-`, lowercased, joined with `-`; name = `<slug>-creator-<agent>`. > slug = the **two trailing path components** of the absolute workspace, `_`→`-`, lowercased, joined with `-`; name = `<slug>-creator-<agent>`.
@@ -70,7 +70,7 @@ To prevent this, you can run this skill inside an **isolated tmux server** using
1. **Via Environment Variable**: 1. **Via Environment Variable**:
```bash ```bash
export TMUX_SERVER_NAME=multi-agent-canary export TMUX_SERVER_NAME=multi-agent-canary
# All subsequent commands (create, status, delete, etc.) will run in the isolated 'multi-agent-canary' tmux server. # All subsequent commands (create, status, stop, etc.) will run in the isolated 'multi-agent-canary' tmux server.
``` ```
2. **Via Option Flag**: 2. **Via Option Flag**:
```bash ```bash
+21 -21
View File
@@ -1,6 +1,6 @@
--- ---
name: tmux-agent-orchestrate-stop name: tmux-agent-orchestrate-stop
description: "Terminate an agent tmux session (claude, antigravity/agy) and update .hermes/agent-sessions.yaml to mark it terminated with timestamp. Does NOT delete on-disk conversation artifacts (jsonl/db) — those are preserved for future resume. Use when ending a work session, switching to a different one, or cleaning up before a fresh start." description: "Stop an agent tmux session (claude, antigravity/agy) and update .hermes/agent-sessions.yaml. Hard mode marks status=terminated; stop options (--capture-id/--reason/--graceful) mark status=stopped with conversation preserved for resume. Does NOT delete on-disk conversation artifacts (jsonl/db) — those are preserved unless --purge-conversation is passed. Use when ending a work session, switching to a different one, or cleaning up before a fresh start."
version: 1.0.0 version: 1.0.0
author: godopu author: godopu
license: MIT license: MIT
@@ -8,20 +8,20 @@ platforms: [linux, macos]
environments: [terminal, tmux] environments: [terminal, tmux]
metadata: metadata:
hermes: hermes:
tags: [agent, tmux, claude, antigravity, agy, multi-agent, delete, terminate, cleanup] tags: [agent, tmux, claude, antigravity, agy, multi-agent, stop, terminate, cleanup]
related_skills: [tmux-agent-orchestrate-create, tmux-agent-orchestrate-resume, tmux-agent-orchestrate-monitor] related_skills: [tmux-agent-orchestrate-create, tmux-agent-orchestrate-resume, tmux-agent-orchestrate-monitor]
prereq_skills: [tmux-agent-orchestrate-create, tmux-agent-orchestrate-resume] prereq_skills: [tmux-agent-orchestrate-create, tmux-agent-orchestrate-resume]
--- ---
# Multi-Agent Delete — Terminate an Agent tmux Session # Multi-Agent Stop — Stop an Agent tmux Session
> **Companion skills**: `tmux-agent-orchestrate-create` (start), `tmux-agent-orchestrate-resume` (re-attach), `tmux-agent-orchestrate-monitor` (live status). > **Companion skills**: `tmux-agent-orchestrate-create` (start), `tmux-agent-orchestrate-resume` (re-attach), `tmux-agent-orchestrate-monitor` (live status).
> **Tmux Isolation**: `delete` 명령은 YAML의 `tmux_server` 필드를 자동으로 파싱하여 해당 격리 서버의 세션을 안전하게 종료(kill)하므로, `TMUX_SERVER_NAME` 환경변수를 수동으로 지정할 필요가 없습니다. > **Tmux Isolation**: `stop` 명령은 YAML의 `tmux_server` 필드를 자동으로 파싱하여 해당 격리 서버의 세션을 안전하게 종료(kill)하므로, `TMUX_SERVER_NAME` 환경변수를 수동으로 지정할 필요가 없습니다.
> **Single source of truth**: `./.hermes/agent-sessions.yaml`. > **Single source of truth**: `./.hermes/agent-sessions.yaml`.
## What this skill does ## What this skill does
Stop an agent's tmux session and **mark the YAML entry as terminated**. Preserves: Stop an agent's tmux session and **mark the YAML entry (terminated or stopped)**. Preserves:
- The tmux session's recorded `pane.pid / cmd / cwd / mcp_attachments` for audit - The tmux session's recorded `pane.pid / cmd / cwd / mcp_attachments` for audit
- The agent's on-disk conversation (claude `*.jsonl`, agy `conversations/*.db`) — so the user can `tmux-agent-orchestrate-resume` later - The agent's on-disk conversation (claude `*.jsonl`, agy `conversations/*.db`) — so the user can `tmux-agent-orchestrate-resume` later
@@ -29,8 +29,8 @@ Stop an agent's tmux session and **mark the YAML entry as terminated**. Preserve
The user explicitly chooses: The user explicitly chooses:
- **soft delete** (default): update YAML only; leave tmux running. Useful when "delete" really means "I'm done with this card". - **soft stop** (default): update YAML only; leave tmux running. Useful when "stop" really means "I'm done with this card".
- **hard delete**: `tmux kill-session` + update YAML. The default when the user says "kill it" or "end the session". - **hard stop**: `tmux kill-session` + update YAML. The default when the user says "kill it" or "end the session".
## Pre-flight ## Pre-flight
@@ -44,7 +44,7 @@ import yaml
d = yaml.safe_load(open('$AGENT_SESSIONS_YAML')) d = yaml.safe_load(open('$AGENT_SESSIONS_YAML'))
names = [s['name'] for s in d.get('tmux_sessions', [])] names = [s['name'] for s in d.get('tmux_sessions', [])]
if '$SESSION_NAME' not in names: if '$SESSION_NAME' not in names:
print('NOT in YAML — refusing to delete (no audit trail). Use tmux-agent-orchestrate-create first, or pass --force-no-yaml.') print('NOT in YAML — refusing to stop (no audit trail). Use tmux-agent-orchestrate-create first, or pass --force-no-yaml.')
raise SystemExit(1) raise SystemExit(1)
" "
@@ -64,15 +64,15 @@ fi
## Workflow ## Workflow
```bash ```bash
# 1. soft delete (YAML only — tmux left running) # 1. soft stop (YAML only — tmux left running)
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \ bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
--session "$SESSION_NAME" --mode soft --session "$SESSION_NAME" --mode soft
# 2. hard delete (default — kill tmux + update YAML) # 2. hard stop (default — kill tmux + update YAML)
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \ bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
--session "$SESSION_NAME" --mode hard --session "$SESSION_NAME" --mode hard
# 3. hard delete + clean up on-disk conversation (DANGEROUS) # 3. hard stop + clean up on-disk conversation (DANGEROUS)
# — this prevents any future resume. Use only when user is certain. # — this prevents any future resume. Use only when user is certain.
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \ bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
--session "$SESSION_NAME" --mode hard --purge-conversation --session "$SESSION_NAME" --mode hard --purge-conversation
@@ -80,7 +80,7 @@ bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
## Stop extension (Option A — `stop` semantics without a 6th skill) ## Stop extension (Option A — `stop` semantics without a 6th skill)
Rather than a separate `tmux-agent-orchestrate-stop` route, `delete` absorbs the Rather than a separate `tmux-agent-orchestrate-stop` route, the base stop command absorbs the
"stop" intent via three opt-in options. Passing **any** of them switches the YAML "stop" intent via three opt-in options. Passing **any** of them switches the YAML
transition from `terminated` to **`stopped`** (`running → stopped`), signalling transition from `terminated` to **`stopped`** (`running → stopped`), signalling
"deliberately stopped, conversation preserved, ready to resume": "deliberately stopped, conversation preserved, ready to resume":
@@ -100,17 +100,17 @@ bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
**Idempotency**: in STOP mode, if the row is already `status: stopped`, the script **Idempotency**: in STOP mode, if the row is already `status: stopped`, the script
prints `already stopped (...)` and exits 0 — re-running is a safe no-op. prints `already stopped (...)` and exits 0 — re-running is a safe no-op.
**Backward compatibility**: with none of these options, `delete` behaves exactly as **Backward compatibility**: with none of these options, the base stop command behaves exactly as
before (`hard``terminated`, `soft``archived`). before (`hard``terminated`, `soft``archived`).
### State machine ### State machine
``` ```
running ──(delete --mode hard)────────────────► terminated running ──(stop --mode hard)────────────────► terminated
running ──(delete --capture-id/--reason/--graceful)► stopped (resumable, conv preserved) running ──(stop --capture-id/--reason/--graceful)► stopped (resumable, conv preserved)
running ──(delete --mode soft)────────────────► archived (tmux left alive) running ──(stop --mode soft)────────────────► archived (tmux left alive)
stopped ──(delete --capture-id … again)───────► stopped (idempotent no-op) stopped ──(stop --capture-id … again)───────► stopped (idempotent no-op)
any ──(delete --purge-conversation --yes)─► (conv deleted, resumable:false) any ──(stop --purge-conversation --yes)─► (conv deleted, resumable:false)
``` ```
Fields written in STOP mode: `status: stopped`, `stopped_at`, `stopped_at_epoch`, Fields written in STOP mode: `status: stopped`, `stopped_at`, `stopped_at_epoch`,
@@ -138,9 +138,9 @@ The script:
- **`tmux kill-session` doesn't just kill the session — it sends SIGHUP to the pane's child processes too.** This is usually what you want (the agent process dies, no zombie reparenting to init). But if you wanted to keep the agent running outside tmux for some reason, use `soft` mode. - **`tmux kill-session` doesn't just kill the session — it sends SIGHUP to the pane's child processes too.** This is usually what you want (the agent process dies, no zombie reparenting to init). But if you wanted to keep the agent running outside tmux for some reason, use `soft` mode.
- **Don't delete on-disk artifacts by default** — the agent's `*.jsonl` / `conversations/*.db` is the data that `tmux-agent-orchestrate-resume` needs. `--purge-conversation` is for when the user is genuinely done with the conversation and wants zero recovery chance. - **Don't delete on-disk artifacts by default** — the agent's `*.jsonl` / `conversations/*.db` is the data that `tmux-agent-orchestrate-resume` needs. `--purge-conversation` is for when the user is genuinely done with the conversation and wants zero recovery chance.
- **YAML is append-only until you write a delete** — if a previous run left the entry as `running` but tmux is actually dead (crash, host reboot), the YAML is stale. Running `tmux-agent-orchestrate-stop --mode hard` will detect "tmux already dead, just update YAML" and proceed. - **YAML is append-only until you write a stop** — if a previous run left the entry as `running` but tmux is actually dead (crash, host reboot), the YAML is stale. Running `tmux-agent-orchestrate-stop --mode hard` will detect "tmux already dead, just update YAML" and proceed.
- **Don't delete the `claude_session_id_own: null` placeholder** — when the user creates a fresh session with `tmux-agent-orchestrate-create` and never sent a message, the entry has `claude_session_id_own: null`. Deletion must preserve that field (it's the audit trail showing "this tmux session never produced a session id of its own"). - **Don't delete the `claude_session_id_own: null` placeholder** — when the user creates a fresh session with `tmux-agent-orchestrate-create` and never sent a message, the entry has `claude_session_id_own: null`. Stopping must preserve that field (it's the audit trail showing "this tmux session never produced a session id of its own").
- **Monitor skill may still be tracking** — if `tmux-agent-orchestrate-monitor` is running a heartbeat loop, deleting a session while it watches will trigger its `tmux ls != yaml` reconciliation. That's expected — let the monitor run, it will mark the entry as `terminated` on its own. Don't fight it. - **Monitor skill may still be tracking** — if `tmux-agent-orchestrate-monitor` is running a heartbeat loop, stopping a session while it watches will trigger its `tmux ls != yaml` reconciliation. That's expected — let the monitor run, it will mark the entry as `terminated` on its own. Don't fight it.
## Verification ## Verification
@@ -12,7 +12,7 @@
# 격리된* conversation artifact 만 삭제 (P0-C). 전역 # 격리된* conversation artifact 만 삭제 (P0-C). 전역
# agent_identities 를 참조하지 않음. resume 불가. # agent_identities 를 참조하지 않음. resume 불가.
# #
# Stop extension (Option A — delete 확장, 새 6번째 스킬 없이 stop 의미론 흡수): # Stop extension (Option A — stop 확장, 새 6번째 스킬 없이 stop 의미론 흡수):
# --capture-id — kill 직전에 이 워크스페이스의 conversation id 를 row 에 확정 # --capture-id — kill 직전에 이 워크스페이스의 conversation id 를 row 에 확정
# 기록 (claude_session_id_own / agy_conversation_id_own) → # 기록 (claude_session_id_own / agy_conversation_id_own) →
# 다음 resume 이 tier-1(race-free) 로 복원. find_workspace_uuid # 다음 resume 이 tier-1(race-free) 로 복원. find_workspace_uuid
@@ -50,7 +50,7 @@ EOF
SESSION_NAME="" SESSION_NAME=""
AGENT="" AGENT=""
MODE="hard" # "delete" 의 자연스러운 의미 = tmux 까지 종료 MODE="hard" # "stop" 의 자연스러운 의미 = tmux 까지 종료
PURGE=0 PURGE=0
YES=0 YES=0
CAPTURE_ID=0 CAPTURE_ID=0
@@ -308,7 +308,7 @@ echo
if [ "$STOP_MODE" = "1" ]; then if [ "$STOP_MODE" = "1" ]; then
echo "=== stop complete ===" echo "=== stop complete ==="
else else
echo "=== delete complete ===" echo "=== stop complete ==="
fi fi
echo " session: $SESSION_NAME" echo " session: $SESSION_NAME"
echo " agent: $AGENT" echo " agent: $AGENT"