Pattern: reusable, data-only expectations
A pattern records expectations as clauses (must, default, recommendation). Each pattern
also has a selector saying where it applies, the sources it came from, and optional hashed local
assets. A blueprint is a pattern that includes other patterns by exact reference. Bindings state
which patterns a context requires or defaults to.
Patterns complement accepted policy. They grant no authority and never execute, fetch or install
anything.
This skill drives the reasoning: which sources to read, what the operator actually confirmed, and
what needs review. The deterministic work is done only by the launcher bin/li-pattern and its
CLI bin/li-pattern.py over
lib/patterns.py: validation, resolution, locking and safe persistence. Never re-implement
validation, hashing or precedence in prose or in another script. The frozen interface is
.claude/plans/reusable-patterns/contract.md in the Lintel source; the decision is ADR-0038.
When to use
- The operator states an expectation that should hold for future work of a given kind or target.
- A repository, team pack or person wants to reuse a known-good structure across work, such as a
dashboard, a report, a deployment topology or a visual language.
- Work must show which expectations applied, at which version, and whether review covered them.
- An existing pattern needs an update, deprecation, retirement, revocation, export or import.
When not to use
- One-off preferences for the current task. State them in the brief instead.
- Enterprise enforcement. A repository can forge a binding, so patterns are advisory structure
under host policy and branch rules, not a control.
- Inferring an organization's policy from generic public guidance, such as cloud landing-zone
recommendations. An inaccessible mandatory source stays unknown; it is never guessed.
Scopes and roots
| Scope |
Catalog |
Activation |
| Repository |
.claude/patterns/catalog.json, with bindings in .claude/patterns/bindings.json |
Bindings and catalog bindings apply at repository scope |
| Active pack |
The effective pack's patterns.source and its pinned includes |
Pack catalog bindings apply at pack scope |
| Personal |
$LINTEL_HOME/patterns/catalog.json |
Never automatic; selected only by an explicit reference or a repository binding |
Default precedence runs in this order:
- Explicit authorized task choice
- Repository
- Active pack
- Explicitly selected personal pattern
- The existing corpus/model fallback
Mandatory clauses constrain the whole chain. With no selected pattern, existing behavior is
unchanged, including Design DNA's brief > profile > corpus order.
A linked (junction or symlink) home, repository, .claude or pattern root is refused. Pass the
real path instead.
Windows path length: the runtime opens pattern files with ordinary paths, so without Windows long-path support a pattern file whose full path exceeds about 260 characters is reported missing (fail-closed, never success). The bundled kit's deepest path is the example asset directory, so on Windows PowerShell 5.1 with LongPathsEnabled=0 the bare installer needs a correspondingly short Lintel home: a home near 108 characters was observed to work and near 134 characters to fail, recoverably, with -Recover. The exact budget depends on the host. Keep pattern sources and the Lintel home at ordinary depths, or enable long paths; full long-path support is not claimed.
Running the helper
Call the launcher from the trusted source root with its interpreter; never run a relative
bin/li-pattern from the working tree, which an installed target repository does not contain.
The launcher resolves the repository root, LINTEL_HOME and the ADR-0029 profile record, and
passes them to the Python CLI as a JSON envelope on stdin:
bash "$LINTEL_SOURCE_ROOT/bin/li-pattern" list
bash "$LINTEL_SOURCE_ROOT/bin/li-pattern" --repo "$LINTEL_REPO_ROOT" resolve --context "$ctx"
Use --repo DIR outside a Git checkout. Runtime operations need the optional Python 3.10+
toolchain. If Python, Bash or the helper is missing, report "pattern check unavailable" once; that
is never "no patterns". See the consumer contract for which work
may continue and which must stop. The exact invocations, status handling, phase obligations and
evidence rules consumers follow are all in that consumer contract.
A successful runtime prints exactly one JSON report on stdout, with its error diagnostics on stderr.
Act on the reported status, not only on whether the exit code is zero. No JSON report on stdout
means "pattern check unavailable", whatever the exit code. That covers a missing runtime (exit 5), a
partial kit, or a missing helper. It is never "no patterns" and never permission to continue dependent
work; see the consumer contract's "Missing runtime" rule. The table applies only when a report was
printed:
| Exit |
Status |
Meaning for the workflow |
| 0 |
ok, ready, empty |
Proceed. empty means no pattern applies and behavior is unchanged |
| 2 |
invalid |
Fix the input; nothing was written |
| 3 |
needs-context |
Ask for or cite the missing facts; do not guess them |
| 4 |
conflict |
Resolve the named conflict: settings, applicability or mandatory baseline |
| 5 |
unavailable |
A configured source is missing, changed, revoked, retired or unverified. Dependent work stops |
| 6 |
collision |
Another writer, or a stale digest. Re-read and retry deliberately |
| 7 |
review-unmet |
Mandatory clause evidence is missing or failing |
Operations
| Command |
Use it to |
Notes |
list, show --ref <source:id@version>, check |
Inspect catalogs or one pattern; validate a document or all sources |
list reads no pattern bodies |
resolve, explain (--context, optional --refs, --overrides, --exceptions, --preview-draft) |
Select the patterns that apply to evidenced context facts |
Advisory candidates are never requirements. explain adds the binding decisions |
resolve --lock <path> |
Freeze a ready or empty selection beside the initiative |
Never overwrites an existing lock. Conflicts and unknown context never lock |
verify-lock --lock --context |
Check pins, lifecycle, revocations and the mandatory baseline before continuing |
Never upgrades a pin silently |
map, project |
Map clauses to existing task IDs, and project one package's clauses |
Regrouping never changes the selection |
capture --input --scope repo|personal --name |
Register a new draft |
Drafts are never selected for execution |
index --source-root |
Re-check registered entries and regenerate their metadata |
Never discovers or blesses unregistered files |
approve --path --version --approval --expected-digest |
Publish a reviewed, strictly newer approved version |
The draft stays unchanged, and every dependency must be approved |
update --path --input --expected-digest [--write] |
Create a strictly newer draft of the same pattern |
Previews the clause diff and dependents; the old version and current pins stay unchanged |
deprecate, retire, revoke --ref --record [--write] |
Record a lifecycle event with its impact |
Deprecated pins warn; retired and revoked pins block; there is no un-revoke |
apply --change [--write] |
Add, replace or remove one repository binding |
Shows the reduced mandatory baseline before a required binding is weakened |
remove --ref [--write] |
Unregister an entry nothing references |
Files and history are never deleted |
resolve/verify-lock --attestations |
Supply reviewed source attestations |
Needed for URL sources of required patterns and for overdue patterns; renewal never changes the selection |
export --refs --out, import --bundle --scope --destination-source --version-map [--write] |
Share patterns as a local bundle |
Import stages drafts with inert provenance; approve children first after review |
review --lock --context --evidence |
Check per-clause evidence coverage after verifying the lock |
Exit 7 on unmet mandatory coverage; never a pass or release clearance |
Every write follows the same rules: explicit inputs, previews before writes, compare-and-swap
digests, and no silent change to active work.
Capture procedure
- Read only the sources the operator authorized: documents, policy exports, code, screenshots or
an interview. Record each one as a source with its
kind, root, section, observed_at,
confidence and reuse limits. A URL is provenance, not a fetch instruction.
- Separate what the operator confirmed from what you observed or inferred. Confirmed sources are
operator-statement or approved-standard with confidence confirmed. Observed or inferred
ones are observation or inferred. Observations become default or recommendation
clauses unless the operator confirms a must.
- Write a narrow selector from evidenced facts. An empty selector means "everywhere" and must be
deliberate. Give each clause a
verify statement that a reviewer can actually check.
- Capture the pattern as a draft, and show the operator its clauses and provenance. Approve only
after review, with a new version and an approval reference. Approval records provenance; it
does not prove the approver's authority.
- Keep each declared asset, and any
root: pattern source, next to the draft file you capture,
or pass --files-from <dir>. Every version carries exactly those files, digest-checked. Nothing
else is copied, and a missing or changed file stops publication.
- Before a pattern source is tracked in Git, protect its raw bytes with a source-scoped
.gitattributes containing * -text beside the catalog, as described in the
pattern template. Never overwrite
an existing attributes file. If a repository policy already governs that path, honor it and
decide explicitly. -text stops line-ending conversion only; it does not disable filters, LFS,
working-tree-encoding or ident, so check those against the policy as well.
- Never copy credentials, private source documents or absolute home paths into a pattern, lock
or export.
Workflow consumers
Phase and generation workflows consume patterns through the shared
consumer contract.
- Without configured patterns, those workflows behave exactly as before, and no prompts or files
are added.
- Direct entry into any phase either resolves the current context or verifies an explicitly
supplied lock.
- Assets are read with
read_asset, bound to that selection.
- Pattern clause coverage is supplemental evidence inside the ADR-0028 review contract, never a
separate pass.
1---2name: pattern3layer: foundation4description: Use when recurring expectations (deployment baselines, dashboard behavior, document structure, visual language) should be captured, reviewed, versioned, shared or applied to named work as data-only patterns with explicit applicability, provenance and review traceability.5color: teal6tools: Read, Write, Edit, Bash, Grep, Glob7voice: internal8cli_support: [claude-code, codex, copilot]9necessity: OPTIONAL10gap_if_skipped: "Established team expectations stay implicit; work is planned and reviewed without an evidenced, versioned baseline."11metadata:12 source: https://skillmd.com/skills/jokerman89/pattern13---1415# Pattern: reusable, data-only expectations1617A pattern records expectations as clauses (`must`, `default`, `recommendation`). Each pattern18also has a selector saying where it applies, the sources it came from, and optional hashed local19assets. A blueprint is a pattern that includes other patterns by exact reference. Bindings state20which patterns a context requires or defaults to.2122Patterns complement accepted policy. They grant no authority and never execute, fetch or install23anything.2425This skill drives the reasoning: which sources to read, what the operator actually confirmed, and26what needs review. The deterministic work is done only by the launcher `bin/li-pattern` and its27CLI `bin/li-pattern.py` over28`lib/patterns.py`: validation, resolution, locking and safe persistence. Never re-implement29validation, hashing or precedence in prose or in another script. The frozen interface is30`.claude/plans/reusable-patterns/contract.md` in the Lintel source; the decision is ADR-0038.3132## When to use3334- The operator states an expectation that should hold for future work of a given kind or target.35- A repository, team pack or person wants to reuse a known-good structure across work, such as a36 dashboard, a report, a deployment topology or a visual language.37- Work must show which expectations applied, at which version, and whether review covered them.38- An existing pattern needs an update, deprecation, retirement, revocation, export or import.3940## When not to use4142- One-off preferences for the current task. State them in the brief instead.43- Enterprise enforcement. A repository can forge a binding, so patterns are advisory structure44 under host policy and branch rules, not a control.45- Inferring an organization's policy from generic public guidance, such as cloud landing-zone46 recommendations. An inaccessible mandatory source stays unknown; it is never guessed.4748## Scopes and roots4950| Scope | Catalog | Activation |51| --- | --- | --- |52| Repository | `.claude/patterns/catalog.json`, with bindings in `.claude/patterns/bindings.json` | Bindings and catalog bindings apply at repository scope |53| Active pack | The effective pack's `patterns.source` and its pinned includes | Pack catalog bindings apply at pack scope |54| Personal | `$LINTEL_HOME/patterns/catalog.json` | Never automatic; selected only by an explicit reference or a repository binding |5556Default precedence runs in this order:57581. Explicit authorized task choice592. Repository603. Active pack614. Explicitly selected personal pattern625. The existing corpus/model fallback6364Mandatory clauses constrain the whole chain. With no selected pattern, existing behavior is65unchanged, including Design DNA's brief > profile > corpus order.6667A linked (junction or symlink) home, repository, `.claude` or pattern root is refused. Pass the68real path instead.6970Windows path length: the runtime opens pattern files with ordinary paths, so without Windows long-path support a pattern file whose full path exceeds about 260 characters is reported missing (fail-closed, never success). The bundled kit's deepest path is the example asset directory, so on Windows PowerShell 5.1 with `LongPathsEnabled=0` the bare installer needs a correspondingly short Lintel home: a home near 108 characters was observed to work and near 134 characters to fail, recoverably, with `-Recover`. The exact budget depends on the host. Keep pattern sources and the Lintel home at ordinary depths, or enable long paths; full long-path support is not claimed.7172## Running the helper7374Call the launcher from the trusted source root with its interpreter; never run a relative75`bin/li-pattern` from the working tree, which an installed target repository does not contain.76The launcher resolves the repository root, `LINTEL_HOME` and the ADR-0029 profile record, and77passes them to the Python CLI as a JSON envelope on stdin:7879```bash80bash "$LINTEL_SOURCE_ROOT/bin/li-pattern" list81bash "$LINTEL_SOURCE_ROOT/bin/li-pattern" --repo "$LINTEL_REPO_ROOT" resolve --context "$ctx"82```8384Use `--repo DIR` outside a Git checkout. Runtime operations need the optional Python 3.10+85toolchain. If Python, Bash or the helper is missing, report "pattern check unavailable" once; that86is never "no patterns". See the [consumer contract](references/consumer-contract.md) for which work87may continue and which must stop. The exact invocations, status handling, phase obligations and88evidence rules consumers follow are all in that [consumer contract](references/consumer-contract.md).8990A successful runtime prints exactly one JSON report on stdout, with its error diagnostics on stderr.91Act on the reported `status`, not only on whether the exit code is zero. **No JSON report on stdout92means "pattern check unavailable", whatever the exit code.** That covers a missing runtime (exit 5), a93partial kit, or a missing helper. It is never "no patterns" and never permission to continue dependent94work; see the consumer contract's "Missing runtime" rule. The table applies only when a report was95printed:9697| Exit | Status | Meaning for the workflow |98| --- | --- | --- |99| 0 | `ok`, `ready`, `empty` | Proceed. `empty` means no pattern applies and behavior is unchanged |100| 2 | `invalid` | Fix the input; nothing was written |101| 3 | `needs-context` | Ask for or cite the missing facts; do not guess them |102| 4 | `conflict` | Resolve the named conflict: settings, applicability or mandatory baseline |103| 5 | `unavailable` | A configured source is missing, changed, revoked, retired or unverified. Dependent work stops |104| 6 | `collision` | Another writer, or a stale digest. Re-read and retry deliberately |105| 7 | `review-unmet` | Mandatory clause evidence is missing or failing |106107## Operations108109| Command | Use it to | Notes |110| --- | --- | --- |111| `list`, `show --ref <source:id@version>`, `check` | Inspect catalogs or one pattern; validate a document or all sources | `list` reads no pattern bodies |112| `resolve`, `explain` (`--context`, optional `--refs`, `--overrides`, `--exceptions`, `--preview-draft`) | Select the patterns that apply to evidenced context facts | Advisory candidates are never requirements. `explain` adds the binding decisions |113| `resolve --lock <path>` | Freeze a ready or empty selection beside the initiative | Never overwrites an existing lock. Conflicts and unknown context never lock |114| `verify-lock --lock --context` | Check pins, lifecycle, revocations and the mandatory baseline before continuing | Never upgrades a pin silently |115| `map`, `project` | Map clauses to existing task IDs, and project one package's clauses | Regrouping never changes the selection |116| `capture --input --scope repo\|personal --name` | Register a new draft | Drafts are never selected for execution |117| `index --source-root` | Re-check registered entries and regenerate their metadata | Never discovers or blesses unregistered files |118| `approve --path --version --approval --expected-digest` | Publish a reviewed, strictly newer approved version | The draft stays unchanged, and every dependency must be approved |119| `update --path --input --expected-digest [--write]` | Create a strictly newer draft of the same pattern | Previews the clause diff and dependents; the old version and current pins stay unchanged |120| `deprecate`, `retire`, `revoke --ref --record [--write]` | Record a lifecycle event with its impact | Deprecated pins warn; retired and revoked pins block; there is no un-revoke |121| `apply --change [--write]` | Add, replace or remove one repository binding | Shows the reduced mandatory baseline before a required binding is weakened |122| `remove --ref [--write]` | Unregister an entry nothing references | Files and history are never deleted |123| `resolve`/`verify-lock --attestations` | Supply reviewed source attestations | Needed for URL sources of required patterns and for overdue patterns; renewal never changes the selection |124| `export --refs --out`, `import --bundle --scope --destination-source --version-map [--write]` | Share patterns as a local bundle | Import stages drafts with inert provenance; approve children first after review |125| `review --lock --context --evidence` | Check per-clause evidence coverage after verifying the lock | Exit 7 on unmet mandatory coverage; never a pass or release clearance |126127Every write follows the same rules: explicit inputs, previews before writes, compare-and-swap128digests, and no silent change to active work.129130## Capture procedure1311321. Read only the sources the operator authorized: documents, policy exports, code, screenshots or133 an interview. Record each one as a source with its `kind`, `root`, `section`, `observed_at`,134 `confidence` and reuse limits. A URL is provenance, not a fetch instruction.1352. Separate what the operator confirmed from what you observed or inferred. Confirmed sources are136 `operator-statement` or `approved-standard` with confidence `confirmed`. Observed or inferred137 ones are `observation` or `inferred`. Observations become `default` or `recommendation`138 clauses unless the operator confirms a `must`.1393. Write a narrow selector from evidenced facts. An empty selector means "everywhere" and must be140 deliberate. Give each clause a `verify` statement that a reviewer can actually check.1414. Capture the pattern as a draft, and show the operator its clauses and provenance. Approve only142 after review, with a new version and an approval reference. Approval records provenance; it143 does not prove the approver's authority.1445. Keep each declared asset, and any `root: pattern` source, next to the draft file you capture,145 or pass `--files-from <dir>`. Every version carries exactly those files, digest-checked. Nothing146 else is copied, and a missing or changed file stops publication.1476. Before a pattern source is tracked in Git, protect its raw bytes with a source-scoped148 `.gitattributes` containing `* -text` beside the catalog, as described in the149 [pattern template](../../scaffolding/01-foundation/templates/pattern/README.md). Never overwrite150 an existing attributes file. If a repository policy already governs that path, honor it and151 decide explicitly. `-text` stops line-ending conversion only; it does not disable filters, LFS,152 `working-tree-encoding` or `ident`, so check those against the policy as well.1537. Never copy credentials, private source documents or absolute home paths into a pattern, lock154 or export.155156## Workflow consumers157158Phase and generation workflows consume patterns through the shared159[consumer contract](references/consumer-contract.md).160161- Without configured patterns, those workflows behave exactly as before, and no prompts or files162 are added.163- Direct entry into any phase either resolves the current context or verifies an explicitly164 supplied lock.165- Assets are read with `read_asset`, bound to that selection.166- Pattern clause coverage is supplemental evidence inside the ADR-0028 review contract, never a167 separate pass.