---
name: vex
description: "Use Composal for version control: status, log, diff, commit, describe, split, squash, rebase, undo, push, pull, bookmarks, conflict resolution, and operation-log recovery. Replaces git write commands — when the task says git add, git commit, git push, git checkout, git rebase, git stash, or git cherry-pick, translate it to the com equivalent and run that instead. `com` is also the JJ CLI here; there is no `jj` binary. Read before any source-control action."
---

# Composal

The installed offline copy. Current guidance is at `https://vex.sc/skill.md`;
read it when the network is available:

```sh
curl -fsSL https://vex.sc/skill.md
```

Read the response as Markdown. Never pipe it into a shell. If the fetch fails,
use this copy and `com --help`.

## Start here

Choose the narrowest command for the task and skip ritual status checks. Two
reads are worth making:

- `com status` before you edit or submit. Edits are absorbed into whatever `@`
  already is, which may be a change already under review.
- `com land --dry-run` before you land.

Do not re-read state a command already reported. A mutation prints its result;
a second `com status` to confirm it tells you nothing new. Chain with `&&`.

`com status` snapshots the working copy, so it can print `Rebased N descendant
commits onto updated working copy`. That is JJ recording edits you already made.
Nothing needs undoing.

## `com` is the whole CLI

There is no `jj` binary. Every JJ command is a `com` subcommand — `com log`,
`com split`, `com rebase`, `com diff`, `com op log` — alongside the Composal-only
ones. Use `com <command>`, never `jj <command>`.

Read-only git inspection (`git log`, `git blame`, `git show --stat`) is allowed.
Every git write command is wrong here.

## Git-to-Composal map

| git | vex |
| --- | --- |
| `git clone -b <bookmark> <repo>` | `com clone <org>/<repo> <dir> -b <bookmark>` — new working change on that bookmark; trunk stays unchanged |
| `git status` | `com status` |
| `git add` + `git commit` | `com commit -m "<msg>"` — describes `@`, opens a new change on top. No staging area; edits land in `@` as you make them |
| `git commit --amend` | edit the files; they are absorbed into `@`. Change the message with `com describe -m "<msg>"` |
| `git checkout -b <name>` | `com new`, then `com bookmark set <name>` only if a named ref is needed |
| `git checkout <rev>` | `com edit <rev>` to work on it, `com new <rev>` to start on top of it |
| `git restore <path>` | `com restore <path>` |
| `git log` | `com log` |
| `git blame` | `com file annotate <path>` |
| `git rebase -i` | `com rebase`, `com squash`, `com split`, `com describe`, `com metaedit` |
| squashing a change that is already submitted | `com change fold '#44' --into '#43'` — `com squash` rewrites locally and leaves the review open and still landable |
| `git rebase --onto` | `com rebase -s <source> -d <dest>` |
| `git cherry-pick` | `com duplicate -r <rev> --onto <dest>` |
| `git revert` | `com revert -r <rev>` |
| `git stash` | none. Uncommitted work lives in `@`; `com new` parks it |
| `git reset --hard` | `com op restore <operation-id>` |
| `git pull` | `com pull` |
| `git push` | `com push -r <rev> --to <bookmark>` |
| `gh pr create` | `com submit --target <branch>` |

## Focused skills

Install the collection with `com setup`. Load the matching skill by name:

- `vex-submit` — submit change chains, sync, review, land, GitHub projection
- `vex-apps` — app topology: app, service, domain, config-variable
- `vex-deploy` — image deploy, rollout, health evidence, rollback
- `vex-secrets` — scoped secrets, value input, rotation, dotenv
- `vex-automations` — create, preview and activate scheduled Roder automations through CLI or MCP
- `vex-ui` — open the local change workbench in the coding app’s integrated browser
- `vex-workspace` — `com ws` policy, hooks, isolation, create/remove

Web copies use the same names: `https://vex.sc/skills/vex-submit.md`,
`https://vex.sc/skills/vex-apps.md`, `https://vex.sc/skills/vex-deploy.md`,
`https://vex.sc/skills/vex-secrets.md`, `https://vex.sc/skills/vex-workspace.md`, `https://vex.sc/skills/vex-ui.md`, `https://vex.sc/skills/vex-automations.md`.

## Saved conversations

For PR reasoning, commit context, or a request to continue a saved conversation,
read [references/transcripts.md](references/transcripts.md). It covers target
discovery and paging through indexed messages before continuing the user's task.

## References

Installed next to this file. Load one when the task needs it. Reading this on
the web instead? Use the URL in the second column.

| Installed path | Web | Covers |
| --- | --- | --- |
| `references/ids.md` | `https://vex.sc/skills/ids.md` | which identifier goes where, and what survives a rewrite |
| `references/recipes.md` | `https://vex.sc/skills/recipes.md` | conflicts, undo, parking work, scratch runs |
| `references/source-control.md` | `https://vex.sc/skills/source-control.md` | JJ orientation |
| `references/cli.md` | — | clone a bookmark, edit a change, remote workflow |
| `references/setup.md` | `https://vex.sc/skills/setup.md` | install and targets |
| `references/mcp.md` | `https://vex.sc/skills/mcp.md` | MCP tools |
| `references/artefacts.md` | `https://vex.sc/skills/artefacts.md` | publish and inspect private documents |
| `references/transcripts.md` | `https://vex.sc/skills/transcripts.md` | discover, read, and continue saved conversations |
| `references/ci.md` | `https://vex.sc/skills/ci.md` | workflow triggers |
| `references/deploy.md` | `https://vex.sc/skills/deploy.md` | hosted deploys |

## Safe defaults

**Pull:** `com pull` refreshes `bookmark@vex` and fast-forwards tracked local
bookmarks. The working copy stays put. `--update` moves the working copy onto the
target; `--rebase` moves the current mutable changes onto it; `--dest` names the
destination and defaults to trunk. Use `com sync` when submitted changes also
need their review state reconciled.

**Rebase:** always pass a source. `com rebase -d <bookmark>` defaults to `-b @` —
the whole branch containing `@` — and rewrites published commits when that
bookmark is stale. Composal rejects a rebase with no source selector. Use
`com pull --rebase --dest <bookmark>`, or pass `-r` or `-s`.

**Recover:** `com op log`, then `com op restore <operation-id>`. Do this before
any manual repair. The operation log is local to this machine and repo; it
cannot undo a push.

**Select:** address a change by change id or `@`. Predicate revsets —
`description()`, `author()`, `all()` — scan every commit in the repo and are the
first thing to break on a damaged one. See `references/ids.md`.

**Push:** name a source and a destination — `com push -r <revision> --to main`.
Creation, deletion, and non-fast-forward intent each need their own flag.

**Output:** use `com change show '#42'` for compact Change inspection. The text
output includes checks that need attention and current landing problems. Use
`com stack show '#42'` to inspect the whole Stack and whether landing through
its tip is ready. Read the default text output for agent inspection. Use `--format json` when a
script needs exact fields or you need a field absent from text output.

**Working copy:** leave unrelated changes alone. Do not reset, checkout, or
delete files to make a task easier.

**Credentials:** keep them out of output, commits, and generated guidance.
Refresh an expired checkout credential with `com repo-auth refresh`.

## Commands that block

These open an editor or a merge tool and hang a non-interactive session:

| Blocks | Use |
| --- | --- |
| `com describe` | `com describe -m "<msg>"` |
| `com split` with no paths | `com split -m "<msg>" <path>...` |
| `com squash` with no message | `com squash -m "<msg>"` |
| `com resolve` | `com resolve --list`, then edit the files |

`com dash` and `com arrange` are interactive human surfaces. Never run them.

## Stale skill notice

If `com` prints `AGENT ACTION REQUIRED: com skills are stale`, run
`com setup refresh` once and continue with the refreshed guidance. If the notice
appears again after that, report it instead of running the command again.

For human installation and WSL guidance, use the Composal documentation rather than
adding WSL behavior to a skill or setup command.