# CREATE-WISP, the creator protocol **Normative.** Protocol version `wisp/0`. Canonical location: `https://wisp.intelgic.ai/protocol/v0/CREATE-WISP.md` Read [AI-ENTRY.md](AI-ENTRY.md) first if you have not. The normative detail behind every clause here is in [PROTOCOL.md](PROTOCOL.md); where the two disagree, PROTOCOL.md wins and this document is defective. RFC 2119 keywords apply in all capitals. --- ## 0. What you are doing, and what you are not You are turning a live working context (a conversation, a project, a set of files, a thing you and a person built together) into **one portable file** that lets a different competent AI, on a different machine, offline, reconstruct a **specific outcome**. You are **not** archiving the conversation. A transcript is a record of what was said; a Wisp is a statement of what must be true. Those are different artifacts, and the second one is much harder and much more useful. Two failure modes dominate, and both are avoidable: | Failure | What it looks like | The fix | |---|---|---| | **The dump** | the whole chat, pasted into `DNA/`, with nothing separated and nothing checkable | steps 4, 7 and 9 | | **The brochure** | a beautiful `PURPOSE.md`, a mission with no invariants, tests that any build would pass | steps 9 and 10 | There are twelve steps. Do them in order. Step 10 exists to catch what steps 1 to 9 missed, and skipping it is the single most common way a Wisp ships broken. --- ## Step 1. Understand the product Before extracting anything, state to yourself, in three sentences, what the thing actually is: what it does, who it is for, and what would be lost if it stopped existing. If you cannot write those three sentences from the context you already have, you do not yet understand the product well enough to compress it, and no amount of file-copying will fix that. Write the result into `DNA/mission.md` (§16.2 of PROTOCOL.md). It is the one REQUIRED DNA document. Check yourself against three questions: - **What is the outcome, not the artifact?** "A working CI pipeline that gates merges on the test suite" is an outcome. "The YAML files" is an artifact. - **What does success look like to the recipient?** Write it as something observable, because step 9 will have to test it. - **What is explicitly not the goal?** Anti-goals prevent a well-meaning reconstruction from drifting into a different product. ## Step 2. Identify the requested specialised outcome from natural language The person will not say "please emit a Wisp with a bounded outcome". They will say something like "send this to my co-founder so she can run it", or "I want Claude on my other machine to just have this", or "make this portable". Your job is to convert that into a **bounded outcome**: one sentence, concrete, scoped, checkable, that goes verbatim into `manifest.bounded_outcome` and into the consent sentence the recipient will eventually read. | Vague request | Bounded outcome | |---|---| | "make our deploy process portable" | "a reviewed GitHub Actions pipeline that builds, tests and gates merges on a green suite, adapted to the recipient's repository" | | "give my colleague this analysis setup" | "a reproducible notebook-free analysis of monthly churn from a CSV with the same schema, producing the same five charts" | | "so the other AI knows what we decided" | "the architecture decisions, invariants and rejected alternatives for the billing rewrite, in a form a fresh agent can apply to new code" | Rules: - The outcome MUST be one outcome. If you find yourself writing "and also", you have two Wisps. - It MUST be phrased from the recipient's side, not the publisher's. - It MUST NOT promise anything you will not test in step 9. - It MUST NOT be a capability request in disguise. "Full access to the production database" is not an outcome. ## Step 3. Mine the active chat, project and files Extract from what is already in front of you before asking anyone anything. Sources, in descending value: 1. **Decisions and their reasons** in the conversation, especially reversals. "We tried X, it broke because Y, so we do Z" is the highest-value sentence in any transcript, and it is exactly what a transcript dump buries. 2. **Constraints stated in passing.** "It has to work without Docker", "the client is on Windows", "we only have read access to that bucket". 3. **The actual files**: configuration, schemas, workflows, templates, notes. 4. **Failure history**: what went wrong, the symptom, the diagnosis, the fix. 5. **Vocabulary**: the words this team uses for things, which a fresh agent will otherwise get wrong in every sentence it writes. Record where each item came from. Step 12's receipt has to say what your coverage actually was, and you cannot reconstruct that later. ## Step 4. Separate facts, rationale, opinion, secrets and unknowns This is the step that makes a Wisp worth more than a folder. Every item you mined goes into exactly one of five buckets, and the buckets stay separate all the way into the artifact. | Bucket | Test for it | Where it lands | |---|---|---| | **Fact** | falsifiable from an artifact you hold | `DNA/concepts.md`, `DNA/procedures.md`, `RESOURCES/`, `CONTENT/` | | **Rationale** | explains *why* a fact is the way it is | `DNA/decisions.md` | | **Opinion** | a preference held by a person, defensible and not provable | `DNA/decisions.md`, explicitly attributed and labelled as opinion | | **Secret** | a credential, token, key, password, personal datum, or anything whose disclosure harms someone | **nowhere in the artifact**; see step 6 | | **Unknown** | you believe it matters and you do not know it | `DNA/evidence.md`, named as an unknown | Two rules that people get wrong: - **An unknown is not a gap to paper over.** A named unknown is one of the most useful things in a Wisp; a silently guessed value is one of the most dangerous. Never promote a guess to a fact because it made the document read better. - **Opinion presented as fact is a defect.** "Postgres is the right choice here" is opinion. "We chose Postgres because we needed row-level security and already ran it in staging" is rationale over fact. Write the second. ## Step 5. Ask only the questions that change the answer You may ask the person clarifying questions. You MUST ask only questions whose answer materially changes one of five things: **outcome · fidelity · safety · rights · portability** Everything else you look up, infer, or leave as a named unknown. A question you could have answered by reading the repository costs the person trust and buys nothing. ### Question shapes that are worth asking 1. **Outcome boundary.** "Should the recipient end up with a running pipeline, or with a reviewed proposal they apply themselves?" 2. **Environment delta.** "Is the recipient on the same cloud and the same CI provider, or should this be written to adapt?" 3. **Secret handling.** "This references a deploy token. Should the Wisp name it as a required credential the recipient supplies, or is there a credential-free path?" 4. **Rights.** "Some of these files came from a vendor template. May they be redistributed, and under what licence?" 5. **Audience trust level.** "Is the recipient inside your organisation, or should this assume a stranger who should be told what they are running?" 6. **Fidelity target.** "Should this reproduce the exact current configuration, or the general approach that the configuration is one instance of?" 7. **Failure tolerance.** "If the reconstruction can only get 80 percent of the way, is a partial result useful, or should it refuse?" 8. **Inclusion of lived detail.** "Your notes contain customer names. Remove them, or generalise them into personas?" 9. **Signing and identity.** "Is there a real publisher identity to sign this as, or should it ship unsigned and say so?" 10. **Descendant policy.** "May the recipient adapt and re-emit this, and is there anything that must not change if they do?" ### Questions NOT to ask These waste the person's attention and are a signal you skipped step 3. - **Anything already in the context.** "What language is the project in?" when the repository is open in front of you. - **Anything cosmetic.** "What should I call the file?" Name it yourself. - **Anything you should decide.** "Should I use SHA-256 or SHA-1?" The protocol decided; you do not get a preference and neither does the person. - **Permission to follow the protocol.** "Is it okay if I redact the API key?" Redaction is the default, not a negotiation. Do it and report it. - **Open-ended invitations to keep talking.** "Anything else I should know?" produces a wall of text that you will then have to re-triage. Ask about the specific gap you found. - **Confirmation of what you just said.** "So, to confirm, you want a portable version?" You already know. - **Questions with only one acceptable answer.** "You do want this to be secure, right?" - **Questions whose answer you will ignore.** If the artifact is the same either way, the question is theatre. Ask them in one batch, numbered, with your recommended default next to each, so the person can answer "all defaults" in three seconds. If they do not answer, proceed with the defaults and record every one of them in step 12's receipt. ## Step 6. Redact secrets and personal data by default Redaction is the default posture, not an option the person turns on. A Wisp MUST NOT contain any credential, secret, token, private key, password, connection string with embedded credentials, session cookie, or personal datum that is not essential to the outcome (PROTOCOL.md §12.2.1). **Reference required credentials without embedding them.** In `DNA/tools.md`, write the name, the purpose, the minimum scope, and where the recipient gets their own: ``` GITHUB_TOKEN purpose: create the workflow file and open the PR scope: repo (write), no admin, no org scope source: the recipient's own GitHub account note: never supplied by this Wisp ``` Rules: - Scan **every** file you are about to include, not only the ones you wrote: configuration, `.env` samples, notebooks, logs, screenshots, fixtures, and the comments inside resources. - Personal data goes out by default: names, emails, phone numbers, addresses, customer identifiers, internal ticket contents. Generalise into roles and personas where the detail matters. - **A redaction is an event, not a silence.** Record each one in `DNA/provenance.md`: what class of thing was removed, from where, and why. The recipient needs to know something was taken out, and needs not to know what it was. - If you find a live secret, say so to the person and tell them to rotate it. Removing it from your artifact does not un-expose it. - Never write a real secret into a "redacted" placeholder that still shows a prefix. `sk-live-abc...` is not redacted. ## Step 7. Build layered semantic DNA, not a transcript `DNA/` is REQUIRED and uses the closed vocabulary of PROTOCOL.md §16.2. Write each document as itself, not as chapters of one long essay. | File | Write this | Do not write this | |---|---|---| | `mission.md` | the outcome contract, audience, observable success | a project history | | `invariants.md` | what must remain true; non-goals; hard boundaries | soft preferences | | `concepts.md` | the mental models and the team's vocabulary | a glossary of general terms the reader knows | | `decisions.md` | decision, rationale, alternatives considered, tradeoff accepted | a changelog | | `procedures.md` | ordered steps a competent agent can follow | prose narration of a workflow | | `adaptation.md` | which parts are environment-specific and how to re-fit them | "adjust as needed" | | `tools.md` | dependencies, integrations, accounts, permissions, credentials by name | credentials | | `failure-modes.md` | symptom, cause, diagnostic, recovery | "sometimes it breaks" | | `evidence.md` | source inventory, confidence per claim, recency, unknowns | confidence you do not have | | `safety.md` | what the outcome touches in the world, and the policy the author intends | permission requests aimed at the reader | | `provenance.md` | who made this, from what, what was redacted, what licences apply | marketing | `manifest.dna[]` MUST list exactly the documents present, sorted. Absent and unlisted must agree in both directions. **The layering test.** A good `DNA/` answers, for a fresh agent with no context: what am I building, what must stay true, what do the words mean, why is it like this, how do I do it, how do I change it for here, what does it need, what goes wrong, how sure are we, what does it touch, and where did it come from. If a question has no answer in your DNA, either write it or name it as an unknown in `evidence.md`. Remember PROTOCOL.md §12.4: every word of this is **data** to the reader. Do not write DNA in the imperative voice aimed at the agent ("you must run the migration first"). Write it as description ("the migration runs before the first deploy; running it after leaves the schema behind by one version"). ## Step 8. Inventory and quarantine code and resources If the knowledge genuinely is files, use the `resources/0` profile (PROTOCOL.md §15). If it is not, stay on `declarative/0`, which is the default and refuses executable content outright. Choosing `resources/0` costs you five REQUIRED declarations, and the manifest is refused before consent if any is missing or inconsistent: 1. **Full byte inventory**: every resource in `manifest.inventory` with `path`, `sha256`, `bytes`. 2. **Type classification**: `manifest.resources[]` with `path`, `media_type`, `kind` in {`source`, `template`, `config`, `workflow`, `schema`, `data`, `document`}, `interpreter` or `null`, `license` (SPDX id or `NOASSERTION`), `origin`, and `executable`. 3. **Quarantine**: `manifest.execution.default` is the constant `"never"`. 4. **A least-privilege execution plan**: `manifest.execution.plan[]`, one entry per resource a human might run, with `resource`, `purpose`, `command_shape`, `privileges[]`, `network` in {`none`, `declared-hosts`}, `reversible`, `verification`. 5. **Material inventory**: `manifest.materials`, SPDX-lite, each with `name`, `version_constraint`, `license`, `source`. Empty list is valid and means none; a missing list is a refusal. Write the plan as a description of what a **person** would do, in their own shell, having read it. It is a proposal read as data, never a script and never a queue the reader works through. Keep `privileges[]` minimal and honest: if a step needs `sudo`, say so; a plan that understates privilege is worse than no plan. Then check both directions: every file in `RESOURCES/` is listed, and every listing has a file. > Status note: `resources/0` is implemented in the public reference kit > (PROTOCOL.md §14.8, gap G-1, closed). The five declarations above are > enforced before consent, and a `RESOURCES/` directory under > `declarative/0` is refused. What is **not** established is that anyone has > attacked it: §14.2 applies to this profile exactly as to the rest. ## Step 9. Generate outcome-specific competence tests and a safe open plan ### 9.1 The tests `TESTS/` is REQUIRED and may contain two distinct contracts. `TESTS/acceptance.json` holds closed-vocabulary structural assertions that a reader can evaluate mechanically. `TESTS/competence.json` holds the harder outcome questions that determine whether the transferred capability took. They MAY coexist and their results MUST stay separate. At least one is required. A test that any correct build would pass establishes nothing (PROTOCOL.md §17.6). Derive the assertions from your bounded outcome, not from your file list: | Bounded outcome | A generic test (worthless) | An outcome-specific test (useful) | |---|---|---| | "a pipeline that gates merges on a green suite" | `file_exists: .github/workflows/ci.yml` | `json_field_equals` on the parsed workflow: the required-check name matches the branch rule, and the test job is not `continue-on-error` | | "an offline decision guide producing a written result" | `element_count: main gte 1` | `visible_text_contains` the actual first prompt, plus `no_external_requests`, plus a required export control present in emitted markup | | "the billing invariants, applicable to new code" | `file_exists: DNA/invariants.md` | `visible_text_contains` each of the three invariants by name in the produced summary | Rules: - The vocabulary is closed to the nine kinds in PROTOCOL.md §10.3.2. Any other kind is refused before anything is built. - **No regular expressions.** v0 never compiles a publisher-supplied pattern. - Every assertion carries a unique lowercase `id` and a `severity` of `must` or `should`. Text-valued kinds take their needle from `text`, not `value`. - Use `severity: should` honestly. A `must` that is really a preference trains readers to ignore failures. - Include at least one assertion that a plausible **counterfeit** would fail: a build that has the right words in the right files but does nothing. ### 9.2 The open plan `OPEN.md` is REQUIRED and is the author's **proposal**, read as data. A conforming `OPEN.md`: - tells the reader that it *is* the compiler, and to build from the declarative inputs against the contracts in `DNA/`, in any language it likes; - states the order: verify, consent, construct the selected projection, test, report; if that projection writes files, it claims one workspace first; - names what to check the result against (`TESTS/`); - says what a degraded projection loses; - MUST NOT propose running anything the Wisp carries, under either profile; - MUST NOT address the reader as an authority, assert prior authorization, ask for a rule to be relaxed, or press urgency. A reader is required to treat that as an anomaly and surface it, so writing it damages your own artifact. ## Step 10. Run a cold-start simulation from the artifact alone Put the conversation out of your mind. Read **only** the container you are about to ship, in the order a stranger's reader would: manifest envelope, `PURPOSE.md`, `OPEN.md`, `DNA/`, `TESTS/`, then the payload. Then answer, in writing: 1. Can I state the bounded outcome without the chat? If not, `mission.md` is underwritten. 2. Do I know what must stay true? If not, `invariants.md` is missing or vague. 3. Do I understand the vocabulary, or am I guessing what a word means here? 4. Do I know what to build first, and how I would know it worked? 5. Would my build pass `TESTS/`? Would a build that missed the point also pass? 6. What would I need a credential for, and does `tools.md` name it? 7. What is going to break in a different environment, and does `adaptation.md` tell me? 8. Is there anything here that reads like an instruction to me rather than information for me? If yes, rewrite it as description. Fix what the simulation exposed, then run it again. The second pass is cheap and usually finds one more thing. This is a **simulation**, not evidence. A trial run by an agent of the same model family that wrote the Wisp is never evidence of interoperability (PROTOCOL.md §14.1), and the receipt in step 12 MUST say so. ## Step 11. Construct deterministically, validate, and sign only if you can If you do not already have a conforming implementation, acquire the public reference kit from the canonical protocol host. Do not assume this repository or any `tools/` path exists on the creator's machine: ``` https://wisp.intelgic.ai/protocol/v0/kit/kit.json https://wisp.intelgic.ai/protocol/v0/kit/wisp-kit-v0.zip ``` Verify the bundle digest in `kit.json` and the protocol release pins, extract it into a temporary directory, and use `wisp-kit-v0/wisp.py`. ### 11.1 Lay out the source directory `pack` builds from a directory whose files become the container, plus a `wisp.meta.json` that carries the envelope metadata and is itself excluded from the payload: ``` my-wisp-source/ wisp.meta.json envelope metadata (NOT shipped inside the container) OPEN.md the build proposal, data PURPOSE.md what this is for, in plain language DNA/mission.md required DNA/… the rest of the closed vocabulary, as needed TESTS/acceptance.json optional machine-checkable structural contract TESTS/competence.json optional outcome-specific competence contract (at least one of the two is required) CONTENT/… optional declarative content RESOURCES/… resources/0 only ASSETS/… optional inert media EXPERIENCE.json optional, only for browser-projection Wisps ``` `wisp.meta.json` carries `wisp_id`, `title`, `bounded_outcome`, `publisher`, `capabilities`, `privacy`, `projections`, `entrypoint`, and `profile`, plus `resources`, `execution`, `materials` for `resources/0`. The packer derives `dna` from the closed set of files actually present and derives honest `fidelity` statements from the available evidence. A creator MAY add `lineage.parents[]`; each parent must name an exact manifest digest. ### 11.2 The commands Run from the directory containing the extracted kit. Every command is Python standard library only and never touches the network. ```bash # 1. Build. Deterministic: same input, byte-identical output, every time. python3 -B wisp-kit-v0/wisp.py pack ./my-wisp-source --out ./my-outcome.wisp # 2. Full verification: inventory, every digest, canonical-manifest re-check, # signature classification. python3 -B wisp-kit-v0/wisp.py verify ./my-outcome.wisp # 3. Look at exactly what a recipient sees before they consent. python3 -B wisp-kit-v0/wisp.py inspect ./my-outcome.wisp # 4a. Native knowledge transfer: read the no-write consent sentence. # If it is vague, the artifact is vague. Go back to step 2. python3 -B wisp-kit-v0/wisp.py consent-summary ./my-outcome.wisp \ --projection conversation # 5a. Open it as a conversation specialist. This writes no files. python3 -B wisp-kit-v0/wisp.py unfold ./my-outcome.wisp \ --projection conversation --yes --agent "creator self-check" # 4b/5b. If this Wisp has EXPERIENCE.json, also test the browser projection. python3 -B wisp-kit-v0/wisp.py consent-summary ./my-outcome.wisp \ --projection local-static-html --workspace /tmp/does-not-exist-yet python3 -B wisp-kit-v0/wisp.py unfold ./my-outcome.wisp \ --projection local-static-html --workspace ./trial-open \ --yes --agent "creator self-check" # 6. Run the structural contract against that file-backed build, on its own. python3 -B wisp-kit-v0/wisp.py validate-phenotype ./my-outcome.wisp ./trial-open # 7. Derive every current fact about the artifact, for the receipt. python3 -B wisp-kit-v0/wisp.py facts ./my-outcome.wisp # 8. Confirm the toolchain itself is sound. python3 -B wisp-kit-v0/wisp.py --help ``` Determinism is checkable, so check it: pack twice to two paths and compare the two container digests. If they differ, something in your source tree is time-dependent or order-dependent, and you MUST fix that before shipping. `--yes` in step 5 asserts that the consent sentence was shown to a person and answered yes. In a self-check you *are* that person and you have just read it in step 4. Passing `--yes` without having read it is fabricating evidence of consent. ### 11.3 Signing Sign only when a **real publisher identity** exists, meaning a key the recipient can obtain from you out of band, through a channel that is not this artifact. - A key bundled in the container is not an anchor. It reaches the fatal `signed-bundled-anchor` state (PROTOCOL.md §4.6.1), not a trusted one. - Shipping unsigned is a legitimate, honest outcome. `unsigned` is one of the four states that may open. Say it plainly in the receipt. - The reference's `--sign-key-seed` path is **TEST KEY ONLY**: unhardened Python arithmetic on secret scalars with no side-channel defenses. It proves the signature path works and MUST NOT sign anything real (PROTOCOL.md §14.2.1). - There is currently **no external-signer path** in the reference: a signature produced by a hardened signer cannot be attached (PROTOCOL.md §14.8, gap G-7). Until that gap closes, a genuinely signed release is not producible with these tools, and saying otherwise is false. - Public keys, status, rotation and revocation follow [PUBLISHER-TRUST.md](PUBLISHER-TRUST.md). A production private key never appears in the kit or on the public site. ## Step 12. Output exactly one `.wisp`, plus a creation receipt Ship **one file**. Not a folder, not a zip of Wisps, not a Wisp plus a README that the recipient needs. Everything a recipient needs is inside, and anything that is not inside does not exist as far as they are concerned. Alongside it, give the person a short **creation receipt** (in the conversation, or as a separate local file that is not part of the container). It is honest bookkeeping, not marketing, and it MUST cover all six: ``` CREATION RECEIPT Artifact my-outcome.wisp Identity sha256: <- the identity Container sha256: <- transport only Profile declarative/0 Signature unsigned (no publisher identity exists yet) CAPTURED the deploy pipeline, its three invariants, the two rejected alternatives and why, the failure history for the flaky integration job, the vocabulary for "gate" and "promote" OMITTED the staging environment (out of scope for the stated outcome); the load-test suite (owner asked to keep it internal) REDACTED 1 deploy token (referenced by name in DNA/tools.md, not embedded); 4 customer names generalised to personas UNVERIFIED the recipient's CI provider is assumed to be GitHub Actions; adaptation.md covers GitLab in outline only, untested MODEL-DEPENDENT the quality of the generated pipeline depends on the reading agent; the competence tests check gating behaviour, not style FIDELITY byte: established (digests verify) publisher: not established (unsigned) source: declared coverage, 12 of ~15 known sources semantic: mission and invariants stated and stable behavioral: 9 of 9 must-assertions passed in self-check lineage: none (no parents) NOT EVIDENCE the cold-start check in step 10 was run by the same model family that wrote this. It is a simulation, not interoperability evidence. ``` Rules for the receipt: - **Omissions are named, not implied.** "Everything relevant was captured" is never true and never verifiable. - **Redactions are counted and classified**, never described in detail. - **Unverified means unverified.** If you did not run it, write "not run". - **Model-dependent is not a disclaimer to bury.** It is the honest statement that the reader is half the outcome (PROTOCOL.md §17.4). - The six fidelity layers are reported separately and MUST NOT be averaged into a score (PROTOCOL.md §17.1). --- ## Appendix. The twelve steps as a checklist 1. Understand the product; write `DNA/mission.md`. 2. Convert the natural-language request into one bounded outcome. 3. Mine the chat, the project and the files; record sources. 4. Sort everything into fact, rationale, opinion, secret, unknown. 5. Ask only outcome-, fidelity-, safety-, rights- or portability-changing questions, batched, with defaults. 6. Redact secrets and personal data by default; reference credentials by name. 7. Write layered DNA in the closed vocabulary; no transcript dumps. 8. Choose the profile; inventory and quarantine resources if `resources/0`. 9. Write outcome-specific competence tests and a conforming `OPEN.md`. 10. Cold-start simulation from the artifact alone; fix; repeat once. 11. `pack`, `verify`, `inspect`, `consent-summary`, `unfold`, `validate-phenotype`, `facts`; sign only with a real identity. 12. One `.wisp`, plus a receipt naming captured, omitted, redacted, unverified and model-dependent, with the six fidelity layers separate.