forge-scribe

Owner-wish ledger: every ask kept verbatim until done+acked. Use for: onthoud dit, wat wilde ik ook alweer, ik heb nog een wijziging, note my change, scrap that, open wishes, did I ask that.

SKILL.md

GitHub

Forge Scribe — never lose what the owner asked

Self-improvement substrate: before applying this skill, read learnings.md in this skill's own folder and honor its corrections. After a run that produced a genuine correction, append it there with a date and real evidence — never invent a lesson.

Every owner prompt is kept word-for-word (secrets scrubbed) and becomes a tracked item R-n that stays visible until it is planned, done with evidence and acked by the owner. The only way to change scribe state is node .claude/forge-bin/forge-scribe.cjs. Never edit the files under .claude/forge-scribe/ by hand.

When to use

  • The owner sends a new wish, change, cancel or preference mid-project ("onthoud dit", "ik heb nog een wijziging", "note my change", "scrap that", "voortaan…").
  • The owner asks what they asked before ("wat wilde ik ook alweer", "open wensen", "did you miss anything I asked").
  • End-of-run reconciliation (before finalize) and on resume of a long project.

Not for: storing a standing rule directly (that is /forge remember), writing a PRD (forge-prd), or taking meeting minutes of a document.

Context rule

Only DIGEST.md (<= 1200 chars) goes back into context. Never paste inbox.jsonl or ledger.jsonl.

Wiring (hooks, rule, finalize)

The hook prints [forge-scribe] Genoteerd: R-n … per captured prompt (the digest only when it changed); act on it. A Stop reminder blocks once per unplanned item; before completion log owner_requests_reconciled (the writer refuses it unless gate is OK) — see config/orchestration/HOOKS_OPT_IN.md section 7.

Lifecycle

unclassified -> open -> planned -> in-progress -> done (evidence) -> acked (owner); side states: defer-proposed (an agent's defer, with reason; NOT final until the owner acks it, then deferred = a recorded carry-over), cancelled (owner), superseded, answered.

Step Command (node .claude/forge-bin/forge-scribe.cjs ...)
capture (automatic: the UserPromptSubmit hook forge-scribe-hook.cjs; by hand only for a missed prompt) capture --text "<prompt>" --source cli --transcript <path>
settle an unclassified item classify R-n change (split a multi-ask: --split "<exact quote>" per ask)
mid-run change: which packages? impact R-n --run <run_id> (read-only proposal)
plan it link R-n --wp wp-3,wp-5 --run <run_id>
start / done transition R-n start · transition R-n done --evidence wp_completed:wp-3 --run <run_id>
propose a carry-over (becomes defer-proposed; needs the owner's ack) transition R-n defer --reason "<why>"
question answered transition R-n answer --reason "<where>"
owner ack / cancel transition R-n ack --prompt P-n (--pid is kept as an alias). P-n must be a hook-captured owner prompt with a clear yes for that exact R-id in the same sentence; no other wording counts as owner approval
status list --status open,planned --json · digest --write
gate gate (run) · gate --final (programme end: also done-but-unacked) — exit 3 = blocked

Evidence types: wp_completed:<wp_id> (linked wp, real event in the run), check_passed:<event_id>, commit:<sha>, standing_rule:<rule id> (preference items only).

Preferences

A preference item ("voortaan…", "always…") is NOT stored as a rule by the scribe. Run forge-scribe.cjs route R-n, ask the owner to confirm, then forge-standing.cjs remember "<text>" (the existing /forge remember path) and close with done --evidence standing_rule:<id>.

Mid-run change protocol

  1. impact R-n --run <id> → proposed wp_ids. 2. Confirm with link. 3. Amend a not-started package, or re-create a completed one as a new agent_work_package_created with supersedes and req_ids:["R-n"].
  2. Head Chef triages only that delta.

Acks are batched

At the end of a run present ONE list of done-unacked items to the owner (batch-the-asks rule). Never pause mid-run per item. Ack/cancel are refused unless the prompt is a real owner message in the session transcript — a classifier, not a proof.

When to dispatch the Scribe agent (sonnet/low, GOAT quick route)

The scribe specialist (.claude/agents/scribe.md, exec-reviewer class, no Write/Edit) is dispatched by the Lead only for a prompt flagged multi_ask (3+ asks), end-of-run reconciliation, or a resume with

= 20 open items. The normal path costs no LLM call: the Lead runs the CLI directly.

Honesty

Never report an item as planned, done or acked unless forge-scribe.cjs output says so; quote the literal gate exit code.