How it works
Promptless for Agent Instructions closes a single loop across five components:
- Instruction Hub — the versioned Git repository where you author your agent instructions.
- pig — the toolchain that validates that hub and compiles it into target-native plugin packages.
- worker — the service in your own infrastructure that ingests agent traces and produces findings, with the Friction Analyzer inside it.
- promptless-host-runtime — the executable that rides inside your Claude and Codex plugins to enroll each host and collect its traces.
- hosted Promptless Runtime — the control plane that issues credentials, projects findings to GitHub, and coordinates remediation.
This page shows how those pieces connect.
The end-to-end loop
Section titled “The end-to-end loop”-
Author instructions in your Instruction Hub. Organize your skills, subagents, hooks, commands, rules, and MCP configs as versioned assets and packages in a Git repository. See Set up your Instruction Hub.
-
Compile the hub to target-native plugins. The
pigtoolchain validates the hub and compiles each package into a plugin for Claude, Codex, Cursor, and Gemini. See Publish and install plugins. -
Publish and install on your fleet. A GitHub Action commits the compiled output to a release branch and rewrites your marketplace manifests, and your fleet installs the plugins and refreshes them on startup. See Publish and install plugins.
-
Enroll each host. The
promptless-host-runtimeinjected into your Claude and Codex plugins enrolls each host with your worker through a browser approval. See Enroll your hosts. -
Ingest native session traces. The host runtime uploads new byte ranges of each native session ledger to your worker, which stores them in your own S3 bucket and Postgres database. See Trace object and sources.
-
Analyze sessions with the Friction Analyzer. The Friction Analyzer studies one session at a time and records findings, each backed by append-only evidence. See Understand findings.
-
Project findings to GitHub issues. The worker sends each finding to the hosted Promptless Runtime, which projects it to a GitHub issue you can triage. See Understand findings.
-
Open a remediation pull request. For a high-confidence finding, an isolated remediation agent — running in your worker, in its own workspace with a repository-scoped token — branches your Instruction Hub repository and opens a pull request with a proposed fix. See Remediate findings.
-
Review and merge. A human reviews and merges the pull request. This human review is the gate — no change lands in your hub without it. See Remediate findings.
-
Recompile and redistribute. The merged change recompiles and republishes, your fleet picks it up on startup, and the loop closes. See Publish and install plugins.
What runs where
Section titled “What runs where”The loop spans three trust zones: your Git repository, your own infrastructure, and hosted Promptless.
- Instruction Hub — a Git repository you own. It holds the source of your governed instructions and receives remediation pull requests.
- pig — a toolchain that runs in your continuous-integration pipeline, invoked by a thin GitHub Action caller. It never runs as a service.
- worker — a service you deploy into your own infrastructure. It stores raw traces and canonical trace objects in your S3 bucket and metadata in your Postgres database, and it runs both the Friction Analyzer and the isolated remediation agent locally.
- promptless-host-runtime — a command-line executable that ships inside your Claude and Codex plugins and runs on each host through generated lifecycle hooks.
- hosted Promptless Runtime — the control plane Promptless operates. It receives only a limited projection of trace metadata, never trace content.
For exactly what crosses each boundary, see Trust and data model.