Hook prompts¶
6 verified entries in plugin / hook.
idle¶
plugin:hook:idle
Lifecycle signal only; no agent-facing text is emitted.
| Field | Value |
|---|---|
| Source path | spec-cli/src/hook-prompts.ts |
| Source revision | 6a63deb6be59a992e9e25e193cc72b1d5c27b77e |
| Content SHA-256 | 9c24281dee2e8570fc04a56d1e92e301db8551e9a53000e03e6f9578521849a7 |
| Content role | signal |
| Handler path | .spec/spexcode/.plugins/core/idle/idle.sh |
| Handler revision | 2acb1c9258ccb34fe471b21449c8693cf2d6f460 |
| Events | Notification |
| Order | 10 |
| Blocking | no |
No prompt text is injected by idle. It records an undeclared idle session on the board.mark-active¶
plugin:hook:mark-active
Freshness signal only; no agent-facing text is emitted.
| Field | Value |
|---|---|
| Source path | spec-cli/src/hook-prompts.ts |
| Source revision | 6a63deb6be59a992e9e25e193cc72b1d5c27b77e |
| Content SHA-256 | 53be22017172a597372e863deb2616f6048238a6a20040eb55f0700fa5e72640 |
| Content role | signal |
| Handler path | .spec/spexcode/.plugins/core/mark-active/mark-active.sh |
| Handler revision | edfc691c462fc9955ed75a204263631eeadd33a5 |
| Events | UserPromptSubmit, PreToolUse |
| Order | 10 |
| Blocking | no |
No prompt text is injected by mark-active. It updates the session lifecycle record before the tool runs.session-fail¶
plugin:hook:session-fail
Failure signal only; no agent-facing text is emitted.
| Field | Value |
|---|---|
| Source path | spec-cli/src/hook-prompts.ts |
| Source revision | 6a63deb6be59a992e9e25e193cc72b1d5c27b77e |
| Content SHA-256 | 048afc79c71a5d85f7eb184bf7de0afb79bc5ee810f97aed56e0ff717261c50a |
| Content role | signal |
| Handler path | .spec/spexcode/.plugins/core/session-fail/fail.sh |
| Handler revision | 2acb1c9258ccb34fe471b21449c8693cf2d6f460 |
| Events | StopFailure |
| Order | 10 |
| Blocking | no |
No prompt text is injected by session-fail. It records a failed governed turn as error.spec-first¶
plugin:hook:spec-first
Blocking prompt injected once before the first governed code read.
| Field | Value |
|---|---|
| Source path | spec-cli/src/hook-prompts.ts |
| Source revision | 6a63deb6be59a992e9e25e193cc72b1d5c27b77e |
| Content SHA-256 | f88d98f57acfb5757ef260e53aa68d542b32b2456a9716454cbfc3c95de03369 |
| Content role | prompt |
| Handler path | .spec/spexcode/.plugins/core/spec-first/spec-first.sh |
| Handler revision | 6a63deb6be59a992e9e25e193cc72b1d5c27b77e |
| Events | PreToolUse |
| Order | 20 |
| Blocking | yes |
Before accessing governed source {path}, read its governing spec FIRST: {owner}. Read the relevant NEIGHBORS too: the parent that scopes it, the siblings it borders, and the children that refine it. Then reconcile deliberately: change the spec if the intent is changing, or make the code honor it. The one forbidden move is code that silently diverges from its spec. (Fires once per session, at the first governed code read.)spec-of-file¶
plugin:hook:spec-of-file
Non-blocking context injected when an actionable edited file needs attention.
| Field | Value |
|---|---|
| Source path | spec-cli/src/hook-prompts.ts |
| Source revision | 6a63deb6be59a992e9e25e193cc72b1d5c27b77e |
| Content SHA-256 | 50be9bb91e5984ef54e5dbacc5b9b8605ae4f7663db4461f6ece3c130f7eaf7c |
| Content role | prompt |
| Handler path | .spec/spexcode/.plugins/core/spec-of-file/spec-of-file.sh |
| Handler revision | 6a63deb6be59a992e9e25e193cc72b1d5c27b77e |
| Events | PostToolUse |
| Order | 10 |
| Blocking | no |
Contract context for this edit:
{details}stop-gate¶
plugin:hook:stop-gate
Blocking and advisory prompt variants emitted at the stop boundary.
| Field | Value |
|---|---|
| Source path | spec-cli/src/hook-prompts.ts |
| Source revision | 6a63deb6be59a992e9e25e193cc72b1d5c27b77e |
| Content SHA-256 | 1441f1d371dbedd66ce0b65b5b5ad4afb8f902a4cdd33deab3940e9ab09c3715 |
| Content role | prompt |
| Handler path | .spec/spexcode/.plugins/core/stop-gate/stop-gate.sh |
| Handler revision | 6a63deb6be59a992e9e25e193cc72b1d5c27b77e |
| Events | Stop |
| Order | 10 |
| Blocking | yes |
## full
Your session state is a CLAIM the graph, your supervisor, and other agents act on — not a box to tick to end the turn. Stopping undeclared makes your outcome a guess. Pick the ONE that is TRUE right now and run `{cli} session <choice>`, choosing the <choice> whose condition holds:
• done --propose merge — spec+code COMMITTED on the branch and genuinely ready for human review. It declares REVIEW and is the ONLY proposal that offers a clickable merge.
• done --propose nothing — TRAP: records no state. Choose merge, close, ask, or park below.
• done --propose close — task genuinely settled, work landed (or none to merge), worktree no longer needed, and no human decision, follow-up, or posted artifact awaits inspection: propose human close. It declares CLOSE-PENDING, not merge. Never run `session close` on your own id.
• ask --note <your-question> — you need the human: a real question or direction, an answered exploratory question or handoff awaiting their follow-up, or posted-artifact inspection. It declares ASKING and resumes only when they reply.
• park --note <what-you-await> — ONLY when a real wake-up will resume a named next action: a managed watch delivery or background task. A watch on terminal children is not a wake-up. It declares PARKED and self-resumes.
DECLARE LAST, THEN STOP: finish everything else in the turn first — speak, send your messages, establish managed watches or arm background waits — and make the declaration your FINAL call. Any tool call AFTER it flips your record back to active (mark-active, by design: activity is activity), so the next stop re-blocks and demands a fresh declaration; declaring last kills that loop at its source.
(This full explanation shows once per session; later undeclared stops get a one-line reminder. `{cli} help session` re-explains the choices any time.)
## terse
undeclared stop — declare the ONE true state as your LAST call: `{cli} session <done --propose merge (review; ONLY clickable merge)|close (close-pending; settled, no human decision/follow-up or posted artifact waiting)|park (parked; real wake-up + next action) / ask (asking; human reply/direction, including exploratory answer or handoff)>`. `done --propose nothing` is a trap: it writes no state and names these choices. Conditions: `{cli} help session`.
## artifact
a posted file/web artifact still needs human inspection; declare `spex session ask --note ...`, and declare it last.
## commit
Not ready to declare done: {reason}. The dogfood ritual lands every change as a git commit on your node branch BEFORE you propose. Commit your spec.md + code on this node branch (spec: <id> — <reason>, with a Session: trailer), then re-run `{cli} session done --propose {proposal}`.
## eval
eval — the loss signal the optimizer reads — flags {count} gap(s) in nodes you changed: {ids}. A node whose score went stale/unmeasured: re-measure it — PRODUCE the measurement YOURSELF with a real run of the scenario's actual surface (its tag on the `spex eval lint --changed` line tells you WHICH surface to run), compare to expected, and file it with `spex eval add <node>`; don't desk-check it, and don't defer to reviewing a recording after the fact. A FRONTEND node with no eval.md: give it one (a scenario — description + expected), since an obvious UI change should carry a loss signal. `spex eval lint --changed` lists them. (Advisory — fires once, not a gate.)