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
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:
@@ -47,8 +47,8 @@ through recall/auto-inject; this skill is the active reflex around that.
|
||||
- **A `Shape ledger at …` line is the ledger speaking, not the record.** It
|
||||
names a duplicate family ("identical body in N other files, no canon"), a
|
||||
repeated name ("defined in N other files") or a canon elsewhere for a name
|
||||
you just wrote — for edits made through Bash
|
||||
(sed, heredocs, scripts) as much as through Write/Edit. Derive the family or
|
||||
you just wrote — for edits made through a shell
|
||||
(sed, heredocs, scripts) as much as through your editor tools. Derive the family or
|
||||
reuse the canon *now*; a family that is convention rather than copies is
|
||||
dismissed with `classify_shapes(..., status="exempt",
|
||||
reason_code="convention-plumbing")`, never ignored.
|
||||
|
||||
@@ -47,12 +47,12 @@ need a hand judgment:
|
||||
- **The sync** stamps a snippet's own reference location `canonical`
|
||||
(`classified_by: mechanical`).
|
||||
- **The write path** stamps instances as you work: when you `get_snippet` a
|
||||
canon and then Write/Edit code that references or resembles it, the
|
||||
canon and then write code that references or resembles it, the
|
||||
definitions being written land as `instance` rows (`classified_by: hook`,
|
||||
the evidence in `reason`), and the prior-art hook tells you what landed
|
||||
the evidence in `reason`), and the prior-art hint tells you what landed
|
||||
("Shape accounting: recorded at … → instance of #N"). Offered-but-unopened
|
||||
snippets stamp nothing — so *pull the canon you are instantiating*; that
|
||||
pull is what turns your reuse into accounting. A hook row is evidence, not
|
||||
pull is what turns your reuse into accounting. A `hook` row is evidence, not
|
||||
judgment: it never overrides a classification you made, and a
|
||||
`classify_shapes` call overrides it.
|
||||
|
||||
@@ -91,8 +91,8 @@ The catalogue exists so the codebase is DRY **from inception**, not as DRY as
|
||||
the last sweep left it. Three surfaces say so without anyone running an audit
|
||||
(milestone 299):
|
||||
|
||||
- **At the write** — the prior-art hint (the Write/Edit hook, and since
|
||||
0.1.39 the after-write hook on Bash, so sed/heredoc/script edits count too)
|
||||
- **At the write** — the prior-art hint (delivered beside a write where your
|
||||
client supports it; shell edits count as much as editor writes)
|
||||
carries a `Shape ledger at <path>` line when a name just written is a known
|
||||
**duplicate family** ("identical body in N other files, no canon"), a
|
||||
**repeated name** ("defined in N other files, no canon") or a
|
||||
@@ -144,7 +144,7 @@ Three questions the ledger answers mechanically (#2793):
|
||||
proposer did not match to that canon. `diverges_from` names the canon.
|
||||
Judge it: `instance` if it should be built from the canon (and rebuild
|
||||
it), `variant` with the why if the departure is deliberate. The write-path
|
||||
hook asks the same question in-band the moment such a shape is written.
|
||||
hint asks the same question in-band the moment such a shape is written.
|
||||
- **History** — `shape_history(project_id, path, symbol?)`: the current rows
|
||||
plus every `classified` / `vanished` / `reappeared` / `drifted` event with
|
||||
its commit — "instance of #N from <date>, re-judged variant of #M because
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user