One command installs the agent rules where agent tools read them #620

Part of #157.

Scope

An operator runs simlock setup once and every later Claude Code or Codex session has a small simlock skill. The skill tells the agent what Simlock is, when to use it, to check its setup with simlock whoami, and to run simlock instructions for the rules. In a terminal, setup asks for the scope and, per tool, whether to connect Simlock's MCP server too; flags answer both for scripts.

Start from origin/feature/157 commits d990d7d3f, ee5262d58, 0fdcdc96d: src/instructions/setup.ts and its tests carry over. Change the Codex paths, replace the copied rules with the router, add the prompts and the MCP step, and re-port the CLI part to src/cli/commands/ (#147 F2).

The task is about 10 Tests lines; it stays one PR because the prompts, the MCP step and the report share one report shape and one command.

In short

simlock setup writes SKILL.md into a simlock directory under each tool's skills directory, for the user (home) or the project (current directory). The skill holds no rules, so it stays right after an upgrade. Simlock's MCP server is connected only after a yes or --mcp, by running the tool's own mcp add command. If it goes wrong, an agent starts without the skill, or a file outside the simlock directory changes.

flowchart LR
  O[Operator] --> S[simlock setup]:::changed
  S -->|asks in a terminal| P[scope, MCP per tool]:::changed
  S -->|writes| K[skills/simlock/SKILL.md]:::changed
  S -->|on yes or --mcp| C[claude/codex mcp add]:::changed
  A[Next agent session] -->|loads| K
  A -->|runs| I[simlock instructions]
  classDef changed stroke-width:3px

Session, after (on a machine with ~/.claude and no ~/.codex):

$ simlock setup
Install only for this project (not every project)? [y/N]
Also connect Simlock's MCP server to Claude Code? [y/N] y
claude-code  skill  wrote      /Users/me/.claude/skills/simlock
claude-code  mcp    connected
codex        skill  skipped    /Users/me/.agents/skills/simlock  (Codex not found here; pass --tool codex to install anyway)

$ simlock setup --project --tool codex --mcp --json
{"scope":"project","tools":[{"tool":"codex","skill":{"status":"wrote","path":"/work/app/.agents/skills/simlock"},"mcp":{"status":"skipped","reason":"codex mcp add has no project scope"}}]}

Before, every one of these is {"error":{"code":"USAGE","message":"Unknown command: setup (run simlock --help for usage)"}}, exit 2 (#147 F1).

Exact strings:

• Scope prompt, on stderr: Install only for this project (not every project)? [y/N]
• MCP prompt, on stderr: Also connect Simlock's MCP server to Claude Code? [y/N] , and for Codex Also connect Simlock's MCP server to Codex? Codex counts it as a second agent beside the CLI. [y/N]
• Refusal message: Refusing to install: <path> exists and is not a directory. Nothing was written. Move it aside and run setup again.
• MCP failure message: MCP not connected for <tool>: <reason>, one per failed tool, joined by ; .
• Report lines: the tool id padded to 11 characters, two spaces, the step (skill or mcp) padded to 5, two spaces, then the status; for skill the status is padded to 9 (the length of connected), then two spaces and the path. So claude-code skill wrote <path> and codex mcp connected. A skipped skill ends with (<Tool name> not found here; pass --tool <tool> to install anyway). The mcp line (statuses connected, already, failed, skipped) follows its tool's skill line only when MCP was asked for, and ends with (<reason>) after failed and skipped. Tool names: Claude Code, Codex.
• MCP is asked for when --mcp is passed or the MCP prompt is answered yes. At project scope Codex gets no MCP prompt; with --mcp it reports skipped (codex mcp add has no project scope).

The router skill

SKILL.md is YAML front matter, name: simlock and a description of at most 1024 characters saying when to use it (before touching an iOS simulator, Android emulator or test phone, or running simctl, adb, emulator, xcodebuild for a simulator, or agent-device), then a short body:

1. One paragraph on what Simlock is: it shares simulators, emulators and phones between agents, and works only if every agent follows its rules.
2. Check it is set up: run simlock whoami. If simlock is not found, or whoami fails, tell the user, and do not touch any device.
3. Get the rules: run simlock instructions and follow them. They match the installed Simlock, so read them again in each session instead of relying on memory.
4. The last line: More: https://callstackincubator.github.io/simlock/docs/getting-started/connect-your-agent/

It holds none of #147's section headings and no other rule.

Technical spec

Facts

Commit cac23e033 unless noted.

Values sent to other tools:

Modules touched

Searches: setupAgentTools, renderSkill, SETUP_REFUSED (0 hits on main); confirm?.( (4 commands); GATEWAY_EXEMPT_PATHS; homedir( in src/cli.

• src/instructions/index.ts: renderSkill(): string, the router skill above.
• src/instructions/setup.ts (new, from the branch): the tool table (claude-code: presence .claude, skills .claude/skills; codex: presence .codex (user scope: $CODEX_HOME when set), skills .agents/skills; all under the scope's base), setupAgentTools({ filesystem, runTool, confirm, homeDirectory, workingDirectory, codexHome?, scope?, tool?, mcp?, interactive }) → SetupReport. runTool(bin, args, { cwd }) resolves { outcome: "exited", code, stderr } | { outcome: "not-found" } | { outcome: "timed-out" }; toolRunner(processRunner) builds it over ProcessRunner.run with timeoutMs: 30_000: ProcessSpawnError → not-found, code === null → timed-out (F8). The unit tests fake runTool with a plain function, and test toolRunner with a hand-written ProcessRunner stub. Steps: scope (flag, else confirm when interactive, else user); inspect every selected tool and refuse before any write (F12); write; then MCP per written tool, one at a time. SetupRefusedError, SetupMcpFailedError (carries the report).
• src/cli/tree.ts, src/cli/commands/setup.ts (new): simlock setup [--user | --project] [--tool <claude-code|codex>] [--mcp | --no-mcp] [--json]. interactive is false with --json. Prints the report, then on SetupMcpFailedError the error line.
• src/cli/types.ts, src/cli/environment.ts: CliEnvironmentPorts and CliEnvironment gain homeDirectory, workingDirectory, codexHome and runTool, filled at the composition root from homedir(), process.cwd(), process.env.CODEX_HOME and toolRunner(new NodeProcessRunner()) (loaded on demand), from strings and a fake function in tests.
• src/cli/errors.ts: SETUP_REFUSED (exit 2) and SETUP_MCP_FAILED (exit 1), checked lazily like SERVICE_FAILED (F10).
• src/cli/index.ts: setup in USAGE and GATEWAY_EXEMPT_PATHS.
• src/instructions/AGENTS.md, src/cli/AGENTS.md: the setup step order, the tool table, the exempt list.
• e2e/helpers/cli.ts: CliOptions.cwd, passed to spawn.
• Tests: src/instructions/setup.test.ts, src/instructions/index.test.ts, src/cli/index.test.ts, e2e/setup.test.ts.
• Website: reference/cli.mdx (row, ## simlock setup section: flags, prompts, both tools, both scopes, the four skill paths, the report, MCP commands; setup added to the exempt list, worded without a count), reference/errors.mdx (SETUP_REFUSED, SETUP_MCP_FAILED), getting-started/connect-your-agent.mdx (first step: simlock setup; the MCP tabs mention setup --mcp).

flowchart LR
  CMD[cli/commands/setup]:::changed --> SET[instructions/setup]:::changed
  SET --> IDX[instructions/index renderSkill]:::changed
  SET --> FS[ports Filesystem]
  SET --> PR[ports ProcessRunner]
  CMD --> ENV[cli environment: home, cwd, runner, confirm]:::changed
  classDef changed stroke-width:3px

sequenceDiagram
  participant S as simlock setup
  participant C as claude (or codex)
  S->>C: mcp add [-s user|project] simlock -- simlock mcp (30 s)
  alt exit 0
    C-->>S: mcp connected
  else claude exit 1, "already exists in"
    C-->>S: mcp already
  else not on PATH
    C-->>S: mcp skipped "claude not found"
  else other exit, or no answer in 30 s
    C-->>S: mcp failed "<first stderr line>" or "timed out after 30 s" → SETUP_MCP_FAILED, exit 1
  end

Surface and extension points

src/instructions grows setupAgentTools, a function taking its ports; no handle. The tool table is the one place that knows the tools; a third tool is a row, and no extension point is added (architecture rule 19: none is named).

Contract and event changes

None after a search of src/contract and docs/internal/EVENTS.md: no daemon operation, event or config key. SETUP_REFUSED and SETUP_MCP_FAILED are CLI-level codes, not contract errors. SetupReport:

{ scope: "user" | "project", tools: [{ tool: "claude-code" | "codex", skill: { status: "wrote" | "replaced" | "skipped", path: string }, mcp?: { status: "connected" | "already" | "failed" | "skipped", reason?: string } }] }. mcp is absent when MCP was not asked for or the answer was no. reason is set for failed and skipped, at most the first line of the tool's stderr, cut to 200 characters.

Other code on the same state

Searched \.claude/skills, \.agents/skills, mcp add in src (0 hits). No other Simlock code writes these directories or the tools' MCP config. A second setup at once on the same scope: both write the same bytes with writeFileAtomic, last rename wins, same result; not tested (two operators running setup at once is not a real case).

Failure modes

State written: the skill directories. An interrupted run leaves some tools' SKILL.md written and others not; each file is whole (writeFileAtomic), and a re-run reaches the same end state. MCP config is written by the tool itself.

Rules in play

• Documentation rule 3, "Nothing the running tool prints ... names a file path in this repository": the skill points only at the website URL; paths on the operator's machine are fine.
• Documentation rule 9: the three pages above.
• Architecture rule 9, "Every external API is accessed through a port interface": files through Filesystem, the tools through runTool over ProcessRunner, the prompt through confirm; home and cwd read only at the composition root.
• Architecture rule 11, "Every wait that crosses a process boundary is bounded": 30 s per tool command.
• Architecture rule 12, "Every exit from a method leaves its subject in exactly one named state": inspect before write, so a refusal writes nothing.
• src/cli/AGENTS.md, router files "import no component for a value": the process runner is loaded on demand.

Tests

Seams: src/instructions/setup.test.ts (model origin/feature/157:src/instructions/setup.test.ts, on MemoryFilesystem, a fake runTool function and a fake confirm), src/instructions/index.test.ts, src/cli/index.test.ts, and e2e/setup.test.ts (fast lane, model origin/feature/157:e2e/setup.test.ts).

• An operator runs setup and gets the skill in the right place for the scope: user → <home>/.claude/skills/simlock/SKILL.md and <home>/.agents/skills/simlock/SKILL.md, nothing under cwd; project → the same under cwd, nothing under home.
• setup picks tools: none named → only tools whose presence directory exists, the others skipped; a file named .claude → skipped; codexHome set to a directory that exists and no ~/.codex → Codex installed at user scope; --tool codex with no .codex → installed, directories created.
• setup asks in a terminal and never blocks a script: scope prompt yes → project; default → user; --user / --project → no scope prompt; not interactive → no prompt, user, no MCP; MCP prompt yes → MCP step runs; default → no mcp in the report; Codex at project scope → no MCP prompt. The fake confirm records each question, asserted against the exact prompt strings above.
• setup re-run replaces only its own files: second run → replaced, same bytes; a stale file in the skill directory → removed; a SKILL.md that is a directory → replaced by the file.
• setup refuses a file or symlink where the skill directory goes: a file; a symlink; a refusal in the second tool → nothing written for the first; via the CLI → SETUP_REFUSED, exit 2, stdout empty, the message exactly as above.
• setup connects MCP through the tool's command: add exit 0 → connected, with the exact arguments and cwd of the Values table for each tool and scope; Claude Code exit 1 with MCP server simlock already exists in user config → already; other exit 1 → failed with its first stderr line, cut to 200 characters; timed-out → failed, timed out after 30 s; not-found → skipped, claude not found; Codex at project scope with --mcp → skipped, codex mcp add has no project scope, nothing run; --no-mcp → nothing run; toolRunner over a stub ProcessRunner: throws ProcessSpawnError → not-found, code: null → timed-out, code: 1 → exited, and it passes timeoutMs: 30000.
• An agent reads the router skill: front matter opens with ---, name: simlock, a non-empty description ≤ 1024 characters; the body names simlock whoami and simlock instructions; it holds none of Add simlock instructions: the rules an agent must follow, printable and served over MCP #147's section headings; the last line is the website URL; no path in this repository (extend Add simlock instructions: the rules an agent must follow, printable and served over MCP #147's test).
• setup prints its report: the report lines exactly as in Exact strings, for a written, a replaced and a skipped skill and each mcp status; --json → one SetupReport object; an MCP failure → the report on stdout, then SETUP_MCP_FAILED naming the tool, exit 1; --tool bogus, two --tool, a positional, --mcp --no-mcp, --user --project → USAGE, exit 2, nothing written; --gateway with no gateway → runs; --help → the usage line, exit 0.
• An operator runs simlock setup for real and the skill lands where the tool reads it: temp HOME, a fake claude script first on PATH that records its arguments and exits 0; setup --tool claude-code --mcp → SKILL.md under HOME equal to renderSkill(), the fake got mcp add -s user simlock -- simlock mcp, exit 0, no daemon socket; setup --tool codex --mcp with no codex on PATH → skill written, mcp skipped, exit 0; setup --project --tool codex --no-mcp with cwd a temp directory → .agents/skills/simlock/SKILL.md under it, nothing under HOME.

Done when

• pnpm test:e2e e2e/setup.test.ts passes: the skill lands at the documented place for each scope, and MCP is connected through the tool's command.
• By hand, on a machine with no Simlock files: simlock setup --tool claude-code, then --tool codex, then starting each tool lists the simlock skill, and asking the agent to use a simulator makes it run simlock whoami and simlock instructions.
• simlock --help lists setup.
• reference/cli.mdx, reference/errors.mdx and connect-your-agent.mdx describe the command, both tools, both scopes, the paths and the two error codes.
• pnpm check is green.

Out of scope

• Editing a file the operator owns (AGENTS.md, CLAUDE.md, a tool's settings or MCP config by hand).
• A dry run or an uninstall.
• Agent tools other than Claude Code and Codex.
• Codex MCP at project scope (F4).
• Changing the rules text: Add simlock instructions: the rules an agent must follow, printable and served over MCP #147.

Depends on

• Add simlock instructions: the rules an agent must follow, printable and served over MCP #147

Written by an agent.