---
name: eck:output-mode
version: "0.7.4"
description: Display or switch the active output mode (guided/standard/concise)
disable-model-invocation: true
---

# Output Mode

Display or switch the active output mode. Modes control response verbosity, tone, and structure — shaping **how** Claude responds without changing **what** Claude can do.

---

## 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}`    |

```bash
printf '%b\n' "${GREEN}[x]${RESET} Step completed"
printf '%b\n' "${RED}[!]${RESET} Something failed"
```

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

### Summary Boxes

Display at checkpoints and at the end of the skill. One blank line before and after.

```bash
echo ""
printf '%b\n' "${ORANGE}${BOLD}Title${RESET}"
echo ""
printf '%b\n' "Label: Value"
echo ""
```

### 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.

### 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
```

---

## Task Registration

| Stage | Subject                    | Active Form            | Statusline    |
| ----- | -------------------------- | ---------------------- | ------------- |
| 1     | Stage 1: Read Current Mode | Reading current mode   | Read (1/3)    |
| 2     | Stage 2: Update Mode       | Updating output mode   | Update (2/3)  |
| 3     | Stage 3: Confirm           | Confirming mode change | Confirm (3/3) |

## Usage

```bash
/eck:output-mode                    # Show current mode
/eck:output-mode guided             # Switch to guided mode
/eck:output-mode standard           # Switch to standard mode
/eck:output-mode concise            # Switch to concise mode
```

---

## Stage 1: Read Current Mode

### Inputs

- `$ECK_HOME/user-preferences.json` — `outputMode` field
- `~/.claude/settings.json` — `outputStyle` field (what Claude Code reads)

### Activities

1. Read `user-preferences.json` and extract `outputMode` (default: `standard`)
2. Parse `$ARGUMENTS` for a target mode (`guided`, `standard`, `concise`)

### Outputs

- Current mode value
- Parsed target mode (if provided)

### Exit Criteria

- Current mode is known
- If a target mode was provided, it is one of: `guided`, `standard`, `concise`

**If no target mode was provided**, display the current mode and stop (skip Stages 2 and 3):

```bash
source $ECK_HOME/colors.sh

echo ""
printf '%b\n' "${ORANGE}${BOLD}Output Mode${RESET}"
echo ""
printf '%b\n' "Mode: {current_mode}"
echo ""
printf '%b\n' "Modes:"
printf '%b\n' "  ${CYAN}guided${RESET}    Explanatory, step-by-step"
printf '%b\n' "  ${CYAN}standard${RESET}  Balanced with brief context"
printf '%b\n' "  ${CYAN}concise${RESET}   Dense, minimal explanation"
echo ""
printf '%b\n' "Switch: /eck:output-mode guided|standard|concise"
echo ""
```

**If the target mode is invalid** (not one of guided/standard/concise):

```bash
source $ECK_HOME/colors.sh

printf '%b\n' "${RED}[!]${RESET} Invalid mode: {value}"
printf '%b\n' "    ${DIM}Valid modes: guided, standard, concise${RESET}"
```

Then reset statusline and stop.

---

## Stage 2: Update Mode

### Inputs

- Target mode from Stage 1

### Activities

1. Read `$ECK_HOME/user-preferences.json`
2. Update the `outputMode` field to the target mode
3. Write the updated JSON back
4. Read `~/.claude/settings.json`
5. Update the `outputStyle` field to point to the correct mode file path: `~/.claude/output-modes/{mode}.md`
6. Write the updated JSON back

The `settings.json` update is required because Claude Code reads `outputStyle` from `settings.json` to load the markdown persona file. Updating `user-preferences.json` alone is insufficient.

### Outputs

- Updated `user-preferences.json`
- Updated `settings.json`

### Exit Criteria

- Both files contain the new mode value
- The `outputStyle` path in `settings.json` points to a valid `.md` file

---

## Stage 3: Confirm

### Inputs

- Previous mode value
- New mode value

### Activities

1. Display summary box with the mode change

### Outputs

- Confirmation output to user

### Exit Criteria

- User sees the new mode and understands it takes effect on the next response

### Output

```bash
source $ECK_HOME/colors.sh

echo ""
printf '%b\n' "${ORANGE}${BOLD}Output Mode${RESET}"
echo ""
printf '%b\n' "${GREEN}[x]${RESET} Mode updated: {old_mode} -> {new_mode}"
printf '%b\n' "${GREEN}[x]${RESET} user-preferences.json updated"
printf '%b\n' "${GREEN}[x]${RESET} settings.json updated"
echo ""
printf '%b\n' "Mode: ${CYAN}{new_mode}${RESET}"
printf '%b\n' "File: ~/.claude/output-modes/{mode}.md"
echo ""
printf '%b\n' "${DIM}Takes effect on your next response.${RESET}"
echo ""
```

Reset statusline on completion:

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

---

## Error Handling

Follow the `output:error-handler` primitive for all error scenarios:

- Missing `user-preferences.json` — create it with default values
- Missing `settings.json` — warn user and skip settings update
- Invalid mode argument — show valid options and stop
- JSON parse failure — report error with file path
- Missing mode file at target path — warn but proceed (installer may need to run)

---

## Related Documents

- `scaffold/project/output-modes/README.md` — output mode descriptions and file locations
- `scaffold/project/primitives/core/output/visual-framework.md` — visual conventions
- `scaffold/project/primitives/core/output/error-handler.md` — error handling conventions
