Set up PIG with a coding agent
Overview
Section titled “Overview”A coding agent such as Claude Code or Codex can set up Promptless Instruction Governance (PIG) for you by following the setup guides. It reuses what already exists and asks you before a change that costs money, grants access, or publishes to your team. Use this page when you want an agent to do the setup work. To do it yourself, start with Set up your Instruction Hub.
Hand the agent the whole setup with the prompt on this page. To hand it one phase at a time, use the Ask your agent prompt in each setup guide. Either way, you finish with a published Instruction Hub, its plugins installed in your agent, and a hub skill that works in a real task. With trace analysis, the agent also deploys the analyzer, enrolls a host, and verifies one analyzed session.
Before you start
Section titled “Before you start”- Decide whether you want trace analysis. A hub and its plugins work without it. Trace analysis adds a self-hosted analyzer, a PostgreSQL database, object storage, and a model provider.
- Start the agent in a terminal that can reach your Git provider and, for trace analysis, your cloud account and Kubernetes cluster.
- Expect to handle sign-ins, the Promptless Dashboard, and host enrollment approval yourself. The agent tells you when.
- Store secrets in your secret manager and give the agent their names, never their values.
Ask your agent to set up PIG
Section titled “Ask your agent to set up PIG”-
Copy this prompt and replace each bracketed value you know. The agent discovers the rest.
Ask your agent: set up PIG end to end Set up Promptless Instruction Governance (PIG) for my team. Followhttps://promptless.ai/docs/governance/agent-setup-guide.mdOutcome: a published Instruction Hub, its plugins installed in my agent, and ahub skill working in a real task. Trace analysis: [yes or no]. If yes, alsodeploy the analyzer, enroll this host, and verify one real session in thePromptless Dashboard.Known inputs (discover the rest before you ask me):- Hub repository: [existing hub URL, or the GitHub or GitLab group for a new one]- My agent: [Claude Code, Codex, Cursor, or Gemini CLI]- Cloud: [AWS, Azure, Google Cloud, or another Kubernetes platform]- Cluster: [kubectl context and namespace, if known]Ask me before paid, access, publishing, or destructive changes, and never askme to paste a credential. Report what you verified, what is blocked, and mynext step. -
Paste the prompt into the agent you started in the terminal from Before you start.
-
Answer the agent’s questions, and approve or decline each plan it shows you.
-
When the agent pauses for a step only you can do, complete the step and tell the agent.
When it finishes, the agent reports each phase as verified, skipped, or blocked, with your next step.
Instructions for coding agents
Section titled “Instructions for coding agents”The rest of this page, up to See also, is for you, the agent. Read all of it before you run a command. The linked guides are the source of truth for commands and configuration. If this page differs from a guide, follow the guide and report the difference. Append .md to a guide’s URL to read it as Markdown. The documentation index lists every page.
Act within scope, ask before consequential changes
Section titled “Act within scope, ask before consequential changes”Without asking, run read-only inspection, prepare files on a local branch, render templates, and run dry runs, terraform plan, pig validate, and pig verify. Reuse existing resources and resume from the first incomplete phase.
Before each of these actions, show the plan, diff, or terraform plan output and wait for approval. An approval covers only the plan you showed.
- Creating a repository, or pushing to a branch that publishes, such as the hub’s source branch.
- Applying Terraform, installing the Helm bootstrap, or applying a
PIGDeployment. These create paid resources or start workloads and schema migrations. - Granting access: IAM, repository and CI token permissions, and the GitHub App’s repository access.
- Enabling trace collection, which can upload the host’s existing session history.
- Replacing, deleting, or importing existing infrastructure, Terraform state, Helm releases, or hub content.
Before each phase that writes, report the exact target: Git remote and branch, cloud account and region, Kubernetes context and namespace, and Promptless organization. Stop if it differs from what the user described.
When a step fails, stop and report it. Do not invent commands, flags, or keys, or switch deployment paths without agreement. Never weaken security to get past an error, such as by disabling TLS verification, making storage public, or broadening IAM.
Preserve what others own. Keep the user’s uncommitted changes and work on a branch. Keep existing Terraform state, backends, and module pins, and do not import resources another workflow owns. Keep the Helm bootstrap out of Terraform helm_release resources and out of continuous GitOps reconciliation. After bootstrap, PIG owns its releases, as GitOps ownership describes.
Keep credentials out of the conversation
Section titled “Keep credentials out of the conversation”- Ask for the name of a secret, Kubernetes Secret, or environment variable, never its value.
- Deliver credentials only through the user’s secret manager, a Kubernetes Secret created from it, or the CI provider’s own token.
- Keep credentials out of Git, Helm arguments, committed
.tfvarsfiles, logs, and output. To confirm a Secret, check its keys, not its value. - Treat Terraform state and saved plans as secrets. Do not copy host enrollment credentials between machines or into the hub.
Pause for steps only a person can do
Section titled “Pause for steps only a person can do”Tell the user what to do and what to tell you afterward, then resume with the listed check.
| Step | Who | How you resume |
|---|---|---|
| Sign in to a Git provider, cloud CLI, or cluster | The user | Rerun the identity check, such as aws sts get-caller-identity |
| Add an analyzer in Settings → Workers and store its credential | A Promptless organization admin | Check that the named Kubernetes Secret has the expected key |
| Select instruction repositories and turn on Trace analyzer in Settings → Workers | A Promptless organization admin | Confirm with the user that the repositories and switch appear |
| Enable CI job token push access in GitLab | A GitLab project maintainer | Rerun the publishing pipeline and inspect its jobs |
Run Claude Code /plugin commands, install a Cursor plugin, or review plugins in Codex | The user | Confirm the installed plugin, then run the skill check |
| Import a Cursor team marketplace | A Cursor team administrator | Confirm the imported plugins with the user |
| Approve host enrollment | A signed-in Promptless organization member | Rerun the runtime status or enroll command |
Report the result
Section titled “Report the result”Report:
- Each phase as verified, skipped, or blocked, with the check that proved it.
- The identifiers you created or reused, such as the hub repository, release version, deployment, namespace, and session ID.
- What is blocked, the user’s next action, and anything you could not test.
Do not report an outcome you did not check.
Phase 1: Inspect the environment and choose a path
Section titled “Phase 1: Inspect the environment and choose a path”-
Look for
hub.yamlandplugins/pig.yamlin the current repository and any repository the user named. Also look for installedpigplugins in the user’s agent. -
Check tools. Hub work needs Git and Python 3.11 or later. Trace analysis also needs
kubectl, Helm 3 or later, Terraform for a cloud guide, and the cloud’s CLI. -
If the request does not say, ask whether the user wants trace analysis. If so, run
kubectl get pigdeployments --all-namespacesandhelm list --all-namespacesagainst the confirmed context. -
Check Supported agents. Every build target receives plugins, but plan trace analysis only for agents listed for native trace collection.
-
Choose a path from Deploy trace analysis:
-
AWS with an existing EKS cluster: Deploy on AWS, the path the current release targets.
-
AKS or GKE: Deploy on Azure or Deploy on Google Cloud. Tell the user these paths are experimental.
-
A cluster with a database, bucket, and workload identity in place: Install with Helm.
-
A team that applies every upgrade itself: Manual Helm management.
-
Stop and ask how to continue when:
- Trace analysis needs a Kubernetes cluster and none exists. The cloud guides do not create one.
- The user wants collection from an agent without native trace collection.
- The instruction repositories to analyze are not on GitHub. A GitLab hub can publish plugins, but the analyzer reads only GitHub repositories.
Done when the user agrees on the hub to create or adopt, the agent to install for, and whether and where to deploy the analyzer.
Phase 2: Create or adopt an Instruction Hub
Section titled “Phase 2: Create or adopt an Instruction Hub”Follow Set up your Instruction Hub and Migrate existing instructions. You need the organization name, marketplace ID, repository location, and first skills or instructions to include.
-
Install the toolchain in a dedicated virtual environment, or reuse one where
pig --helpworks. -
To adopt a hub, clone it and work on a branch. Do not run
pig initover it. -
To create a hub, run
pig init --hub . --org <organization>in a new directory.--orgis required. Add--marketplace-id <marketplace-id>when the user chose a marketplace ID. Keep the generatedpigplugin, because the toolchain requires its ID. -
Add skills and group them into plugins. To import instructions, run
pig scanon one source at a time and review each import, because it replaces a destination skill with the same ID. -
Run
pig validate --hub ., thenpig verify --hub ., and commit to a local branch.
Ask for approval before you create the remote repository or push to it.
Done when pig verify prints a verified release ID and the commit contains hub.yaml, plugins/, and assets/. To resume, rerun pig verify on an existing hub.yaml.
Phase 3: Configure publishing
Section titled “Phase 3: Configure publishing”Follow Publish your hub.
-
Check for
.github/workflows/instruction-hub-*.ymlor anincludeof the toolchain template in.gitlab-ci.yml. -
Add the guide’s workflow files or GitLab template. Set
hub-rootwhen the hub is not at the repository root. -
Check repository settings. GitHub workflows need write permission to the source branch and
release/stable. GitLab needs job token push access, which a project maintainer enables.
Ask for approval before you push the workflow to the source branch, which starts publishing.
Done when the run succeeded and release/stable contains hub.release.json and dist/<target>/<plugin-id>/ for each plugin in stable_plugins. If publication stops because a branch advanced, update from the latest source and rerun. Do not force-push.
Phase 4: Install plugins and check a skill
Section titled “Phase 4: Install plugins and check a skill”Follow Install the plugins.
-
Confirm the user can read the hub repository and
release/stable. -
Install
pigand the needed plugins from the agent’s tab in the guide. Run Codex and Gemini CLI terminal commands yourself. Ask the user to run Claude Code slash commands and app or dashboard steps. -
Reload or restart the agent as the guide describes.
Done when the plugin is listed at the published version. A hub skill must also run in a real task in a new session and read its supporting files.
Phase 5: Deploy the trace analyzer
Section titled “Phase 5: Deploy the trace analyzer”Skip this phase without trace analysis and report the hub as ready. Otherwise, follow Deploy trace analysis, the cloud guide from phase 1, Install with Helm, and the configuration reference. You need:
- The cloud account, region, and cluster context.
- The analyzer hostname and how its certificate is managed.
- The model provider and model.
- The secret names for the analyzer credential, database connection string, and model key.
-
Check Before you begin and list missing items before you start.
-
Ask a Promptless organization admin to register the analyzer. Promptless shows the credential once, and the admin stores it in the secret manager.
-
Select the release from the stable catalog, download its files, and check every digest as in Select and verify a release. Stop if a digest differs. Never use an unreleased branch or candidate tag.
-
For a cloud guide, extract the example from the verified release archive. Fill the example inputs with confirmed values and configure the user’s remote state backend. Run
terraform init -backend-config=backend.tfbackend -lockfile=readonly,terraform validate, andterraform plan -out=pig.tfplan. -
Show the plan summary. Stop if it replaces the cluster, broadens shared permissions, or destroys retained storage. After approval, apply the saved plan and save the
deployment_configurationoutput, which contains no credentials. -
Create the namespaces and the analyzer ServiceAccount with the output’s annotations. Confirm Secret
pig-credentialsand ConfigMappig-postgres-cahave the required keys, without reading values. -
Write the bootstrap values for the cluster’s ingress controller, run
helm lintandhelm templateon the verified chart, and show the permissions, images, and Ingress. Install after approval. -
Write
pig-deployment.yamlfrom the guide’s example and the Terraform output. Show thekubectl apply --dry-run=serverresult, then apply after approval. -
Wait for the
PIGDeploymentto reportReady=True. Ask the user to point DNS at the Ingress address, then check/healthzand the unauthenticated policy route over HTTPS from the hosts’ network. -
Ask a Promptless organization admin to select instruction repositories and confirm that trace analysis is enabled.
Done when the PIGDeployment reports Ready=True and the HTTPS checks pass from the hosts’ network. In Settings → Workers, the analyzer must show Healthy with a recent Last checked in time, selected repositories, and Trace analyzer set to On. This proves the deployment runs. Phase 7 proves analysis works.
To resume, read the status of an existing PIGDeployment, Helm release, or Terraform state and continue from the first failing check. Do not reinstall the bootstrap over a supervisor that has updated itself. For a blocked update, follow Updates and recovery.
Phase 6: Enable trace collection and enroll a host
Section titled “Phase 6: Enable trace collection and enroll a host”Follow Enroll your hosts. You need the analyzer’s HTTPS address and the agreed pilot host.
-
Confirm collection is approved for this host, and point the user to the trust and data model. The first collection can upload existing session history.
-
Set
trace_ingestion.enabled: trueinhub.yaml, runpig verify, and show the diff. Publish through the hub’s CI after approval. -
Update the
pigplugin on the pilot host, and setPROMPTLESS_WORKER_BASE_URLto the analyzer’s address where the agent launches. -
Start enrollment in a new session or with the runtime’s
enrollcommand. The host needs a local browser. After the user approves the host in the browser, rerun the command. -
Run the runtime’s
ensureandstatuscommands for the same host family.
Done when the runtime reports the host enrolled against the expected analyzer and the host appears in Settings → Host access.
Phase 7: Verify the whole setup
Section titled “Phase 7: Verify the whole setup”Follow Verify your deployment.
-
Ask the user to run a small, non-sensitive task that uses a hub skill in a new session, in a repository selected for analysis. Record the agent source and session ID.
-
Wait for the configured quiet window after the session ends.
-
Run the runtime’s
collect --include-activecommand and confirmtrace_upload_complete. -
Run each check in the guide for that session ID with read-only database sessions. Do not copy session content into your report.
Done when all of these pass for the same session:
- A hub skill ran.
- The host is enrolled and checked in.
- The trace is stored and readable through the analyzer’s identity.
- At least one analysis run of the current trace revision succeeded. Zero findings is a valid result.
- Promptless acknowledged the trace, and the session shows Succeeded on the Dashboard’s Traces page.
- The
PIGDeploymentreportsAcceptance=True.
A ready pod, published release, listed plugin, or upload acknowledgment alone does not pass. When a check fails, find the first failing stage with observability and troubleshooting and report it.
See also
Section titled “See also”- Set up your Instruction Hub, to create the hub yourself
- Deploy trace analysis, to plan the infrastructure before the agent deploys it
- Trust and data model, to review what collection uploads before you approve it
- Observability and troubleshooting, to diagnose a phase that the agent reports as blocked