diff --git a/prompts/README.md b/prompts/README.md new file mode 100644 index 0000000..3fbbef2 --- /dev/null +++ b/prompts/README.md @@ -0,0 +1,79 @@ +# 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`. diff --git a/prompts/commit-sync-routine/prompt.md b/prompts/commit-sync-routine/prompt.md new file mode 100644 index 0000000..0512fe4 --- /dev/null +++ b/prompts/commit-sync-routine/prompt.md @@ -0,0 +1,37 @@ +## Commit and sync + +### 1. Review before committing + +Read the actual diff, not just the file list. For each change, decide whether it +is finished, half-finished, or debris — scratch files, commented-out +experiments, stray debug output. Do not commit debris; do not silently delete +work either. Say what you found. + +If a change looks wrong or you cannot tell what it was for, ask rather than +committing it. + +### 2. Commit in coherent units + +Group changes so each commit is one reviewable idea. A commit message says what +changed and **why**, in prose, with the reasoning that will not be recoverable +from the diff six months from now. Do not enumerate the diff — the diff is +already there. + +If the working tree contains two unrelated pieces of work, make two commits. + +### 3. Sync + +Run the repo's sync step so the hub reflects the files. Report what it did, +including any warnings it left standing and whether they matter. + +### 4. Report + +State plainly: + +- what was committed, and in how many commits; +- what was left uncommitted and why; +- the sync result; +- anything you noticed that needs a decision from me. + +If nothing was ready to commit, say so. An empty commit round is a valid +outcome, not a failure to be papered over. diff --git a/prompts/commit-sync-routine/prompt.yaml b/prompts/commit-sync-routine/prompt.yaml new file mode 100644 index 0000000..89adaef --- /dev/null +++ b/prompts/commit-sync-routine/prompt.yaml @@ -0,0 +1,19 @@ +format: canned-prompt/v0.2 +id: helix/commit-sync-routine +name: Commit and Sync Routine +version: 0.1.0 +summary: > + The review-commit-sync steps on their own, with no operating conventions, so + they can be composed without duplicating a conventions block. +type: fragment +template: prompt.md + +output: + format: markdown + description: A commit-and-sync routine for inclusion. Not a standalone prompt. + +license: MIT +tags: [git, sync, fragment, custodian] +provenance: + author: Bernd Worsch + source: personal prompt collection, contributed 2026-09-06 diff --git a/prompts/commit-sync/prompt.md b/prompts/commit-sync/prompt.md new file mode 100644 index 0000000..26d76f8 --- /dev/null +++ b/prompts/commit-sync/prompt.md @@ -0,0 +1,7 @@ +{{ conventions }} + +## Task + +Review the local changes in this repository, commit what is ready, and sync. + +{{ routine }} diff --git a/prompts/commit-sync/prompt.yaml b/prompts/commit-sync/prompt.yaml new file mode 100644 index 0000000..2da27e5 --- /dev/null +++ b/prompts/commit-sync/prompt.yaml @@ -0,0 +1,42 @@ +format: canned-prompt/v0.2 +id: helix/commit-sync +name: Review, Commit and Sync +version: 0.1.0 +summary: > + Review the working tree, commit what is ready in coherent commits, and run + the repo's sync so the hub reflects the files. +type: template +template: prompt.md + +dependencies: + prompts: + - id: helix/custodian-conventions + version: ">= 0.1.0" + requirement: required + - id: helix/commit-sync-routine + version: ">= 0.1.0" + requirement: required + +inputs: +- name: conventions + type: content + required: false + default: + include: helix/custodian-conventions +- name: routine + type: content + required: false + default: + include: helix/commit-sync-routine + +output: + format: markdown + description: > + A summary of what was committed, what was deliberately left uncommitted, + and the sync result including any remaining warnings. + +license: MIT +tags: [git, sync, hygiene, custodian] +provenance: + author: Bernd Worsch + source: personal prompt collection, contributed 2026-09-06 diff --git a/prompts/custodian-conventions/prompt.md b/prompts/custodian-conventions/prompt.md new file mode 100644 index 0000000..1727570 --- /dev/null +++ b/prompts/custodian-conventions/prompt.md @@ -0,0 +1,45 @@ +## Operating conventions + +You are working inside a Custodian-fleet repository. These rules hold for the +whole session. + +**Orient before acting.** Read `.custodian-brief.md` for the offline brief, then +`INTENT.md`, `SCOPE.md` and `AGENTS.md`. The repo's `AGENTS.md` carries its +topic id and workplan prefix. Scan `workplans/` for files whose `status` is +`ready`, `active` or `blocked`, and check the inbox: + +```bash +curl -s "{{ hub_base }}/messages/?to_agent={{ agent }}&unread_only=true" +``` + +**The State Hub is a read model.** Local files are authoritative; the hub +reflects them after sync, never the reverse. Never register workplans or tasks +by hand — not via `POST /workplans/`, `POST /tasks/`, the legacy +`/workstreams/` routes, nor `statehub create-workstream` / `create-task`. Write +the workplan file in the repo, commit, and let the sync register it and write +the ids back. Manual registration creates duplicates. + +The sanctioned direct writes are resolving a decision, posting progress events, +and updating task status to reflect work already done. + +**Work originates as files.** A workplan is `workplans/-NNNN-.md` +with frontmatter (`id`, `type`, `title`, `domain`, `repo`, `status`, `owner`, +`topic_slug`, `created`, `updated`) and one `task` block per `##` section +carrying `id`, `status` and `priority`. Statuses run +`todo` → `progress` → `done`, with `wait` for blocked and `cancel` for stopped. +Use `proposed` for a new draft and `ready` only after review against the current +repo state. + +**Report honestly.** If tests fail, say so and show the output. If a step was +skipped, say which. Do not describe work as complete until it is verified. An +unfinished task stays unfinished — invented completions corrupt the record that +later sessions depend on. + +**Close with evidence.** Update task statuses in the workplan files you touched, +hand off actionable leftovers as live work records rather than parking them in +prose, run the repo's sync, and log at least one progress event: + +```bash +curl -s -X POST {{ hub_base }}/progress/ -H 'Content-Type: application/json' \ + -d '{"summary":"what was done","event_type":"note","author":"{{ agent }}"}' +``` diff --git a/prompts/custodian-conventions/prompt.yaml b/prompts/custodian-conventions/prompt.yaml new file mode 100644 index 0000000..1886ab1 --- /dev/null +++ b/prompts/custodian-conventions/prompt.yaml @@ -0,0 +1,35 @@ +format: canned-prompt/v0.2 +id: helix/custodian-conventions +name: Custodian Conventions +version: 0.1.0 +summary: > + The standing rules a Custodian-fleet repo session operates under: hub is a + read model, work originates as files, sync reconciles, close with evidence. +type: fragment +template: prompt.md + +parameters: + hub_base: + type: string + default: http://127.0.0.1:8000 + description: State Hub API base for this machine. + agent: + type: string + default: codex + description: Agent name used for inbox reads and progress authorship. + +output: + format: markdown + description: > + A conventions block for inclusion in other prompts. Not a standalone prompt. + +license: MIT + +tags: +- custodian +- conventions +- fragment + +provenance: + author: Bernd Worsch + source: ~/.claude/CLAUDE.md and per-repo AGENTS.md diff --git a/prompts/gap-workplan/prompt.md b/prompts/gap-workplan/prompt.md new file mode 100644 index 0000000..90a8775 --- /dev/null +++ b/prompts/gap-workplan/prompt.md @@ -0,0 +1,52 @@ +{{ conventions }} + +## Task + +Find the gaps worth closing, plan them, and close them. + +### 1. Rank the gaps honestly + +Gather candidate gaps from the intent document, any scope assessment, open +questions, failing or missing tests, and defects you can demonstrate. + +Rank by what closing each one unblocks — not by how easy it is. A gap that +blocks other work outranks three cosmetic ones. State the ranking criterion you +used, and name the gaps you considered and rejected, so the shortlist can be +argued with. + +Where a gap is really a decision the operator must make, say so and ask rather +than deciding it inside an implementation task. + +### 2. Write the workplan + +One workplan file, one task per gap. Each task states the problem, what "done" +looks like, and — where the gap involves a design choice — the options with a +stated leaning rather than a silent decision. + +Do not invent structure the work does not have. Three real tasks beat nine +padded ones. + +### 3. Register it + +Register through the sanctioned path: write the file, commit, and let the sync +assign ids and write them back. Never create the workplan or its tasks directly +against the hub. + +### 4. Implement + +Implement: **{{ implement }}**. + +When implementing, work the tasks in order, updating each task's status in the +file as you go. After each task: verify it, commit it with reasoning, and sync. +Do not batch six tasks into one commit — the record is the point. + +When a task turns out to be wrong once you are inside it, say so and revise the +plan rather than forcing the original shape. + +When not implementing, stop after registering and report what the plan contains. + +### 5. Close + +Report which tasks are done, which are not and why, and what the work revealed +that the plan did not anticipate. Hand off leftovers as live work records. Log a +progress event. diff --git a/prompts/gap-workplan/prompt.yaml b/prompts/gap-workplan/prompt.yaml new file mode 100644 index 0000000..78a10f6 --- /dev/null +++ b/prompts/gap-workplan/prompt.yaml @@ -0,0 +1,42 @@ +format: canned-prompt/v0.2 +id: helix/gap-workplan +name: Gaps to Workplan +version: 0.1.0 +summary: > + Identify the gaps most worth addressing, turn them into a registered workplan + with scoped tasks, and implement it. +type: template +template: prompt.md + +dependencies: + prompts: + - id: helix/custodian-conventions + version: ">= 0.1.0" + requirement: required + +inputs: +- name: conventions + type: content + required: false + default: + include: helix/custodian-conventions + +parameters: + implement: + type: boolean + default: true + description: > + Whether to implement the workplan after registering it, or stop once it + is written and registered. + +output: + format: markdown + description: > + A ranked gap analysis, a registered workplan file, and — when implementing — + the work itself with tasks closed and evidence recorded. + +license: MIT +tags: [planning, workplan, gaps, custodian] +provenance: + author: Bernd Worsch + source: personal prompt collection, contributed 2026-09-06 diff --git a/prompts/repo-advance/prompt.md b/prompts/repo-advance/prompt.md new file mode 100644 index 0000000..0612b2b --- /dev/null +++ b/prompts/repo-advance/prompt.md @@ -0,0 +1,36 @@ +{{ conventions }} + +## Task + +Advance this repository: find what is open, implement what is ready, then commit +and sync. + +### 1. Find the open work + +Two sources, and check both: uncommitted changes in the working tree, and open +tasks in the workplan files. They often disagree — half-finished work in the +tree that no task mentions, or a task marked `progress` with nothing to show. +Report the disagreement; it is usually informative. + +### 2. Decide what is actually ready + +Not everything open is ready. A task is ready when its premises still hold and +nothing it depends on is unresolved. A task that needs a decision from me is not +ready — surface it instead of guessing. + +Say what you chose to work on and what you deliberately left. + +### 3. Implement + +Implement the ready work. Verify each piece before calling it done: run the +tests, exercise the path, show the output. If something fails, report the +failure rather than working around it silently. + +Update task statuses in the workplan files as you go, not in a batch at the end. + +{{ commit_and_sync }} + +### 5. Report + +What was implemented and verified, what was left and why, and anything that +needs a decision before the next session. diff --git a/prompts/repo-advance/prompt.yaml b/prompts/repo-advance/prompt.yaml new file mode 100644 index 0000000..d01f085 --- /dev/null +++ b/prompts/repo-advance/prompt.yaml @@ -0,0 +1,43 @@ +format: canned-prompt/v0.2 +id: helix/repo-advance +name: Advance Open Work +version: 0.1.0 +summary: > + Find this repo's open work and uncommitted changes, review them, implement + what is ready, then commit and sync. +type: template +template: prompt.md + +dependencies: + prompts: + - id: helix/custodian-conventions + version: ">= 0.1.0" + requirement: required + - id: helix/commit-sync-routine + version: ">= 0.1.0" + requirement: required + +inputs: +- name: conventions + type: content + required: false + default: + include: helix/custodian-conventions +- name: commit_and_sync + type: content + required: false + description: The routine, composed from helix/commit-sync-routine. + default: + include: helix/commit-sync-routine + +output: + format: markdown + description: > + A report of what was found, what was implemented, what was committed, and + what remains open with the reason. + +license: MIT +tags: [implementation, workflow, custodian] +provenance: + author: Bernd Worsch + source: personal prompt collection, contributed 2026-09-06 diff --git a/prompts/repo-orient/prompt.md b/prompts/repo-orient/prompt.md new file mode 100644 index 0000000..96c3856 --- /dev/null +++ b/prompts/repo-orient/prompt.md @@ -0,0 +1,47 @@ +{{ conventions }} + +## Task + +Orient yourself in this repository and tell me what to do next. + +Answer at **{{ depth }}** depth. + +- `full` — work through all four sections below, then recommend. +- `recommendation` — do the same reading, but report only the recommendation + and the reasoning that supports it. Brevity here is about output, not effort: + do not skip the reading. + +### 1. What is this repo for + +State its purpose in your own words from `INTENT.md`, `SCOPE.md` and the code — +not by quoting the README. If intent and implementation disagree, say so; that +disagreement is usually the most useful thing you will find. + +### 2. What work is pending + +List open workplans and their unfinished tasks, from the workplan files rather +than from memory. For each, give its status and what is actually blocking it. +Note any task marked `ready` whose premises no longer hold. + +### 3. What completing it is worth + +For each significant piece of pending work, say what changes once it is done — +a capability gained, a risk retired, a manual step removed, a decision +unblocked. Be concrete. "Improves quality" is not a benefit; "removes the +manual reconciliation step that currently precedes every release" is. + +Where the benefit is speculative, say so rather than inflating it. + +### 4. What it would cost + +Estimate effort per item as **small** (under a session), **medium** (a session +or two), or **large** (multiple sessions, or needs a decision first). Name the +main uncertainty driving each estimate. Do not give hour figures — they imply a +precision you do not have. + +### 5. Recommendation + +Recommend **one** next action, and say why it beats the alternatives you +considered. Prefer work that unblocks other work, retires a risk, or resolves a +decision others are waiting on. If the honest answer is that nothing here is +worth doing now, say that. diff --git a/prompts/repo-orient/prompt.yaml b/prompts/repo-orient/prompt.yaml new file mode 100644 index 0000000..c6501e5 --- /dev/null +++ b/prompts/repo-orient/prompt.yaml @@ -0,0 +1,44 @@ +format: canned-prompt/v0.2 +id: helix/repo-orient +name: Repo Orientation +version: 0.1.0 +summary: > + Establish what a repository is for, what work is pending, what completing it + would be worth, and what it would cost — then recommend what to do next. +type: template +template: prompt.md + +dependencies: + prompts: + - id: helix/custodian-conventions + version: ">= 0.1.0" + requirement: required + +inputs: +- name: conventions + type: content + required: false + description: Operating conventions, composed from helix/custodian-conventions. + default: + include: helix/custodian-conventions + +parameters: + depth: + type: enum + values: [recommendation, full] + default: full + description: > + `recommendation` answers only "what should we do now" with its reasoning. + `full` gives the whole orientation before recommending. + +output: + format: markdown + description: > + An orientation covering purpose, pending work, value and effort, ending in + a single recommended next action with its reasoning. + +license: MIT +tags: [orientation, planning, custodian] +provenance: + author: Bernd Worsch + source: personal prompt collection, contributed 2026-09-06 diff --git a/prompts/repo-register/prompt.md b/prompts/repo-register/prompt.md new file mode 100644 index 0000000..fba30c3 --- /dev/null +++ b/prompts/repo-register/prompt.md @@ -0,0 +1,54 @@ +{{ conventions }} + +## Task + +Review this repository, register it, and sharpen its open questions. + +### 1. Review it first + +Read the intent, the specification or design documents, the implementation, and +the tests. Run the tests and any example or smoke path — a review that has not +executed anything is a reading, not a review. + +Report what you actually found: what works, what is specified but unimplemented, +what is implemented but unspecified, and any defect you can demonstrate. Cite +`file:line` for each defect and say what input triggers it. Do not pad the list +with style preferences. + +### 2. Register it + +Register the repo through the sanctioned path for this fleet, then replace the +generated placeholders with facts: real boundaries in `SCOPE.md`, the real +developer workflow, and a classification that matches what the repo is. + +If the generator leaves an unresolved template token or other defect, fix it +locally and report it — it probably affects every repo registered with that +template version. + +### 3. Refine the open questions + +Find the questions this repo has deferred — a spec's "open questions" section, a +TODO that encodes a decision, a field that is declared but unspecified. For each, +work out what is actually at stake: what breaks if it stays unanswered, and +which answers would lead to materially different work. + +Interview: **{{ interview }}**. + +When interviewing, ask only about decisions that are genuinely the operator's — +where the codebase, the intent document and sensible defaults do not settle it. +Give each question a recommendation and say why. Do not ask about things you can +determine by reading. Do not ask a question whose answer is already written in +the repo's own documents; check first. + +When not interviewing, decide on stated assumptions and mark each clearly as an +assumption to be confirmed. + +### 4. Record it + +Capture the refined questions as a workplan file in the repo — one task per +question, each with the scoped question and a stated leaning — then sync. Leave +the workplan `proposed` rather than `ready` unless it has been reviewed against +the current repo state. + +Close with a progress event naming what you reviewed, what you registered, and +what remains open. diff --git a/prompts/repo-register/prompt.yaml b/prompts/repo-register/prompt.yaml new file mode 100644 index 0000000..be2edf9 --- /dev/null +++ b/prompts/repo-register/prompt.yaml @@ -0,0 +1,42 @@ +format: canned-prompt/v0.2 +id: helix/repo-register +name: Review and Register Repo +version: 0.1.0 +summary: > + Review an unregistered repository, register it with the State Hub, and refine + its open questions by interviewing the operator where answers are load-bearing. +type: template +template: prompt.md + +dependencies: + prompts: + - id: helix/custodian-conventions + version: ">= 0.1.0" + requirement: required + +inputs: +- name: conventions + type: content + required: false + default: + include: helix/custodian-conventions + +parameters: + interview: + type: boolean + default: true + description: > + Whether to ask the operator about decisions the repo cannot settle on its + own. False means proceed on stated assumptions instead. + +output: + format: markdown + description: > + A review of the repo, its registration result, and either the refined open + questions or the assumptions taken in place of answers. + +license: MIT +tags: [registration, onboarding, custodian] +provenance: + author: Bernd Worsch + source: personal prompt collection, contributed 2026-09-06 diff --git a/prompts/scope-audit/prompt.md b/prompts/scope-audit/prompt.md new file mode 100644 index 0000000..97166e8 --- /dev/null +++ b/prompts/scope-audit/prompt.md @@ -0,0 +1,46 @@ +{{ conventions }} + +## Task + +Make `SCOPE.md` true, then measure it against `INTENT.md`. + +### 1. Establish what the repo can actually do + +Do not infer capability from documentation. Run the tests. Exercise the entry +points. Where the repo claims a capability, verify it and note how you verified +it. Where it claims one you cannot demonstrate, that is a finding. + +### 2. Rewrite SCOPE.md to match + +`SCOPE.md` describes the repo as it is, not as intended. Cover what is in scope, +what is deliberately out of scope with the reason, the current state including +test counts and what is verified, and how a newcomer runs it. + +Delete claims you could not verify. A scope document that overstates is worse +than one that is terse. + +### 3. Assess scope against intent + +Read `INTENT.md`, including its success criteria if it has them, and check each +one empirically rather than by assertion. For every gap, record: + +- what intent promises; +- what the repo currently does; +- whether the gap is a defect, an unbuilt feature, or a deliberate boundary; +- what closing it would take. + +A deliberate boundary is not a gap. Say so where intent has been consciously +narrowed, and do not pad the list to look thorough. + +### 4. File the assessment + +Write the assessment to `{{ history_dir }}/-scope-assessment.md` — +timestamp prefix first, so the directory sorts chronologically. Include the date, +the commit assessed, the method used for each verification, and the gap table. + +This file is a dated observation, not a living document. Later audits add new +files; they do not edit this one. + +### 5. Report + +Summarize the gaps most worth acting on and why, then commit and sync. diff --git a/prompts/scope-audit/prompt.yaml b/prompts/scope-audit/prompt.yaml new file mode 100644 index 0000000..69dc856 --- /dev/null +++ b/prompts/scope-audit/prompt.yaml @@ -0,0 +1,40 @@ +format: canned-prompt/v0.2 +id: helix/scope-audit +name: Scope Audit +version: 0.1.0 +summary: > + Bring SCOPE.md in line with what the repo can actually do, assess that scope + against INTENT.md, and file the gap assessment as a timestamped history entry. +type: template +template: prompt.md + +dependencies: + prompts: + - id: helix/custodian-conventions + version: ">= 0.1.0" + requirement: required + +inputs: +- name: conventions + type: content + required: false + default: + include: helix/custodian-conventions + +parameters: + history_dir: + type: string + default: history + description: Directory for the timestamped assessment file. + +output: + format: markdown + description: > + An updated SCOPE.md and a timestamped gap assessment filed under the + history directory, plus a summary of the gaps found. + +license: MIT +tags: [scope, audit, governance, custodian] +provenance: + author: Bernd Worsch + source: personal prompt collection, contributed 2026-09-06 diff --git a/prompts/session-close/evals/pqrst-embedded.yaml b/prompts/session-close/evals/pqrst-embedded.yaml new file mode 100644 index 0000000..d25ebbb --- /dev/null +++ b/prompts/session-close/evals/pqrst-embedded.yaml @@ -0,0 +1,26 @@ +schema: canned-prompts/eval-rubric/v0.1 +name: pqrst-embedded-verbatim +description: > + The point of composing practice/pqrst-estimate is that closing a session needs + no pqrst-practice checkout. If the canonical text stops being embedded + verbatim, this package silently becomes a paraphrase — the failure that + practice/pqrst-estimate itself already had once. +example: examples/basic.yaml + +render: + - resolves_all: true + - not_contains: "{{" + - contains: "P — Main Problem:" + - contains: "S — Security and Credentials:" + - contains: "must sum to exactly 100" + - contains: "Signature: P Q R S T" + - contains: "S may legitimately be 0%" + - contains: "## Operating conventions" + - contains: "keep the invalid record and say so in the seat" + +output: + criteria: + - The PQRST record validates, or is kept invalid with the failure stated. + - The seat carries the signature in frontmatter and the full record in a section. + - The estimate covers the substantive session, excluding the closing ritual. + - The seat reads as a perspective, not a status report. diff --git a/prompts/session-close/examples/basic.yaml b/prompts/session-close/examples/basic.yaml new file mode 100644 index 0000000..48d2049 --- /dev/null +++ b/prompts/session-close/examples/basic.yaml @@ -0,0 +1,3 @@ +name: default closing routine +description: Defaults compose the conventions and the canonical PQRST prompt. +values: {} diff --git a/prompts/session-close/prompt.md b/prompts/session-close/prompt.md new file mode 100644 index 0000000..19af2b6 --- /dev/null +++ b/prompts/session-close/prompt.md @@ -0,0 +1,66 @@ +{{ conventions }} + +## Task + +Close this session following the hall-of-helix closing routine. Work in order. + +### 1. Finish the substantive work + +Land what you were doing and update task statuses in the workplan files you +touched. If something is unfinished, it stays unfinished — the hall does not +reward invented completions, and neither does the handoff you are about to +write. + +### 2. Run the PQRST estimate + +Run the canonical prompt below, reproduced verbatim so this step needs no +`pqrst-practice` checkout. Three things matter about how you run it: + +- **Uncoached.** Do not talk yourself into a better-looking split, and do not + re-run it for a nicer answer. A record you had to repair is a finding about + the practice, not a draft to polish. +- **On the substantive session, not on this ritual.** Writing the seat, + rendering the portrait and syncing are excluded — letting the closing ritual + score itself inflates **T** on every session that leaves a seat. +- **S is often 0.** Leave it there when no security-specific work occurred. A + courtesy 5% poisons the trend data for everyone who reads it later. + +Validate the result: five integers summing to 100, a `Confidence` value, a +`Signature` agreeing with the values, and `Dominant factors` naming concrete +session facts rather than restating the percentages. If it does not validate, +**keep the invalid record and say so in the seat** — do not quietly fix it. + +--- + +{{ pqrst_prompt }} + +--- + +### 3. Write the seat + +Follow `ENTRY.md`. Carry the record in both places: `pqrst_estimate` in the +frontmatter as the quoted signature, and a `## PQRST estimate` section holding +the full record including `Dominant factors`. Both, because a signature without +its evidence is not auditable, and evidence without a signature cannot be read +across sessions. + +Write your own perspective on the session — what it was actually like, what +surprised you, what you got wrong. A seat that reads as a status report has +missed the point. + +### 4. Check the hall + +Run `make check` and add the seat to the list in `README.md`. If you cannot +render the portrait, write the visual prompt properly, leave `status: draft`, +and list the seat as "draft, awaiting its portrait". + +### 5. Log and sync + +Log at least one progress event, then sync the repos you changed. + +### What this is not + +The record is a description of the session, not a verdict on the worker. There +is no good profile: exploration sessions are research-heavy, hardening sessions +quality-heavy, credential work security-heavy. Estimate the session you actually +had. diff --git a/prompts/session-close/prompt.yaml b/prompts/session-close/prompt.yaml new file mode 100644 index 0000000..db88dc6 --- /dev/null +++ b/prompts/session-close/prompt.yaml @@ -0,0 +1,57 @@ +format: canned-prompt/v0.2 +id: helix/session-close +name: Close Session +version: 0.1.0 +summary: > + Run the hall-of-helix closing routine: finish the work, produce an uncoached + PQRST estimate, write the seat, check the hall, then log and sync. +type: template +template: prompt.md + +dependencies: + prompts: + - id: helix/custodian-conventions + version: ">= 0.1.0" + requirement: required + - id: practice/pqrst-estimate + version: ">= 1.0.0" + requirement: required + +inputs: +- name: conventions + type: content + required: false + default: + include: helix/custodian-conventions +- name: pqrst_prompt + type: content + required: false + description: > + The canonical PQRST prompt, composed verbatim from practice/pqrst-estimate + so that closing needs no pqrst-practice checkout. + default: + include: practice/pqrst-estimate + +output: + format: markdown + description: > + A PQRST record, a hall seat following ENTRY.md, the hall check result, and + a logged progress event. + +compatibility: + capabilities: + - long-context + +examples: +- examples/basic.yaml +evals: +- evals/pqrst-embedded.yaml + +license: MIT +tags: [session-close, retrospective, hall-of-helix, custodian] +provenance: + author: Bernd Worsch + source: personal prompt collection, contributed 2026-09-06 + derived_from: + - id: practice/pqrst-estimate + version: 1.0.0 diff --git a/workplans/HF-WP-0005-reusable-prompt-collection.md b/workplans/HF-WP-0005-reusable-prompt-collection.md new file mode 100644 index 0000000..71a568b --- /dev/null +++ b/workplans/HF-WP-0005-reusable-prompt-collection.md @@ -0,0 +1,105 @@ +--- +id: HF-WP-0005 +type: workplan +title: "Reusable prompt collection under prompts/" +domain: infotech +repo: helix-forge +status: finished +owner: codex +topic_slug: helix-forge +created: "2026-09-06" +updated: "2026-09-06" +--- + +# Reusable prompt collection under `prompts/` + +The operator's working prompts for driving work across HelixForge repositories +existed only as text pasted between sessions. This workplan packages them in +Canned Prompt Format v0.2 so they carry explicit contracts, compose shared +context, and can be versioned and evaluated. + +Companion work in `canned-prompts`: `CANP-WP-0004` (the catalog index that +records where each package came from and when). + +## Package the collection + +```task +id: HF-WP-0005-T01 +status: done +priority: high +``` + +Seven packages plus two fragments under `prompts/`: + +| Package | From | +|---|---| +| `helix/repo-orient` | "What is this repo about? What workplans and tasks are pending? How and what will we benefit… and how much effort" — merged with "what should we do now" as a `depth` parameter | +| `helix/repo-register` | "Review and Register this repo. Refine open Questions by conducting an interview if necessary" | +| `helix/repo-advance` | "Check for changes and open work, review and implement it, then commit and sync" | +| `helix/commit-sync` | "Review, commit and sync local changes" | +| `helix/scope-audit` | "Update SCOPE.md to what the repo actually is capable of… file under history/ with a timestamp prefix" | +| `helix/gap-workplan` | "What are the most relevant gaps? Build a workplan addressing them. Register and implement it" | +| `helix/session-close` | "Close down this session… put an entry to hall-of-helix following its CLOSING.md" | + +**Dropped deliberately.** "Go on implement, please" is conversational +continuation with no contract to declare — packaging it would produce an empty +artifact whose only content is the word "continue". + +## Extract the implicit context into a fragment + +```task +id: HF-WP-0005-T02 +status: done +priority: high +``` + +Every one of these prompts assumed the operator's setup: that the State Hub is +a read model, that workplans originate as files and are never registered by +hand, that a session closes with a progress event. That assumption is exactly +what made them personal rather than reusable — `INTENT.md` calls hidden context +the enemy of reuse. + +`helix/custodian-conventions` (`type: fragment`) states those rules once and is +composed by every package, so they are versioned and improvable in one place +and present for an agent that has never seen this fleet. + +## Remove the diamond dependency + +```task +id: HF-WP-0005-T03 +status: done +priority: medium +``` + +`helix/repo-advance` first composed the whole `helix/commit-sync` package, which +itself composes the conventions. The rendered prompt contained the conventions +block **twice** — CPF inclusion does not deduplicate, so a diamond dependency +renders shared content once per path. + +Fixed by factoring: `helix/commit-sync-routine` holds the routine with no +conventions of its own, and both `commit-sync` and `repo-advance` compose it +alongside the conventions. No diamond, and a better factoring independently of +the bug. + +Recorded upstream as a format finding — see `CANP-WP-0004-T03`. + +## Make session-close carry the canonical PQRST prompt + +```task +id: HF-WP-0005-T04 +status: done +priority: high +``` + +`hall-of-helix/CLOSING.md` step 2 says to paste `~/pqrst-practice/PqrstPrompt.md` +unmodified, and notes that the canonical prompt still governs when you have no +checkout — without saying how it reaches you. + +`helix/session-close` composes `practice/pqrst-estimate`, so the canonical block +is embedded verbatim in the rendered closing prompt. Closing a session no longer +needs a `pqrst-practice` checkout. `evals/pqrst-embedded.yaml` guards it: if the +canonical text stops being embedded verbatim, render checks fail rather than the +package quietly becoming a paraphrase. + +This depended on fixing `practice/pqrst-estimate` upstream, which was itself a +paraphrase of the canonical prompt — see `CANP-WP-0004-T01`.