crawl-call

Imported from CRELLIA-S-L/crawl-call (AGENTS.md). Install upstream with npx skills add CRELLIA-S-L/crawl-call. Copyright stays with the author.

Crawl Call: Chomp Company — agent guide

A summary for coding agents; the project follows the SRS-DD standard. On any conflict, specs/README.md wins — it is the single normative document on the specification. System behavior is described in specs/ as numbered requirements with links between them and references to code.

• Specification rules — specs/README.md, by section; python3 tools/srs_view.py --vocabulary prints the words a block may use.
• Engineering principles — specs/constitution.md (ART-*); they apply to every task.
• Markdown is not wrapped to a width — a line breaks where the meaning breaks, never inside a sentence; the renderer does the wrapping.
• Check — python3 tools/srs_check.py.
• Run the tests — sh scripts/run-tests.sh <simulator-udid>: it boots the simulator, builds and runs as separate phases under a watchdog, and prints what each took. CRAWLCALL_TIMEOUT sets the watchdog. The reasoning, the phase times and why it is not one command are in specs/50-verification.md.
• Run a build on the phone — CRAWLCALL_DEVICE=<device-udid> sh scripts/run-on-device.sh <app> [screenshot]: it installs, launches, waits, captures if asked, and closes the app again — on the way out as well as at the end, because a run is over when the app is terminated (specs/50-verification.md, FR-TOOL-180). CRAWLCALL_WATCH sets how long it is left running; CRAWLCALL_RECORD=<file> switches the frame record on, takes it off the phone and names the slowest frames (FR-TOOL-250). The device is given by the environment; no device identifier lives in the repository — the maintainer's standing rule, not a requirement.
• Read — python3 tools/srs_view.py <ID> for one requirement with its links resolved, --code <path> for the requirements describing a file (--statements adds what each obliges), <ID> --where for the lines that carry it (--source prints them), --areas for what the specification is divided into, --open for a page a non-engineer can read; .claude/skills/srs-page/SKILL.md is the procedure around it.
• Check a finished change — .claude/skills/srs-check/SKILL.md reads the verification method and the tests field of every requirement the change touched, and offers exactly those; it runs nothing unasked.
• Skills — the procedures in .claude/skills/*/SKILL.md are plain markdown; an agent without a skill system reads them directly as workflow guides.
• Freeze a baseline — python3 tools/srs_baseline.py X.Y.Z writes the row into specs/92-baselines.md; the commit that carries it is the baseline, and .claude/skills/srs-baseline/SKILL.md is the procedure. Nothing here commits or tags for you.
• Upgrade the framework — python3 tools/srs_upgrade.py shows the version transition, the upgrade notes and the file list, then asks; .claude/skills/srs-upgrade/SKILL.md is the procedure. No framework clone, no address to look up.

Two ways in

A question about how the system works starts with what this project wrote about itself — specs/00-glossary.md, specs/01-introduction.md, specs/02-overview.md: short, and in the project's own words, which a search over requirement text assumes you already know. Then --areas, then one area, then the requirement, then its code.

A change to behavior starts at the loop below.

The loop

1. Before changing behavior, find the requirements that describe it: python3 tools/srs_view.py --code <path/to/file>, or the tables in specs/90-traceability.md. None exist — create one first, with the initial status per the Lifecycle section of specs/README.md.
2. Plans reference requirement IDs, not prose.
3. Implement.
4. Record what you chose: each way the change met a requirement that could have been met another way is a decision — Workflow in specs/README.md says what counts — and goes into specs/adr/; when there was none, the report says so.
5. Close the loop: status, code, tests — in the same set of edits as the code.
6. Run the checker.

The rules most easily broken

1. Changing behavior — first find or create the requirement, then write the code.
2. specs/90-traceability.md is generated by a script; never edit it by hand.
3. Builds, tests, and every other action that ART-030 of the constitution reserves run only with the user's explicit confirmation. A run on a device is closed when it is over — the app terminated, not left in the background — including a run that failed or was interrupted; the reason is the next measurement's cold start (specs/50-verification.md).
4. Naming a record to a person — a requirement, a decision, and where the project keeps the layers an element or a grounds record: at its first mention in what the person reads as a whole (a message, a plan, a report), give its title, the file it is written in and its status, pasted from the tool, never typed: python3 tools/srs_view.py --cite <ID>… prints FR-<AREA>-<NNN> — <its own title> (specs/<file>.md, <status>) and cites a decision by its ADR-NNNN; python3 tools/srs_arch.py --cite and python3 tools/srs_grounds.py --cite print the same form for an element and a register record. Afterwards the number alone is enough; inside specs/, arch/ and grounds/ the identifier is the name. A line a checker printed is run through --cite before it is relayed. The rule holds in a table, a list, the steps of a plan and the report of any procedure — a template with no place for the citation is one you add it to. It is checked at sending: what was pasted is what the tool printed — no bold around it, no backticks around the file, nothing added inside the brackets. A mention in passing is a mention. A span named as a set — FR-<AREA>-010 through FR-<AREA>-090, a whole area — is one name, not a mention of each member. A commit message and the changelog are the exception and name identifiers bare, in a trailing parenthesis. A number the specification does not carry yet is a proposal, and is marked as one.
5. Reading the code behind a change — take the files from the code and tests fields of the requirements the change belongs to (--code <path> answers from the other end), not from a search over the repository. Go wider where you must, and say where you went.
6. Reporting to a person — write in sentences that follow one another, and keep a list or a table for what the reader has to count or compare. A label with a fragment after it is a note to yourself.
7. Saying what the project's files say — read the source in the same message and match the sentence to it before sending, not to what you remember. A count is derived over the current files, a claim that something is nowhere written names what was searched, and a paraphrase is checked against the passage it paraphrases.
8. Putting something to a person for a decision — a sentence for a document, a requirement's text, a step of a plan: the message that asks carries the text as it would be written, quoted in a block where it is long; "as shown above" is a key handed over instead of the thing, the same failure as a bare identifier.
9. A rule the conversation settles — where something agreed will bind the work after this task is over and no requirement says it, offer to author the requirement, naming what it would oblige and the area it belongs to. Offered, never written: the maintainer decides whether it is written at all.
10. A commit that alters behavior names the requirement identifiers it implements, bare, in a trailing parenthesis — ART-060 asks the commit or the pull request for them, and the identifiers are the ones the change was planned from.