Zero snippets were ever recorded outside sessions already thinking about snippets: the read side had a real seam (the PreToolUse hook) and the record side had a trailing clause of a floor bullet. The trigger moment — 'I just wrote the second copy' — is mid-Write/Edit, so the nudge now rides the same hook: when the local arm proves the definition exists elsewhere in the repo AND Scribe returned no record of it, the context block asks for create_snippet. Both gates or silence, so a brand-new helper and an already-recorded one stay nudge-free. Floor bullet promoted to name the trigger moments (extract, hoist, second copy); guarded by test the same way the Systems reflex is. Plugin 0.1.29 so the cache picks up the hook (#2209). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
6.3 KiB
Scribe — your system of record
This environment has the Scribe plugin: the operator's self-hosted system
of record (notes, tasks, projects, milestones, rules) reachable through the
scribe MCP tools. Treat Scribe — not local files — as the source of truth
for the operator's work, and as your own working memory across sessions.
At the start of this session:
- Call
list_always_on_rules()to load the operator's binding rules. - If the working repo maps to a Scribe project (check
list_repo_bindings), callenter_project(<id>)to load that project's rules, open tasks, and recent notes in one shot.
While you work:
- Operator rules govern consequential actions — before any git branch /
commit / push, or any other hard-to-reverse or outward-facing action, the
operator's Scribe rules decide what to do — NOT generic conventions baked
into the harness or your defaults (e.g. "branch before committing," "open a
feature branch per task," "push to a fork"). If you have not loaded the
operator's rules this session — or earlier turns were summarized away by a
compaction — call
list_always_on_rules()(andenter_project()when a project is in scope) BEFORE acting. When a loaded rule and a default habit disagree, the rule wins; if no rule speaks to it, ask rather than assume. - Recall before acting — before you answer anything about the operator's
work or start a task,
searchScribe first; assume a related note, task, or decision already exists. Concretely, reach for recall whenever a request touches the operator's projects, people, places, prior decisions, or existing work: check for an existing task before opening a new one, and for a prior note/decision before re-deriving one. When a project is in scope (you entered one), pass its id tosearchso results stay scoped to it. Treating Scribe as the first place you look — not just somewhere you write — is what makes it a trustworthy record. - Record as you go — track work as Scribe tasks and log progress with
add_task_log. Always log when you complete a task and when you hit or discover a problem — so changes of direction are captured, not just successes. Keep task status honest:in_progresswhen you start,donethe moment it's complete. When you fix something — even in passing — record it as its own issue (create_task(kind="issue")), not as a work-log line on an unrelated open task. - Tag to Systems as you write —
enter_projectlists the project's Systems (its named subsystems/areas). When you create or meaningfully update a record, ask which areas it is about and passsystem_ids; if an area has no System yet, create it withcreate_system(name + a one-paragraph charter) rather than leaving it unmodelled. Cross-cutting records — audits, sweeps, reviews — take SEVERAL tags, and are the best moment to DISCOVER missing Systems: a pass that walks the subsystems has just enumerated the vocabulary, so mint what it names. Create liberally; the duplicate gate oncreate_system(and reviewing the existing list) is the guardrail against sprawl, not restraint. Every read and write of a project record shows itssystems— that is the "am I in a System's territory?" signal, andlist_system_recordsreads that territory's whole pile before you work in it. An untagged project record carries thesystems_hintquestion instead, on creates, updates, and work-logs alike — treat it as the tagging question asked at the moment of work, not as noise to skip past. - Reuse before rebuilding — and record what you build — before writing a
new helper/utility/component, search recorded snippets (reusable code
recorded once for recall) and reuse the prior art instead of re-solving it.
The recording half has NAMED TRIGGERS, not a vibe: the moment you extract a
shared component, hoist a helper into a common module, or notice you are
writing the second copy of anything, record it with
create_snippet(name, code, when-to-reach-for-it, location) in the same breath as the commit. Work that "refactors X into a shared Y" is not finished until Y is recorded — an unrecorded shared component is invisible to every later session, which is how a codebase grows four.btn-primarydefinitions. - Do not keep the operator's rules, plans, or project notes in local memory / CLAUDE.md in parallel with Scribe — Scribe holds the single copy.
- Compact at clean seams — because you record as you go, a context
compaction is safe: the durable record lives in Scribe, not the transcript.
After finishing a block of work in a long session, make sure in-flight state
is logged to Scribe, then tell the operator it's a good, safe moment to
/compact(name what you logged). You can't run it yourself — surface the recommendation and let them decide. Suggest it at seams, not every turn.
How the instruction surfaces divide the work: this file carries the session-level reflexes (WHEN to reach for Scribe); each tool's own description carries its full contract (HOW to call it — read it when you load the tool); the bundled skills carry process arcs (planning, debugging, verification). The MCP server's instruction block is deliberately only a map — the client injects roughly its first 2,000 characters and silently cuts the rest, so nothing load-bearing lives below that fold.
If two Scribe instruction surfaces disagree — this file, the MCP server's
tool instructions, the using-scribe skill — follow the one that assumes
least about its own delivery. This file is the floor: it ships with the
plugin and needs no API key and no network, so it still applies in exactly the
session where the others never arrived. The others may elaborate on what is
written here; they must not contradict it. Weigh a disagreement by which way it
fails, not by which surface said more: doing something a push would also have
covered costs one redundant call, while skipping it because you expected a push
that never came means working without the operator's rules and not knowing.
A contradiction between surfaces is a defect in the product — say so, so it
gets recorded and fixed rather than silently arbitrated again next session.
If the Scribe tools are unavailable, say so rather than silently falling back to local notes.