TLDR: Setup guides reach your AI agent through surfaces that can hide text from you but not from the model. GuideCheck is an open standard for a constrained, plain-text assistant-guide.txt that a human can read in full before authorizing an agent to act. It ships a five-level conformance ladder, a reference verifier, and a hosted checker. Conformance verifies form, not safety — and the standard says so on every level.
The guide you skimmed isn't the guide the model read
You point your coding agent at a project's setup guide. "Install this, configure that, run the migration." You skim the page in your browser. It looks reasonable. You approve. The agent runs.
Here is the part that should bother you: the guide you skimmed is not necessarily the guide the model read.
Setup instructions travel through HTML, rendered Markdown, PDFs, docs sites, copied issue comments, terminal output, even screenshots. Every one of those surfaces can carry content a model ingests but a human never sees:
- hidden HTML comments
- off-screen CSS
- white-on-white text
- script-inserted text
- invisible Unicode control characters
- terminal escape sequences
...and a wall of other nefarious instructions buried far below the fold.
You approved what was visible. The model acted on all of it.
That gap stays harmless right up until your agent has a shell, a package manager, and write access to your repo. Then it is the whole problem.
A plain-text surface you can actually review
GuideCheck is an open standard that closes that gap. It defines a constrained plain-text artifact — assistant-guide.txt — for the assistant-facing parts of an install, configuration, remediation, or migration flow. The whole point is that a human can read the entire instruction surface, in full, before authorizing an agent to follow it.
It is a PAICE Foundation standard, currently draft v0.2.1, openly licensed, with a reference verifier you can run locally and a hosted checker at guidecheck.org/verify.
snapsynapse
/
guidecheck
AI setup guides can hide instructions a model reads but a human never sees. GuideCheck is the plain-text standard that makes an assistant's instruction surface reviewable before it acts.
GuideCheck
AI setup guides can hide instructions a model reads but a human never sees
GuideCheck is the standards project for the Human-Verifiable Assistant Guide
profile: a constrained plain-text profile for assistant-guide.txt, covering
assistant-facing install, implementation, remediation, migration, and
operational instructions that a human can review in full before an assistant
acts on them.
Canonical site: https://guidecheck.org/ Verifier: https://guidecheck.org/verify
New here: ADOPTION.md is the practical on-ramp. It explains the conformance
ladder, gives a level-by-level path, and carries the guide-author checklist.
Naming model
- The standards project, public checker, ecosystem, and site are GuideCheck.
- The artifact is
assistant-guide.txt. - The profile is the Human-Verifiable Assistant Guide profile.
- A conformant file is an
assistant-guide.txtartifact that satisfies a specific profile version. - A GuideCheck conformance claim is valid only when backed by verifier output, guide hash, achieved level, and findings.
Conformance is not safety
Conformance to this profile, at any level, does not…
🔒 One file, no presentation layer
The artifact is a .txt file served at /.well-known/assistant-guide.txt. No HTML. No CSS. No script. The bytes you read are the bytes the agent reads, in every editor, terminal, and viewer.
From Level 2 up, the file is restricted to ASCII (bytes 0x0A and 0x20–0x7E). That single rule shuts the door on homoglyph swaps, bidirectional-override tricks, zero-width joiners, and mixed-script obfuscation in one move. There is nothing to render differently, because there is nothing to render.
📏 An 8 KiB cap, on purpose
The file has a hard 8 KiB size cap. That is not a storage decision — it is calibrated against human attention.
The original draft used 16 KiB. In review, that allowed roughly fifteen action blocks with comfortable prose, and a fifteen-step approval ceremony stops being review and becomes ritual. So the cap was pulled in to match a signal the verifier already emits: a warning past ten approvals. Tight is the feature. A flow that genuinely can't fit usually should have been two flows.
8 KiB at a careful reading pace is under ten minutes of focused review. Aviation checklists, surgical timeouts, and security.txt files all trend small for the same reason: high-stakes artifacts reviewed under time pressure have to stay short.
✅ Structured actions with explicit approval gates
Instructions an agent may execute live in structured [action] blocks — never in loose prose. Each block declares a class and whether it needs a human's go-ahead:
[action]
id: check-version
class: normal
approval: not-required
command: example-cli --version
cwd: .
notes: Detects an existing install. Read-only.
[/action]
Actions are classed as normal, networked, destructive, privileged, persistence-changing, data-accessing, or code-executing. The dangerous classes require explicit human approval, and a conformant guide can't quietly bury a rm -rf in a paragraph and hope the model runs it. Prose is context. Only approved action blocks are executable.
The standard also forbids chained guides: a guide can verify its own identity, but it can never tell an agent to fetch and follow another guide. Silent transitive trust is the attack.
🪜 A five-level conformance ladder — and an honest one
Conformance is additive. Level 1 is "a plain-text guide exists and is reachable." Level 2 adds the byte profile and size limits. Level 3 adds the safety contract, required sections, and approval gates. Level 4 adds verifiable provenance with a sidecar manifest and a cross-channel hash. Level 5 is a guide plus a runtime that mechanically enforces the contract.
Here is the line the standard repeats on every level, in every document: conformance is not safety. A verifier confirms form. It cannot tell you a publisher is trustworthy or that a guide is safe to follow. The tempting move was to let the hosted checker hand out a green safety badge. We deliberately didn't — a checker that becomes a root of trust is just a new single point of failure. The human stays in the loop. The standard only makes the surface they're reviewing honest.
Tech stack
- Reference verifier: a dependency-free Python CLI (scripts/guidecheck_verify.py) — evaluates the file's bytes, never executes its content
- Hosted verifier: a preview web checker on Vercel that fetches a guide by URL and runs the same Level 1–3 logic
- Conformance corpus: a fixture suite of valid and invalid guides, so independent verifier implementations stay in agreement
- Specs: spec.md and verifier-conformance.md, versioned together so they can't drift
The non-obvious call was scoping the verifier to Levels 1–3 only. Level 4 provenance and Level 5 runtime claims aren't shipped as "verified" until their fixtures are complete. Claiming a check you can't yet back with tests is how a standard quietly loses its meaning.
"Why not just use llms.txt?"
Fair question. llms.txt points an assistant at documentation — it's a discovery file, with no safety profile, no byte constraints, and no execution model. robots.txt and security.txt are single-purpose and carry nothing an assistant would execute. None of them was built for the case where an agent acts on what it reads. GuideCheck is that missing layer, and it's designed to sit alongside sandboxing and least privilege, not replace them.
Try it
Point the hosted verifier at any guide URL:
https://guidecheck.org/verify
Or run the reference verifier on a local file:
python3 scripts/guidecheck_verify.py assistant-guide.txt --pretty
ADOPTION.md in the repo is the practical on-ramp — the conformance ladder, a level-by-level path, and a guide-author checklist.
Your turn
If you've handed a setup task to an AI agent lately: how do you currently know the instructions it followed are the ones you actually read? Drop it in the comments 👇