Reuse-first

Before writing code that matches a cross-cutting pattern, check whether the pattern belongs in a shared library, framework or CLI of the Stack. If it does and isn't there yet, put it there first — never in the caller.

This is the meta-policy for reuse. The decision tree, pre-Write protocol, and promotion pipeline live here and only here. Categorical rules (versioning discipline, a11y baseline, build-time determinism, wire compatibility, etc.) live in the four sub-policies under policies/reuse/, which inherit from this file.

This policy is the enforcement mechanism for engines/sdk/koder_kit/docs/rfcs/RFC-001-spec-encapsulation-across-platforms.md, generalised across categories per meta/docs/stack/rfcs/policies-RFC-001-reuse-first-hierarchy.md.

When this applies

The check is mandatory when the code you are about to write implements any of these patterns. The Category column locates each pattern under the sub-policy that owns its categorical rules:

This list is not exhaustive. When you find a new cross-cutting pattern not listed here, the decision protocol below still applies — and the pattern gets added to this list with its category and home.

Note on categories. Each category has a sibling sub-policy under policies/reuse/ that codifies the rules specific to that kind of shared code. Sub-policies inherit from this meta and do not redeclare the decision tree, the protocol, or the promotion pipeline.

Category	Sub-policy	Distinct rules (preview)
ui-framework	policies/reuse/ui-framework-first.kmd (planned, Phase 2)	theme contract, safe-area, a11y baseline, i18n, cross-variant parity, golden tests
runtime-lib	policies/reuse/runtime-lib-first.kmd (planned, Phase 2)	strict SemVer, API stability tiers, multi-language parity, perf benchmarks, ≥85% coverage
build-tooling	policies/reuse/build-tooling-first.kmd (planned, Phase 2)	determinism, idempotence, no-network, self-stamping, ≥3-uses-→-binary alignment
protocol	policies/reuse/protocol-first.kmd (planned, Phase 2)	ratified RFC before mainline, version negotiation, N-version BC, schema evolution, cross-implementation tests

When this does NOT apply

• Product-specific business logic. An algorithm unique to

  suite/cine (video transcoding), a schema unique to vertical/edictus (licitação rules), a state machine unique to ai/kortex (DevOps decisions) — all stay in the product. Shared libraries hold plumbing, not product substance.

• One-off scripts under scripts/, context/scripts/, or similar.
• Test code and build configuration.
• Hotfixes that cannot wait for an SDK release. Apply the fix locally;

  open a follow-up ticket to promote to the shared library once the emergency is over.

• Spike / prototype code explicitly scoped as throwaway.

Decision protocol

When you are about to write code matching a pattern in the table above, before the first Write/Edit call, answer these three questions in your response:

1. Does this pattern already exist in a shared library / framework / CLI?
   • If yes → use it. No local implementation. Stop.
   • If partially → extend the shared library (new parameter, new method),

     not the caller. The library change is the actual work of this ticket.

   • If no → continue to question 2.

2. Will ≥ 3 other Koder modules plausibly need this pattern?
   • If yes → implement in the shared library directly. Open a ticket

     for the caller module to adopt the new feature.

   • If no → implement locally, but open a follow-up ticket in the

     library's own backlog (engines/sdk/<name>/backlog/pending/NNN-promote-<pattern>.md or dev/<tool>/backlog/pending/...) recording the pattern for future promotion when a 2nd or 3rd consumer appears.

3. Am I sure the canonical home doesn't already have it?
   • grep the relevant library's lib/src/ (Flutter) / src/ (JSGoetc.) /

     cmd/ (Go CLI) for the feature name before answering "no" to question 1. The cost of the grep is ~100 tokens; the cost of duplicating an existing widget / function / CLI subcommand is a landmine waiting to go off.

Enforcement

Per-session (AI discipline)

Every AI session (/k-go, /k-parity, /new-product, ad-hoc coding) that touches code matching a listed pattern must answer the three questions above in its response before writing code. This is visible to the user and auditable in the transcript.

Post-hoc (automated)

/k-housekeep gains an audit pass (enginessdkkoder_kit backlog KIT-3) that greps for duplicate local implementations of each pattern and reports them under § Reuse adoption (per category, sourced from sub-policies). Non-adopters get a warning, not an error — the policy is strong encouragement, not a blocker.

Pre-commit gates (automated)

/k-commit enforces specific reuse and parity contracts before allowing a release commit through:

These gates are codified rules, not advisory checks — they block the commit and require remediation (/k-test-gen-regress for the first, kicon generate --module <path> for the second; or /k-commit --autogen-icons to fix-and-stage in one hop).

Promotion pipeline

A backlog ticket exists for each "should-probably-be-shared" pattern: engines/sdk/<name>/backlog/pending/NNN-promote-<pattern>.md (or the CLI's equivalent path). When the ticket sees its 2nd or 3rd "me too" comment / referenced consumer, it graduates to the shared library with full test coverage. Duplicate-count is tracked automatically by the housekeep audit.

Rationale

Without this policy, RFC-001 is aspirational: the SDKs exist, but no mechanism forces anyone to check them before coding. The cost is exactly what previous sessions witnessed:

• The theme toggle was reinvented in dev/eye with a three-state design

  that violated specs/themes/light-dark.kmd.

• The safe-area pattern was forgotten entirely, leading to clipped UI that

  was only caught by a screenshot review.

Both would have been prevented by a 30-second check against this policy.

For AI agents specifically (see RFC-001 §2.1), this policy collapses the cost of every cross-cutting implementation from spec-ingest + impl + verify + drift-detection to a single library call. The policy is thus also a token-budget optimisation — the most impactful one in the Koder Stack.

Exceptions

When you determine the reuse path does not apply, state the exception explicitly in the response. This converts silent drift into visible, reviewable decisions. Example:

*"This is product-specific transcoding logic for suite/cine — the reuse pattern check at policies/reuse-first.kmd does not apply."*

Related

• meta/docs/stack/rfcs/policies-RFC-001-reuse-first-hierarchy.md — the

  RFC that defines this hierarchy and the migration plan.

• engines/sdk/koder_kit/docs/rfcs/RFC-001-spec-encapsulation-across-platforms.md —

  the strategic RFC this policy enforces.

• policies/sdk-first.kmd — legacy alias of this file. Redirects here;

  scheduled for removal after two release cycles per policies-RFC-001 §5 Phase 5.

• commands/k-sdkify.md — the inverse-direction command: walks the

  monorepo, detects existing local boilerplate duplicating shared patterns, and refactors to adopt the canonical home. reuse-first prevents new drift; k-sdkify cleans up existing drift. Same list of patterns, same decision tree.

• commands/k-go.md § Princípio de implementação: hyperscale-first —

  sibling principle; reuse-first and hyperscale-first apply together at every implementation decision.

• policies/code-first.kmd — orthogonal sibling policy

  (mechanical-vs-analytical axis vs the cross-cutting-vs-product-specific axis enforced here). Both apply simultaneously.

• specs/themes/light-dark.kmd, specs/app-layout/safe-area.kmd,

  specs/errors/user-facing-messages.kmd — the three specs first encapsulated in koder_kit per RFC-001.