/** * Setup guide for agents (Issue #3059) * * The page the landing page's one-line prompt points an agent at: * https://kewton.github.io/CommandMate/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 setup`. * * Do not edit this constant by hand: edit `website/setup.md` and copy it here. * `tests/unit/cli/commands/docs-setup-3059.test.ts` fails when the two differ * by a single byte. */ export declare const SETUP_GUIDE = "# Set up CommandMate 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 CommandMate on their machine. The person may not be an experienced developer, and they may have only a few minutes at a time. Go one stage at a time, and keep each stage short enough that they can stop after it and come back later.\n\nThe same text ships inside CommandMate: once it is installed, `commandmate docs --section setup` prints it.\n\n**This guide or the team guide?** This guide sets up CommandMate itself: install, pairing a phone, and one agent at a time. If the person wants a development team \u2014 one to three vendors' agent CLIs in the five fixed roles (a PM, a development lead, workers, a reviewer and a judge), with the `roles` command (a send to the wrong role exits 32), `mem` and the restart brief \u2014 use the team guide instead: https://kewton.github.io/CommandMate/team-setup.md (`commandmate docs --section team-setup`). The team guide installs CommandMate first if it is missing, then builds the team.\n\n**If the person names stages, do those stages here.** A prompt that names them (the landing page's Level 3 asks for Stages 4 to 6) takes priority over this fork: do the stages they named in this guide, and do not switch them to the team guide on your own. Offer the team guide only when they want a whole team and have not named the stages.\n\n## Instructions for the agent reading this\n\n1. **Explain each stage before you start it.** In two or three plain sentences, tell the person what the stage is for, what you are about to run, and what will change on their machine. Then run it.\n2. **Never run an \"Ask the person first\" step without a clear yes.** Each stage lists them. Ask in plain words, say what it installs or opens 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.\n4. **Do not answer for the person.** Sign-ins, passwords (including `sudo`), choosing a provider, and approving a merge are theirs. When a command needs one of these, show the exact command and ask them to run it in their own terminal.\n5. **Stay inside this guide.** Use only commands shown here, `commandmate --help`, 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 named here (npm, the operating system's package manager, nodejs.org).\n6. **Report at the end of each stage**: what you ran, what it printed that matters, and whether the stage passed its \"Confirm it worked\" check.\n7. **Do Stage 2 (Pair your phone) last, unless the person asks for it now.** Stages 3 to 6 run `commandmate` on this machine's CLI. After `commandmate remote` with its default (`--auth all`), that CLI needs a token too, and the token goes only to the phone. So finish Stages 3 to 6 first, then pair the phone. Stage 2 explains the choice if the person wants the phone sooner.\n8. **If you are Codex: your shell has no network by default.** If fetching this guide or an `npm` 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 stage you are in, ask before any of these:\n\n- Installing anything: Node.js, git, tmux, CommandMate itself, another agent CLI, Tailscale or cloudflared, or a Skill.\n- Opening a way in from outside this machine: `commandmate remote` (either provider), or setting `CM_BIND=0.0.0.0`. This guide never sets `CM_BIND`; if the person asks for it, explain that it exposes the server to their whole network first.\n- Turning on Auto Yes: `commandmate auto-yes --enable`, or `commandmate send ... --auto-yes`.\n- Merging a pull request.\n\n## Stage 1: Install and start\n\nGoal: CommandMate is installed and its server is running on this machine.\n\n### Check\n\n```bash\nuname -s # Darwin = macOS, Linux = Linux or WSL2\ngrep -i microsoft /proc/version # prints a line only inside WSL2 (Linux only)\nnode -v # needs v22 or newer\nnpm -v\ngit --version\ntmux -V\ncommand -v brew # macOS: is Homebrew present?\ncommand -v commandmate && commandmate --version\n```\n\nWrite down which of these are missing or too old. Native Windows is not supported; on Windows, CommandMate runs inside WSL2 (see https://github.com/Kewton/CommandMate/blob/main/docs/en/user-guide/wsl2-setup.md).\n\n### Run\n\nInstall only what the check found missing, after the person agrees.\n\n- **macOS with Homebrew**: `brew install node git tmux` (leave out what is already there).\n- **macOS without Homebrew**: tmux needs a package manager. Tell the person that, and let them decide whether to install Homebrew from its own official instructions. Do not install it for them. git alone can come from Apple's tools: `xcode-select --install`.\n- **Linux / WSL2 (Debian or Ubuntu)**: `sudo apt update && sudo apt install -y git tmux`. The `sudo` password is the person's to type. If `node -v` is missing or older than v22, the distribution's package is usually too old: tell the person and use the official Node.js download (https://nodejs.org/en/download) in the way they choose.\n\nThen install and start CommandMate:\n\n```bash\nnpm install -g commandmate # the global install: for daily use\ncommandmate --version\ncommandmate init --defaults # writes ~/.commandmate/.env; repositories go under ~/repos\ncommandmate start --daemon\n```\n\n**`npx commandmate@latest` versus the global install.** `npx commandmate@latest` is the one-line way for a person to try CommandMate in their own terminal: it asks its setup questions and opens the browser. It needs an interactive terminal, so when you run it from your tool it only prints help. Use the global install above when you are the one running the commands, and for anything the person will keep using.\n\n### Ask the person first\n\n- Each tool you are about to install (Node.js, git, tmux), and the exact command.\n- `npm install -g commandmate`.\n- If `~/.commandmate/.env` already exists, `commandmate init --defaults` stops with \".env file already exists\": CommandMate is already configured, so skip `init`. Do not add `--force` without asking: it replaces their settings.\n\n### Confirm it worked\n\n```bash\ncommandmate status # reports the server as running, with its URL\n```\n\nTell the person to open the URL it prints (by default http://localhost:3000) in their browser.\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- The server does not start: `commandmate status`, then `commandmate stop --force` and `commandmate start --daemon` again. Read what it prints rather than retrying blindly.\n\n## Stage 2: Pair your phone\n\nGoal: the person scans a QR code with their phone and sees CommandMate there.\n\n`commandmate remote` makes this server reachable from outside the machine through a provider, and prints a QR code that pairs one phone. There are two providers, and **the person chooses which one**:\n\n| | Tailscale (`--provider tailscale`) | Cloudflare (`--provider cloudflare`) |\n|---|---|---|\n| Who can reach it | Only devices signed in to the person's own Tailscale network (tailnet) | Anyone with the URL: it is a public address on the internet |\n| What protects it | The tailnet, plus CommandMate's token login | A one-time pairing code (single use, expires in 10 minutes by default), plus CommandMate's token login |\n| Needs | The Tailscale app on this machine and on the phone, both signed in to the same account, with HTTPS (Serve) available | `cloudflared` installed on this machine; no account |\n| Approval | No public-tunnel approval | A public tunnel: `--yes` only after the person agrees |\n\nExplain both in plain words and ask which one they want. If they cannot decide, Tailscale keeps the server off the public internet; Cloudflare needs fewer accounts.\n\n**When to do this stage.** By default (`--auth all`), once `commandmate remote` runs, the `commandmate` CLI on this machine also needs a token, and the token goes only to the phone. Stages 3 to 6 run on that CLI, so they stop working. Ask the person which they want:\n\n- **Pair the phone last (recommended).** Skip to Stage 3 now, and come back to this stage after Stage 6.\n- **Pair the phone now, and keep the CLI on this machine.** Add `--auth remote-only` to the `commandmate remote` command below. Only the phone's route then needs the token: every process on this machine, agents included, can operate CommandMate without logging in. Say that plainly before they choose it.\n\n### Check\n\n```bash\ncommandmate status # is the server running, and with authentication?\ncommandmate remote status # is a remote session already recorded?\ntailscale status # Tailscale: installed and signed in?\ncloudflared --version # Cloudflare: installed?\n```\n\n### Run\n\n1. Install the chosen provider if the check found it missing, after the person agrees:\n - **Cloudflare**: on macOS `brew install cloudflared`; on Linux, from Cloudflare's official package repository for their distribution.\n - **Tailscale**: the person installs the Tailscale app from Tailscale's official distribution on this machine and on their phone, and signs in themselves. Signing in is theirs to do.\n2. If `commandmate status` showed the server running, stop it first, so `remote` can start it again with authentication: `commandmate stop`.\n3. Publish and pair:\n\n```bash\ncommandmate remote --provider tailscale\n# or, only after the person agreed to a public URL:\ncommandmate remote --provider cloudflare --yes\n```\n\n`remote` starts the server itself, publishes it, and prints the QR code. Show the person the QR code and tell them to scan it with the phone's camera. If the output is too narrow for a QR code, it prints a URL instead: that URL contains the pairing code, so give it only to the person and do not save it to a file or a log.\n\nIf the QR code cannot be read, or scanning it does not get the person in, have them copy the pairing URL and paste it into the address bar of the phone's browser. Pasting the link into the address bar is the way that worked in the hands-on check; do not save the link to a file.\n\nWhen you hand the link or QR to the person, also tell them the time it expires: `remote` and `remote pair` print a `Pairing expires: HH:MM (in N m), works once` line, and `pairing.expiresAt` in `--json` is the same time. If it has passed, run `commandmate remote pair` (only works while the code is unused), otherwise `commandmate remote stop` and then `commandmate remote`.\n\nTo get the link as text again without reopening the tunnel, run `commandmate remote pair` (or `commandmate remote pair --json` and read `pairingUrl`). The URL stays the same, and it works only while the code is unused.\n\n### Ask the person first\n\n- Which provider: Tailscale or Cloudflare.\n- Installing that provider.\n- Running `commandmate remote` at all: it opens a way in from outside this machine.\n- Pairing now or after Stage 6, and, if now, whether to add `--auth remote-only`.\n- `--yes`: only after they agreed to the public Cloudflare URL. Never add `--yes` to get past a question they have not answered.\n\n### Confirm it worked\n\n- The person says the phone opened CommandMate.\n- `commandmate remote status` shows `Pairing: consumed`.\n\nTo close the way in later: `commandmate remote stop`. The server keeps running.\n\n### If it fails\n\n- Exit 1, \"no provider is usable\": read the reason it prints. For Tailscale it is usually \"not connected\" (the person has not signed in) or \"no MagicDNS name\". Do not switch to Cloudflare without asking: that changes who can reach the machine.\n- Exit 2 without a terminal: Cloudflare needs `--yes`, or a server is running that `remote` has to restart. Ask the person, then run `commandmate stop` and try again.\n- Exit 2, \"a server with authentication is already running\": `commandmate stop`, then `commandmate remote` again.\n- The QR code is cut off in the agent's chat pane, or the person lost it, and it has not been used yet: run `commandmate remote pair`. The public URL stays the same and the earlier link stops working. The new code keeps the original expiry time.\n- The code expired or was already used: run `commandmate remote stop`, then `commandmate remote` again for a new QR code (`remote pair` prints nothing for a used or expired code). `--pairing-expires 30m` gives a slower person more time.\n- After pairing, the browser on this machine asks for a login and the CLI stops answering: that is the default `--auth all`. Do not look for a way to give the token to the CLI. Ask the person to choose: run `commandmate remote stop` and finish Stages 3 to 6 on this machine first, or pair again with `--auth remote-only` (every process on this machine can then operate CommandMate without logging in).\n\n## Stage 3: Add a second agent\n\nGoal: a second agent CLI, for example Command Code or Codex, can work in one of the person's repositories through CommandMate.\n\nBefore Stages 3 to 6: CommandMate needs at least one of the person's repositories registered. The CLI cannot register one; the person does it in the browser, under **Repositories \u2192 Add Repository**.\n\n### Check\n\n```bash\nclaude --version\ncodex --version\ncommandcode --version # Command Code\ncommandmate ls # the worktrees CommandMate knows about\n```\n\nIf `commandmate ls` lists nothing, the person has not registered a repository yet. CommandMate only manages repositories under `~/repos` (the `CM_ROOT_DIR` that `init` set). Ask the person to open **Repositories \u2192 Add Repository** in the browser and add one, or to tell you where their repository is so you can check whether it is under that directory. Then run `commandmate sync` and `commandmate ls` again.\n\n### Run\n\nInstall the CLI the person picked, after they agree:\n\n```bash\nnpm install -g command-code # Command Code; CommandMate runs it as `commandcode`\nnpm install -g @openai/codex # Codex\n```\n\nSigning in to the CLI is the person's: ask them to run `commandcode` (or `codex`) once in their own terminal and finish its sign-in. Then add it to a worktree and give it a first, small message:\n\n```bash\ncommandmate instances add --agent command-code\ncommandmate instances \ncommandmate send \"Read the README and summarize this repository in three lines.\" --instance command-code\ncommandmate wait --instance command-code --timeout 600\ncommandmate reply --instance command-code\n```\n\nFor Codex, use `--agent codex` and `--instance codex`.\n\nThe first time Codex starts in a worktree it shows two confirmation screens. Show them to the person with `commandmate capture --instance codex`; do not answer them yourself.\n\n- `Trust this folder?`: whether Codex may work in this folder.\n- `Hooks need review (5 hooks are new or changed)`: these hooks are not from the repository. CommandMate wrote them into `~/.codex/hooks.json` itself, marked with `# commandmate:agent-hooks`, and they only send Codex's events to CommandMate on localhost. Check this with `grep -n 'commandmate:agent-hooks' ~/.codex/hooks.json` before you say where they came from. If the person does not trust them, Codex still works, but CommandMate cannot receive Codex's state as events, so `wait` and the status shown in the browser are less accurate.\n\n### Ask the person first\n\n- Which CLI to add, and installing it.\n- The sign-in, which they do themselves.\n- Do not turn on Auto Yes (`--auto-yes`, `commandmate auto-yes --enable`) to get past the CLI's own confirmations. If it stops on a question, show the person with `commandmate capture --instance command-code` and let them answer.\n\n### Confirm it worked\n\n- `commandmate instances ` lists the new instance.\n- `commandmate reply --instance command-code` prints its answer.\n\n### If it fails\n\n- \"is not installed or not in PATH\": the message names the install command. Run `commandcode --version` to check, and ask before installing.\n- `wait` exits 10: the agent is waiting on a question (often its own sign-in or a permission). Show the person `commandmate capture --instance command-code`.\n- `wait` exits 124: it timed out. Check `commandmate capture` before waiting again.\n- \"Worktree ID not found\": run `commandmate sync`, then `commandmate ls`, and copy the ID exactly.\n\n## Stage 4: Give your team a PM\n\nGoal: one session plans the work and hands tasks to the others. That session is the lead. Skills from CommandMate's official Catalog teach it the method. In Stages 4 and 5 this one session does everything and is called the lead; Stage 6 then splits it into a PM and a development lead.\n\n**Stages 4 to 6 are the short form.** They build the team by hand: roles written as sections in the instructions file, compared with the IDs `commandmate whoami` prints, with a PM, a development lead and a worker. For the five fixed roles as CommandMate roles (`commandmate roles`, a send to the wrong role exits 32), with `mem`, the restart brief and isolated worktrees, use the team guide instead: https://kewton.github.io/CommandMate/team-setup.md (`commandmate docs --section team-setup`). Do the stages here when the person named them; offer the team guide when they want a whole team and have not.\n\n### Check\n\n```bash\ncommandmate skill list # what the Catalog offers\ncommandmate skill info cmate-orchestrate # versions, risk, compatibility\ncommandmate skill status cmate-orchestrate --worktree \n```\n\n### Run\n\nPick the exact version from `skill info`, show the person the plan, and install after they agree:\n\n```bash\ncommandmate skill install cmate-orchestrate --worktree --version --dry-run\ncommandmate skill install cmate-orchestrate --worktree --version --yes --ack-risk cmate-orchestrate@\n```\n\n`cmate-orchestrate` is a high-risk Skill: it needs `--ack-risk @` in addition to `--yes`. A Skill that is not high-risk needs only `--yes`. The Skill lands in `.agents/skills/` and `.claude/skills/` of that worktree.\n\nAn agent reads its Skills when its session starts, so the lead session has to start again. Ask the person whether to restart it from the worktree screen; if they prefer the CLI, `commandmate instances kill ` stops it and the next `commandmate send` starts it again.\n\nThen ask the lead in plain words. For example, sent to the lead session (in Claude Code the Skill is also available as `/cmate-orchestrate`):\n\n```bash\ncommandmate send \"Use the cmate-orchestrate skill to plan issues #12 and #13. Show me the plan; do not run anything that changes the repository yet.\" --instance claude\n```\n\nThe plan step changes nothing. Steps that change something run only when the person approves them.\n\nCommand Code's plan mode (Command Code only; this workaround can be removed once #3125 is fixed): if the lead enters plan mode, it stops on a REVIEW screen and CommandMate cannot send a comment to it from the CLI. When you only want a plan, ask in plain words as above and do not have the lead enter plan mode.\n\n### Ask the person first\n\n- Installing each Skill, after showing the `--dry-run` plan. Say plainly that `cmate-orchestrate` is marked high-risk and what `--ack-risk` acknowledges.\n- Restarting the lead session.\n- Every approval the lead asks for, and every merge. You never approve or merge on the person's behalf.\n\n### Confirm it worked\n\n- `commandmate skill status cmate-orchestrate --worktree ` reports it as installed.\n- The lead's reply (`commandmate reply --instance claude`) shows a plan.\n\n### If it fails\n\n- `skill install` exits 2: `--version` is missing or does not exist. Copy it from `skill info`.\n- Exit 12: the install was not confirmed: no `--yes`, or a high-risk Skill without `--ack-risk`. Ask again rather than adding flags on your own.\n- Exit 11: the worktree has local changes in the way. Show the person `git status` in that worktree.\n- Exit 1: the server or the Catalog could not be reached. Check `commandmate status`.\n- The agent does not know the Skill: its session started before the install. Restart it.\n\n## Stage 5: Let checks decide what's done\n\nGoal: \"done\" means the repository's own checks passed, not that an agent said so.\n\n### Check\n\n```bash\nls .commandmate/verify.yaml # in the repository: are gates declared?\ncommandmate skill status cmate-verify --worktree \n```\n\n### Run\n\n1. Declare the gates. Either install the `cmate-verify` Skill (as in Stage 4, after the person agrees) and ask the lead to write `.commandmate/verify.yaml` with it, or draft it from the repository's CI definitions:\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 the gates (lint, type check, tests and so on) and change them only with their agreement.\n\nBefore handing over a task that commits, check that git knows who is committing: `git config user.name` and `git config user.email` in the repository (a worker's commit fails when they are empty). If they are empty, ask the person for their name and email, and set them only with their answer. Do not let a worker invent a bot name. The person may also choose to have the worker leave the changes uncommitted.\n\n2. Run the gates once on the worktree as it is:\n\n```bash\ncommandmate verify \n```\n\n3. Hand a task over under a contract, and let the gates judge it. A contract is a YAML file in the repository, `.commandmate/tasks/.yaml`, that states the goal, the files the agent may change, and the checks that decide when it is done:\n\n```yaml\nversion: 1\ntitle: \"Issue #12: \"\ngoal: |\n Implement issue #12. Commit when the work is done.\nscope:\n allow:\n - \"src/**\"\n - \"tests/**\"\nverify:\n gates: [lint, unit] # gate ids from .commandmate/verify.yaml\nsuccess:\n requireWorkEvidence: true\n requireScopeClean: true\n```\n\n```bash\ncommandmate send --contract .commandmate/tasks/issue-12.yaml --instance command-code\ncommandmate wait --instance command-code --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- Installing `cmate-verify`, and writing `.commandmate/verify.yaml` into their repository.\n- Which gates to declare, and any later change to them.\n- Merging the result. A passed gate means the checks passed; whether to merge is still the person's decision.\n\n### Confirm it worked\n\n- `commandmate verify ` ends with exit 0, or with a gate failure the person recognizes as real.\n- `commandmate verify history` lists the run.\n\n### If it fails\n\n- `verify` exits 21 right away: the worktree has no work yet. That is expected before a task.\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- 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\n## Stage 6: Hand the work to a PM\n\nGoal: the person talks to one PM session. The PM does not write code: it asks a development lead, the development lead hands one task to a worker under a contract, and the checks decide when it is done. The PM then tells the person, in the first line, whether they have to do anything.\n\nStages 4 and 5 used one lead session. Here you keep that session as the development lead and add a separate PM next to it. The roles are written into the repository's instructions file, and each session compares the IDs `commandmate whoami` prints with those sections and states its own role. The role templates are in https://github.com/Kewton/CommandMate/blob/main/docs/en/user-guide/team-roles.md (Japanese: https://github.com/Kewton/CommandMate/blob/main/docs/user-guide/team-roles.md).\n\n**For a whole team, use the team guide.** This stage builds a PM, a development lead and a worker, keeping the roles in the instructions file. The team guide sets up the five fixed roles (a PM, a development lead, workers, a reviewer and a judge) as CommandMate roles, through the `roles` subcommand, so a send names the role it must hold and one that does not hold it exits 32, and it adds `mem`, the restart brief and one worktree per worker: https://kewton.github.io/CommandMate/team-setup.md (`commandmate docs --section team-setup`). Do this stage when the person named it; offer the team guide when they want a whole team and have not.\n\n**Out of scope here.** Creating one worktree per issue, `profile-init.mjs` and `commandmate sync` are the full `cmate-orchestrate` workflow. This stage hands one task to a worker in a worktree that already exists, as in Stage 5. For the full workflow, read the `cmate-orchestrate` Skill's own documents after this stage.\n\n### Check\n\n```bash\ncommandmate instances # which instances the worktree has\ncommandmate skill status cmate-delegate --worktree \ncommandmate skill status cmate-orchestrate --worktree # from Stage 4\nls .commandmate/verify.yaml # from Stage 5\ngit check-ignore -v .commandcode/ .claude/skills/cmate-x/ .agents/skills/cmate-x/ # each path should print a rule\n```\n\n### Run\n\n1. Add the PM as a separate instance. Keep the lead from Stage 4 as the development lead. Use the instance id that `add` prints:\n\n```bash\ncommandmate instances add --agent claude\n```\n\n2. Install `cmate-delegate` for the PM, the way Stage 4 installed a Skill: pick the version from `commandmate skill info cmate-delegate`, show the `--dry-run` plan, install after the person agrees, and restart the PM session so it reads the Skill.\n\n3. Give the PM permission to run only the two commands it needs. The person adds these rules to the PM session's permission settings (for Claude Code, `.claude/settings.local.json` or the `/permissions` screen). Show them the exact text and let them add it:\n\n```text\nBash(commandmate send :*)\nBash(commandmate ask :*)\n```\n\n4. Make git ignore what the Skills generate. Without this, the contract's scope gate (`requireScopeClean`) fails every task because those files appear as changes. Add these lines to the repository's `.gitignore` after the person agrees, and add only the ones for the agents they use:\n\n```text\n/.commandcode/\n/.claude/skills/cmate-*/\n/.agents/skills/cmate-*/\n```\n\n5. Write the roles into the instructions file that the sessions read (`CLAUDE.md`, `AGENTS.md` and so on). Use the templates in `team-roles.md`: one section each for the PM, the development lead and the worker. Then ask each session to run `commandmate whoami` (it prints the worktree, the instance id, the tool and the alias, not a role), compare the instance id with the role sections, and say in its own words which role it has.\n\n6. Hand one task through the whole chain. From this machine, ask the PM in plain words. The PM asks the development lead with `commandmate ask`; the development lead hands one task to one worker under a contract and waits for the gates, exactly as in Stage 5 (`send --contract`, then `wait --verify`):\n\n```bash\ncommandmate send \"Ask the development lead to take issue #12 through one worker, under a contract with our verify gates. Do not write code yourself. When it is done, report to me: line 1 says whether I have to do anything, then what happened.\" --instance \n```\n\n7. **Merging stays with the person.** The default is that the person merges. A PM may be allowed to merge under conditions, but only if the person chooses that and has it written into the PM's instructions file as an operating rule. It is not a switch in the product. A rule of that kind says, for example: merge only when the head is the commit the checks verified, every gate passed, CI is green and the review has no blocker; if any of these is missing, or the change loosens a gate or a judgement, hand it back to the person. The product itself guarantees only that the checks passed and CI is green; the PM has to confirm the head and the review. Do not write this rule into the instructions file unless the person asked for it.\n\n8. If the person wants the PM to keep going while they are away, use a time-boxed run. Ask for it in absolute terms, for example: \"Work until 09:30 JST today. You may do X and Y, and nothing else. If you stop, report what is done and what is left.\" State the time and the time zone, what the PM may do, and what it must report when it stops. Match Auto Yes to the remaining time. It is not a security boundary:\n\n```bash\ncommandmate auto-yes --enable --duration 3h --instance --stop-pattern 'DONE:|BLOCKED:'\n```\n\n`--duration` takes whole hours from 1h to 24h, so pick one that ends no later than the deadline. `--stop-pattern` is a regular expression matched against the terminal output. It stops Auto Yes early when the pattern shows up and cannot forbid a command from running. Anything the person must not allow belongs in the contract's scope and in their own approval.\n\n### Ask the person first\n\n- Installing `cmate-delegate`, after showing the `--dry-run` plan, and restarting the PM session.\n- Adding the two permission rules to the PM session, and editing `.gitignore` and the instructions file.\n- Turning on Auto Yes, and the deadline, the time zone and what the PM may do during a time-boxed run.\n- Letting the PM merge under conditions. Do not suggest it as the default.\n- Every merge otherwise. You never approve or merge on the person's behalf.\n\n### Confirm it worked\n\n- `commandmate instances ` lists the PM and the development lead as separate instances.\n- In each session, the instance id from `commandmate whoami` matches one role section, and the session states that role itself.\n- The worker's contract run ends with `commandmate wait --instance --verify` exiting 0.\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.\"), and lists each decision with the options to choose from.\n\n### If it fails\n\n- `ask` or `send` exits 99: first find out whether anything was sent. Read what the CLI printed to stderr: it states when nothing was sent (for example a prompt that was not ready) and when the message may already be in. Then look at the other session with `commandmate capture --instance `. Send again after a minute only when stderr says nothing was sent. Exit 99 also comes from a server error, from a send whose outcome is unknown, and from a failure while `ask` waits after it has sent. If neither stderr nor the screen settles it, treat it as unconfirmed and do not send again; tell the person.\n- The PM stops at a permission question for `commandmate send` or `commandmate ask`: the rule from step 3 is missing or does not match the worktree id. Show the person the exact rule.\n- The gates fail every task on files you did not touch: the ignore lines from step 4 are missing.\n- Auto Yes ended before the deadline: `--duration` is shorter than the time left, or the stop pattern matched. Check `commandmate auto-yes `, tell the person, and do not turn it on again without asking.\n- A session cannot find its instance id in the role sections, or states a different role: the instructions file has no section for that id, or the id in it is wrong. Fix the file and ask the session to read it again; restart it only if it does not pick the file up.\n- Exit 20 or 21 from `wait --verify`: see Stage 5. Report it to the person through the PM; do not weaken the gate.\n\n## Where to read more\n\n- CommandMate on GitHub: https://github.com/Kewton/CommandMate\n- CLI operations guide, every flag and exit code: https://github.com/Kewton/CommandMate/blob/main/docs/en/user-guide/cli-operations-guide.md\n- Roles for a PM, a development lead and a worker: https://github.com/Kewton/CommandMate/blob/main/docs/en/user-guide/team-roles.md\n- A worked example of a team: https://github.com/Kewton/commandmate-team-demo\n- The project site: https://kewton.github.io/CommandMate/\n"; //# sourceMappingURL=setup-guide.d.ts.map