bvandeusen
ffd08507f1
CI & Build / Python lint (push) Successful in 3s
CI & Build / Plugin hooks (push) Successful in 9s
CI & Build / integration (push) Successful in 15s
CI & Build / TypeScript typecheck (push) Successful in 33s
CI & Build / Python tests (push) Successful in 47s
CI & Build / Build & push image (push) Successful in 29s
_INSTRUCTIONS told an agent the SessionStart hook was how rules reach a session, and used that as the argument against a host-memory pointer. The using-scribe skill said the opposite — pull them yourself, treat any push as a bonus. Nothing said which wins, and #119 makes these surfaces the specification, so this was the product behaving two ways. #2198 is the case that settles it: every plugin hook was silently inert for an extended period. An agent trusting the push would have run with no binding rules and no signal, while those rules govern branch, commit and push. So: _INSTRUCTIONS now leads with the explicit pull and names the hook as a delivery optimisation. The argument against a host-memory pointer survives — it never needed the hook to be reliable, because the pull IS the bridge and it is written into every surface a session already loads. The static context gains the tiebreaker for the next disagreement: follow the surface that assumes least about its own delivery. "Most detailed wins" is wrong precisely because the most detailed surface is the one with a delivery precondition. It goes there by its own logic — a tiebreaker arriving over MCP cannot arbitrate what to do when MCP is absent. Guarded by tests/test_instruction_surfaces_agree.py: every session-start surface states the pull, and no surface names the push without it. Plugin version bumped so the cache that executes actually picks the file up (#2209). Refs #2497
68 lines
4.3 KiB
Markdown
68 lines
4.3 KiB
Markdown
# 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`),
|
|
call `enter_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()` (and `enter_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, `search` Scribe 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 to `search` so 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_progress` when you start, `done` the
|
|
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.
|
|
- **Reuse before rebuilding** — 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; when you build something
|
|
reusable, record it with `create_snippet` (name, code, when-to-reach-for-it,
|
|
location) so a later session is offered it, not left to write it again.
|
|
- 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.
|
|
|
|
**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.
|