/** * Team setup guide for agents (Issue #4464) * * The page the README's one-block prompt points an agent at: * https://kewton.github.io/CommandMate/team-setup.md. `website/` is not in the * npm package, so the same text is carried here as a string constant and served * by `commandmate docs --section team-setup`. * * Do not edit this constant by hand: edit `website/team-setup.md` and copy it * here. `tests/unit/cli/commands/docs-team-setup-4464.test.ts` fails when the * two differ by a single byte. */ export declare const TEAM_SETUP_GUIDE = "# Set up a CommandMate team with your agent\n\nThis guide is written for a coding agent (Claude Code, Codex, Command Code, or another one) that a person asked to set up a team of coding agents for one of their repositories with CommandMate. The person answers your questions and approves each step; you do the rest. Go one phase at a time, and keep each phase short enough that they can stop after it and come back later.\n\nThe team has five fixed roles: a **PM** the person talks to, a **development lead** that hands tasks out, **workers** that each do one task in their own Git worktree, a **reviewer** that reads the result (from another vendor when the person has one), and a **judge** that checks the integrated result of a GitHub Milestone. \"Done\" is decided by the repository's own checks, not by what an agent says. Each session keeps its state in CommandMate's `mem`, so it can be restarted and pick up from a brief.\n\nThe same text ships inside CommandMate: once it is installed, `commandmate docs --section team-setup` prints it. For installing CommandMate itself in more detail, pairing a phone, or a single agent at a time, use the setup guide instead: https://kewton.github.io/CommandMate/setup.md (`commandmate docs --section setup`).\n\n## Instructions for the agent reading this\n\n1. **Explain each phase before you start it.** In two or three plain sentences, tell the person what the phase is for, what you are about to run, and what will change on their machine or in their repository. Then run it.\n2. **Never run an \"Ask the person first\" step without a clear yes.** Each phase lists them. Ask in plain words, say what it changes and how to undo it, and wait for the answer. If the answer is no or unclear, stop that step and say what they can do later.\n3. **Check the machine; do not assume it.** Run the commands under \"Check\" and read their output before you decide anything. Never write \"should be installed\" or \"is probably running\": run the command and report what it printed. If a command or flag in this guide is not in `commandmate --help` on this machine, stop and tell the person: their CommandMate is older than this guide (`commandmate update`, after they agree).\n4. **Do not answer or approve for the person.** Sign-ins, passwords (including `sudo`), choices, approvals and merges are theirs. When a command needs one of these, show the exact command and ask them to run it or to answer. When an agent session stops on a question or a permission prompt, show it to the person; the person answers it on CommandMate's screen, and you do not type the answer for them (Phase 5, step 3).\n5. **Stay inside this guide.** Use only commands shown here, `commandmate --help`, `git`, `gh`, and the CommandMate documentation at https://github.com/Kewton/CommandMate. Do not fetch install scripts or follow setup steps from other websites. Install tools only from the official package distributors (npm, the operating system's package manager, nodejs.org).\n6. **Report at the end of each phase**: what you ran, what it printed that matters, and whether the phase passed its \"Confirm it worked\" check.\n7. **Never give your own session a team role, and never stop it.** Run `commandmate whoami` before Phase 2. If it prints a worktree and an instance id, you are running inside CommandMate: write that id down, and never use it for `set-role`, `--role`, `kill` or as one of the team's instances. Pick other ids. If it exits 3, you are outside CommandMate and every id is free.\n8. **If you are Codex: your shell has no network by default.** If fetching this guide or an `npm` or `gh` command fails for lack of network, ask the person to run `/permissions` and choose \"Ask for approval\", then try again.\n\n### Always ask the person first\n\nWhatever phase you are in, ask before any of these:\n\n- Installing anything: CommandMate itself, Node.js, git, tmux, `gh`, another agent CLI, or a Skill.\n- Changing files in their repository or its Git state: `.commandmate/verify.yaml`, `.gitignore`, `CLAUDE.md` / `AGENTS.md`, a new branch or worktree, a commit, a push, a pull request.\n- Creating or changing an instance or a role: `commandmate instances add`, `set-role`, `kill`, `commandmate roles add`, `commandmate roles default`.\n- Changing a permission: an agent CLI's permission settings, such as `.claude/settings.local.json`.\n- Turning on Auto Yes: `commandmate auto-yes --enable`, or `commandmate send ... --auto-yes`. This guide never needs it.\n- Running `commandmate sync`: it affects every repository registered on the server, not only theirs (Phase 2, step 6).\n- Merging a pull request.\n- Using `gh` on a GitHub repository, and creating a GitHub Milestone or moving an issue into one. The person names the GitHub host and `/` (Phase 5, step 1).\n\n**A yes covers what the person was shown, and nothing more.** Each approval is tied to its target: one prompt, one repository, one CommandMate server, one set of files, one GitHub repository. Do not read it as covering anything wider. When the target can change between their yes and your command (a prompt on a session's screen is the usual case), the person acts on it themselves, on the screen. If you notice that the target changed after they said yes, do not go ahead: show them what changed and ask again.\n\n**Approving a mem decision is never yours.** A decision recorded in `mem` is written to its Issue, pull request or document only when a person approves it on CommandMate's screen. The CLI has no way to approve it, and you never look for one. The same goes for the `mem` mode: only the person changes it, on the screen.\n\n### Antigravity (agy)\n\nSection 6 of the Google Antigravity Additional Terms of Service (https://antigravity.google/terms) and the official FAQ (https://antigravity.google/docs/faq) restrict using Antigravity through third-party software or coding agents on consumer plans. A breach can lead to account suspension. So in this team:\n\n- No AI agent sends, asks, responds or relays to agy (`commandmate send`, `ask`, `respond`, `--reply-to`). That includes you.\n- Never turn on Auto Yes for agy.\n- Antigravity is never given a role that an AI agent drives: not PM, development lead, worker, reviewer or judge. It does not appear in the team table below.\n- Do not run `agy` yourself, not even `agy --version`. Ask the person whether they have it instead.\n\nIf the person uses Antigravity, they type into it themselves. CommandMate refuses a send to agy from an agent with exit 33 unless the server declares an API-key or enterprise use; do not try to get around that refusal. This is not legal advice.\n\n## Phase 1: Environment, your agent CLIs and a team that fits them\n\nGoal: CommandMate is installed and running, the person's repository is registered, and the person has agreed to a team table built from the agent CLIs they already have.\n\n### Check\n\n```bash\nuname -s # Darwin = macOS, Linux = Linux or WSL2\nnode -v # needs v22 or newer\ngit --version\ntmux -V\ngh --version # GitHub CLI, for issues and milestones\ngh auth status # is gh signed in?\ncommand -v commandmate && commandmate --version\nclaude --version # Claude Code\ncodex --version # Codex\ncommandcode --version # Command Code\n```\n\nIf `commandmate` is installed, also run:\n\n```bash\ncommandmate status # is the server running, and at which URL?\ncommandmate ls # the worktrees CommandMate knows about\ncommandmate whoami # exit 3: you are outside CommandMate; otherwise, your own instance\n```\n\n### Run\n\n1. **Install and start CommandMate** if the check found it missing, after the person agrees. Node.js, git and tmux come first; if one is missing or too old, follow Stage 1 of https://kewton.github.io/CommandMate/setup.md for it. Then:\n\n```bash\nnpm install -g commandmate\ncommandmate init --defaults\ncommandmate start --daemon\ncommandmate status\n```\n\nIf `~/.commandmate/.env` already exists, `commandmate init --defaults` stops with \".env file already exists\": CommandMate is already configured, so skip `init`. Do not add `--force`.\n\n2. **Register the repository.** Ask the person which repository the team works on and where it is. Run `commandmate ls`. If it is not listed, the person registers it: the CLI cannot. Ask them to open CommandMate's screen, go to **Repositories \u2192 Add Repository**, and add it. The screen accepts repositories under the directory `init` set (`CM_ROOT_DIR`, by default `~/repos`); if theirs is elsewhere, tell them so, and let them choose whether to move or clone it under that directory. Adding it on the screen lists its worktrees; run `commandmate ls` again. Write down the worktree id of the repository's main checkout; this guide calls it ``, its path ``, and its branch ``.\n\n3. **Propose a team.** Build the table from the CLIs the check found, and show it to the person. Every row uses the same five roles and the same checks; only who plays each role changes.\n\n| The person has | PM | Development lead | Worker | Reviewer | Judge |\n|---|---|---|---|---|---|\n| Claude Code, Codex and Command Code | Claude Code | Claude Code | Command Code | Codex | Claude Code |\n| Claude Code and Codex | Claude Code | Claude Code | Codex | Claude Code (a session that did not do the work) | Claude Code |\n| Claude Code and Command Code | Claude Code | Claude Code | Command Code | Claude Code (a session that did not do the work) | Claude Code |\n| Command Code and Codex | Command Code | Command Code | Command Code | Codex | Command Code |\n| Claude Code only | Claude Code | Claude Code | Claude Code | Claude Code (a session that did not do the work) | Claude Code |\n| Command Code only | Command Code | Command Code | Command Code | Command Code (a session that did not do the work) | Command Code |\n\n- The reviewer is never the session that did the work. When the person has a second vendor, the reviewer comes from the other vendor than the worker; with one vendor, say plainly that the review is by the same vendor in a fresh session, which is weaker. The checks in Phase 3 are the same in every row.\n- The PM and development lead have been tried in recorded runs on Claude Code and on Command Code. A team led from Codex alone has not been: if Codex is all the person has, tell them so and ask whether to go on with Codex as PM and development lead.\n- Antigravity is not in this table (see \"Antigravity (agy)\" above).\n- The PM, the development lead, the reviewer and the judge are instances in ``, never your own instance (instruction 7). Each worker runs in its own worktree, one per issue (Phase 2 and Phase 5).\n\n### Ask the person first\n\n- Installing CommandMate and anything it needs, each with its exact command.\n- Which repository, and adding it on the screen (Repositories \u2192 Add Repository) if `commandmate ls` does not list it.\n- Which row of the table to use, or a change to it.\n- If `gh` is missing or not signed in: installing it, and signing in, which is theirs (`gh auth login` in their own terminal). They may also skip it: then, in Phase 5, ask them for the milestone's issue numbers, titles and acceptance criteria, and the team works from their answer.\n\n### Confirm it worked\n\n- `commandmate status` reports the server as running.\n- `commandmate ls` lists the repository, and you have written down ``.\n- The person agreed to one team table, and you have written down which CLI plays each role.\n\n### If it fails\n\n- `commandmate: command not found` after `npm install -g`: npm's global bin directory is not on `PATH`. Run `npm prefix -g` and show the person; the fix is in https://github.com/Kewton/CommandMate/blob/main/docs/en/user-guide/cli-setup-guide.md#command-not-found-error.\n- `EACCES` during `npm install -g`: do not retry with `sudo`. Show the person the \"Permission Error (EACCES)\" section of the same setup guide.\n- The port is already in use: `commandmate start --daemon --port 3001`, then `commandmate status`.\n- `commandmate ls` does not list the repository: it has not been added on the screen yet. Ask the person to add it under **Repositories \u2192 Add Repository**, then run `commandmate ls` again.\n- The screen refuses the path: it is outside `CM_ROOT_DIR`. Tell the person; moving or cloning the repository under that directory is their choice.\n- \"Worktree ID not found\": run `commandmate ls` and copy the ID exactly. If the worktree is really missing from the list, see \"Before every `commandmate sync`\" in Phase 2, step 6.\n\n## Phase 2: Five fixed roles and isolated worktrees\n\nGoal: each of the five roles is a CommandMate role, each team session is an instance that holds its role from the moment it starts, and the person knows how a worker gets its own worktree.\n\nA role is text CommandMate gives the session when it starts. It is an instruction to the model, not a permission: it limits nothing. What a session may run is set by its CLI's permission settings and by the person's approvals. The task contract's scope (Phase 3) does not limit it either: the scope is checked after the work, against what changed.\n\n### Check\n\n```bash\ncommandmate whoami # your own instance, if you run inside CommandMate (instruction 7)\ncommandmate roles list\ncommandmate roles defaults --repo \ncommandmate instances \n```\n\n### Run\n\n1. **Define the five roles**, after showing the person the text. Change the wording with them if they want; keep each one short:\n\n```bash\ncommandmate roles add pm --stdin <<'EOF'\nYou are the PM. You talk to the person and to the development lead only. You do not write code or edit the repository. Turn the person's request into a brief for the development lead, follow progress, and report to the person. Approvals, merges and mem decisions are the person's.\nEOF\ncommandmate roles add dev-lead --stdin <<'EOF'\nYou are the development lead. You take briefs from the PM and never ask the person directly. Hand each task to one worker under a task contract, wait for the checks, ask the reviewer to read the result, and report to the PM. Never weaken a check to make it pass.\nEOF\ncommandmate roles add worker --stdin <<'EOF'\nYou are a worker. Do the one task in your contract. Change only the files the contract says the person approved, and commit only if it says the person approved that; the scope is checked after your work, so keeping inside it is on you. If the task needs a file outside the scope, or the contract does not say you may commit, do not do it: say so and stop.\nEOF\ncommandmate roles add reviewer --stdin <<'EOF'\nYou are the reviewer. You read; you do not change files. Review the diff you are given against the issue and answer APPROVE or REJECT, with the reasons and the lines they are about.\nEOF\ncommandmate roles add judge --stdin <<'EOF'\nYou are the judge. When the PM asks, check the integrated result of a milestone against each issue's acceptance criteria on the base branch, and report GO or NO-GO per issue with what you ran. You do not change files.\nEOF\n```\n\n2. **Give each team session its role.** First read `commandmate instances `: the worktree lists the agent CLIs chosen for it (by default `claude`, `codex` and `antigravity`). A CLI id such as `command-code` can be used even when it is not listed. An id it lists gets its role with `set-role`; a new one is created with `add --id`, so you know its id. Never use your own instance (instruction 7). For the first row of the table:\n\n```bash\ncommandmate instances \ncommandmate instances add --agent claude --id claude-2 --role pm\ncommandmate instances add --agent claude --id claude-3 --role dev-lead\ncommandmate instances add --agent claude --id claude-4 --role judge\ncommandmate instances set-role codex --role reviewer\ncommandmate instances \n```\n\nWith Claude Code only, the reviewer is one more Claude Code instance: `commandmate instances add --agent claude --id claude-5 --role reviewer`. For Command Code, use `--agent command-code --id command-code-2` and so on (`instances --help` does not list `command-code` among the `--agent` values, but `add` accepts it, as `send --help` lists). If an id is taken, pick the next number. Write the ids into the team table: this guide calls them ``, ``, `` and ``.\n\n3. **Make every new worker start as a worker.** Workers run in worktrees made later, so set the role as the repository's default for the worker's CLI:\n\n```bash\ncommandmate roles default command-code --repo --role worker\n```\n\nUse the worker's tool from the table (`claude`, `codex` or `command-code`). An instance that was given a role in step 2 keeps it; the default only applies to instances that have none.\n\n4. **Send to a role, not just to an instance.** From now on, a send to a team session names the role it must hold: `commandmate send \"\" --instance --role pm`. If the session is running under another role, or CommandMate has no record of how it started, the send exits **32** and types nothing. A role is fixed when the process starts: stop it (`commandmate instances kill `, after the person agrees) and send again.\n\n5. **Permissions for the team sessions.** The PM and the development lead run `commandmate` commands. For Claude Code, all instances in `` share that worktree's `.claude/settings.local.json`; show the person these rules and add them only after they agree:\n\n```text\nBash(commandmate send:*)\nBash(commandmate ask:*)\nBash(commandmate wait:*)\nBash(commandmate reply:*)\nBash(commandmate capture:*)\nBash(commandmate verify:*)\nBash(commandmate mem:*)\nBash(commandmate brief:*)\n```\n\nFor Codex and Command Code, show the person that CLI's own permission screen and let them choose. Do not widen a permission to get past a prompt.\n\nEach worker worktree is a separate directory with its own permission settings (for Claude Code, its own `.claude/settings.local.json`). So a worker, and the development lead when it works there, will stop on permission prompts the first time it edits files or runs a check. Those prompts go to the person (Phase 5, step 3); adding rules to a worker worktree is again their choice.\n\n6. **One worktree per issue.** A worker never shares a working copy with another session. When Phase 5 starts an issue, its worktree is made next to the repository, after the person agrees:\n\n```bash\ngit -C worktree add ../-issue- -b feature/- \n```\n\nCommandMate lists the new worktree after a sync. **Before every `commandmate sync`**, this one and any retry, tell the person what it does and wait for a yes: it re-reads every repository registered on the CommandMate server that `commandmate status` shows, not only theirs; it deletes that server's records of worktrees that no longer exist in Git, in any of those repositories, and stops the sessions running in them; and it stops the global assistant session if one is running. The person may prefer to press the sync button on the screen themselves; it does the same. After the sync:\n\n```bash\ncommandmate sync\ncommandmate ls\n```\n\nThe new worktree shows up in `commandmate ls` with its own worktree id: this guide calls it ``.\n\n### Ask the person first\n\n- The text of each role, and creating the five roles.\n- Creating each instance, giving it a role, and the repository default for workers.\n- Stopping a session with `kill` so it starts again with its role.\n- Each permission rule, and which file it goes into.\n- Each new worktree and branch.\n- Each `commandmate sync`, after saying what it does on the whole server (step 6).\n\n### Confirm it worked\n\n- `commandmate roles list` lists `pm`, `dev-lead`, `worker`, `reviewer` and `judge`.\n- `commandmate instances ` lists the PM, the development lead, the reviewer and the judge as separate instances, each with its role.\n- `commandmate roles defaults --repo ` shows `worker` for the worker's tool.\n- `commandmate send \"Run commandmate whoami and tell me your role in one line.\" --instance --role pm` exits 0, and `commandmate reply --instance ` says it is the PM.\n- None of the team's instance ids is your own (instruction 7).\n\n### If it fails\n\n- Exit 2 from `roles` or `instances`: an unknown or ambiguous role, an instance not on the roster, or a tool roles do not apply to. Read the message; `commandmate roles list` and `commandmate instances ` show what exists.\n- Exit 31: the instance already exists, or the roster changed while you wrote. Read `commandmate instances ` again, then use `set-role` for an existing instance, unless it is your own (instruction 7): then pick another id.\n- Exit 32 from `send --role`: the running session holds another role or its start is not known. Ask the person, `kill` it, and send again.\n- Exit 33: the target is Antigravity. Stop; it has no place in this team.\n- The new worktree is not in `commandmate ls` after `commandmate sync`: show the person `git -C worktree list` and the output of `sync`; do not make it again under another name, and do not sync again without a new yes (step 6).\n- You notice that an instance you were about to use is your own: stop, pick another id, and tell the person.\n\n## Phase 3: Done means the checks passed\n\nGoal: the repository declares its checks in `.commandmate/verify.yaml`, a task is handed over under a contract, and `wait --verify` reports pass or fail from those checks.\n\n### Check\n\n```bash\nls /.commandmate/verify.yaml\ngit -C config user.name\ngit -C config user.email\ngit -C check-ignore -v .commandcode/ .claude/skills/cmate-x/ .agents/skills/cmate-x/\n```\n\n### Run\n\n1. **Draft the gates from the repository's own scripts and CI**, show them to the person, and write them only after they agree:\n\n```bash\ncommandmate verify init --cwd --dry-run # print the draft, write nothing\ncommandmate verify init --cwd # write it (never overwrites)\n```\n\nShow the person each gate (lint, type check, tests and so on) and change them only with their agreement.\n\n2. **Set what the checks compare against.** The checks judge a worker's work as the difference between its worktree and a base ref. Without one, they use the remote's default branch (`origin/HEAD`), which does not have this setup's commits (they are not pushed), may not be ``, and may not exist at all. So, with the person's agreement, set it to the local base branch in `.commandmate/verify.yaml`. The draft's `options:` block has a commented-out `# baseRef:` line; replace that one line with this one, indented the same, and leave the rest of the block as it is:\n\n```yaml\n baseRef: \n```\n\nA local branch works from every worktree of the repository, because worktrees share their branches.\n\n3. **Keep generated files out of the checks.** Without these lines, the contract's scope check fails every task because files the tools write appear as changes. Add them to the repository's `.gitignore` after the person agrees, only the ones for the CLIs they use:\n\n```text\n/.commandmate/*\n!/.commandmate/verify.yaml\n/.commandcode/\n/.claude/settings.local.json\n/.claude/skills/cmate-*/\n/.agents/skills/cmate-*/\n```\n\n4. **Run the checks once, before committing:**\n\n```bash\ncommandmate verify \n```\n\nAt this point the new `verify.yaml` and `.gitignore` are uncommitted changes, so they count as work and every gate runs: expect exit 0, or a failure the person recognizes as real. (After the commit in the next step, the same command exits 21: nothing differs from `` any more. That is expected.)\n\n5. **Commit only `.commandmate/verify.yaml` and `.gitignore` to ``**, after the person agrees, so every worktree made from it has the same checks. Pushing is not needed. If `git config user.name` or `user.email` is empty, ask the person for their name and email and set them only with their answer; do not invent a bot name.\n\n6. **A task contract.** The development lead writes one per task in the worker's worktree, as `.commandmate/tasks/issue-.yaml`. It states the goal, the files the worker may change, whether it may commit, and the checks that decide when it is done. The files and the commit come from the person: the PM asks them before the issue starts (Phase 5, step 1) and passes their answer down in the brief. If the brief does not say, the development lead stops and asks up through the PM instead of writing the contract.\n\nThe scope is a check made after the work, against what changed in Git. It does not stop a session from editing a file outside it: by the time the check fails, the edit has been made. So a worker keeps inside it from its instructions, and its CLI's permission prompts stay on.\n\nIn the example below, the lines in angle brackets come from the brief: copy what the person approved, not the example. The `scope` lines are an example for a person who approved `src/` and `tests/`. `autoYes: mode: off` makes sure Auto Yes never answers this task's prompts, even if someone turns it on for the worker's session; leaving it out keeps whatever is set on that session, which in this team is off.\n\n```yaml\nversion: 1\ntitle: \"Issue #: \"\ngoal: |\n Implement issue #. Change only the files the scope allows.\n \nscope:\n allow: # the files the person approved, from the brief\n - \"src/**\"\n - \"tests/**\"\nverify:\n gates: [lint, unit] # gate ids from .commandmate/verify.yaml\nautoYes:\n mode: off\nsuccess:\n requireWorkEvidence: true\n requireScopeClean: true\n```\n\nThe development lead hands it over and waits for the checks. `` is the worker's CLI id from the team table (`command-code`, `claude` or `codex`; it works in the new worktree whether or not that worktree lists it):\n\n```bash\ncommandmate send --contract .commandmate/tasks/issue-.yaml --instance \ncommandmate wait --instance --verify\n```\n\n`wait --verify` exits **0** when every gate passed, **20** when a gate failed, and **21** when there is no work to judge (no commits and no changes).\n\n### Ask the person first\n\n- Writing `.commandmate/verify.yaml`, which gates it declares, its `baseRef`, and any later change to them.\n- Editing `.gitignore`.\n- Setting `git config user.name` / `user.email`, and the commit to ``.\n\n### Confirm it worked\n\n- Before the commit, `commandmate verify ` ended with exit 0, or with a gate failure the person recognizes as real.\n- `git -C log -1 --stat` shows the commit with only `.commandmate/verify.yaml` and `.gitignore`.\n- `git -C check-ignore -v .claude/settings.local.json .claude/skills/cmate-x/` prints a rule for each.\n- `commandmate verify history` lists the run.\n\n### If it fails\n\n- Exit 20: a gate failed. `commandmate verify show ` shows which one and the end of its log. Report it; do not weaken the gate to make it pass.\n- Exit 20 with \"work-evidence: no base ref\" or \"base ref is unreachable\": `options.baseRef` is missing or names a branch that does not exist. Check the `options:` block of `verify.yaml` and `git -C rev-parse --verify `, and fix `baseRef` with the person's agreement.\n- Exit 20 from the scope check on files nobody meant to change (for example `.claude/settings.local.json`): the `.gitignore` lines from step 3 are missing or not committed to ``.\n- Exit 21 right after the commit: expected (step 4).\n- The contract is rejected (exit 2): it prints every problem, for example a gate id that is not in `verify.yaml`. Fix the contract, not the gates.\n- `verify init` finds nothing to draft from: ask the person which commands they run to check their work, and write those as gates with their agreement.\n\n## Phase 4: mem, the restart brief, screen-only approval, and the instructions file\n\nGoal: each session writes what it cannot leave anywhere else into `mem`, a restarted session picks up from a brief, decisions wait for the person on the screen, and the repository's instructions file tells every session these rules.\n\n### Check\n\n```bash\ncommandmate mem mode --worktree \ncommandmate skill list\n```\n\n### Run\n\n1. **Turn `mem` on \u2014 the person does it, on the screen.** The mode can only be changed on CommandMate's screen: **Repositories \u2192 the repository's \"mem\"**, as rules for branch names. Ask the person to set it to `on` for `` and for the workers' branches (for example `feature/**`), and to turn on \"Insert at start\" so a restarted session gets its brief with the first message. Then confirm it:\n\n```bash\ncommandmate mem mode --worktree # should say on\n```\n\n2. **Skills from the official Catalog**, if they help this team. Run `commandmate skill list`. For each Skill the person wants (for example `cmate-delegate`, for one session to ask another, or `cmate-verify`, for the checks), pick the version from `commandmate skill info `, show the plan, and install after they agree:\n\n```bash\ncommandmate skill install --worktree --version --dry-run\ncommandmate skill install --worktree --version --yes\n```\n\nA Skill marked high-risk also needs `--ack-risk @`: explain what it acknowledges and ask first. Skills are read when a session starts, so the sessions need a restart afterwards. Nothing in this guide depends on a Skill: the template below is enough on its own.\n\n3. **Write the team rules into the instructions file** the sessions read (`CLAUDE.md` for Claude Code, `AGENTS.md` for Codex and Command Code; both if the team uses both), after the person agrees. Fill in the instance ids from the table:\n\n```markdown\n## Team\n\n| Role | Instance | Talks to |\n|---|---|---|\n| PM | `` | the person, the development lead |\n| Development lead | `` | the PM, workers, the reviewer |\n| Worker | one per issue worktree | the development lead |\n| Reviewer | `` | the development lead |\n| Judge | `` | the PM |\n\n- At the start, run `commandmate whoami`, find your instance id in the table, and say your role in one line. If you are not in the table, say so and stop.\n- The person talks to the PM only. The PM never sends to a worker; the development lead never asks the person. Questions and approvals go up through the PM.\n- A brief from the PM has five parts: the issue; what the person approved for it (the files that may change, and whether the worker may commit); how far merging is allowed (default: none; stop and report \"mergeable\"); when to stop; and the last line of the report (`DONE: ` or `STOP: `).\n- The development lead writes the person's approval into the contract and hands nothing more down. If a brief does not say what the person approved, or the work needs more than that, stop there and report up through the PM; do not start or widen it.\n- A contract's scope is checked after the work; it does not stop an edit. Keep inside it yourself. Every contract says `autoYes: mode: off`.\n- Making a worktree and `commandmate sync` are the development lead's, and each needs the person's yes first, through the PM. Before asking, say what `sync` does: it re-reads every repository registered on the CommandMate server, not only this one, deletes its records of worktrees that no longer exist in Git and stops their sessions, and stops the global assistant session. The person may press sync on the screen instead.\n- Done means `commandmate wait --instance --verify` exited 0. Report 20 or 21 as they are; never weaken a check.\n- The PM's report starts with one line that says whether the person has to do anything (\"Nothing needs your attention now.\" or \"2 decisions are waiting for you.\"), then each decision with its options, the recommended one first.\n- When a session you asked stops on a question or a permission prompt (`wait` or `ask` exits 10), do not answer it for that session: report it up. The person answers it on CommandMate's screen.\n- Merging is the person's.\n\n## mem and restarts\n\n- Keep in mem only what CommandMate cannot know itself: what you intend (`commandmate mem now \"\"`), what you wait for, the next step, and decisions. Use `commandmate mem add --kind --text \"\"`, with `--close-when` for waiting, next and external items.\n- A decision goes in as `commandmate mem add --kind decision --text \"\" --promote-to issue:#`. Only the person approves it, on CommandMate's screen. You never approve a decision and never write it into the Issue yourself.\n- When your context is getting long, or after the agent CLI was updated, write your state into mem and tell the PM; the person restarts the session. After a restart, read your brief first (`commandmate brief`) if it was not given with the first message.\n\n## Antigravity\n\n- No agent sends, asks, responds or relays to Antigravity (agy), and Auto Yes is never turned on for it (Google Antigravity Additional Terms of Service, Section 6: https://antigravity.google/terms).\n```\n\nCommit the instructions file to `` after the person agrees, so new worktrees have it.\n\n4. **Restart the team sessions once**, after the person agrees, so they read the instructions and the Skills: `commandmate instances kill ` for each team instance (never your own, instruction 7), and the next `send --role` starts it again with its role.\n\n### Ask the person first\n\n- Turning `mem` on, which they do themselves on the screen, and for which branches.\n- Each Skill, after showing the `--dry-run` plan; `--ack-risk` for a high-risk one.\n- Writing and committing the instructions file.\n- Restarting the sessions.\n\n### Confirm it worked\n\n- `commandmate mem mode --worktree ` says `on`.\n- `commandmate brief --worktree --instance ` prints a brief (exit 0).\n- Each team session, asked to run `commandmate whoami`, states the role the table gives it.\n\n### If it fails\n\n- `mem` commands exit 50: the mode is not `on` for that branch. Ask the person to check the rule on the screen; you cannot change it.\n- `brief` exits 50: the same; exit 52: the worktree or instance id is wrong (`commandmate instances `).\n- `skill install` exits 12: it was not confirmed (no `--yes`, or a high-risk Skill without `--ack-risk`). Ask again rather than adding flags on your own. Exit 11: the worktree has local changes in the way; show the person `git status`.\n- A session does not follow the instructions file: it started before the file was written. Restart it, after the person agrees.\n\n## Phase 5: The first GitHub Milestone\n\nGoal: the PM takes one issue from a GitHub Milestone through the development lead and a worker, and the issue's work passes the checks.\n\n### Check\n\nAsk the person first which GitHub repository the team's issues are in (step 1), then:\n\n```bash\ngh issue list --repo / --milestone \"\" --state open\ncommandmate instances \ncommandmate mem mode --worktree \n```\n\n### Run\n\n1. **Agree on the run.** Ask the person:\n - Which GitHub repository: its host (for example `github.com`) and `/`, in their words. Do not work it out from the Git remotes yourself: a checkout can have more than one (a fork and its upstream), and a remote URL can hold a credential. Show them the host and `/` you will use and let them confirm it. Use that same one for every `gh` command, reading and changing alike: `--repo /` on `github.com`, `--repo //` on another host, and `gh api --hostname ` there.\n - Which GitHub Milestone. Without `gh` (Phase 1), ask for its issue numbers, titles and acceptance criteria instead, and put them in the brief. If there is no milestone yet, suggest a small trial milestone with one or two small issues; create it and move the issues only after they agree (`gh api repos///milestones -f title=\"\"`, then `gh issue edit --repo / --milestone \"\"`).\n - Which issue goes first.\n - What the worker may do for it: which files may change (for example `src/` and `tests/`) and whether it may commit in its own worktree. The PM passes this down in the brief; the development lead writes it into the contract. Without an answer, the team stops before the work starts.\n - The deadline, with its time zone, and when to stop (for example: a check fails twice, a change outside the contract's scope is needed, or an approval is needed).\n - How far merging is allowed. The default is none: the PM reports \"mergeable\" and the person merges.\n\n2. **Brief the PM.** Send the person's answers as one brief:\n\n```bash\ncommandmate send \"Milestone , issue # first. Ask the development lead to take it through one worker in its own worktree, under a contract with our checks, then have the reviewer read it. I approved: changes under only, and commits in the worker's worktree ; nothing else. Merging: none, report mergeable. Stop if a check fails twice, a change outside the scope is needed, or an approval is needed. Deadline