Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open
  • Is something wrong?
#147 0 comments 0 reactions 1 assignee View on GitHub

Maintainers usually reply within 1 day

@V3RON is already working on this.

Since Sep 27, 2026.

Assessment

This issue has not been assessed yet.

Description

task:ready

Standalone task opened by the maintainer; no parent feature.

Scope

Simlock is advisory: it only works when every agent never calls simctl, adb, avdmanager, or emulator directly and only drives devices it leased. Today those rules live in the docs, and each team rewrites them into every agent's system prompt by hand.

After this PR an operator runs simlock instructions and gets one self-contained text block to paste into an agent's system prompt or AGENTS.md, and an MCP client can read the same text as a resource. The block tells an agent, in plain words:

  • Never call the platform tools directly; use simlock simctl / simlock adb, which inject the device set or adb port.
  • How to lease: set a stable SIMLOCK_AGENT_ID, run simlock catalog first, then simlock lease --platform … --device … in the background (or --detach plus simlock lease renew before ttlDeadline), read the one JSON line on stdout, and read progress from stderr.
  • One lease per agent, --all and nuke are operator commands, release with simlock release <lease-id> or by exiting the holder.
  • Never pass --allow-download unless told to.
  • What exit codes 10, 11, 13, and 14 mean and what to do on each.
  • How to reach a leased device: the environment block, simlock simctl/simlock adb, and that the refused verbs (simctl create/erase/delete, adb kill-server, emu kill) are refused on purpose.
  • Over MCP: the four tools and that lease_status is the thing to call after a context compaction.

Technical spec

Modules touched
  • src/instructions/index.ts (new): one exported AGENT_INSTRUCTIONS: string (Markdown) and renderInstructions(format: "text" | "json"). The only source of the text; nothing is duplicated in the CLI or MCP.
  • src/cli/index.ts: new instructions command. Prints the Markdown on stdout by default; --json prints {"instructions": "<markdown>"}. Any other flag is USAGE (exit 2). Never connects to, or auto-starts, the daemon. Listed in simlock --help.
  • src/mcp/server.ts: register a resource simlock://instructions (text/markdown) returning AGENT_INSTRUCTIONS; declare the resources capability. No new tools.
  • docs/CLI.md: a ## simlock instructions section, and add the command to the "human-oriented view … accept --json" exception list in the intro. README.md: one sentence under "Getting started" and one under "MCP integration".
Contract and event changes

None. No daemon operation, no event, no config key.

Rules in play
  • docs/internal/agent-rules/documentation.md rule 3: the printed text must name no file path in this repo. Point at the package's homepage URL if a pointer is needed.
  • docs/internal/agent-rules/testing.md: every test title below is a claim.
  • docs/internal/agent-rules/architecture.md rule 8: the text is static and frontend-owned; the daemon does not learn about it.
Tests
  • simlock instructions prints the agent instructions on stdout and exits 0 without starting a daemon (e2e, fast lane: assert no socket appears under SIMLOCK_HOME).
  • simlock instructions --json prints one JSON object whose instructions field equals the text output.
  • simlock instructions --bogus fails with USAGE and exit 2.
  • The agent instructions name no path inside this repository (unit: the text matches neither docs/ nor .md).
  • The agent instructions name every refused passthrough verb the drivers refuse (unit: derive the expected list from the drivers' refusal constants, not a copy).
  • The MCP server lists simlock://instructions and reading it returns the same text the CLI prints (e2e, MCP session flow).

Done when

  • simlock instructions and simlock instructions --json behave as specified above, verified by the e2e tests.
  • simlock --help lists the command.
  • An MCP client can read simlock://instructions.
  • docs/CLI.md and README.md describe the command; pnpm check is green.

Out of scope

  • Generating the text from the live catalog or config; it is static.
  • A prompt-typed MCP primitive; a resource is enough for v1.
  • Any new MCP tool.

Depends on

Approval

  • Approved for delivery

Written by an agent.

Dominant language
TypeScript
Stars
14
Forks
0
Avg merge
1d 3h
Merged PRs (30d)
49

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from callstackincubator/simlock

All issues in callstackincubator/simlock

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.