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

Request: #154

Problem

Simlock is advisory. It works only when every agent knows the rules: lease first, never call simctl or adb directly, build iOS apps so they can be installed on Simlock's simulators. Today those rules live on the website, and the operator copies a sample block into each agent's AGENTS.md or CLAUDE.md by hand, on each machine or project, and again whenever the rules change. That sample block is already out of date: it never mentions agent-device, which is how most agents now use Simlock. A missing or stale copy is invisible until an agent breaks another agent's device.

Who it is for

• An agent of any kind (agent-device first, then the simlock CLI, then MCP) that needs a device and must know the rules before it touches one.
• An operator setting up Simlock for agents that run under Claude Code or Codex, for themselves on one machine or for a whole team through one project.

Outcome

• One command, simlock instructions, prints the full rules for the installed Simlock version as one Markdown text. It covers agent-device, iOS builds, the simlock CLI and MCP, one section each, and only what works today.
• An MCP client gets a short version of the rules automatically when it connects, and can read the full text as a resource.
• One command, simlock setup, installs a small simlock skill for Claude Code and Codex. The skill says what Simlock is, when to use it, how to check it is set up, and to run simlock instructions for the rules. The rules are never copied into the skill, so an upgrade needs no re-run.
• In a terminal, setup asks whether to install for this user or this project (user by default), and per tool whether to connect Simlock's MCP server too (no by default). Flags answer both questions for scripts.
• The website docs teach this flow in place of the hand-copied block.

How it works for the user

flowchart TD
  Op[Operator runs simlock setup] --> Scope{Terminal?}
  Scope -->|yes| AskScope[Asks: this project only? y/N]
  Scope -->|no, or --json| User[User scope unless --project]
  AskScope --> Write[Writes the simlock skill for each tool found]
  User --> Write
  Write --> Refuse{A file or symlink where the skill directory goes?}
  Refuse -->|yes| Stop[SETUP_REFUSED, exit 2, nothing written]
  Refuse -->|no| Mcp{MCP: --mcp, or yes at the prompt?}
  Mcp -->|yes| Add[Runs the tool's own mcp add]
  Mcp -->|no| Report[Prints what it wrote, replaced, skipped]
  Add --> Report
  Report --> Agent[Next agent session loads the skill]
  Agent --> Who[Agent runs simlock whoami]
  Who --> Rules[Agent runs simlock instructions and follows it]

Before:

$ simlock instructions
{"error":{"code":"USAGE","message":"Unknown command: instructions (run `simlock --help` for usage)"}}

After:

$ simlock instructions
# Using Simlock to share iOS simulators and Android emulators
...
## Rules for every agent
...
## agent-device
...

$ 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)

Examples

What could go wrong

• The rules say something Simlock no longer does, and an agent follows them. Likely over time; each later change to the commands has to update its section.
• An agent starts without the skill because setup wrote it where the tool does not look. Unlikely: paths come from the tools' own source.
• setup changes a file outside the simlock skill directory, or a tool's MCP config the operator did not agree to. Unlikely: MCP is connected only after a yes or --mcp, and through the tool's own command.

Words used

• rules text: the Markdown simlock instructions prints, e.g. its ## agent-device section.
• section: one ## part of the rules text for one way an agent uses Simlock (agent-device, the CLI, MCP), plus the rules for every agent.
• router skill: the short SKILL.md setup installs. It points at simlock instructions and holds no rules itself.
• skill directory: <tool's skills directory>/simlock, e.g. ~/.claude/skills/simlock. Simlock owns it whole.
• scope: where setup installs. User: under the home directory, for every project. Project: under the current directory, to commit with the app.
• server instructions: the text an MCP server sends when a client connects. Claude Code adds it to the agent's prompt, cut at 4096 characters by default.

Non-goals

• Editing a file the operator owns, such as a project's AGENTS.md or CLAUDE.md, or a tool's settings file. MCP is connected only through the tool's own mcp add command.
• A dry run or an uninstall. The report after the run is the preview. Deleting the simlock directory by hand, or claude mcp remove simlock, is the uninstall.
• Agent tools other than Claude Code and Codex. Others use simlock instructions and paste.
• Describing commands that do not exist yet (simlock run holds a lease around one command, and a detached lease follows the agent process #944 simlock run, simlock simctl and simlock adb on a worker run only against the caller's lease, and fill the device in #948 lease-scoped simctl/adb, MCP: a run_on_device tool runs simctl, adb or devicectl against the session's lease #949 run_on_device, agent-device on the same Mac works with no operator step: loopback session identity and on-by-default #950 zero-config agent-device). Each one updates its own section when it ships.
• Rules that depend on this machine's config or catalog. The text is static.
• agent-device open --physical: agent-device 0.21.28 has no such flag. The text teaches phones through simlock lease --physical until agent-device ships it.

Completion conditions

• simlock instructions prints the rules on stdout, exit 0, without connecting to or starting a daemon; --json prints the same text in one JSON object. Checked by e2e.
• The rules text has the sections Rules for every agent, agent-device, iOS builds, simlock CLI and MCP, in that order, and each names what the Behaviours table lists. Checked by unit tests that read the expected values from the code that defines them.
• The text and the skill name no file path in this repository.
• An MCP client that connects gets server instructions of at most 4096 characters, and can read simlock://instructions, equal to what the CLI prints. Checked by e2e.
• On a machine with no Simlock files, simlock setup for Claude Code and then for Codex, followed by starting each tool, gives the agent the simlock skill without a paste. Checked by hand per tool, and by an e2e test that finds the skill at the documented place.
• The user scope writes only under the home directory; the project scope only under the current directory. Nothing outside the skill directories and their missing parent directories changes, except MCP config written by the tool's own command after a yes or --mcp.
• Re-running setup leaves the same files.
• No command of this feature connects to or starts the daemon.
• The website's CLI reference and "Connect your agent" page describe both commands; the hand-copied rules block is gone.

Open questions

Decisions

• None needs an ADR: every choice is local to one task and cheap to reverse. Recorded here:
  • The rules text is one Markdown text with fixed ## sections, one per surface. A later feature changing a surface edits its section in the same PR (documentation rule 9 covers it: the text is CLI output).
  • The skill is a router, not a copy, so the rules always match the installed Simlock.
  • setup connects MCP only through claude mcp add / codex mcp add. codex mcp add has no project scope, so a project-scope run never connects MCP for Codex.
  • Codex skills go to .agents/skills/simlock (user: under the home directory; project: under the current directory). That is where Codex 0.163.0 reads them; ~/.codex/skills is deprecated.

Shared values

Behaviours

Tasks

flowchart LR
  T147["#147 rules text, instructions, MCP"] --> T620["#620 simlock setup"]

• Add simlock instructions: the rules an agent must follow, printable and served over MCP #147 Add simlock instructions: the rules an agent must follow, printable and served over MCP — an agent or operator prints the current rules, and an MCP agent gets them on connect.
  Risk: an agent follows a rule Simlock no longer has, or misses agent-device.
• One command installs the agent rules where agent tools read them #620 One command installs the agent rules where agent tools read them — an operator installs the router skill, and optionally MCP, for Claude Code and Codex with one command.
  Risk: an agent starts without the skill, or a file outside the simlock directory changes.

Completion conditions: the first four and the last are delivered by #147's Done when, except their skill and setup halves (no repository path in the skill; the website describing setup), which #620 delivers with the others.

Open work in the same area:

• simlock run holds a lease around one command, and a detached lease follows the agent process #944, simlock simctl and simlock adb on a worker run only against the caller's lease, and fill the device in #948, MCP: a run_on_device tool runs simctl, adb or devicectl against the session's lease #949, agent-device on the same Mac works with no operator step: loopback session identity and on-by-default #950 (requests): each changes a section of the rules text. No Depends on: they are not specified; whichever ships later edits its section.
• Lease limit per platform: one iOS and one Android per agent without allowing two of either #947 (request): per-platform lease limits. The text already says the operator sets the limit, so it needs no change. No Depends on.
• iOS: make the device set configurable so Xcode tools can target a leased simulator #946 (request): configurable iOS device set. The iOS builds section stays true while the default stays. No Depends on.
• agent-device docs: parallel agents need their own --session #931 (agent-device bug): --session per agent. The agent-device section teaches it now. No Depends on.
• Branch origin/feature/157 (closed feat(cli,mcp): add simlock instructions, the rules an agent must follow #150, feat(cli): add simlock setup to install the agent rules as a skill #166 merged into a deleted branch): the earlier build. Add simlock instructions: the rules an agent must follow, printable and served over MCP #147 and One command installs the agent rules where agent tools read them #620 start from it.

Written by an agent.