Key concepts
This page defines the primitives the rest of the documentation refers to. Read it once end to end, then use it as a glossary.
Instruction Hub
Section titled “Instruction Hub”An Instruction Hub is a versioned Git repository that holds your governed agent instructions as source. It declares which packages to compile and which agent targets to compile for, and it receives remediation pull requests when a finding is fixed. To scaffold and configure one, see Set up your Instruction Hub.
Assets
Section titled “Assets”An asset is a single governed unit of instruction. There are six kinds: skill, rule, agent, command, hook, and mcp. Each asset lives under assets/<kind>s/ and is referenced in the kind:id form — for example, skill:agent-slack or mcp:repo-mcp. A skill is a directory with a SKILL.md file and optional references/, scripts/, and an asset.yaml sidecar.
Packages
Section titled “Packages”A package groups assets for distribution. Each package is a packages/<id>.yaml file with an id, a name, a list of owners, and an includes list of kind:id asset references. Your hub declares which packages to compile in its stable_packages list.
Every hub must include one required package named pig (display name PIG, an empty includes list). At compile time, the toolchain injects a managed update skill and the host runtime into the pig package, so it always ships even though you never add assets to it. Beyond pig, the packages in a hub are entirely your own — you define them around your teams and workflows.
The pig toolchain
Section titled “The pig toolchain”pig is the toolchain that validates an Instruction Hub and compiles it into target-native plugin packages. It is a Python command-line program (also invoked as promptless-instruction-hub) that runs in your continuous-integration pipeline rather than as a service, and it lives in the public Promptless/instruction-hub-toolchain repository. See The pig CLI reference.
Compile targets
Section titled “Compile targets”A compile target is an agent harness that pig can compile a package for. There are four: Claude, Codex, Cursor, and Gemini. A hub compiles to all four by default; you can narrow the set in your hub configuration. See Supported agents.
Plugins
Section titled “Plugins”A plugin is the compiled, target-native form of a package. pig writes each one to dist/<target>/<package>/ — for example, dist/claude/<package>/. Your fleet installs plugins from a marketplace and refreshes them on startup. See Publish and install plugins.
The host runtime
Section titled “The host runtime”promptless-host-runtime is a command-line executable the toolchain injects into your Claude and Codex plugins at compile time. It enrolls each host with your worker and collects that host’s native session traces. It runs through generated lifecycle hooks rather than as a daemon. See Enroll your hosts.
Enrollment
Section titled “Enrollment”Enrollment is how a host proves its identity to your worker. The host runtime opens a browser approval page; a signed-in member of your organization approves the host, and the runtime caches a one-time per-host credential (a plihost_ token) locally. The worker holds no shared secret — it verifies each credential through hosted introspection. See Trust and data model.
Traces and sessions
Section titled “Traces and sessions”A trace is one agent session, reconstructed from the native session ledgers the agent CLI writes locally. The host runtime ingests from exactly three sources (Claude Code, Claude Desktop, and Codex) and uploads new byte ranges to your worker, which stores a canonical trace object per session. See Trace object and sources.
The worker and Friction Analyzer
Section titled “The worker and Friction Analyzer”The worker is the instruction-hub-worker service you deploy into your own infrastructure. It accepts trace uploads, stores them in your S3 bucket and Postgres database, and runs the Friction Analyzer. The Friction Analyzer is the analysis component inside the worker: it studies one session at a time and produces findings. See Deploy the analyzer worker.
Findings and evidence
Section titled “Findings and evidence”A finding is a specific instruction failure the Friction Analyzer records, with a severity, a confidence, and a supporting-evidence list. Every finding carries at least one piece of evidence (a cited range of a session digest and a summary of what happened there), and evidence is append-only, so recurrence accumulates rather than overwrites. See Understand findings.
Remediation
Section titled “Remediation”Remediation is the flow that turns a high-confidence finding into a fix. An isolated remediation agent branches your Instruction Hub repository and opens a pull request; a human reviews and merges it, and the merged change recompiles and redistributes. Only high-confidence findings are eligible, and human review is the gate. See Remediate findings.
Hosted Promptless Runtime
Section titled “Hosted Promptless Runtime”The hosted Promptless Runtime is the control plane Promptless operates. It issues and verifies host enrollment credentials through introspection, receives the finding mutations your worker authors and projects them to GitHub issues, and coordinates remediation. It receives only a limited metadata projection of each trace, never trace content. For what crosses that boundary, see Trust and data model.