feat(410): the skills own the full reflexes, in words any client can read (#4029)
CI & Build / Python lint (push) Successful in 3s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / integration (push) Successful in 53s
CI & Build / TypeScript typecheck (push) Successful in 55s
CI & Build / Python tests (push) Successful in 1m34s
CI & Build / Build & push image (push) Successful in 16s

Step 2 of milestone 410 "One owner per piece of guidance". Skills are the
part of every client package shared verbatim (Agent Skills, decision #4027),
so they state each reflex in full and name no particular client.

using-scribe gains what only the static session context said:
- a retrieved rule outranks a default habit; ask when no rule speaks to it
- log on completing a task and on hitting a problem, not only successes
- the systems_hint on an untagged record is the tagging question, answered
  at the moment of work

Client-specific text leaves the skills, rewritten as the universal idea:
- using-scribe: "keep one copy" no longer names CLAUDE.md, MEMORY.md, native
  auto-memory or autoMemoryEnabled; "this plugin" becomes Scribe
- reusing-code / shape-accounting: Write/Edit and Bash become editor tools
  and shell edits; the prior-art "hook" becomes the prior-art hint; a plugin
  version number is dropped

tests/test_guidance_ownership.py:
- test_the_skills_name_no_particular_client fails on any Claude Code path,
  memory file, slash command, hook event or tool name in a skill, each
  marker commented with why it is client-specific; a companion test shows
  it can fail
- three registry topics for what using-scribe now owns; the loss guard
  stays green

Plugin version minted.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-09-14 11:50:30 -04:00
co-authored by Claude Opus 5
parent f3036f0cd7
commit 0a29252f9b
5 changed files with 95 additions and 29 deletions
+31 -20
View File
@@ -31,28 +31,25 @@ Do this actively. Nothing is handed to a session up front to stand in for it —
rules arrive by retrieval, when your work or the operator's message matches
one — so asking and entering the project are the reliable path.
## Scribe holds these functions — don't keep a second copy
## Scribe holds these functions — keep one copy
This plugin makes Scribe the home for the operator's **rules, recall, and
planning** — the jobs Claude's native auto-memory would otherwise do. When the
plugin is present, route those jobs to Scribe and **do not also write them to
native memory**: codify rules with `create_rule` / `create_project_rule`,
capture durable knowledge as Scribe notes, and keep plans in Scribe milestones
(via `start_planning`) — not in `MEMORY.md` or `CLAUDE.md`. One copy, in Scribe; let any existing local
memory shrink as Scribe takes over. Don't maintain both stores in parallel.
Scribe is the home for the operator's **rules, recall, and planning** — the
jobs your client's own local memory files would otherwise do. Route those jobs
to Scribe instead of also writing them locally: codify rules with
`create_rule` / `create_project_rule`, capture durable knowledge as Scribe
notes, and keep plans in Scribe milestones (via `start_planning`). One copy, in
Scribe; let any existing local memory shrink as Scribe takes over.
Two constraints on *how* that's achieved:
- **Steer behavior; never flip a native switch.** The plugin must work with
native auto-memory at its default (ON). Never tell the operator to set
`autoMemoryEnabled:false` or otherwise disable a built-in function to make
Scribe "win" — a setting the operator may not know was changed (and wouldn't
know to restore) is exactly the hidden breakage to avoid. You replace memory's
functions by *doing the work in Scribe*, not by turning memory off.
- **A Scribe-shaped hole is acceptable.** If the plugin is later removed, the
operator recovers context over time — that's fine. You do **not** need to keep
native memory as a self-sufficient fallback. The only thing to avoid is
breakage caused by a settings change the operator didn't make knowingly.
- **Steer behaviour; leave the client's own settings as they are.** Scribe works
alongside a client's built-in memory at its defaults. You replace memory's
functions by *doing the work in Scribe*, so there is no reason to ask the
operator to switch a built-in feature off — a setting they didn't knowingly
change is breakage they won't know to restore.
- **A Scribe-shaped hole is acceptable.** If Scribe is later removed, the
operator recovers context over time — that's fine. Local memory doesn't need
to be kept as a self-sufficient fallback.
## The reflex
@@ -98,6 +95,13 @@ Two constraints on *how* that's achieved:
session it has nothing to do with — but retrieval only fires if something
asks.
**A retrieved rule outranks a default habit.** Before a hard-to-reverse or
outward-facing act — changing shared state, publishing, deleting, sending
something outside the session — the operator's rules decide what to do, not
the generic conventions your client or your training suggest. When a rule
and a habit disagree, the rule wins; when no rule speaks to it, ask rather
than assume.
**Ask hardest where you feel most certain.** Rules about which TOOL to reach
for — use the forge's MCP client rather than curling its API, don't stand up
a local stack, don't run the suite CI owns — govern moves that feel like
@@ -118,7 +122,9 @@ Two constraints on *how* that's achieved:
plans/specs to local `.md` files. See the **writing-plans** skill.
5. **Keep state honest.** Set a task `in_progress` when you start it, `done` the
moment it's complete; log progress as you go.
moment it's complete; log progress as you go. Always log when you
**complete** a task and when you **hit or discover a problem**, so a change
of direction is on the record and not only the successes.
6. **Fixes are issues, not work-logs.** When you fix a problem — even one solved
in passing — record it as its own issue (`create_task(kind="issue")`) with
@@ -141,6 +147,11 @@ Two constraints on *how* that's achieved:
not restraint. Only a record genuinely about no particular area goes
untagged.
Every read and write of a project record shows its `systems`. An untagged
one carries a `systems_hint` question instead — on creates, updates and
work-logs alike. Treat it as the tagging question asked at the moment of
work: tag the record, create the missing System, or deliberately leave it.
8. **Name the record, never just its number.** Whenever you refer to a Scribe
record — in a message to the operator, a commit message, a task body, a
work-log — write the id *and* its title: `#3244 "the staleness signal"`,
@@ -307,6 +318,6 @@ nothing will tell you it drifted.
## Other Scribe process-skills
This plugin also ships focused process-skills — writing-plans, reporting-back,
Scribe also ships focused process-skills — writing-plans, reporting-back,
systematic debugging, verification, and brainstorming. Reach for the matching one when its
situation arises, the same way you reach for this skill.