toolshed

Toolshed

Working state that survives sessions and models — but not the task. Everything in docs/work/<slug>/ dies at close. Survivors are formal genres (ADR, spec, RFC) authored from deliverable-shaped records. "BS if we keep it; under the same feature it is gold."

Path stays under docs/: docs/work/<slug>/. The skill name is toolshed.

The law (non-negotiable)

The laws bind the agent, not the owner. An owner may waive a law: the waiver is recorded in docs/work/TOOLSHED.md (the survivor file — never the mortal folder) as law N waived for <slug>: <reason, date>, and the agent states the consequence once, then complies. Silent erosion and standoffs are both failures.

1. Mortality. Folder deleted in the closing PR. No archive directory. Archive of record = the closing PR (final packet/summary in its description) plus ≥1 commit containing the folder that reached the default branch. Bare "git history" is not enough: under squash-merge a folder added and deleted inside one PR leaves zero trace on main. assert-close.sh enforces the merged-commit precondition; deliverables still stamp the final SHA. Why keeping it loses: kept folders drift against the ADRs they duplicate; STATE becomes a resume surface for a task nobody resumes; and superseded-but-decided records — correct in a ledger — read as current guidance once they are permanent docs. Deliverables win by being the only copy.
2. Slug identity, ticket optional. Never require a ticket to start.
3. Boundary rule. Contract-changing decisions promote to permanent home the moment decided — not at close, and in the same PR as the change they govern (after-the-fact ADRs are ratification theater — the named, documented way this practice dies). A decision made ahead of its implementation promotes with the PR that implements it: an ADR for a contract the code does not have is the mirror image of ratification theater. Toolshed links to them. Once promoted/accepted, an ADR is immutable — supersede, never edit. Partial supersession: the amending ADR adds one pointer line to the amended ADR's header; the amended body stays immutable.
4. Evidence self-sufficiency of survivors. ADRs/specs inline dated, graded evidence + reproduction command when the evidence lives in toolshed. Evidence may also live in PRs, CI, other skill artifacts — toolshed does not own all proof; point at it.
5. Evidence hygiene. Aggregates, shapes, masked patterns: yes. Payloads, customer IDs, PII: never.
6. Deliverable-shaped records. Decisions are proto-ADRs (options + flip condition). Close is a transform, not a rewrite.
7. Records are upsert-only. Corrections are loud (History lines) — never silent edits, never deletions; supersede instead.
8. One slug = one branch/worktree = one active agent. No published convention safely handles two agents writing the same STATE.md concurrently — don't be the experiment. Parallel agents get parallel worktrees (and usually parallel slugs); merge via git, not via hope.
9. Branch-carried preferred; local-only allowed while testing. Default long-term: track docs/work/ on the feature branch and commit as you go — an uncommitted toolshed protects nothing; it dies with the working tree. While the flow is under active change, repos may gitignore docs/work/ — then resume is machine-local; survivors must land in PR/permanent docs before the machine is disposable. seed.sh warns when ignored; stale-check.sh flags never-committed and abandoned toolsheds.
10. STATE is a resume surface, not a novel. Soft cap ~120 lines for new toolsheds. No full packet, no E-appendix, no W-registry dump inside STATE. Ledgers in D/Q/E; optional ship matrix in packet.md. Legacy bloated STATE (pre-toolshed / mid-flight): do not force a full rewrite — use assert-state.sh --soft (warn) until that task closes.
11. Understanding before proposal. Template Understanding = not started. assert-started.sh must pass before design/implementation.
12. Freshness. A toolshed untouched for 21+ days is presumed stale — resume it or close it. stale-check.sh [--strict] reports (CI-friendly). Staleness is a smell, not a crime; the response is triage, not archive.