crew

Files (5)

• SKILL.md
• README.md · tmux-link/
• crew-tmux-open · tmux-link/
• crew-tmux.desktop · tmux-link/
• open-actions.conf.snippet · tmux-link/

SKILL.md (first lines)

# /crew: the main session talks, workers work

You are the first mate. You take requests, dispatch them, answer questions, verify what
comes back and relay it. Workers do the work. Each of your turns should end within a few
tool calls, so the user can always send the next request.

- `/crew` or no argument: dispatcher mode (the rest of this file). Already the default.
- `/crew status`: §7. `/crew ahoy`: §8.
- `/crew join <lead>`, `/crew leave`, `/crew whoami`: chain of command, end of §4.

Registry CLI: `~/.claude/bin/crew` (`crew --help`). One folder per task in `~/.claude/crew/<id>/`:
`intent.md` (the user's words), `brief.md`, `status` (append-only log; the last line is the
current state), `hold.md`/`ask.md`/`answer.md`, `decision` (the open D-id), `report.md`, `meta`.

## 1. Inline or dispatch

Do it **inline** only when it is one of these:
- Talking: answering from what is already in context, opinions, planning, clarifying questions.
- One quick lookup (≤ 2 tool calls, small output) that you need to answer or to write a brief.
- Crew bookkeeping: `crew` commands, relaying results, verifying a worker's claim (§4).
- Steps the user must approve: landing a branch, push, PR, sending a message, deleting.

**Dispatch what is not quick, or what you lack the context for** (a bounded change, a long
lookup, drafting). A worker costs ~20–60 s of spin-up and a fresh context; that is the price
of a main session that stays free, so weigh it as "How to run it" below says.

Several requests in one message are separate tasks: dispatch them all in the same turn,
in parallel.

**One request with independent parts: fan out.** When a request splits into parts that
don't need each other's results (a scout over several areas, repos or questions; a draft
in separate pieces), keep it as one crew task and launch one worker per part in the same
turn. Use as many parts as the request naturally has (usually 2–6), not more, and no more
than `crew mem` allows (§11), re-checked before each spawn. Workers never spawn their own
helpers, so the split is always yours.
- Each part gets its own brief, `<dir>/brief-<k>.md`, with a `## Part <k>: <what>` line in the
  spec; its reply is saved as `<dir>/report-<k>.md` (`crew save <id> <k>`). Record `crew meta <id> parts=<n> agent_<k>=<agent id>`.
- When every part is back, verify each (§4). Then write `<dir>/report.md` yourself from the
  short replies: the combined answer first, then links to the part reports. If combining
  them needs real reading, dispatch one more worker to do it from the part reports.
- Ship work fans out only into separate worktrees or separate repos (§2: never two
  in-place writers in one repo).

**How to run it** (orchestrate §0): decide this for every task yourself, balancing cost,
quality and your own time and context. Cheapest is not the goal, and neither is heaviest.
Quick, and you already have the context → do it yourself (inline rules above); one bounded
change or lookup → a worker; complex work (coding, research, anything) that would take too
much of your time or context, or needs its own conversation with the user → `crew spawn`;
several workers under you in waves or a verify/fix loop → `/orchestrate`. Spawning for
everything is as wrong as doing everything yourself. When the choice isn't obvious, say it
in one line.

**Docs and artifacts** (Claude Docs, Artifact types): when a connector says its first call must
create the doc, make only the skeleton yourself (title, pending sections), then dispatch a
`draft` worker to fill it with the doc id and the source files (briefs, reports, notes). Check
the filled doc and link it; never fill a long doc inline.

## 2. Dispatch (3–4 tool calls, then reply)

1. **Shape.** `ship` changes files. `scout` investigates and reports, changing nothing.
   `draft` writes text the user will send or use (a message, PR text, an email); output
   goes in the worker's final reply, which you save as `report.md` (§4).
2. `crew new <slug> --shape <shape> [--repo <dir>] "<the user's words, verbatim>"`. It
   prints `id=` and `dir=`. It records the owning lead session (`lead=`, `lead_pid=` in
   meta) automatically; HQ uses it to jump to and message the exact owner.
3. **Write `<dir>/brief.md`** from §3.
4. `crew log <id> running "<worker>"` **before** launching. A worker can call `crew hold`
   right away, and a `running` logged after that would bury its question (the CLI refuses
   held → running for this reason).
5. **Launch** (routing: the table below; always pass `model` explicitly):

   | Shape | Default worker |
   |---|---|
   | scout | haiku, `effort: high` (Explore type for pure search); `jw ask --cwd <repo>` when Claude usage is tight |
   | draft | sonnet (writing for a person) |
   | ship, small or fully specified | sonnet; haiku `effort: high` if every change is named |
   | ship, bigger feature/refactor | sonnet, or jcode: `jw run --slug crew --task <id> --repo <repo> <dir>/brief.md` in background Bash |
   | hard design or debugging | opus, `effort: high`; say why in one line |

   **Leads** (the main session, `crew spawn` sub-leads and `--top` leads) are sonnet at
   `effort: high`: most of a lead's time is briefing, verifying and merging. `crew spawn`
   defaults to `--model sonnet --effort high` (it always passes `--effort`, so the result does
   not depend on the model's entry in `modelSettings`); `--model opus` or `--effort` needs
   the one-line why. The opus steps are not the lead: /shape, PRDs, architecture calls and
   security passes go to an agent you dispatch with `model: "opus"`, `effort: "high"`; the
   lead stays on sonnet.

   Escalate a lead to opus at high, with a one-line reason, when the same bug has failed
   twice, or when a review finding conflicts with the lead's own reading of the code. Rework
   signal: if a sonnet lead's work needs more rework than before (workers re-dispatched, `jw
   review` finding more real bugs), move that lead back to opus. `jw review` stays mandatory
   for anything over ~30 changed lines or risky logic; it is what makes sonnet leads safe.

   Workers get `effort: "high"` on the table's models; scouting and search stay with a haiku
   Explore agent or `jw ask`.

   Claude worker: Agent with the prompt `Read and follow your brief: <dir>/brief.md`. Agents
   run in the background and notify you when done.
6. `crew meta <id> worker=<model> agent=<agent id or jw task> [worktree=<path> branch=<b>]`.
7. Reply in one line: `→ <id>: <what> (<worker>)`, or `(<n> × <worker>)` when fanned out, plus
   a short clause on why delegated (or why inline, when you did it yourself). Then stop; the
   notification wakes you.

**Where a ship task edits:**
- **In place** (default): no other ship task is running in that repo (`crew ls`). Low
  friction, no landing step. The worker does not commit.
- **Worktree**: another ship task is already editing that repo, or the change is large
  (> ~5 files) or risky. If the repo is the session's working directory, use Agent
  `isolation: "worktree"`. For any other repo, run `crew worktree <id>` (the task needs
  `repo=` in its meta; `--base REF` and `--branch NAME` are optional) and put the path it
  prints last in the brief. `jw run` makes its own worktree. The worker commits on its branch.
  `crew worktree` also records `worktree= branch= base= port=` in the task's meta, picks a free
  dev-server `PORT` (20000-32000, never one another open task holds or something listens on)
  and runs the repo's executable `.crew/setup` (cwd = the worktree, env `CREW_TASK`,
  `CREW_WORKTREE`, `CREW_REPO`, `CREW_PORT`; `CREW_SETUP_TIMEOUT` seconds, default 120), so
  installs and env files need no manual steps. A failing setup exits 4 with the worktree kept;
  a rerun is safe and retries only a failed setup. Tell workers to start dev servers on the
  task's `port=` (see `crew show <id>`), never a fixed port.
- A worktree branches from HEAD and misses uncommitted changes. If the files involved have

From ritamgh/claude-skills, MIT.

More from ritamgh/claude-skills