small-scripts/context/claude-profile-modes.md

# claude-profile engagement modes

## Status

**Built and tested via dryrun. NOT yet exercised in a real `claude` launch.**

The feature ships as part of `scripts/claude-profile` (rewritten this session from 104 to ~280 lines). Spec is at `specs/claude-profile.spec.md`. All 37 dryrun assertions pass via `tests/test-claude-profile.sh`. Full test suite (`tests/run-all.sh`) is green: 8 of 8 test files passing.

## What was built

| Component | Path |
|---|---|
| Spec | `specs/claude-profile.spec.md` |
| Picker bash | `scripts/claude-profile` |
| 5 mode files | `data/claude-profile/modes/{chat,quick,deep,hybrid,orch}.md` |
| Preset example | `data/claude-profile/presets.yaml.example` |
| Test script | `tests/test-claude-profile.sh` |

The five modes:

| Mode | Driver model | Async | For |
|---|---|---|---|
| `chat` | Haiku (`claude-haiku-4-5-20251001`) | no | No project, conversation only |
| `quick` | Sonnet (`claude-sonnet-4-6`) | no | Single small focused job |
| `deep` | Sonnet | yes | Hard design/debugging, plan + spec enforced, Opus via named workflows |
| `hybrid` | Haiku | yes | Cheap driver, escalates to Opus/Sonnet subagents on demand |
| `orch` | Sonnet | yes | Decompose work, dispatch container agents, auto-fires `/loop 2m /orchestrate` |

## What is NOT done

1. **Not symlinked into `~/sbin`.** The new script lives at `~/dev/claude/small-scripts/scripts/claude-profile` but is not yet on PATH. To install:
   ```bash
   ln -sf "$HOME/dev/claude/small-scripts/scripts/claude-profile" "$HOME/sbin/claude-profile"
   ```
2. **Not exercised against real `claude`.** Dryrun confirms the resolved values; an actual launch (e.g. `claude-profile oreillyit --mode quick` or `--mode chat`) is the first thing the next session should try.
3. **Presets file not installed.** Example template is at `data/claude-profile/presets.yaml.example`. To use presets, copy to `~/.claude-oreillyit/presets.yaml` and edit.
4. **CLAUDE.md does not yet read `active-mode.env`.** When a real launch happens with `--project <name>`, the existing CLAUDE.md project picker will still appear and the user has to confirm the same project. This is the first follow-up listed below.

## How the runtime contract works

1. `claude-profile` resolves the profile, mode, and (for some modes) follow-up answers.
2. Writes `$CLAUDE_CONFIG_DIR/active-mode.env` with all resolved values (machine-readable, key=value).
3. Writes `$CLAUDE_CONFIG_DIR/last-mode` with the mode name (used as picker default next time).
4. Reads the mode file's body (everything after the YAML frontmatter), appends it to the context-load output, and passes the combined string via `--append-system-prompt`.
5. Resolves the mode's `driver` field through a hardcoded mapping table to a full Claude model ID.
6. Executes `claude --model "<full-model-id>" --append-system-prompt "<combined>" "${pass-through-args[@]}"`.

The mode file's prose body is what tells the driver model how to behave (escalation rules, plan-mode triggers, async policy, status-line format, on-`/clear` behaviour). The frontmatter is parsed by bash for the launcher's own decision-making.

## Driver mapping (lives in the script as a constant)

| Frontmatter `driver` | `--model` argument |
|---|---|
| `haiku` | `claude-haiku-4-5-20251001` |
| `sonnet` | `claude-sonnet-4-6` |
| `opus` | `claude-opus-4-6` |
| `opus-1m` | `claude-opus-4-6[1m]` |

When new model versions ship, update the `DRIVER_MAP` associative array near the top of `scripts/claude-profile`.

## Next session — recommended order

1. **Install the symlink:** `ln -sf "$HOME/dev/claude/small-scripts/scripts/claude-profile" "$HOME/sbin/claude-profile"`
2. **Real-launch test:** `claude-profile oreillyit --mode chat` first (lowest blast radius — Haiku driver, no project, no async). Verify the mode body actually appears in the system prompt and the model behaves per the chat mode rules.
3. **Then `--mode quick`** with a real project to verify the Sonnet driver and the no-async constraints.
4. **Then `--mode deep`** to verify plan-mode auto-engagement and the named-workflow escalation table.
5. **If anything feels off,** `tests/test-claude-profile.sh` is the fast feedback loop — run it after any picker-bash changes.
6. **Once happy with v1,** start picking up follow-ups from `FUTURE.md` (see "Follow-ups" below).

## Follow-ups (sequenced)

All in `FUTURE.md`. Suggested order:

1. **CLAUDE.md project picker integration** — read `CLAUDE_PROJECT` from `active-mode.env`, skip the duplicate picker. Quick win.
2. **Status-line script: render the mode tag** — the user explicitly asked for this; humans need to see the active mode at a glance. Lives in the claude-foundations repo, not small-scripts.
3. **`bg-model-call` wrapper** — referenced by the `deep` and `hybrid` modes but not yet built. Own small-scripts entry with its own spec and tests.
4. **`switch mode` skill** — mid-session re-pick. Lower priority; depends on whether mode switching turns out to be common in practice.
5. **MiniMax-driven inverted architecture** — biggest item, real research project. Token-budget sketch is the precondition before any code; if savings <30% it's not worth pursuing.

## Files touched this session

- Created: `specs/claude-profile.spec.md`, `data/claude-profile/modes/{chat,quick,deep,hybrid,orch}.md`, `data/claude-profile/presets.yaml.example`, `tests/test-claude-profile.sh`, `context/claude-profile-modes.md` (this file)
- Modified: `scripts/claude-profile` (rewritten), `README.md`, `CLAUDE.md`, `FUTURE.md`
- Pruned: 4 reflected session logs from March (`memory/log/2026-03-17.*.md` and `2026-03-23.123551.md`)

## Key gotchas to remember

- **`read -rp` under `set -e` exits silently if stdin is not a TTY.** Always guard interactive reads with `[[ -t 0 ]]` and provide a default. Without this, `--dryrun` hangs or silently exits when run from scripts. See `memory/gotchas-bash.md` for the broader pattern.
- **`context-load` is on PATH via `~/sbin`, not a sibling of `claude-profile`.** The script uses `command -v context-load` first, with sibling fallback for testing isolation.
- **Use full model IDs, not aliases.** The `claude-code-guide` agent only confirmed `sonnet`/`opus` aliases work; `haiku` is unverified. The mapping table uses full IDs throughout for safety and unambiguous version selection.
- **`claude --model` is session-scoped.** Switching driver mid-session is impossible — it requires a relaunch. The `switch mode` follow-up works around this by writing a new `active-mode.env` for the next `/clear` to pick up.