🧭 Choose the right AI working contract before you ask AI to work.
ai-protocol-kit is a collection of practical AI protocols for making AI-assisted work more structured, inspectable, and repeatable. 🛠️🔍♻️
These are not magic prompts. 🪄🚫
They are working contracts: instructions you give to an AI so it knows how to approach a task, what to check, what not to assume, when to stop, and what kind of output is acceptable. 📜✅🛑
The protocols are experimental and shaped from real workflows: rough ideas, repository reviews, README work, GitHub publication, public pages, bug findings, structured outputs, and complex sessions where AI needs stronger rails before it acts. 🧪🧱🌐🤖
Do not pick a protocol by name first. 🧩
Pick it by the failure mode you want to prevent.
Use these when the work is still fuzzy, overloaded, or easy for AI to collapse too quickly. 🌫️➡️🧱
- 🧩 Idea Shaping Protocol v1
- 🔍 Pre-Task Expansion Protocol v1
- 🧬 Structural Shaping Protocol v1
- 📡 System Reading Protocol v0.2
Use these when the goal is to turn intent into an execution-ready brief. 🎯📐🛠️
Use these when evidence, uncertainty, observations, bugs, or claims must stay separated. 🔎🧪📌
Use these when the problem is not just unclear, but structurally easy to collapse, misread, over-simplify, or resolve with a fake compromise. 🧠⚖️🔍
Use these when the work touches repositories, README files, GitHub Pages, badges, telemetry, discovery files, public project pages, or publication hygiene. 🐙📦🌐🚀
- 🚦 GitHub Repository Publication Preparation Protocol v2
- 📝 GitHub README Framing and Authoring Protocol v2
- 🧿 GitHub Pages Discovery Set Protocol v1
- 📊 GitHub Badge, Telemetry & Counter Protocol v1.2.3
- 🌐 Public Page Publication Protocol v2
- 🛰️ HTML and Website Discovery Set Protocol v1.2
Use these when the AI session itself needs stronger behavior rails. 🤖🧭🧰
Some protocols appear in more than one lane because they can play different roles. That is intentional, but stacking is still not the default. 🔁🛑
| Lane | Use when | Protocols |
|---|---|---|
| 🐣 Shape the work | The task is ambiguous, premature, overloaded, or underspecified. | 🧩 Idea Shaping · 🔍 Pre-Task Expansion · 🧬 Structural Shaping · 📡 System Reading |
| 🧾 Brief the artifact | AI needs a clear brief before writing, building, or structuring output. | 🧱 HTML Page & Tool Briefing · 🗣️ Output for Real Readers |
| 🐞 Review findings and evidence | The job is inspection, bugs, uncertainty, evidence, or claim control. | 🐞 Field Findings & Bugs · 📡 System Reading |
| 🧠 Reasoning, constraints & system reading | The task needs expansion, system interpretation, or constraint-aware reasoning before output. | 🔍 Pre-Task Expansion · 📡 System Reading · 🌀 PHI-Lens |
| 🐙 GitHub / public repo & page publishing | The work touches GitHub, Pages, README, public pages, discovery files, badges, or publication hygiene. | 🚦 Repository Publication · 📝 README Framing · 🧿 Pages Discovery · 📊 Badge/Telemetry · 🌐 Public Page Publication · 🛰️ Website Discovery |
| ⚙️ Govern agentic sessions | AI must operate with tools, files, repo state, review loops, or multi-pass control. | ⚙️ Agentic Posture |
The GPT Agentic Posture Contract depends on Canvas as a separate, persistent execution ledger. Since OpenAI’s May 28, 2026 GPT-5.5 update, Canvas is no longer available in GPT-5.5 Instant or GPT-5.5 Thinking. Without Canvas, the contract remains useful as posture guidance, but it should not be treated as a full agentic execution protocol.
A limited workaround may still exist in some ChatGPT sessions: start from a model or flow where Canvas can still be opened, open Canvas first, then invoke the contract only after the assistant can see Canvas editing tools. This is fragile, UI-dependent, and not contractual.
Default rule: use one protocol. ☝️
Stack only when one protocol controls the session and another controls the artifact or publication target. 🧱➕🧭
- 🚦 GitHub Repository Publication Preparation Protocol v2
- 📝 GitHub README Framing and Authoring Protocol v2
- 📊 GitHub Badge, Telemetry & Counter Protocol v1.2.3 only if badges, counters, analytics, or validation checks are actually needed
- 🌐 Public Page Publication Protocol v2
- 🧱 HTML Page & Tool Briefing Protocol v2 if implementation briefing is needed
- 🧿 GitHub Pages Discovery Set Protocol v1 or 🛰️ HTML and Website Discovery Set Protocol v1.2 before publishing
- 🐞 Field Findings & Bugs Protocol v2
- 🌀 PHI-Lens Protocol v4.a only if constraints conflict and a flat compromise would be misleading
- 🔍 Pre-Task Expansion Protocol v1 if the task may collapse too quickly into the obvious answer
- 📡 System Reading Protocol v0.2 if the real system behavior matters more than declared intent
- 🌀 PHI-Lens Protocol v4.a only if constraints interact and the output needs an explicit gate
- ⚙️ GPT Agentic Posture Contract
- 🔺 Triad AI Orchestration Protocol v3 only if executor/reviewer separation is needed
- 🐞 Field Findings & Bugs Protocol v2 if findings must be captured as evidence
- 🎯 Pick the protocol closest to the actual job.
- 📋 Paste or upload the protocol into the AI context before execution.
- 📦 Provide the target material: files, repo snapshot, page, README, bug report, idea, or constraints.
- ✅ Let the protocol control the workflow: questions, gates, review, assumptions, stop conditions, and final output.
Do not stack protocols casually. 🛑
Use the smallest set that fits the task. 🧘♂️
| Protocol | Best use |
|---|---|
| 🧿 GitHub Pages Discovery Set Protocol v1 | Prepare GitHub Pages user/org sites, project sites, or custom-domain Pages sites with correct publication roots, discovery files, canonical URLs, sitemap, robots handling, and low-noise machine-readable footer links without breaking GitHub Pages path rules. |
| 🚦 GitHub Repository Publication Preparation Protocol v2 | Prepare a repository for clean GitHub publication, forcing project classification, workspace and risk audit, minimal file/package decisions, GitHub feature choices, and confirmation before commits, remotes, Pages, or push. |
| 📊 GitHub Badge, Telemetry & Counter Protocol v1.2.3 | Decide which badges, counters, analytics, traffic checks, or validation checks make sense for a GitHub repo or GitHub Page without adding vanity widgets. |
| 📝 GitHub README Framing and Authoring Protocol v2 | Write or restructure a GitHub repository README from repository evidence, reader fit, and the real job the README must perform. |
| ⚙️ GPT Agentic Posture Contract | Make ChatGPT work more like Codex: tool-aware, grounded in real files and artifacts, ledger-based, verification-oriented, and willing to stop when the task is not ready. |
| 🌐 Public Page Publication Protocol v2 | Prepare, restructure, or publish a public page, landing page, showcase, portfolio page, documentation entrypoint, or GitHub Pages site with page role, audience, metadata, accessibility, links, visual identity, and publication risks closed before deploy or push. |
| 🧩 Idea Shaping Protocol v1 | Turn a rough idea into a clear structure before asking AI to write, plan, design, or build anything. |
| 🧱 HTML Page & Tool Briefing Protocol v2 | Guide an AI from raw intake to a complete implementation brief for a static HTML page, web surface, or local tool. |
| 🐞 Field Findings & Bugs Protocol v2 | Capture findings and bugs as structured artifacts while keeping evidence, inference, uncertainty, relations, and later promotion separate. |
| 🛰️ HTML and Website Discovery Set Protocol v1.2 | Prepare static HTML pages or websites with machine-readable discovery files, head metadata, canonical URLs, sitemap, robots rules, and low-noise footer links. |
| 🌀 PHI-Lens Protocol v4.a | Handle non-trivial AI tasks where constraints interact and a flat compromise would hide the dominant force, counterforce, or asymmetry. |
| 🔍 Pre-Task Expansion Protocol v1 | Stop an AI from collapsing too quickly into the obvious answer by exposing alternative readings, tensions, and surrounding shape first. |
| 🗣️ Output for Real Readers Protocol v2 | Write guides, README text, emails, pages, forms, instructions, or reader-facing material with reader, purpose, tone, constraints, and language closed before drafting. |
| 🧬 Structural Shaping Protocol v1 | Shape ambiguous input into operational form before synthesis, with gates, evidence level, source boundaries, and artifact direction explicit. |
| 📡 System Reading Protocol v0.2 | Read the gap between declared intent and observable behavior to extract the operative principle of a system without premature solutions. |
| 🔺 Triad AI Orchestration Protocol v3 | Run a review loop between an executing AI near the real target and a reviewing AI over snapshots, repo state, diffs, or files while preserving target authority and patch/test evidence. |
Use this kit when you want AI-assisted work to be more: ✨
- 🔍 inspectable
- ♻️ repeatable
- 🧱 structured
- 🧭 constrained
- 🐙 repository-aware
- 🛑 honest about stop conditions
- 📌 explicit about evidence and assumptions
It is useful for practical, messy, non-theoretical situations where the AI should not simply improvise from a vague prompt. 🧪🛠️
This is not a replacement for judgment. 🧠
These protocols do not guarantee correctness. They reduce common failure modes: rushing to the obvious answer, writing for the wrong reader, inventing unsupported claims, treating chat summaries as repository truth, publishing before review, or letting AI tools approve their own work.
They also do not override higher-priority instructions. Safety, legality, privacy, data integrity, and tool limits remain above any protocol in this kit. 🛡️⚖️🔐
Active working kit. 🧪
Protocols may evolve as they are tested in real workflows. 🔁
This project was developed with AI assistance. 🤝🤖
The project, documentation, and repository materials were shaped through human-directed work supported by AI tools during drafting, structuring, review, and refinement. 🧭✍️🔎
AI assistance does not make the project automatically correct, complete, or suitable for every use case. Read it, test it, and adapt it to your own context. 🧪📌
Creative Commons Attribution-ShareAlike 4.0 International. 📄🌍
See LICENSE. ✅