bvandeusenandClaude Opus 5.5
f1fbdf746a
CI & Build / Python lint (push) Successful in 5s
CI & Build / Plugin hooks (push) Successful in 18s
CI & Build / TypeScript typecheck (push) Successful in 54s
CI & Build / integration (push) Successful in 52s
CI & Build / Python tests (push) Successful in 1m38s
CI & Build / Build & push image (push) Successful in 33s
Recording used to be decided by machinery — the only "record it" prompt fired when a same-named copy already existed (#2664), so a first instance of a reusable piece was never asked about, and judgment arrived only through audits. Now the question is asked where the knowledge is: the end of the turn that wrote the code, of the agent that wrote it. - Write hooks keep `<sid>.written.ids` (path, kind, name) for every definition a write names; a new file adds a `file` line for its stem — a candidate in any language without a framework rule (scribe_written_append). - Stop hook scribe_shape_check.sh sends the ledger to GET /api/plugin/shape-check and blocks once, in the server's words, when anything is unjudged. Same discipline as the report check: never twice, never without a recorded check, another hook's loop left alone; the ledger is kept when the instance cannot be reached. - shape_ledger.unjudged_shapes: no row, unclassified, scoped and hook stamps are unjudged; an agent/audit/import verdict is not. A snippet recorded at the shape answers for it until the refresh stamps it canonical. - services/shape_check owns the reason text and records every outcome in app_logs (passed / blocked / judged_after_block / left_after_block). - classify_shapes(repo=…) judges a shape the ledger has not synced yet via a provisional row under a bound repo; the sync confirms it, or vanishes and revives it with the verdict intact. An unbound repo is refused. Plugin version minted. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
6.5 KiB
6.5 KiB
Packaging Scribe for an agent client
This is the maintainer contract for shipping Scribe into an agent client: what every client package shares, what each one adds, and where a new client's files go. It follows from decision #4027 (milestone 410): the server orients, the skills hold the depth, and a client adapter only times delivery and says what that one client needs said.
Claude Code is the only client built today. The layout below is kept so adding another one means adding files, not moving or rewriting any.
Shared by every client package
| Piece | Where | What it is |
|---|---|---|
| The skills | plugin/skills/*/SKILL.md |
Agent Skills (the open SKILL.md format). They state every Scribe reflex in full and name no client. tests/test_guidance_ownership.py fails if a skill names a particular client, or references anything outside its own folder. Every client package ships this folder verbatim. |
| The MCP server | <base URL>/mcp |
HTTP, Authorization: Bearer <fmcp_ key>. Its _INSTRUCTIONS is a client-neutral orientation — the workflow across tools (≤1,600 chars, #4389); each tool's description carries its contract; in-band responses (placement, report_back, systems_hint, the duplicate gate, the guessed-id refusal) fire in every client. |
| The adapter API | <base URL>/api/plugin/* |
Plain GET endpoints any client's hooks can call with the same key (read scope is enough): context (live session state), retrieve (rules, preferences and notes for a message), prior-art (records and shape-ledger hints for code being written), tool-rules (rules for a command about to run), report-check (records a completion-report check and returns the reason for a block), processes (stored Processes to expose as skills). |
| The API key | Scribe → Settings → API Keys | One fmcp_ key per install. Read scope for hooks; write scope for the MCP tools. |
Added by each client
| Piece | What it holds | Rule of thumb |
|---|---|---|
| A manifest | Name, version, how to reach the MCP server with the key, where the skills and hooks are | Only that client's format. |
| Hooks | Scripts in that client's hook format that call the adapter API at the right moment and print what comes back | Timing and transport only. A hook may print status lines (unconfigured, unreachable, running version) and pointers; guidance text comes from the server or the adapter's own static text. |
| Commands | That client's command wrappers, e.g. a process sync | Optional. |
| Adapter static text | What only that client needs said: its local memory files, its compaction command, its commands | Never a copy of a skill or of _INSTRUCTIONS. The loss guard and ownership registry in tests/test_guidance_ownership.py cover it. |
The worked example: Claude Code
| File | Role |
|---|---|
.claude-plugin/plugin.json |
Manifest: mcpServers.scribe (HTTP, Authorization: Bearer ${user_config.api_token}), userConfig for the base URL and key, version (minted, never hand-edited; see README). |
../.claude-plugin/marketplace.json (repo root) |
The marketplace entry pointing at ./plugin. |
hooks/hooks.json |
Wires the scripts to Claude Code events. |
hooks/scribe_session_context.sh |
SessionStart: adapter static text + running version + GET /api/plugin/context; a reload banner after compaction. |
hooks/scribe_autoinject.sh |
UserPromptSubmit: GET /api/plugin/retrieve for the message. |
hooks/scribe_prior_art.sh |
PreToolUse on editor writes: GET /api/plugin/prior-art. |
hooks/scribe_after_write.sh |
PostToolUse on shell commands: the same check for code written through the shell. |
hooks/scribe_tool_rules.sh |
PreToolUse on shell commands: GET /api/plugin/tool-rules. |
hooks/scribe_report_check.sh |
Stop: when the turn closed a task, checks the reply for the completion sections and reports to GET /api/plugin/report-check; blocks once, with the reason the server returns. |
hooks/scribe_shape_check.sh |
Stop: sends the definitions the turn wrote (the write hooks' <sid>.written.ids ledger) to GET /api/plugin/shape-check; blocks once, with the reason the server returns, so the agent judges what it built. |
hooks/scribe_sync_processes.sh + commands/sync.md |
GET /api/plugin/processes → ~/.claude/skills/scribe-proc-* stubs; /scribe:sync on demand. |
hooks/scribe_defs.sh |
Shared shell helpers: config, dedup ledgers, outage line. |
hooks/scribe_static_context.md |
The adapter static text. |
Hook config arrives as CLAUDE_PLUGIN_OPTION_API_ENDPOINT / CLAUDE_PLUGIN_OPTION_API_TOKEN (uppercased by Claude Code, #2198), with SCRIBE_URL / SCRIBE_TOKEN as an override.
How other clients would map
Researched, not tested (spike #4023, September 2026). Re-check each client's current docs before building.
- Agent Plugins 1.0 (Codex, Cursor, GitHub Copilot / VS Code, Kiro, ChatGPT): a root
plugin.json, askills/folder, and anmcp.json. That is the sameplugin/skills/plus two small files. Hooks, commands and rules are not part of v1; each client adds its own under a reverse-domain directory (e.g.com.<client>/) that other clients ignore. - Gemini CLI:
gemini-extension.jsonconfiguring the MCP server, a context file, and bundled skills. - Client-native formats also exist (
.codex-plugin/,.cursor-plugin/) where a client wants more than the shared standard carries. - Claude Code does not read Agent Plugins: only
.claude-plugin/plugin.json.
Open questions for whoever builds the second package
- Passing the key to the MCP server. Claude Code substitutes
${user_config.api_token}into the header. Agent Plugins'mcp.jsonand Gemini's extension config have their own variable and secret handling. Decide per client, and keep the key out of files that get committed. - Coexistence in one folder. Whether a root
plugin.json(Agent Plugins) beside.claude-plugin/plugin.jsonchanges how Claude Code loads the plugin is untested. Test it before shipping both fromplugin/, or give the second client its own package directory that reusesplugin/skills/. - Hook parity. Other clients' hook events differ and are partly implemented. Map each Scribe hook to the nearest event, and where none exists, leave that timing to the in-band server responses rather than writing a copy of the guidance.
- Process skills. The Claude Code sync writes
~/.claude/skills. Another client needs its own skills location, or the MCP skills extension (SEP-2640) once a client supports it.