Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/XxYouDeaDPunKxX/ai-protocol-kit/llms.txt

Use this file to discover all available pages before exploring further.

The GitHub Badge, Telemetry & Counter Protocol v1.2.3 is a decision protocol for signal layers on GitHub repositories and GitHub Pages. A signal layer is one of: a badge, a counter, a telemetry or analytics tag, a validation script, a verification workflow, an external signal service, or a traffic and observability review. Use this protocol before adding or modifying any of these layers — to ensure each signal has a genuine job rather than serving as decoration or implied maturity signalling.

​
Core Principle

Signals are not decoration. A signal is justified only when it improves understanding, verification, observability, maintenance, reuse confidence, or operational decision-making. Do not add a signal to make a repository look more mature than it is. Do not create infrastructure only to justify a badge. Do not measure a surface before its relevant integrity is closed.

​
What This Protocol Governs

This protocol evaluates signal layers only. It reads repository, licence, release, workflow, Page, and metadata state as evidence. This protocol must NOT create or govern:
Out of scopeWhy
Publication packagesGoverned by the Repository Publication protocol
Licensing choicesOut of protocol scope
Repository identity or settingsNot a signal layer
Discovery filesGoverned by discovery protocols
Citation infrastructureOut of protocol scope
Funding or support setupOut of protocol scope
Release or changelog strategyOut of protocol scope

​
Decision States

Every evaluated signal receives exactly one decision state.
StateDefinition
APPLYUse now — evidence and prerequisites are satisfied.
SKIPDo not use — the signal is not justified.
DEFERMay become valid after a concrete, known trigger.
BLOCKED_INTEGRITYCannot decide — the relevant surface has not passed the required validation gate.
BLOCKED_PAGE_STATECannot decide — a Page-dependent signal lacks required Page evidence.
BLOCKED_EXTERNAL_SERVICECannot decide — external service behaviour, privacy, dependency, or purpose is unresolved.
BLOCKED_SIGNAL_EVIDENCECannot decide — the gate is not the problem, but a specific backing fact required by the signal is missing.

​
DEFER Output Requirement

For every DEFER decision, the output must include all four of:
  1. Unblock trigger — the concrete event that would allow re-evaluation
  2. Owner — who is responsible for the trigger, if known
  3. Required evidence after trigger — what must be verifiable once the trigger fires
  4. Signal to re-evaluate — which signal this DEFER applies to

​
BLOCKED vs DEFER

BLOCKED is not a softer DEFER. If no concrete trigger exists, use SKIP or a BLOCKED state — not DEFER. BLOCKED means a prerequisite condition is absent and cannot be assumed away.
Blocked state disambiguation
StateUse when
BLOCKED_INTEGRITYThe relevant surface has not passed the required validation gate.
BLOCKED_SIGNAL_EVIDENCEThe gate is not the problem — a specific backing fact for the signal is missing.
BLOCKED_PAGE_STATEPage existence, URL, deployment state, or insertion surface blocks a Page-dependent signal.
BLOCKED_EXTERNAL_SERVICEExternal service behaviour, privacy, dependency, or purpose is unresolved.
Examples
ScenarioCorrect state
Licence badge requested; licence file or recognition state is unknownBLOCKED_SIGNAL_EVIDENCE
Workflow badge requested; workflow existence or status is unknownBLOCKED_SIGNAL_EVIDENCE
Workflow exists but has not passed the required runBLOCKED_INTEGRITY
Page analytics requested; Page URL is unknownBLOCKED_PAGE_STATE
Analytics service privacy behaviour is unknownBLOCKED_EXTERNAL_SERVICE

​
Phases

1
Phase 1 — Classify Signal Context
2
Determine only what affects signal choice: repository name, repository type, primary published unit, primary reader, signal purpose, existing README, existing licence state, existing release or tag state, existing scripts, workflows, badges, counters, analytics, external signal services, GitHub Page state (only if a requested signal depends on a Page), maintenance model, and observability need.
3
Supported repository types
4
TypeDescriptionPROFILE_HUBPersonal or organisation profile repositoryPROTOCOL_REPOAI protocol, contract, or behavioural spec repositoryKIT_DOCS_REPOKit, documentation, or guide repositoryTECHNICAL_REPOCode, library, tool, or application repositorySTATIC_PAGE_REPORepository whose primary output is a static pageCONTENT_REPOWritten, media, or mixed content repositoryARCHIVE_REPOArchived or inactive repositoryINTERNAL_OPERATIONAL_REPOInternal tooling or operational scriptsHYBRID_REPOMore than one type in meaningful proportion
5
Do not recommend repository settings, description, topics, homepage, social preview, or repository features from this phase.
6
Phase 2 — Detect Existing Signals
7
Inspect enough evidence to classify existing signals:
8
LayerClassification optionsBadgesnone / semantic / dynamic / service / stale / unknownCountersnone / README hit counter / profile counter / service counter / unknownTelemetrynone / Page analytics / product analytics / unknown / misplacedValidation scriptsnone / local script / package script / custom validator / unknownVerification workflowsnone / existing workflow / passing workflow / failing workflow / unknownExternal servicesnone / badge service / analytics service / counter service / status service / unknownTraffic review sourceGitHub-native / external / none / unknown
9
If a signal exists but its backing evidence does not, mark it stale or invalid and report it under Existing Signal Cleanup.
10
GitHub Traffic review is operator-facing by default. It must not be exposed as a public signal unless explicitly exported by the operator. Stars, forks, and watchers are public counters — not GitHub Traffic review.
11
Existing Signal Cleanup
12
For each stale, invalid, misleading, or unsupported existing signal, output: signal, current target, problem, missing or invalid backing evidence, minimum action (remove / replace / block until evidence exists), and risk if left unchanged.
13
Phase 3 — Integrity Gate
14
Before recommending public badges, counters, analytics, external services, or public status signals, close the relevant integrity gate.
15
Integrity passes only when one of these is true:
16
  • The check was executed successfully.
  • A passing result is available from reliable evidence.
  • An existing workflow covers the relevant surface and passes.
  • The operator explicitly provides a passing result.
    • 17
    Allowed while integrity is blocked
    18
  • Recommend a validation script
  • Recommend a verification workflow
  • Recommend an exact check command
  • Recommend removal of a stale or unsupported existing signal
    • 19
    Not allowed while integrity is blocked
    20
  • Public badge, counter, analytics, external public signal, or public status signal
    • 21
    Phase 4 — Page Signal Gate
    22
    Activate only if at least one requested signal depends on a GitHub Page, or the operator explicitly asks to evaluate Page-dependent signals.
    23
    Allowed Page-dependent signals: Page analytics, Page hit counter, Page availability badge, uptime badge, external Page telemetry.
    24
    Not in scope for this gate: discovery files, canonical URLs, Open Graph, sitemap, robots, llms.txt, raw-manifest.json, footer discovery links.
    25
    Phase 5 — Evaluate Signal Families
    26
    Evaluate only the families relevant to the requested signals:
    27
  • Semantic badges
  • Dynamic GitHub badges
  • Service badges
  • README or profile counters
  • Page analytics or telemetry
  • Validation scripts
  • Verification workflows
  • Workflow or status badges
  • External signal services
  • GitHub Traffic or observability review
  • Signal-tied reporting

    • ​
    What Makes a Signal Justified vs Unjustified

    Justified signals

    • Status badge backed by real project state
    • Licence badge when the licence file exists and is recognised
    • Workflow badge after the workflow exists and passes at least once
    • Release badge when a release or tag exists
    • Page analytics when a Page exists and the data informs a maintenance decision
    • Validation script when a real repeated integrity check is needed

    Unjustified signals

    • Fake build or package badge
    • Coverage badge without coverage evidence
    • Release badge without any release or tag
    • Badge wall (badges added for appearance)
    • Maturity-signalling badge unsupported by project state
    • Counter with no maintenance or decision use attached
    • Analytics on a Page surface whose privacy implications are unresolved

    ​
    Semantic Badge Vocabulary

    Use controlled semantic badge values unless the operator explicitly approves a new one. Do not create synonyms when an existing value works.
    experimental · active · stable · maintained · archived · deprecated

    ​
    Signal-Only Presets

    Presets guide signal selection only. They must not recommend repository settings, publication work, discovery files, citation infrastructure, funding, or release strategy.
    • Profile counter: optional
    • Profile/status semantic badge: conditional
    • GitHub Traffic review: optional/internal
    • Stats widgets: usually SKIP
    • Project badge wall: SKIP
    • Semantic badges: status / type / use
    • Dynamic badges: licence if licence state is known
    • GitHub Traffic review: optional/internal
    • Validation script or workflow: conditional if real check surface exists
    • Workflow badge: only if real workflow exists and passes
    • Release/version/download badge: only if release/tag/artefact evidence exists
    • Page analytics: only if Page signal gate passes
    • Semantic badges: status / type
    • Dynamic badges: licence if licence state is known
    • Integrity workflow: conditional if docs/links/check surface exists
    • Counters: optional
    • GitHub Traffic review: optional/internal
    • Page analytics: only if Page signal gate passes
    • Validation script or workflow: core if real check surface exists
    • Workflow badge: only after passing workflow
    • Release/download badge: only if artefacts exist
    • Service/package badge: only if backing service/package exists
    • README hit counter: usually SKIP
    • Page analytics: conditional if Page signal gate passes and a maintenance decision exists
    • Uptime/Page availability badge: conditional after Page state and external service gate pass
    • Deployment workflow badge: only if workflow evidence exists
    • Badge wall on page: SKIP
    • Archive/status badge: conditional
    • Active status badge: SKIP
    • Analytics/counters: SKIP unless a real review decision exists
    • Workflow badge: SKIP unless integrity still matters
    For hybrid repositories: identify component types, choose one PRIMARY preset, choose SECONDARY presets only for signal families they actually justify, resolve public signal conflicts by choosing the smaller public signal surface.The output must state: PRIMARY_PRESET, SECONDARY_PRESETS, INCLUDED_SIGNAL_FAMILIES, EXCLUDED_SIGNAL_FAMILIES, and conflict decisions.

    ​
    Output Structure

    The protocol produces a signal decision table:
    SignalDecisionWhyTargetEvidencePrerequisiteUnblock triggerRisk
    Followed by sections for: Applied signals, Deferred signals, Skipped signals, Blocked signals, Signal cleanup, Evidence read, Integrity gate, Page signal gate (if relevant), External service gate (if relevant), and Next minimum action.

    ​
    Final Rule

    A signal is correct only when it has a job. If it does not improve understanding, verification, observability, maintenance, reuse confidence, or operational decision-making — skip it. If evidence is missing — block it. If the trigger is known but not yet satisfied — defer it with the trigger. If it is decorative — reject it.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us