toolcraft git:20260915.df30567A

Immutable. This exact content is served forever at /api/v1/blob/6587bf072243a87a.

---
name: toolcraft
description: Doctrine (kernel §3.8) — when an operation will recur across independent sessions, the unit of work is a durable, tested, cataloged tool, not a throwaway script. Defines what counts as a durable tool, what stays disposable, the procedure sibling (a project skill), and the fail-closed rule that a task is incomplete until a durable tool is cataloged or recorded absent. AUTHORING a tool is agent.tool-smith; CATALOGING one happens inside the single canonize close-out spawn. This node is the rule both of them answer to, and every session reads it.
id: skill.toolcraft
tier: 2
kind: skill
origin: seed
title: toolcraft — the doctrine of durable, tested, cataloged tools versus throwaway scripts
owns:
  - rule.toolcraft
  - toolcraft.durability-criteria
requires:
peers:
  - agent.tool-smith
  - protocol.canonize
  - protocol.grill
  - protocol.harvest
  - method.engineering-posture
artifacts:
  - templates/skill.template.md
  - templates/agent.template.md
  - templates/prompts/handback-payload.md
load_when:
  - "should this script be kept, is this a durable tool"
  - "recurring operation across sessions"
  - "catalog a tool, tools_built, skills_built"
  - "throwaway prototype versus reusable tooling"
  - "crystallize a repeated procedure into a project skill"
prevents: A roster with an author for durable tools and no standard for them — nothing saying what earns durability, so every judgement about whether to build one is made fresh and no two sessions draw the line in the same place.
est_tokens: 1240
---

# toolcraft — the durable-tool doctrine

This node owns **the toolcraft rule** (kernel §3.8) — durable tools compound;
throwaway scripts are rework. When an operation will recur across independent
sessions, the unit of work is a **durable, tested tool** with a stable
interface — designed so at plan time, named in `tools_built` on every handback,
and cataloged in `docs/graph/tools/` by the librarian inside the close-out
spawn. Genuine one-offs and throwaway prototypes stay disposable. A task is
**not complete** until any durable tool is cataloged or explicitly recorded
absent.

Work generates capabilities, not only knowledge. A task needs an operation
performed — seed a fixture, migrate a schema, probe an endpoint, regenerate a
client — and an agent writes code to do it. If that code dies with the session,
the next task that needs the same operation writes it again, slightly
differently, with a fresh chance to get it wrong. Toolcraft is the doctrine that
keeps a capability once it is worth keeping.

**This node is the rule, not either half of the work.** Three things used to sit
in one file and are now separate, because they happen at different times and are
done by different actors:

| | Who | When |
|---|---|---|
| **the rule** — what earns durability | this node; every session reads it | always |
| **authoring** — building the tested tool | `docs/graph/agents/tool-smith.md` | mid-task, when the recurrence is noticed |
| **cataloging** — the page in `docs/graph/tools/` | the librarian, inside `docs/graph/protocols/canonize.md` | once, at close-out |

There is still **no separate cataloging spawn**: a second spawn with the same
bootstrap and lint run would be coordination waste, and canonize owns that rule.
Authoring is not a close-out step and never was — canonize catalogs the tool "it
produced", and the producer is the tool-smith.

## What counts as a durable tool (`toolcraft.durability-criteria`)

Catalog a piece of real code that:
- **recurs across independent sessions** — an agent, expert, or skill
  will plausibly run it again in a future task (the trigger is
  recurrence, not size);
- has a **stable interface** — a named entry point, defined inputs and
  outputs, a documented invocation, not a copy-pasted snippet;
- is **authorized by a test** (§3.4) — at least one test pins what it
  does, so a future session can trust and change it safely;
- **lives in the repository**, committed where the project keeps its
  tooling, reachable by path.

## What stays disposable

- a **genuine one-off** — needed once, no future task plausibly repeats it;
- a **throwaway prototype** written to learn a library or shape — the
  blessed carve-out of the test-first rule (§3.4); recorded, if
  anywhere, as an exception in `grill.md §9`;
- anything embedding secrets, credentials, or production/personal data;
- project-specific tooling aimed at the seed — that is `harvest`'s
  agnosticism gate.

## The procedure sibling — durable skills

A tool is durable *code*; a **skill** is a durable *procedure* — the
disciplined sequence for a recurring kind of work (a migration recipe, a
release choreography, a data-reset dance). Same recurrence trigger, different
shape: if the recurring thing is code that runs, it is a tool; if it is the
*how* — the ordered steps and the gate each one clears, usually composing
existing protocols and tools — it is a skill. When such a procedure recurs and
no core `docs/graph/skills/` discipline covers it, author it as a project skill from
`docs/graph/templates/skill.template.md`, the same
way a missing role is commissioned from `docs/graph/templates/agent.template.md`. Its
**home is the graph node** `docs/graph/skills/<name>.md`; create the projection
in each harness directory the plant actually uses
(`.claude/skills/<name>/SKILL.md` and kin) in the same pass, so the harness can
load it before the next install — `install.sh` projects what the graph holds,
so from then on the projection is maintained for you. It
**composes** disciplines by reference, never restating them. The core `docs/graph/skills/` stay the fixed shared
methodology — a project skill is the optional, project-specific procedure on
top.

## Design-time half of the rule

The doctrine cuts earlier than task end: when `grill` identifies a
recurring operation, the plan-of-record names a durable tool — or, when the
recurring thing is a *procedure* rather than code, a project skill — as the
unit of work; the capability is *designed* durable, not retrofitted. Workers
name every tool they build in `tools_built` and every recurring procedure in
`skills_built` in their handback payload
(`docs/graph/templates/prompts/handback-payload.md`); those fields are what the
close-out brief forwards to the librarian.

## Fail-closed doctrine

A task is **not complete** until any durable tool it produced is
cataloged and any procedure it repeated is crystallized into a project
skill, or the close-out has explicitly recorded "no durable tool / no skill,
because …" (for Tier 0/1 tasks, the session's one-line self-record in
the delivery covers this — see `docs/graph/protocols/canonize.md`). A task that
built a reusable capability — a tool, or a procedure worn in by repetition —
but left it uncaptured is a silent capability leak: the next session cannot
find what exists, so it rewrites it.

Cross-project mirror: `harvest` folds **project-agnostic** tools into the
seed's `tool-corpus/` and **project-agnostic** skills into `skill-corpus/`,
user-triggered only.

## Bounded execution lives elsewhere

The discipline for running a command that may outlive its session — explicit
bounds, detached launches, a durable log, bounded polling, liveness as an
observed signal, completion by marker — was filed here because toolcraft was the
nearest protocol. It is an execution discipline every session needs, not
tool-authoring doctrine, and its home is `method.engineering-posture`
(`toolcraft.bounded-execution`).