sim-use: Skill for Claude Code

Write AI docs

sim-use uses AI-docs-driven development. A substantial change starts with a record in docs/ai/, and each decision is written down when it is made, not reconstructed later. The record answers "why is it built this way?" for the next human or agent. Read docs/ai/README.md first: it has the index and the folder layout.

When to write

A new entry (docs/ai/NNN-<slug>/) is necessary when the work:

• adds a verb, a platform, a transport, or a backend, or changes how a verb reaches a device (dispatch, daemon, HID transport, bridge);
• changes a contract: the daemon wire protocol, the bridge wire protocol (PROTOCOL_VERSION), the --json envelope, the bundled skill's compatibility floor (MINIMUM_SIM_USE_VERSION), or the host-environment matrix;
• starts as an investigation (a new Xcode, a reproducible failure, an upstream idb change) and ends in a decision;
• fixes a bug whose root cause or fix shape must guide later code (for example, "HID from a short-lived process is lost on the dtuhidd transport").

An amendment to an existing entry is necessary when follow-up work, a review round, or a later finding changes what the entry says. Look for an existing entry on the topic before you open a new one.

No record is necessary for typo or formatting fixes, dependency bumps, test-only or fixture-only changes, small fixes that need no separate design record, reviews, and status reports. Keep changelog entries focused on user impact, not root-cause detail. If you are not sure, ask: will someone later need the reasoning to change this code safely? If yes, write it down.

Workflow

1. New entry: plan first

1. Get the next number: ls docs/ai | sort, then take the highest NNN + 1 (three digits). Numbers are never reused.
2. Before you write code, create docs/ai/NNN-<kebab-slug>/000-plan.md from the template below, with Status: Planned. Use 000-investigation.md when the work starts as a root-cause hunt: record the reproduction, the evidence and the hypotheses, then the decision.
3. Add the entry to the index table in docs/ai/README.md.
4. Implement the work in the normal branch and PR flow. When you make a decision that the plan did not foresee, record it at once in the plan's Decisions table, or in an amendment.
5. After the work lands, write 001-action.md: what shipped, the PRs, the key files, and the deviations from the plan. Set the plan status to Implemented. Ship the docs in the same PR as the code when you can.