Versioned Prompts
In IST, the instructions an AI session follows are not text you paste into a chat. They are files shipped in a kit, installed with skit, and versioned like any other package.
This page explains why.
Prompts are what you ship
A Manager/Worker setup works because every session gets the same instructions: how to delegate, how to report, which tools to call. Those instructions are as much a part of the system as the CLIs themselves. If they drift, behavior drifts.
So IST treats them as a release artifact:
| Kit part | What it is | Where it ends up |
|---|---|---|
| Profile | The system prompt and allowed tools for one role (e.g. tda-worker) | ~/.ist/profiles/ |
| Prompt | An on-demand instruction a session reads with skit prompt show <name> | ~/.ist/prompts/global/ or ~/.ist/prompts/profiles/<profile>/ |
| CLI dependencies | The commands the prompts tell the AI to run | Global npm packages |
| Hooks, states, permission packs | Supporting files | See Installation Locations |
A kit has a name and a version (@ist/tda-kit@<version>), and skit install records which version of which kit wrote which files in ~/.ist/installed-kits.json.
What versioning gives you
Reproducibility
Two machines that install the same kit version get the same profile and prompt files. A kit also pins the CLI versions its prompts were written against, so a prompt never tells the AI to use a flag the installed CLI does not have.
An IST release goes one step further: snapshot install @ist/beta installs a tested combination of CLIs and kits at fixed versions. Run snapshot current to see what you have.
Clean upgrades and rollback
Re-installing a kit removes the files recorded for its previous version before copying the new ones. A prompt that was dropped in the new version disappears instead of lingering.
Because any published version can be installed again, rolling back is an ordinary install:
skit install @ist/tda-kit@<previous-version>
You can check what is installed at any time:
skit list
skit prompt list
Ownership is explicit
skit knows which files belong to which kit. Anything under ~/.ist/prompts/ or ~/.ist/profiles/ that no kit owns shows up in skit orphans, which makes hand edits visible instead of silent.
Slots: where your own instructions go
Kits are shared; your project's rules are not. Kit authors therefore leave slots: a profile tells the AI to read a prompt that the kit does not ship, and you provide it.
The TDA profiles use a conventions slot. On startup, a tda-worker session is told to run:
skit prompt show conventions --profile tda-worker 2>/dev/null \
|| skit prompt show conventions
and to continue without it if neither exists. To fill the slot, write the file yourself:
| File | Read by |
|---|---|
~/.ist/prompts/profiles/tda-worker/conventions.md | tda-worker sessions only |
~/.ist/prompts/global/conventions.md | Every role that looks for conventions |
Because no kit owns these files:
- Upgrading or reinstalling the kit does not touch them. Your conventions survive kit updates.
skit orphanslists them. That is expected. Don't runskit orphans --cleanwithout checking the list.
The general rule: put shared, versioned behavior in kits, and put local, project-specific rules in slots.
Next
- What Changes on an Upgrade: what moves together when a kit or an IST release is upgraded
- When Sessions Load Prompts: when a session actually sees the new files