Reuse first, as code

A shared library that nobody finds is not reuse. This chapter turns reuse first into a layered control: a governed asset catalog, an instructions file that sends the coding agent to it, an advisory agent hook, a recorded decision, and deterministic checks in the CI pipeline (continuous integration, the automated build and test run on every change) that enforce the result. Counts in this chapter are illustrative.

Local agent hooks are advisory. They nudge the coding agent and they can be skipped. Enforcement lives in the CI pipeline and in branch protection, which run whether or not anyone used an agent.

1. The problem · ten implementations of one idea

The organization had ten different date-and-time implementations (illustrative) across its services. A shared library, shared-datetime, already existed. Each implementation got the domain wrong in its own way, and three of them turned a contractual due date into a moment in time.

The fix is not "use the library". The fix is a temporal-domain contract, owned by architecture and published in the catalog, that says what each kind of time value is.

2. The temporal-domain contract

The contract names four kinds of time value and one rule for each. The worked example in chapter 8 applies it end to end.

3. The reference architecture · eight layers

Each layer catches something the others miss. No single layer proves that a duplicate does not exist.

4. Layer 1 · the catalog entry

A catalog entry is evidence, not marketing. The coding agent and the developer both read it, so it states limits as clearly as features.

5. Layer 2 · the instructions file

The instructions file is the team's standing context for the coding agent, reviewed like code. This excerpt is illustrative and vendor-neutral.

## Dates and times (temporal-domain contract v1)
- Before writing any date, time, zone or calendar helper, query the asset catalog
  for the capability "temporal". Prefer reuse; extend if close; create only with a
  decision record.
- Use shared-datetime 4.x. Never add another date library.
- A due date is a date-only value: LocalDate. Never parse it into a date-time.
- A cutoff is an Instant computed only by payment-schedule-service. Never compute it
  from the due date. Format it with formatPaymentCutoff(cutoffInstant, customerZone).
- The customer zone comes from profile-service as an IANA zone name. If missing,
  use the fallback table and show the fallback label.
- Issued statements are immutable. Do not re-render them.
- Record every reuse, extend or create choice in reuse-decision.yaml in the pull request.

6. Layer 3 · the advisory hook

An agent hook is a small program that the agent's runtime calls at a fixed event, such as just before the agent writes a file. This one fires when the agent is about to create something that looks like a new date utility. It returns candidates from the catalog with evidence; it never claims that reuse is certain.

A generic configuration sketch (not any product's syntax):

hooks:
  - name: reuse-advisory-new-date-utility
    event: before_tool_call            # agent is about to write or create a file
    match:
      tools: [write_file, create_file]
      paths: ["src/**"]
      exclude: ["**/test/**", "**/generated/**"]
      content_regex: "new Date\\(|Date\\.parse\\(|setHours\\(|[+-]0[0-9]:00"
    run: catalog-check --capability temporal --stdin
    timeout_ms: 3000
    on_timeout: allow_with_warning     # fail-open: advisory only
    on_match: inject_context           # candidates go back to the agent
    audit_event: reuse.advisory.shown

What the hook returns to the agent:

{
  "decision": "advise",
  "candidates": [
    {
      "asset": "shared-datetime",
      "version": "4.2",
      "capability": "LocalDate due date; formatInstant for the source cutoff instant in customer zone",
      "status": "supported",
      "evidence": "catalog entry; temporal-domain contract v1; 7 teams / 31 repositories (illustrative)"
    }
  ],
  "ask": "Record reuse, extend or create in reuse-decision.yaml"
}

In Claude Code this is a PreToolUse hook in settings (Claude Code hooks); in GitHub Copilot CLI a preToolUse hook (GitHub Copilot hooks). Verify current docs before you build one; event names and payloads change.

7. Layer 4 · the reuse decision record

The reuse decision record is a small machine-readable file in the pull request. The CI pipeline checks that it exists; the reviewer checks that its reason holds.

# reuse-decision.yaml
change: show contractual due date and payment cutoff consistently
capability: temporal
decision: extend                 # reuse | extend | create
asset: shared-datetime
version: "4.2"
reuse:
  - LocalDate for the due date (no conversion)
  - formatInstant(cutoff, customerZone) for the cutoff
extend:
  what: formatPaymentCutoff(cutoffInstant, customerZone), display only: formats the
        authoritative instant from payment-schedule-service with the zone label
        (or the labelled fallback zone); never calculates or overrides the cutoff
  why: three services recomputed the cutoff differently; payment-schedule-service alone
       computes it, and 4.2 has no labelled cutoff formatter
  owner_review: architecture temporal working group
create: none
alternatives_rejected:
  - local helper in notification-service (duplicates the rule)
contract: temporal-domain-contract v1
decided_by: developer
reviewed_by: architect     # not the author
date: 2026-10-29

8. Layers 5 and 6 · CI checks and branch protection

These layers fail closed. They run on every pull request, from any tool or none.

A banned-pattern rule in a grep or semgrep style (illustrative):

rules:
  - id: date-only-parsed-as-instant
    languages: [typescript, javascript]
    severity: ERROR
    message: >
      dueDate is a date-only value. new Date() turns it into an instant at
      midnight and can show the wrong calendar day. Use LocalDate.parse from
      shared-datetime (temporal-domain contract v1).
    pattern-either:
      - pattern: new Date($X.dueDate)
      - pattern: new Date(dueDate)
      - pattern: Date.parse($X.dueDate)
  - id: fixed-utc-offset
    languages: [typescript, javascript, java]
    severity: ERROR
    message: Use an IANA zone name from profile-service, never a fixed offset.
    pattern-regex: '"[+-]0[0-9]:00"'

A decision-record check (illustrative):

# ci/check-reuse-record.sh: fail when a new utility file arrives without a record
new_utils=$(git diff --name-only --diff-filter=A origin/main...HEAD -- 'src/**/util*' 'src/**/*date*')
if [ -n "$new_utils" ] && [ ! -f reuse-decision.yaml ]; then
  echo "New utility files without reuse-decision.yaml:"; echo "$new_utils"
  exit 1
fi

Branch protection makes these checks required and adds a required reviewer who is not the author. When a coding agent opened the pull request, the person who asked the agent is the author for this rule.

9. Layers 7 and 8 · exceptions and catalog feedback

10. The asset lifecycle

A reusable asset has a life: someone proposes it, someone assesses it, and someone retires it. Without the last step, the catalog fills with entries that agents still recommend.

Next: the worked example applies every layer to one ask. Copy-ready versions of the hook specification, the decision record and the catalog entry are in templates; Lab 3 in labs builds the hook and the CI check.