Helmor Cli

interface:
  display_name: "Helmor CLI"
  short_description: "Use Helmor from the terminal."
  default_prompt: "Use the Helmor CLI to inspect data, manage workspaces, send prompts, or run Helmor as an MCP server."


# `/helmor-cli break` — split an existing change into a stack

`break` is the mirror of `stack`: instead of planning a stack from scratch, it
takes the change you've **already written** in the current workspace and carves
it into a stack of small, dependent PRs — **confirming the slicing granularity
with the user** before committing to anything. The output is the normal stack:
one workspace + PR per slice, nested in the sidebar.

**Input**: the current workspace's full diff vs its base branch. The current
workspace becomes the stack's **root**, so capture a recovery ref before you
rewrite anything:
```bash
git commit -am "WIP: snapshot before break"   # only if the working tree is dirty
ORIG=$(git rev-parse HEAD)                      # the full change you're slicing
git branch helmor/break-backup "$ORIG"          # named recovery point
```
Source every slice below from `$ORIG` (not the branch name) — once the root is
reset, the branch no longer points at the full change.

## Workflow

### 1. Analyze the diff
```bash
git diff --name-status <base>...
```
(`<base>` is the workspace's target branch, e.g. `origin/main` — the system
prompt tells you which.) Read the changed files and their add/modify/delete
status, and group them by concern (schema/data, backend/API, UI, tests, docs…).

### 2. Propose a slicing
Build a **dependency-ordered** list of slices (bottom depends on nothing new;
top depends on everything below), e.g. `db → api → ui`. For each slice give: a
title, the files it contains, and the one-line reason it depends on the slice
below. Show the full proposal.

### 3. Confirm granularity WITH the user — the point of `break`
Do NOT auto-split. Present the proposal and let the user steer the granularity
with structured choices:
- **Approve** as-is.
- **Coarser** — merge two adjacent slices.
- **Finer** — split a slice (e.g. pull tests into their own layer).
- **Move a file** — reassign a file to a different slice.
- **Reorder** — fix the dependency order.

Loop until the user approves. Also **proactively ask** about ambiguous files — a
single file whose changes span concerns (e.g. `utils.ts` with both schema and UI
helpers): keep it whole in one slice, or flag it for a manual hunk-level split
(out of scope for v1 — see Limits).

### 4. Materialize the stack (bottom-up) — your current workspace becomes the root
The workspace you're in becomes the **bottom** layer; only the higher layers are
new workspaces. No throwaway launchpad, nothing to delete afterward.

For each slice K, from the bottom up:

1. Get the layer's workspace:
   - **bottom slice (root) = your current workspace** — reset it onto the base and
     rebuild it as slice 1 only:
     ```bash
     git reset --hard <base>                  # e.g. origin/main — the slicing base
     git checkout "$ORIG" -- <slice-1 added/modified files>
     git rm <slice-1 deleted files>           # if any
     git commit -m "<slice 1 title>"
     ```
   - **every higher slice**: `helmor workspace new --parent <slice K-1 workspace>`
     (the first higher layer's `--parent` is your current workspace).
2. Apply **only slice K's files** onto that layer (it already contains slices
   1..K-1 because it forked off the layer below), sourcing from `$ORIG`:
   - added / modified files: `git checkout "$ORIG" -- <files>`
   - deleted files: `git rm <files>`
   - then commit with the slice title.

   Drive each higher layer with a focused dispatch so it works inside its own
   worktree (pass `$ORIG`'s SHA explicitly; `helmor/break-backup` resolves it too):
   ```bash
   helmor send --workspace <id> --plan "Apply ONLY these files from <ORIG-sha>: <list>. \
   Added/modified: git checkout <ORIG-sha> -- <files>. Deleted: git rm <files>. \
   Commit as '<title>'. Do not touch anything