From 95e1d47cebaa69d6b794f7184830d088cf40c953 Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Sat, 13 Jun 2026 15:57:22 -0400 Subject: [PATCH] ref(mcp): neutralize dev-shaped vocabulary in _INSTRUCTIONS + add write-mandate (B9/A4) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The MCP instructions are domain-neutral except a thin layer of dev vocabulary and one project-specific paragraph (B10 audit, task 812). Make the data store's own instructions serve any domain, and add the missing positive write-mandate. B9 (neutralize): - 'before writing code' -> 'before you dive in' - Note examples 'dev-logs' -> 'logs of what happened' - record trigger 'a merge, a shipped feature, a finished plan' + 'dev-log note' -> 'finishing a task, or hitting/discovering a problem that changes direction' (folds in B8: log pivots, not just wins; mirrors the static-tier wording) - recall examples 'ticket/dev-log' -> 'task/prior note' (server + SKILL.md) - 'Engineering and workflow rules' -> 'Workflow and standards rules' - slim the 'developing Scribe itself' ACL paragraph to a neutral one-liner (project-specific specifics already live in rules #47/#78) A4 (write-mandate): state up front that Scribe is the system of record — record work here, recall before acting, don't keep project work in local files. Refs plan 812 (B9, A4, B8-trigger); B10 audit work-log. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugin/skills/using-scribe/SKILL.md | 2 +- src/scribe/mcp/server.py | 34 +++++++++++++++-------------- 2 files changed, 19 insertions(+), 17 deletions(-) diff --git a/plugin/skills/using-scribe/SKILL.md b/plugin/skills/using-scribe/SKILL.md index 1525626..fccccfb 100644 --- a/plugin/skills/using-scribe/SKILL.md +++ b/plugin/skills/using-scribe/SKILL.md @@ -51,7 +51,7 @@ Two constraints on *how* that's achieved: 1. **Recall before acting.** Before answering a question about the operator's work, or starting a task, `search` Scribe (and `list_tasks` / `list_notes`) - for prior art — an existing ticket, decision, or dev-log — instead of + for related prior work — an existing task, decision, or note — instead of re-deriving it or opening a duplicate. When a project is in scope, pass its `project_id` so results stay scoped. diff --git a/src/scribe/mcp/server.py b/src/scribe/mcp/server.py index de6b7b8..c67756d 100644 --- a/src/scribe/mcp/server.py +++ b/src/scribe/mcp/server.py @@ -7,7 +7,10 @@ from quart import Quart _INSTRUCTIONS = """ Scribe is the user's self-hosted second-brain and project-management data -store. You (Claude) are the assistant. +store, and your own system of record for their work. You (Claude) are the +assistant: record what you do here — tasks, work-logs, decisions, notes — and +recall from here before acting. Do not keep the user's project work in local +files (CLAUDE.md, scratch/auto memory) in parallel; Scribe holds the single copy. Hierarchy: Project -> Milestone -> Task/Note. @@ -21,8 +24,9 @@ What each part is for, and when to reach for it: time with work-logs (add_task_log) rather than rewriting the body. - Plan: a task with kind=plan — HOW you'll execute a chunk of work. The body holds the design + step checklist; work-logs record progress. Start one with - start_planning when beginning non-trivial work, before writing code. -- Note: durable free-form knowledge — reference material, decisions, dev-logs. + start_planning when beginning non-trivial work, before you dive in. +- Note: durable free-form knowledge — reference material, decisions, logs of + what happened. No lifecycle, not actionable. Reach for one to CAPTURE something worth keeping. - Typed entities (person/place/list): structured records about people, places, and checklists. @@ -43,11 +47,11 @@ Reach for Scribe to RECALL, not just to record. Scribe is a second brain — its value is mostly in what it already holds, so make searching it a reflex, not something you wait to be asked for: - Before you answer a question about the user's work, or start a task, search - Scribe first (search / list_tasks / list_notes). Assume relevant prior art - already exists — a related ticket, an earlier decision, a dev-log — and look + Scribe first (search / list_tasks / list_notes). Assume relevant prior work + already exists — a related task, an earlier decision, a prior note — and look before you re-derive it or open a duplicate. - Before creating a task, search for an existing one (search content_type= - 'task') — don't open a second ticket for work already tracked. + 'task') — don't open a second task for work already tracked. - Scope to the project in scope. When a project is active (you called enter_project), pass its project_id to search / list_tasks / list_notes so results stay inside that project. Querying with no project_id pulls in every @@ -69,9 +73,10 @@ Keep task state honest — this is what makes the project a trustworthy record: - The moment a task's work is complete, set it done. Never leave finished work at todo/in_progress — an out-of-date status makes Scribe misrepresent what's left to do. -- At a significant landing (a merge, a shipped feature, a finished plan), write - a short dated dev-log note on the project (create_note) summarizing what - landed, and mark the plan/task done. +- At a meaningful point — finishing a task, or hitting or discovering a problem + that changes direction — write a short dated note on the project (create_note) + capturing what happened (the pivots, not just the wins), and set the finished + task to done. Scribe maintains a Rulebook system (Rulebook -> Topic -> Rule). Rules carry an actionable statement plus optional Why and How-to-apply context. At the @@ -81,7 +86,7 @@ in scope, get_project(id) returns applicable_rules (rules from rulebooks the project subscribes to) and subscribed_rulebooks; consult those too. Full text (Why / How-to-apply) is available via get_rule(id). -Engineering and workflow rules live in Scribe. When you notice a pattern +Workflow and standards rules live in Scribe. When you notice a pattern worth codifying, call create_rule (cross-project, lands in a rulebook+topic) or create_project_rule (one project only, no rulebook ceremony). Do NOT add new engineering rules to CLAUDE.md or to ~/.claude/.../memory/feedback_*.md @@ -162,12 +167,9 @@ get_process(name) and follow the returned prompt verbatim, including any "clarify first" steps it contains. Author a new one with create_process(title, body); edit with update_process. -When you are developing Scribe itself (not just using it as a data store), -honor the multi-user sharing ACL: every read or mutation of user data must -scope by owner + direct shares + group shares through services/access.py -(can_read_* / can_write_* / can_admin_*) — never assume a single operator. An -unscoped query (a fetch-by-id with no ownership check) is a cross-user data -leak; "works for one user" is not done. +When developing Scribe itself, honor its multi-user sharing ACL: scope every +read and mutation of user data by owner + shares — never assume a single +operator. (This instance's rules carry the specifics.) """