tegwick
883409665f
HF-WP-0005. The prompts used to drive work across HelixForge repositories existed only as text pasted between sessions. They are now Canned Prompt Format v0.2 packages with declared inputs, parameters and output contracts. Seven packages: repo-orient (merging "what is this repo about" with "what should we do now" as a `depth` parameter), repo-register, repo-advance, commit-sync, scope-audit, gap-workplan, session-close. "Go on implement, please" is deliberately not packaged. It is conversational continuation with no contract to declare, and packaging it would produce an artifact whose only content is the word "continue". Every one of these prompts assumed the operator's setup — the State Hub is a read model, workplans originate as files and are never registered by hand, a session closes with a progress event. That assumption is what made them personal rather than reusable. helix/custodian-conventions states those rules once as a fragment composed by every package, so they are versioned, improvable in one place, and present for an agent that has never seen this fleet. helix/commit-sync-routine exists for a narrower reason. repo-advance first composed the whole commit-sync package, which itself composes the conventions, so the rendered prompt carried the conventions block twice — CPF inclusion does not deduplicate, and a diamond dependency renders shared content once per path. Factoring the routine out removes the diamond and is a better factoring regardless. Recorded upstream as canned-prompts CANP-WP-0004-T03. helix/session-close composes practice/pqrst-estimate, so the canonical PQRST block is embedded verbatim. hall-of-helix CLOSING.md says the canonical prompt still governs when you have no pqrst-practice checkout, without saying how it reaches you; this is how. evals/pqrst-embedded.yaml fails if the canonical text stops being embedded verbatim, rather than letting the package quietly become a paraphrase. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Bjefh8NUiEiahN4JLwoSKM Assistant: claude-code Assistant-Model: opus Assistant-Process: 388925@bnt-lap001 Assistant-Session: 3507023f-e0fd-4a1e-9d90-a0d4217d1502
79 lines
3.5 KiB
Markdown
79 lines
3.5 KiB
Markdown
# 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`.
|