How it works

PIG connects publishing instructions with learning from sessions. You can publish instructions independently. Adding trace analysis gives your team evidence about how those instructions perform in practice.

This page explains the components, where they run, and what each one depends on. For individual terms, see Key concepts.

The components at a glance

Scroll horizontally to view the architecture.

Instruction Hub

Git repository

Published plugins

Host machineworkstation, laptop, agent host

AI agent

Trace collector hooks installed by Instruction Hub plugin

Session

Model provider

Reuse the same model provider your agents use

Trace digest

Session traces

Detected instruction issues & proposed updates

Your cluster

Trace analyzer

Looks for agent errors, mistakes, inefficiency, misconfiguration, etc.

Auto-updates on by default

Trace objects

Trace bucket

Object storage: S3, GCS, etc.

Analysis state

PostgreSQL

Findings, remediations, & analyzer status

Promptless cluster

Promptless Dashboard

Review findings, remediations, analyzer status and agent instruction health

1. Instruction Hub → Published plugins → AI agent.
2. AI agent → Session → Model provider shared with the trace analyzer.
3. Host trace collector → Session traces → Trace analyzer.
4. Trace analyzer → Detected instruction issues and proposed updates → Instruction Hub.
5. Trace analyzer → Trace digest → Model provider shared with the AI agent.
6. Trace analyzer → Trace objects → Trace bucket.
7. Trace analyzer → Analysis state → PostgreSQL.
8. Trace analyzer → Findings, remediations, and analyzer status → Promptless Dashboard.

Raw traces are stored in your trace bucket. Trace digests are sent to the model provider your agents use.

Components every hub uses

Component	Where it runs	What it does	Depends on
Instruction Hub	Your Git repository	Holds instruction source, plugin definitions, and release configuration	Authors and reviewers
pig toolchain and publishing CI	An author’s machine and your CI runners	Validate source, build plugins, and publish releases	Hub source and repository publishing permissions
Marketplace and released plugins	Your release repository	Make the compiled instructions available to agents	A successful publish and agent access to the repository
Agent and host runtime	Each user’s workstation or agent host	Load installed instructions; optionally enroll and upload native traces	An installed plugin; analyzer connectivity for collection

Components used only for trace analysis

Component	Where it runs	What it does	Depends on
Trace analyzer	Your Kubernetes cluster	Accept traces, reconstruct sessions, run analysis, and propose improvements	PostgreSQL, native object storage, Promptless, model access, and the selected instruction repositories
Trace bucket	Your cloud account	Store raw trace chunks and reconstructed sessions	Private object storage and analyzer access
PostgreSQL	Your cloud account	Store host identity, ingestion progress, and analysis state	Dedicated database and analyzer access
Promptless	Promptless infrastructure	Manage enrollment and deployment coordination; record findings and coordinate GitHub issues and remediation	Your organization’s deployment and repository connections
Model provider	Your configured provider endpoint	Process session and instruction context for analysis and remediation	Model access and configured credentials

The deployed trace analyzer service is named pig-trace-analyzer. Its analysis component is called the Friction Analyzer. These names refer to a service and a component inside it; you do not install two analysis services.

Publish an instruction

1. Author shared source

   Acme keeps a review-docs skill in its Instruction Hub. The skill defines the review scope, accuracy and clarity checks, and the evidence each finding needs. Acme includes it in a docs plugin for writers and a dev plugin for developers.

   The skill is an asset; the plugin is a named selection of assets. Updating the shared source changes both plugins on the next publish. Repository-specific facts, such as one project’s build command, can remain in that repository rather than being generalized for every team.

2. Validate and build

   The author runs pig validate to check the hub and pig verify to compile it in a temporary directory. CI runs the same checks on the pull request. These checks catch configuration and build errors; reviewers still need to assess whether the instructions are correct and useful.

   The toolchain builds for the configured targets: Claude, Codex, Cursor, and Gemini. Different targets support different asset types and installation mechanisms. A successful build does not prove the desktop agent has installed the plugin or can execute every instruction it contains.

3. Publish and install

   After review and merge, a GitHub or GitLab publishing pipeline builds the release output. It updates the release branch and marketplace pointers and records the hub version. Authors work with source on the default branch; agents install the released output.

   Acme’s writers install the docs plugin and its developers install dev. Both install the required pig plugin, which includes the managed hub-update skill for Claude and Codex. That skill helps refresh the marketplace and installed plugins. Each host’s installation and reload behavior still applies.

See Publish and install plugins for CI configuration and the installation checks.

Learn from a session

1. Prepare the analyzer and enable collection

   Your platform team deploys the analyzer and connects its database, bucket, and model provider. It configures a deployment with Promptless and makes the analyzer reachable from the hosts that will upload traces. An organization administrator selects the instruction repositories the analyzer reads in PIG Settings.

   The hub owner then enables trace_ingestion.enabled, publishes a new release, and refreshes installed plugins. This adds the managed collection runtime to the Claude and Codex versions of the pig plugin. The setting does not create infrastructure or enroll hosts by itself.

2. Enroll each host

   A host opens the browser enrollment flow. A signed-in organization member approves it, and Promptless issues a credential for that host and deployment. The host uses that credential to authenticate to your analyzer.

   The collector reads supported native session logs: Claude Code, Claude Desktop, and Codex. A Claude Desktop source must actually exist and be enrolled; installing a Claude plugin alone does not make Desktop traces available. Cursor and Gemini plugin builds do not include native trace collection.

3. Collect and store the trace

   As sessions run, the collector uploads new complete lines from native logs. Your analyzer stores raw chunks and reconstructed traces in your trace bucket, with host attribution, ingestion progress, and analysis state in PostgreSQL.

   The host retains its upload ledger and retries unacknowledged ranges on later collection passes. First collection can upload existing session history when a source has no acknowledged offset. Later collection resumes from the acknowledged position. For source and retry details, see Trace object and sources.

4. Analyze the session

   The analyzer examines sessions after they finish or become quiet. It uses session evidence and instruction-hub context to investigate instruction failures. That work calls the model provider you configured.

   For example, an older release of Acme’s review-docs skill omits prerequisite checks. Agents following it repeatedly approve setup guides without checking required permissions. The analyzer can identify the missing instruction and cite the observed reviews. A completed analysis can also produce no finding; absence of a finding is not an ingestion failure.

5. Review and improve

   The analyzer writes findings and evidence to Promptless. Promptless coordinates their GitHub issues and remediation state. When a finding warrants an instruction change, an isolated remediation task in the worker can prepare a pull request against the hub.

   Acme’s reviewer checks the evidence and the proposed instructions, runs the relevant checks, and merges an accepted fix. The hub’s publishing pipeline distributes a new release. Refreshing the installed plugins makes the correction available to the team’s agents.

An organization administrator selects the instruction repositories the analyzer reads in PIG Settings. Each is a GitHub repository with a main branch, and the analyzer receives GitHub App tokens from Promptless to read them. GitLab hub publishing does not imply GitLab analyzer or remediation support.

Keep the two update paths distinct

Instruction releases change the content your agents install. Hub owners publish them through Git, and agent users refresh their plugins.

Analyzer releases change the service that collects and studies traces. The trace analyzer updates automatically to stable releases by default. You can pause updates or pin a release. See Manage updates and recovery.

Next steps

• Set up an Instruction Hub to begin publishing.
• Migrate existing instructions if your team already has shared guidance.
• Review the trust and data model, then plan your deployment to add analysis.