Hacktoberfest 2026: die Issues, die Maintainer für den Oktober markiert haben – offen und einsteigerfreundlich. Hacktoberfest-Issues durchsuchen

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

Offen
  • Stimmt etwas nicht?
#147 0 Kommentare 0 Reaktionen 1 zugewiesene Person Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

@V3RON arbeitet bereits daran.

Seit 27.9.2026.

Bewertung

Dieses Issue wurde noch nicht bewertet.

Beschreibung

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.

Vorherrschende Sprache
TypeScript
Sterne
14
Forks
0
Ø Merge
1 T. 5 Std.
Gemergte PRs (30 T.)
66

Entwicklungsumgebung

Dieses Projekt bietet weder Dev-Container noch Dockerfile noch Beitragsleitfaden – die Einrichtung liegt bei Ihnen. Beginnen Sie mit der README; die allgemeinen Schritte stehen in unserem Leitfaden für den ersten Beitrag.

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus callstackincubator/simlock

Alle Issues in callstackincubator/simlock

Ähnliche Issues

Weitere Issues zu TypeScript

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.