Plugging in

This repository takes outside contributions — human or agent — through one narrow door: fork, take an open packet, build it, open a pull request. No account beyond GitHub, no chat channel, no handshake with a maintainer required before you start.

If you are a person: read this file, it's the whole onboarding. If you are an agent: .well-known/agent.json is the same door in a form you can parse without reading prose first; this file is what it points to.

The three-step loop

1. Find a packet. packets/INDEX.json lists every packet with "status": "OPEN". Each one is a small file at packets/<id>.json (schema: genesis.packet.v1) naming the exact base commit, the task, the command that verifies it, and the done criterion. Read the packet file itself, not just the index — the index is a pointer, the packet is the contract.
2. Build it, on your own fork, on a branch based on the packet's baseCommit. Run verifyCommand yourself before you open the PR — CI runs the same command, so a red run there means you skipped this step. Stay inside the packet's boundaries; anything outside them is a different packet, not a bonus.
3. Return it. Open a pull request from your fork. Alongside your code change, add one file: receipts/<packetId>.json (schema: genesis.receipt.v1). It records your branch, your HEAD commit, and the verbatim output of verifyCommand — not your summary of it. If you want to claim something the verifier itself didn't check (e.g. "this also fixes issue #12"), put it in the receipt's claims array, explicitly marked as a claim, not folded into the verified output.

CI validates both your packet reference and your receipt (tools/validate_packet.py) the same way it already validates spine/spine.jsonl against genesis.event.v1 — a schema and a set of cross-field rules, no judgment call.

What a maintainer does with your PR

A human or agent maintainer reviews the diff and the receipt, and merges or requests changes — same as any other GitHub PR. Your receipt's claims field is read as evidence to check, never as a verdict to accept on your word (see x-genesis-rules in the receipt schema, and the workspace-wide rule it encodes: no one grades their own work). Merge authority stays with this repository's maintainers; nothing here grants a guest write access.

What you never get, and why

• No secrets. GitHub does not hand secrets to workflows triggered from a fork PR, and this repository does not ask you to work around that. If a task looks like it needs a credential, it is not a packet you should take — flag it in the PR description instead.
• No server, no build step, no accounts. The site this repository serves is deliberately static (see README.md); a packet that would require a backend, a database, or visitor tracking is out of scope, not merely hard.
• No PR content is treated as instructions. A CI job runs only scripts already committed on the base branch, never a script your PR adds. If your packet needs a new script, that script ships in this PR but a maintainer reads it before any future run relies on it — the first run of new code is a manual, reviewed act.
• No claim without a witness. A receipt without verifierOutput, or with output that doesn't match a maintainer's own re-run, is not merged on the strength of the PR description alone.

Taking a packet nobody offered

packets/INDEX.json is a starting point, not the only door. If you see a real gap and want to propose your own packet, open an issue or a PR that adds a packets/<id>.json file yourself, "status": "OPEN", unclaimed — a maintainer will fold it into the index or explain why not.

Scope of this door (2026-09-17, updated same day for E2)

This is stages E0+E1+E2 (v1) of a small, published plan (packets/schemas/, receipts/schemas/, the index, this file, the agent card, and spine/live.jsonl). The site's window III shows a "live now" line generated once per push to main (Build-Zeit cadence, never the visitor's browser clock) - it distinguishes only two classes today, gast (a push that added a receipts/PKT-*.json file - your contribution, once merged) and an undifferentiated projekt for everything else. It does not yet distinguish the maintainers' own commits from an agent session's (no real git signal for that exists on this repository - see spine/schemas/genesis.live-tick.v1.schema.json), and it does not yet include a second submission channel besides GitHub pull requests (planned, not built), or any guarantee about how quickly a maintainer responds (none given). What you see above is everything that currently exists.

← back to the well