---
name: eck:pause
version: "0.7.4"
description: "Save current session state to STATE.md for clean handoff or later resume via /eck:resume."
disable-model-invocation: false
---

# Pause

Save the current session state and prepare for a clean handoff. Resume later with `/eck:resume`.

> Never loses work. Saves all context needed to resume exactly where you stopped (P6).

---

## Visual Framework

Follow these conventions for all terminal output displayed to the user via the Bash tool.

### Output Mode Awareness

Before producing output, read the user's preferred output mode:

```bash
cat $ECK_HOME/user-preferences.json 2>/dev/null
```

Extract the `outputMode` field and adapt verbosity:

- **guided** — Add explanatory prose after key steps. Describe what is happening and why.
- **standard** (default) — Balanced. Show steps with brief context for non-obvious decisions.
- **concise** — Steps and summary box only. No prose, no explanations.

If the file is missing or `outputMode` is absent, use **standard**.

### ANSI Colors

Declare these variables at the top of **every** Bash tool call (shell state does not persist between calls):

```bash
source $ECK_HOME/colors.sh
```

Every color sequence **must** end with `${RESET}`. No exceptions.

### Stage Banners

Mark major stage transitions with a bold banner. One blank line before and after.

```bash
echo ""
printf '%b\n' "${ORANGE}${BOLD}STAGE NAME${RESET}"
echo ""
```

### Status Symbols

| Symbol | Meaning          | Color       |
| ------ | ---------------- | ----------- |
| `[*]`  | Active / running | `${CYAN}`   |
| `[x]`  | Completed        | `${GREEN}`  |
| `[!]`  | Error            | `${RED}`    |
| `[-]`  | Skipped          | `${DIM}`    |
| `[>]`  | In progress      | `${YELLOW}` |
| `[ ]`  | Pending          | `${DIM}`    |

No emoji in output. Use only these bracket symbols for status.

### Summary Boxes

Display at checkpoints and at the end of the skill. Box width: 55 characters. Labels padded to 16 characters. One blank line before and after.

### Error Format

```bash
printf '%b\n' "${RED}[!]${RESET} Error message here"
printf '%b\n' "    ${DIM}Recovery guidance here.${RESET}"
```

### Spacing Rules

- One blank line before and after stage banners and summary boxes.
- No blank lines within step lists.
- Maximum output line width: 70 characters.

---

## Task Registration

| Stage | Subject           | Active Form      | Statusline      |
| ----- | ----------------- | ---------------- | --------------- |
| 1     | Stage 1: Snapshot | Taking snapshot  | Snapshot (1/3)  |
| 2     | Stage 2: Save     | Saving state     | SaveState (2/3) |
| 3     | Stage 3: Confirm  | Confirming pause | Confirm (3/3)   |

### Statusline Stage Updates

At the **start** of each stage, update the statusline:

```bash
bash $ECK_HOME/update-stage.sh "{Statusline text from table}"
```

At **skill completion** (success or error), reset:

```bash
bash $ECK_HOME/update-stage.sh
```

---

## Usage

```
/eck:pause
```

No arguments needed — captures current session state automatically.

---

## Stage 1: Snapshot

### Inputs

- Current session context (active command, stage, task list, feature name, flags)
- `TASKS.md` path (if exists)
- Git working directory state

### Activities

1. Capture current session context:
   - Active command (which `/eck:*` is running, if any)
   - Current stage and step within that command
   - Task list state (completed, in-progress, remaining)
   - TASKS.md path (if exists)
   - Feature name and flags
   - Current git branch
   - Uncommitted changes (if any)
2. Check for uncommitted work:
   ```bash
   git status --porcelain
   ```
3. If uncommitted changes exist, stage and commit them as a WIP commit:
   ```
   [>] Uncommitted changes detected
   [x] Created WIP commit: "wip: pause checkpoint for {feature}"
   ```
4. Display snapshot summary

### Outputs

- WIP commit (if uncommitted changes existed)
- Captured session state data ready to write

### Exit Criteria

- Session context captured and uncommitted work committed (if applicable)

## Stage 2: Save

### Inputs

- Session state data captured in Stage 1
- `$CLAUDE_PROJECT_DIR/.claude/` directory

### Activities

1. Write STATE.md using `ops:state-save` primitive to `.claude/STATE.md`:

   ```markdown
   # ECK Session State

   Command: {active_command}
   Feature: {feature_name}
   Plan: {plan_path}
   Mode: {dev_mode}
   Flags: {flags}
   Branch: {current_branch}

   ## Stopped at

   {current_stage}: {current_step}

   ## Completed

   - {list of completed stages/tasks}

   ## Remaining

   - {list of remaining stages/tasks}

   ## Timestamp

   {ISO 8601 timestamp}
   ```

2. Verify STATE.md was written successfully:
   ```bash
   test -f "$CLAUDE_PROJECT_DIR/.claude/STATE.md" && echo "ok"
   ```

### Outputs

- `.claude/STATE.md` written with full session state

### Exit Criteria

- STATE.md exists and is verified readable

## Stage 3: Confirm

### Inputs

- STATE.md path from Stage 2
- WIP commit hash from Stage 1 (if created)

### Activities

1. Display pause confirmation box:

   ```
   Session Paused

   Command: /eck:develop
   Stopped at: Stage 4: Execute (Wave 2)
   State saved: .claude/STATE.md
   Branch: feat/auth-123
   WIP commit: abc1234 (if created)

   Resume with: /eck:resume
   ```

2. Reset statusline: `bash $ECK_HOME/update-stage.sh`

### Outputs

- Confirmation displayed to user

### Exit Criteria

- User sees confirmation and knows how to resume; statusline reset

---

## Error Handling

- If no active command is running, still save state (git branch, uncommitted changes, task list)
- If STATE.md already exists, confirm overwrite with AskUserQuestion
- WIP commits use a recognizable prefix (`wip:`) so `/eck:resume` can identify and optionally squash them
- At completion, reset statusline: `bash $ECK_HOME/update-stage.sh`
