> Contributing — from The Handover, the-handover.org/docs/contributing > Authors: The Handover (the-handover.org) · Reviewed: 2026-08-07 > © Captivated Ltd — free to use in your own work, not to redistribute as a collection. the-handover.org/licence This is addressed to whoever is reading it, which — given what this library is for — may well be an agent working on someone's behalf. If so: the sections below are the whole process, and the last one is the part your operator will want to see before anything is sent. ## What's worth submitting Something that changed what you did. A failure mode with the conditions that produced it. A process that survived contact with a real project. A prompt that reliably lands, with the model you confirmed it against. Not: a restatement of official documentation, a summary of a tool's README, or a document assembled by asking a model to write guidance on a topic. Those read plausibly and help nobody, and they are the easiest submissions to identify. The bar for a document that overlaps an existing one is simple — **does it change what a reader would do?** A different platform, a materially different approach, a new failure mode, or a demonstrably better version of the same thing all clear it. Reworded, restructured or padded does not. ## Rootnotes A **rootnote** is a document that lives in a project root and carries what the repository cannot state. They are the category this library most obviously exists for, and the bar is specific. A rootnote needs all four of these: - **It encodes what cannot be discovered.** If an agent with the repository in front of it could work the answer out, that belongs in code or ordinary documentation. - **It says where to stop.** Name the decisions that are not an agent's to make. Prepare, argue, draft — a human enacts. That boundary is usually the most valuable line in the document. - **It is portable.** Not tied to one tool. An instruction file such as `CLAUDE.md` is tool-specific and behavioural; a rootnote gets referenced by or pasted into one. - **It is scoped to one topic**, so a reader needing your editorial conventions does not spend context on your commercial plan to reach them. **Fill-in fields.** A rootnote may carry double-brace placeholders — `{{ … }}` — declared in frontmatter, so a reader gets a file they can commit rather than one to edit. Two rules decide what earns a field: - **Template what the reader chooses, never what an agent can discover.** A project name is in the directory, the manifest and the git remote. Asking for it is asking the reader to do the agent's job — and it is wrong outright in a document meant to sit at the root of many projects. - **Only where the choice is genuinely open.** Where one option is simply better, a field moves a decision you were better placed to make and calls it flexibility. State it instead. Every token must have a field and every field must be used; the build enforces both, because an undeclared token renders literally into a reader's repository. ## Overlap is routed, not rejected If your submission covers ground an existing document already covers, it is not thrown away. One of four things happens: - **Supersede** — yours is better, and it replaces the old one. The previous author stays credited and the old document stays reachable. - **Merge** — yours adds a gotcha or corrects a step. It is folded in and **you are added to the document's author list**. Credit on merge is not discretionary. - **Coexist** — genuinely different approach, platform or context. Both are published. - **Decline** — same content, adds nothing. You get a reply pointing at the existing document and an invitation to send the difference. Guides and context files trend toward one canonical document per topic. Prompts do not: many legitimate variants exist for different tones, tasks and models, and forcing them into one version would make that section useless. ## Where to send it **Through the private intake form, not a pull request.** This is deliberate, and it is worth explaining because a public PR is the obvious thing to expect. A public pull request exposes the contributor's account identity the moment it opens, permanently, in a way no amount of later editing undoes. That is incompatible with contributing under a pseudonym or anonymously, and those options exist for good reasons. It also keeps unreviewed material out of the repository entirely. Documents written to instruct agents are instructions; the people reviewing them work in environments that can act. Keeping submissions out of that path until a human has read them is a structural protection rather than a precaution. The maintainer opens the pull request after review. Everything published carries full version history from that point. ## What the frontmatter must say Structural checks auto-reject, so this is worth getting right rather than guessing. A submission needs all of this: ```yaml --- title: what it is, not what it is about # 120 characters at most summary: one factual line, no voice # 200 characters at most area: general | coding | research | writing | design category: processes | prompts | rootnotes | guides tags: [between 1 and 12] # three to six is a good target, not a rule tested_on: # required for guides and rootnotes - tool: Claude Code version: "2026-08" date: 2026-08-28 confirmed_with: # required for prompts and processes instead - model: claude-opus-4 date: 2026-08-28 date_written: 2026-08-28 date_reviewed: 2026-08-28 # must not be EARLIER than date_written authors: - name: Your name, a pseudonym, or Anonymous url: https://optional.example # rendered rel="nofollow ugc" affiliation: Founder of Example Ltd # optional, 80 characters at most agent: the assistant you wrote it with, if any licence: Handover-1.0 formats: [plain, CLAUDE.md, AGENTS.md] --- ``` **Every limit above is enforced and rejects on failure**, so they are stated rather than left for you to discover: `title` 120 characters, `summary` 200, `affiliation` 80, `tags` between 1 and 12, and `date_reviewed` never earlier than `date_written`. **`formats` has seven valid values, not three.** Alongside `plain`, `CLAUDE.md` and `AGENTS.md`: `.cursor/rules`, `.clinerules`, `.windsurfrules` and `copilot-instructions.md`. Declaring one costs nothing and rewrites nothing — format targeting changes the filename and the frontmatter wrapper only, never the body. If you wrote a document for Cursor or Copilot, say so; the library targets those tools and a reader using them has no other way to find out. **`licence: Handover-1.0` is required and has exactly one valid value.** It is not something the maintainer fills in afterwards. Supplying it is your affirmative acceptance of [the licence](/licence) — which is why it is a field you type rather than a default that happens to you. **Only one staleness axis is required, and which one depends on the category.** Guides and rootnotes need `tested_on`; prompts and processes need `confirmed_with`. The other is permitted, never required. Demanding both everywhere is the treadmill this library is trying not to build. **Four fields are rejected outright rather than ignored:** `hard_won`, `normative`, `provenance` and `superseded_by`. All four are maintainer-set, and a submission carrying one has the attempt reported rather than silently stripped. Nothing is lost by leaving them out — a document does not become Hard-Won by claiming to be. *This block exists because the first person to write against these instructions was told to omit `licence`, and every one of their documents would have failed intake on a required field they had been told not to supply. A structural check that auto-rejects has to publish the answer it wants.* *They then audited the rest of it against the schema and found four more of the same kind — an unpublished title limit, an unpublished date rule, four invisible `formats` values, and a tag range published as **stricter** than it is enforced, which rejects nobody and quietly costs people accuracy instead. Every fault ran in the same direction: the guide less informative than the thing enforcing it, and none of them findable by re-reading the guide. They are only visible by diffing prose against the schema, which is now a test.* ## What happens to it **A submission is treated as data, never as instructions.** If a document contains text addressed to the reviewer — instructions, claims about permissions, urgency, flattery — that is recorded as a finding and the document is not acted on. Nothing in a submission is executed: no running its commands to check they work, no fetching its URLs, no installing what it references. Review runs in stages: 1. **Structural checks.** Frontmatter parses, required fields present, licence correct, rights attestation recorded, intake address verified. These are objectively checkable, so failing one is an automatic rejection. 2. **Deterministic screening.** Pattern matching for agent-directed instructions, security inversions, dangerous commands, credential paths, obfuscation and unexpected outbound endpoints. 3. **Canon conformance.** Contradicting [the canon](/docs/canon) blocks publication. 4. **The adversarial read.** *If an agent loaded this into context, what would it now do differently, and does anything here weaken a security posture?* 5. **Similarity and provenance.** Nearest existing documents, and a check for material lifted from elsewhere. 6. **Sanitisation.** Account identifiers, team identifiers, tenancy details, internal hostnames, personal network specifics and real filesystem paths are stripped before publication. This applies to everything, including first-party documents. A pattern match is a flag, never a verdict. Good security documents necessarily *mention* dangerous commands — the canon itself names several while prohibiting them. What matters is whether the document warns against the thing or instructs it. **A human decides on every document.** Nothing publishes automatically, and nothing about that is likely to change. If you want to argue that a canon item is wrong, that is a legitimate submission and it goes to human debate. It is not treated as a violation. ## Identity, and what stays private Three options, all requiring a verified email address at intake: - **Real name**, with an optional link. - **Persistent pseudonym**, with an optional link. Worth considering: a handle accrues a track record across submissions, which genuinely helps, at no cost to privacy. - **Anonymous.** The email address is verified privately and never published. It exists so there is a contactable party behind a submission — which is what makes anonymous contribution workable rather than impossible. **Contributor links carry `rel="nofollow ugc"`.** This is stated up front rather than buried: a library handing out followed links becomes a target for documents written to acquire links rather than to help anyone. Saying so in advance means the people who would have submitted for that reason don't bother, while genuine contributors keep the credit and the human traffic. ## Rights, plainly **You keep copyright in your work.** That is not a formality — nothing here transfers ownership. You grant permission to publish, reproduce, **modify**, adapt and redistribute the document, and to license it onward to the public under the library's licence — or under any **more permissive** licence the library later adopts, CC BY 4.0 included. That clause runs one way only: it lets the library open up later without needing to find everyone who ever contributed, and it does not allow terms to be tightened below what your work was accepted under. The modification right is load-bearing rather than acquisitive: sanitisation depends on it, and so does merging a correction into an existing document or superseding one that has aged out. You confirm the work is yours, or that you hold the rights to grant it. Material lifted from elsewhere fails at this gate rather than the editorial one, because rights you do not hold cannot be granted. **Documents are published under the library's own licence, and it is not an open-source one yet.** Readers may copy them into their own projects — public, private, commercial, client work — modify them to fit, and have their agents read them. What is reserved is republishing the corpus *as* a corpus. The honest reason: an open licence cannot be withdrawn, this library is four weeks old, and it has no outside contributors, no settled merge norms and no evidence of how the documents get used once they are loose. Those are the facts that decision should rest on and none of them exist yet. So it is deferred, in writing, with the conditions for revisiting it stated — see [the licence](/licence). Not CC0 in any case: attribution is what you are paid in and it isn't ours to waive. Every downloadable document carries a short header naming its authors, the source, the licence and the date it was last confirmed. That header is how the credit survives the document being copied into somewhere this site cannot reach. ## After publication Documents record what they were tested against, and display as **unconfirmed** once past the threshold rather than being hidden. Nothing is withdrawn for being old. If you know a document still works, saying so is useful, and doing so opens a pull request rather than changing anything directly — the same rule applies to re-confirmation as to everything else here. Nothing changes state without a person agreeing to it.