diff options
| -rw-r--r-- | docs/design/2026-06-02-flush-promotion.org | 209 |
1 files changed, 209 insertions, 0 deletions
diff --git a/docs/design/2026-06-02-flush-promotion.org b/docs/design/2026-06-02-flush-promotion.org new file mode 100644 index 0000000..d34ad89 --- /dev/null +++ b/docs/design/2026-06-02-flush-promotion.org @@ -0,0 +1,209 @@ +#+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. |