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.claude/skills/forge-scribe/SKILL.md
GitHubForge 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
impact R-n --run <id>→ proposed wp_ids. 2. Confirm withlink. 3. Amend a not-started package, or re-create a completed one as a newagent_work_package_createdwithsupersedesandreq_ids:["R-n"].- 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.