# prompts/

Reusable prompts for working across HelixForge and the wider Custodian fleet,
packaged in [Canned Prompt Format](../../canned-prompts/CannedPromptFormat.md)
v0.2 so they carry an explicit contract rather than living as pasted text.

## The collection

| Package | What it does |
|---|---|
| `helix/repo-orient` | What is this repo for, what is pending, what is it worth, what would it cost — then one recommendation |
| `helix/repo-register` | Review an unregistered repo, register it, and sharpen its open questions by interview |
| `helix/repo-advance` | Find open work and uncommitted changes, implement what is ready, commit and sync |
| `helix/commit-sync` | Review the working tree, commit in coherent units, sync |
| `helix/scope-audit` | Make `SCOPE.md` true, assess it against `INTENT.md`, file a dated gap assessment |
| `helix/gap-workplan` | Rank the gaps worth closing, write and register a workplan, implement it |
| `helix/session-close` | The hall-of-helix closing routine, with the canonical PQRST prompt embedded |

Two fragments (`type: fragment`) are composed by the others rather than used
directly:

| Fragment | Composed by |
|---|---|
| `helix/custodian-conventions` | every package above |
| `helix/commit-sync-routine` | `helix/commit-sync`, `helix/repo-advance` |

## Why fragments

Each of these prompts used to assume a great deal: that you knew the State Hub
is a read model, that workplans originate as files, that you never register a
workplan by hand. That assumption is what made them personal rather than
reusable — INTENT calls hidden context the enemy of reuse.

`custodian-conventions` states those rules once. Every package includes it, so
the rules are versioned, improvable in one place, and present for an agent that
has never seen this setup.

`commit-sync-routine` exists for a narrower reason: `commit-sync` and
`repo-advance` both need the routine, and both need the conventions. Composing
the whole `commit-sync` package into `repo-advance` rendered the conventions
block **twice** — a diamond dependency, and CPF inclusion does not deduplicate.
Factoring the routine out removes the diamond.

## Using them

```bash
CP=~/canned-prompts/reference/canned_prompts.py
for p in custodian-conventions commit-sync-routine repo-orient commit-sync \
         repo-register scope-audit gap-workplan repo-advance; do
  python3 $CP add ~/helix-forge/prompts/$p
done
python3 $CP add ~/canned-prompts/examples/pqrst-estimate   # session-close needs it
python3 $CP add ~/helix-forge/prompts/session-close

python3 $CP render helix/repo-orient --set depth=recommendation
python3 $CP eval helix/session-close
python3 $CP index
```

Order matters: a package is validated when added, and a composed dependency
must already be in the catalog.

## session-close and PQRST

`helix/session-close` composes `practice/pqrst-estimate`, which is a faithful
package of `~/pqrst-practice/PqrstPrompt.md`. The canonical block is therefore
embedded **verbatim** in the rendered closing prompt, so closing a session no
longer requires a `pqrst-practice` checkout — `CLOSING.md` says the canonical
prompt still governs when you have none, and this is how it travels.

`evals/pqrst-embedded.yaml` guards that: if the canonical text stops being
embedded verbatim, the render checks fail rather than the package quietly
becoming a paraphrase.

## Provenance

These began as Bernd's working prompts, contributed 2026-09-06. Each manifest
records that in `provenance`; the consuming catalog additionally records where
and when each package entered it, in its `index.yaml`.