prompt-linker 0.9.1

Ahead-of-time compiler/linker for LLM agent prompts — compose instruction sets from interchangeable parts.

prompt-linker

Compile an LLM agent's instruction set from interchangeable parts — the way a program is linked from objects chosen at build time.

prompt-linker is an ahead-of-time compiler/linker for agent prompts. You write a stable algorithm as skeletons with named slots, write the variable behavior as interchangeable implementations, and declare which implementation fills each slot in a build manifest. The linker inlines the chosen implementations into the skeletons and emits one flat, fully-resolved instruction that the agent runs with zero runtime indirection.

Why

Configurable agent pipelines usually rot in one of two ways:

• inline conditionals (if mode == X …) entangle every variation into one monolith;
• runtime resolution pays a tool-call + tokens for every slot, on every iteration.

prompt-linker pays its indirection once, in deterministic code (zero model tokens), and hands the agent a single readable artifact. "Modes" become data — named presets over a small space of bindings — not branches in the engine. Adding a new behavior is a new implementation + a manifest line; the algorithm is never edited (Open–Closed).

Concepts

Term	Is
Configuration	a self-contained directory (manifest + skeletons/ + contracts/) that compiles independently; a project may hold many
Contract	a named, reusable signature (inputs, postcondition, invariant); declared once, with an optional default impl
Slot	an occurrence of a contract in a skeleton — {{ slot: <contract-id> }}, the hole to fill
Implementation	one concrete block that satisfies a contract and fills its slots
Skeleton	a prompt template containing slots
Skill	a deliverable bundle (a top-level subdir of skeletons/) — a convention, not required
Manifest	Linker.yaml: names the configuration, binds each contract → an impl (+ named presets)
Binding / Resolution	a contract → impl pair / the resolved set of them (defaults → preset → overrides)
Linker	deterministic step that inlines implementations into skeletons
Verifier	proves every slot is bound once and each implementation satisfies its contract

Quick look

# Linker.yaml
preset: team
overrides: { continuation: spawn-next }   # run-local contracts only
presets:
  solo: { task-source: local,   continuation: stop }
  team: { extends: solo, task-source: tracker }

# skeletons/autonomous-agent/run.md
## Phase 1 — Acquire work
{{ slot: task-source }}

prompt-linker compile --preset team → a flat compiled/<name>-<config-hash>/autonomous-agent/run.md with the tracker implementation inlined — clean text the agent reads with no hint it was assembled from parts (the output dir is content-addressed so a host can freeze a run by recording its path); provenance lives in a GENERATED header. (compile --annotated adds per-block markers for an AI verifier — a debug build, never shipped.) Copy Examples/StarterTemplate to begin your own configuration, or read Examples/TestConfiguration for a fuller, runnable one.

Install & adopt

prompt-linker is on PyPI — consume it as an installed package, not a vendored copy:

pipx install prompt-linker            # or: uvx prompt-linker … / pip install prompt-linker
prompt-linker init prompts/my-config  # scaffold a configuration + install a consumer skill + patch .gitignore

init is the one-shot way for a host repo to adopt the tool: it scaffolds a starter configuration, appends compiled/ to your .gitignore, and installs a small Claude Code skill into .claude/skills/prompt-linker/ that teaches a host agent to consume the tool (no internals). Use --skill-only to refresh just the skill after an upgrade. From a source checkout the entry point is PYTHONPATH=src python -m prompt_linker.cli.

Usage

Run a command against a configuration directory (its ROOT):

prompt-linker verify  Examples/TestConfiguration                  # check coherence; writes nothing
prompt-linker compile Examples/TestConfiguration --preset team    # → compiled/ (gitignored)
prompt-linker deploy  Examples/DeployExample  --root .            # install/distribute a build into host paths
prompt-linker check   Examples/TestConfiguration --security       # AI verifier (opt-in; needs [ai] extra)

Two ways to consume a build: use-in-place (compile, then point the runtime agent at the printed content-addressed path — commit nothing) or install/distribute (deploy — lay the build out into host paths another tool discovers by location, recorded in a committed deploy-receipt.json; deploy --check is the CI/pre-commit freshness gate).

verify, compile, and deploy are deterministic and fail closed (and include a security scan); check is the opt-in, model-using AI verifier (conformance, coherence, injection review). Full command reference: Docs/Commands.md.

Status

✅ Released on PyPI (prompt-linker, latest 0.9.0). The deterministic linker/verifier, the opt-in AI verifier, host adoption (init), and both consumption modes (compile / deploy) all run. Docs: the design in Docs/PromptLinker.md, the CLI in Docs/Commands.md, verification layers in Docs/Verification.md, emitted errors in Docs/Errors.md; open questions and planned work in Roadmap/Roadmap.md.

Implementation: Python 3.11+, distributed via PyPI (pipx run prompt-linker / uvx prompt-linker). The npm name is reserved; a native JS build is deferred until there is demand for embedding the linker as a JS library.

License

MIT