# spt-mobile — agent working rules

> **Canonical source of truth for how agents work in this repo.** Harness-agnostic:
> Claude Code reads it via the one-line `CLAUDE.md` (`@AGENTS.md`); other harnesses read
> this file directly. Edit working rules HERE, never in `CLAUDE.md`.

`spt-mobile` is the Android Mobile Gateway app for spt: subnet browse, live digests,
two-way messaging, and Pebble voice capture routed to starred endpoints. The phone is a
paired peripheral of one Mobile Gateway endpoint per paired host — never a node (ADR-0001);
the device link is iroh via an embedded Rust JNI slice built with cargo-ndk (ADR-0002).

**Orientation — read before working:** `DESIGN.md` (v1 rulings, the requirement source),
`CONTEXT.md` (glossary/model, authoritative for meaning),
`docs/adr/` (decisions), `docs/KNOWN-HAZARDS.md` (invariants we must not re-break),
`docs/SPT-CORE-NEEDS.md` (asks pending on spt-core), `docs/{DOCS-STRATEGY,TRACEABILITY}.md`.

## Source-independence from spt-core (binding)

spt-mobile is built **independently of spt-core source**. The contract surface is the
**public docs**: <https://sabermage.github.io/spt-releases>. No spt-core crate/path
dependencies; no answering design or implementation questions by reading spt-core source.

If you have a question about spt-core behavior, it is exactly one of:

1. **You are not reading the public docs closely enough** — go back and read them.
2. **There is a gap in the docs** — the behavior exists but isn't documented.
3. **Worst case: spt-core is missing a feature this project needs.**

Your job is to identify WHICH of the three it is, with solid evidence (doc citations, or a
minimal reproduction against the released binaries). If it's an spt-core-side issue (2 or
3), **inform doyle** (`$OWL ring doyle <you>` — his perch is on legacy spt) with the
evidence. This rule is imperative to this project's success and to spt-core's ongoing
development: spt-mobile is the forcing customer that proves the public contract is
complete.

**Published-crate channel (on the table, not yet exercised):** spt-core's original plan
includes publishing some of its crates as **libraries** (not source) for third-party devs.
That would be a legitimate dependency channel — consuming a published library is not a
source dependency. If a piece of this project would be accelerated by a published crate
(wire/format types especially), tell doyle with the specific crate + surface needed and it
can be arranged. Until a crate is actually published, the clean-room-from-public-docs rule
above stands.

## Requirement traceability (binding)

This project uses [`traceable-reqs`](https://github.com/BigscreenVR/traceable-reqs)
(`traceable-reqs.toml` = the authoritative `REQ-*` registry). The full contract is
`docs/TRACEABILITY.md`. The rules you must follow:

1. **Tag evidence in the same change.** When you write a function/test/doc-section that
   satisfies a requirement stage, add its tag in that same commit:
   `// [impl->REQ-FOO]` · `// [unit->REQ-FOO]` · `<!-- [doc->REQ-FOO] -->`
   Stages: `doc` / `impl` / `unit` / `int`. Tag *on or immediately above* the real
   evidence — never at file tops to satisfy coverage.
2. **Run `traceable-reqs check` before declaring work done.** Exit-1 means missing/invalid
   evidence — fix it, don't ship it.
3. **New requirement → add it to `traceable-reqs.toml` first** (with a `REQ-*` id), then
   satisfy it. No untracked work; no untagged evidence.
4. **KNOWN-HAZARDS are `REQ-HAZARD-*` requirements** — each needs a test before it's
   "covered." Treat the hazard list as a conformance checklist you must satisfy, not advice.
5. **Activate, don't pre-fail.** Requirements you aren't yet working stay
   `required_stages = []`. Activate (set real stages) only when starting the milestone that
   delivers them.

## Other conventions

- Match surrounding code style. spt-core's wire/schema formats (message envelope,
  digest format, `--json-payload` sender-metadata shape) are copied **verbatim** from
  spt-core — never re-derive them; clean-room everything else.
- Honor every `docs/KNOWN-HAZARDS.md` invariant — these are real bugs already paid for once
  (or hazards you have committed to never introduce). Each is a `REQ-HAZARD-*` with a test.
- Docs are dual-audience (human + AI dev-agent) per `docs/DOCS-STRATEGY.md`; doc generation
  is CI-gated against drift.
- Commit messages end with the project's co-author trailer:
  `Co-authored by: <your live agent name>` (e.g. `Co-authored by: flynn`).

## Plans and context hygiene

- **JIT plans.** Plan the next immediate body of work just-in-time (a short `*-PLAN.md`),
  not the whole project up front. A plan names scope, open design questions, tasks, and the
  gate (build + `traceable-reqs check` green).
- If you finish a significant body of work without need for user intervention, or if your
  context gets too high, you can clear your own context and keep moving:
  1. Create a JIT plan for the next immediate body of work, if it isn't already planned.
  2. If you are a live agent: commune immediate next steps + a broad project-status/end-goal
     summary, then clear.