1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
#+TITLE: Flush Promotion — Handoff Bundle (from work)
#+AUTHOR: Craig Jennings & Claude
#+DATE: 2026-06-02
* Provenance
This is the preserved handoff bundle that produced the =/flush= skill and the
=SessionStart(clear)= resume hook. It arrived from the work project's inbox on
2026-06-02 (validated there the same day), and was implemented in rulesets in
commit =526df6d= (=feat(flush): add /flush skill and SessionStart(clear) resume
hook=).
Kept as design provenance — the rationale for why =/flush= exists, the decision
to package it as a skill rather than a project-workflow doc, and the original
=flush.org= workflow doc the skill was built from. The third bundle artifact,
=session-clear-resume.sh=, lives on as the canonical hook at
=hooks/session-clear-resume.sh=.
What landed vs. the promotion steps below:
- Step 1 (=/flush= skill) — done: =flush/SKILL.md=.
- Step 2 (hook canonicalization) — done: =hooks/session-clear-resume.sh= +
=~/.claude/hooks/= symlink.
- Step 3 (settings commit) — done: =.claude/settings.json= SessionStart entry,
plus =hooks/settings-snippet.json= updated so a fresh machine wires it on
=make install-hooks=.
- Step 4 (workflow-doc template) — skipped: the skill supersedes the
project-workflow doc, so both halves are global with no per-project sync.
- Step 5 (notes AVAILABLE WORKFLOWS entry) — n/a: rulesets has no such template
section to mirror into.
* Promotion Handoff Note (work → rulesets)
Promote the flush workflow + SessionStart(clear) hook into rulesets templates.
VALIDATED in the work project on 2026-06-02: built the flush workflow + a
SessionStart matcher=clear hook, then live-tested it — refreshed the
session-context anchor in place, /clear, and the fresh session read the anchor
and resumed the same logical session (replied 'flushed.', restated Active Goal +
Next Step, kept working) without re-running startup. The loop works end to end.
WHAT FLUSH IS: a mid-session context flush — the checkpoint half of the
wrap/restart-rhythm. Refresh the session-context anchor in place, /clear, resume
from the anchor. Cheaper tokens + sharper context without fragmenting the
session into archive files. Distinct from wrap-it-up (archives to .ai/sessions/
+ commits) and startup (genuine fresh start). One logical session spans the
/clear boundaries.
TWO ARTIFACTS:
1. flush.org — the workflow doc (pre-clear checkpoint half; post-clear half is
driven by the hook). Preserved below.
2. session-clear-resume.sh — the SessionStart(clear) hook. General by design:
anchor present -> resume + say 'flushed.'; anchor absent -> run startup
(covers a stray /clear). Reaches the model only via
hookSpecificOutput.additionalContext. Resolves the AI_AGENT_ID-aware anchor
path, falling back to the singleton .ai/session-context.org. Now canonical at
hooks/session-clear-resume.sh.
DECISION (2026-06-02, updated): package the pre-clear half as a /flush SKILL
(~/code/rulesets/flush/SKILL.md), not just a project workflow doc. Rationale: the
post-clear hook is already global, so making the pre-clear half a skill makes
BOTH halves global — /flush is callable by name from any project with no
per-project workflow-doc sync. Match the existing skill shape under
~/code/rulesets/<name>/SKILL.md (see voice/, debug/, add-tests/). The flush.org
doc filed here becomes the skill's reference body / the basis for SKILL.md; keep
a project-workflow template too only if it adds value beyond the skill.
AGENT-INVOCABLE + AGENT-INITIATED: the skill must be callable by the agent
itself, and the agent — not only the user — should decide when it's time to
flush (clean task boundary + large enough context, per the wrap/restart-rhythm).
HARD CONSTRAINT: /clear is user-only; the agent CANNOT execute /clear. So
"agent-initiated" means the agent runs the pre-clear checkpoint (refresh anchor +
verify-gate) on its own judgment, then PROMPTS the user "checkpoint saved, type
/clear to reset" — the agent proposes and does all the work; the user supplies
the single /clear keystroke. Do NOT design anything that assumes the agent can
self-trigger /clear.
PROMOTION STEPS (do these in a rulesets session):
1. /flush SKILL — author ~/code/rulesets/flush/SKILL.md per the DECISION +
AGENT-INITIATED notes above, built from flush.org. Pre-clear checkpoint (dump
live state -> refresh * Summary in place -> append dated flush marker to
* Session Log -> verify the write landed (gate) -> prompt the user to /clear).
Agent-callable; agent may initiate at a clean boundary.
2. HOOK CANONICALIZATION — the hook at ~/.claude/hooks/session-clear-resume.sh
is currently a REAL file, not rulesets-canonical. Move it to
~/code/rulesets/hooks/ and symlink ~/.claude/hooks/session-clear-resume.sh ->
it, matching the existing pattern (precompact-priorities.sh etc.). Otherwise
the settings.json reference breaks on a fresh rulesets clone.
3. SETTINGS COMMIT — ~/code/rulesets/.claude/settings.json already has the
SessionStart matcher=clear -> session-clear-resume.sh entry added
(uncommitted, valid JSON; ~/.claude/settings.json is a symlink to it). Review
+ commit it.
4. WORKFLOW TEMPLATE (optional) — if a project-workflow template still adds value
alongside the skill, promote flush.org into the rulesets project-workflow
templates and adjust intra-doc links (wrap-it-up.org, startup.org) to
template-relative paths. Otherwise the skill supersedes it.
5. NOTES ENTRY TEMPLATE — the work project's notes.org AVAILABLE WORKFLOWS got a
flush entry; mirror that into whatever template seeds AVAILABLE WORKFLOWS if
one exists.
Source: work project session 2026-06-02 (evening). Anchor:
work/.ai/session-context.org.
* Original flush.org Workflow Doc
The pre-clear checkpoint workflow as it existed in the work project, preserved as
the basis the =/flush= skill was built from.
** Summary
Mid-session context flush. Refresh the session-context anchor in place, then
=/clear=, then resume the same logical session from the anchor — cheaper tokens
and a sharper context window without fragmenting the session into many archive
files.
Distinct from wrap-it-up (which archives to =.ai/sessions/= and commits) and from
startup (which pulls rulesets + project, syncs templates, surfaces inbox +
reminders for a genuine fresh start). Flush does none of that — it keeps one
session alive across a =/clear= boundary.
** When to use
- Triggered by: "flush", "flush it", "let's flush", "flush the context".
- The current task has a clean boundary and the context window is large enough
that a reset would sharpen the work (the wrap/restart rhythm).
- You want to stay in the same logical session — same goal, same anchor file —
not start a new day or hand off.
Do NOT use for:
- End of day / done for now → wrap-it-up (archives + commits).
- Fresh start on another machine, or after being away → startup.
** How it works (two halves around /clear)
=/clear= wipes the conversation, so the workflow can't run straight through it.
It splits at the clear:
- Pre-clear (this agent): refresh the anchor + verify it landed, then hand the
=/clear= to the user. Claude cannot run =/clear= itself — it is a user-only
command.
- Post-clear (the SessionStart(clear) hook, =~/.claude/hooks/session-clear-resume.sh=):
the cleared session has no memory of the flush, so the hook injects "read the
anchor and resume" into the fresh context. After =/clear= the model loads that
instruction but waits for the user's next message before acting — one keystroke
is expected, not a bug.
** Execution
*** Phase 1 — Pre-clear checkpoint (this agent)
1. Dump everything not yet on disk. Before touching the anchor, make sure the
live working state is captured: decisions reached this turn, =file:line=
targets, the exact next action, any finding that would be expensive to
reconstruct. The whole point is that nothing is lost across the clear.
2. Resolve the anchor path.
#+begin_src bash
sc=$(.ai/scripts/session-context-path 2>/dev/null || echo .ai/session-context.org)
#+end_src
Create it with the skeletal structure (=#+TITLE=, =* Summary= with empty
subsections, =* Session Log=) if it doesn't exist yet.
3. Refresh the =* Summary= in place. Write/overwrite the subsections so the
anchor reflects current state:
- Active Goal — the overall goal of the session (one or two sentences).
- Decisions — what's been settled so far.
- Data Collected / Findings — load-bearing facts, with exact identifiers.
- Files Modified — what changed on disk this session.
- Next Steps — the immediate next action, specific enough to resume blind.
Do NOT archive and do NOT start a new file — refresh the existing one.
4. Append a flush marker to the =* Session Log=.
#+begin_src bash
date "+%Y-%m-%d %a @ %H:%M:%S %z"
#+end_src
Add =** <timestamp> — flushed= with a one-line note on what's in flight, so
the log stays a continuous narrative across clears.
5. Verify the write landed — gate before clearing. Re-read the anchor and
confirm the Active Goal and Next Steps are present and current. If the write
didn't land, STOP and fix it — do not tell the user to =/clear=. There is no
recovering the conversation after =/clear=.
6. Hand off the clear. Tell the user: the checkpoint is saved (name the anchor
path), type =/clear= now, then send any message to resume.
*** Phase 2 — Post-clear resume (SessionStart(clear) hook + fresh agent)
Driven by the hook, not this file — but documented here so the loop is legible:
1. The user types =/clear=. =~/.claude/hooks/session-clear-resume.sh= fires and
injects "read the anchor, say 'flushed.', resume" into the fresh context.
2. The user sends any message (e.g. "go", "resume").
3. The fresh agent reads the anchor, replies =flushed.= on its own line, restates
the Active Goal + immediate Next Step, and continues. It does NOT run startup
or re-sync anything — this is a resume, not a fresh start.
If the anchor is absent (a stray =/clear= with no prior flush), the hook instead
points the fresh session at startup.
** Notes
- The anchor persists across as many flushes as a day needs. Only wrap-it-up
archives it to =.ai/sessions/= and commits — that's the single end-of-session
boundary.
- The hook is global (=~/.claude/settings.json= → SessionStart matcher =clear=),
so it works in any project that has a session-context anchor.
- Promotion: this workflow + the hook are candidates for the rulesets templates
(the wrap/restart-rhythm task predicted this). Validate here, then file to the
rulesets inbox.
* Refinement — notes.org-before-anchor on resume (work handoff, 2026-06-02 21:06)
A follow-up handoff from work, implemented the same evening. On a flush resume,
read notes.org key sections BEFORE the session-context anchor.
Motivating failure (work project, 2026-06-02): right after a flush resume, the
agent went to start a dashboard chore and concluded the dashboard repo wasn't
cloned — hunting =~/code= with shallow finds — when notes.org's code-locations
section documented the exact path. The resume had the anchor but not notes.org,
so it lacked the standing context and floundered. The anchor carries
session-specific state; notes.org carries the project's standing knowledge
(code-repo paths, conventions, key contacts) a resumed session needs to act
correctly.
Changes landed:
- =hooks/session-clear-resume.sh= — anchor-present branch now injects "read
.ai/notes.org key sections (Project-Specific Context, Active Reminders,
Pending Decisions; skip About This File), then the anchor." Runtime-guarded on
notes.org presence: absent → resume from the anchor alone.
- =flush/SKILL.md= — Phase 2 (post-clear resume) documents the same read order
so the skill text and the hook agree.
A small ordering/scope addition, not a redesign.
|
