Lintel on GitHub Copilot. Generated from skills/pattern/SKILL.md; edit the canonical file, then run
li-copilot init.
- Resource root:
../../.. from this skill's base directory (the Lintel source with bin/,
lib/, skills/). Write plans, state and evidence into the working repository's .claude/
tree, never into the resource root.
- Skill-relative paths: this skill's own
scripts/, references/ and data/ folders (and a
<base> that the workflow defines as its own directory) mean
../../../skills/pattern/ in the Lintel source, not this generated folder.
${LINTEL_SKILLS_DIR:-skills} means the skills root, ../../../skills. A bin/li-run step
runs in the working repository, so use $LINTEL_SKILLS_DIR/pattern/ there.
- Shell steps: run Bash snippets with Bash (Git for Windows'
bash.exe on Windows, never
System32\bash.exe). Save a snippet to a temporary .sh file and run
bash "<resource root>/bin/li-run" <file>; it prepares LINTEL_SOURCE_ROOT, LINTEL_REPO_ROOT
and the profile context.
- Tools: Read=
view, Write=create, Edit=edit, Bash=bash/powershell, Grep=grep,
Glob=glob, AskUserQuestion=ask_user, TodoWrite=the plan checklist, Task or a named role=task
with that custom agent, WebFetch=web_fetch.
- Other Lintel workflows are native skills: invoke
/li-<name> rather than reading their
files. Named roles such as CodeReviewer are custom agents.
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: li-pattern3description: Use when recurring expectations should be captured, reviewed, versioned, shared or applied to named work as data-only patterns with explicit applicability, provenance and review traceability.4metadata:5 source: https://skillmd.com/skills/jokerman89/li-pattern6---78> **Lintel on GitHub Copilot.** Generated from `skills/pattern/SKILL.md`; edit the canonical file, then run9> `li-copilot init`.10> - **Resource root:** `../../..` from this skill's base directory (the Lintel source with `bin/`,11> `lib/`, `skills/`). Write plans, state and evidence into the working repository's `.claude/`12> tree, never into the resource root.13> - **Skill-relative paths:** this skill's own `scripts/`, `references/` and `data/` folders (and a14> `<base>` that the workflow defines as its own directory) mean15> `../../../skills/pattern/` in the Lintel source, not this generated folder.16> `${LINTEL_SKILLS_DIR:-skills}` means the skills root, `../../../skills`. A `bin/li-run` step17> runs in the working repository, so use `$LINTEL_SKILLS_DIR/pattern/` there.18> - **Shell steps:** run Bash snippets with Bash (Git for Windows' `bash.exe` on Windows, never19> `System32\bash.exe`). Save a snippet to a temporary `.sh` file and run20> `bash "<resource root>/bin/li-run" <file>`; it prepares `LINTEL_SOURCE_ROOT`, `LINTEL_REPO_ROOT`21> and the profile context.22> - **Tools:** Read=`view`, Write=`create`, Edit=`edit`, Bash=`bash`/`powershell`, Grep=`grep`,23> Glob=`glob`, AskUserQuestion=`ask_user`, TodoWrite=the plan checklist, Task or a named role=`task`24> with that custom agent, WebFetch=`web_fetch`.25> - **Other Lintel workflows** are native skills: invoke `/li-<name>` rather than reading their26> files. Named roles such as `CodeReviewer` are custom agents.2728# Pattern: reusable, data-only expectations2930A pattern records expectations as clauses (`must`, `default`, `recommendation`). Each pattern31also has a selector saying where it applies, the sources it came from, and optional hashed local32assets. A blueprint is a pattern that includes other patterns by exact reference. Bindings state33which patterns a context requires or defaults to.3435Patterns complement accepted policy. They grant no authority and never execute, fetch or install36anything.3738This skill drives the reasoning: which sources to read, what the operator actually confirmed, and39what needs review. The deterministic work is done only by the launcher `bin/li-pattern` and its40CLI `bin/li-pattern.py` over41`lib/patterns.py`: validation, resolution, locking and safe persistence. Never re-implement42validation, hashing or precedence in prose or in another script. The frozen interface is43`.claude/plans/reusable-patterns/contract.md` in the Lintel source; the decision is ADR-0038.4445## When to use4647- The operator states an expectation that should hold for future work of a given kind or target.48- A repository, team pack or person wants to reuse a known-good structure across work, such as a49 dashboard, a report, a deployment topology or a visual language.50- Work must show which expectations applied, at which version, and whether review covered them.51- An existing pattern needs an update, deprecation, retirement, revocation, export or import.5253## When not to use5455- One-off preferences for the current task. State them in the brief instead.56- Enterprise enforcement. A repository can forge a binding, so patterns are advisory structure57 under host policy and branch rules, not a control.58- Inferring an organization's policy from generic public guidance, such as cloud landing-zone59 recommendations. An inaccessible mandatory source stays unknown; it is never guessed.6061## Scopes and roots6263| Scope | Catalog | Activation |64| --- | --- | --- |65| Repository | `.claude/patterns/catalog.json`, with bindings in `.claude/patterns/bindings.json` | Bindings and catalog bindings apply at repository scope |66| Active pack | The effective pack's `patterns.source` and its pinned includes | Pack catalog bindings apply at pack scope |67| Personal | `$LINTEL_HOME/patterns/catalog.json` | Never automatic; selected only by an explicit reference or a repository binding |6869Default precedence runs in this order:70711. Explicit authorized task choice722. Repository733. Active pack744. Explicitly selected personal pattern755. The existing corpus/model fallback7677Mandatory clauses constrain the whole chain. With no selected pattern, existing behavior is78unchanged, including Design DNA's brief > profile > corpus order.7980A linked (junction or symlink) home, repository, `.claude` or pattern root is refused. Pass the81real path instead.8283Windows 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.8485## Running the helper8687Call the launcher from the trusted source root with its interpreter; never run a relative88`bin/li-pattern` from the working tree, which an installed target repository does not contain.89The launcher resolves the repository root, `LINTEL_HOME` and the ADR-0029 profile record, and90passes them to the Python CLI as a JSON envelope on stdin:9192```bash93bash "$LINTEL_SOURCE_ROOT/bin/li-pattern" list94bash "$LINTEL_SOURCE_ROOT/bin/li-pattern" --repo "$LINTEL_REPO_ROOT" resolve --context "$ctx"95```9697Use `--repo DIR` outside a Git checkout. Runtime operations need the optional Python 3.10+98toolchain. If Python, Bash or the helper is missing, report "pattern check unavailable" once; that99is never "no patterns". See the [consumer contract](../../../skills/pattern/references/consumer-contract.md) for which work100may continue and which must stop. The exact invocations, status handling, phase obligations and101evidence rules consumers follow are all in that [consumer contract](../../../skills/pattern/references/consumer-contract.md).102103A successful runtime prints exactly one JSON report on stdout, with its error diagnostics on stderr.104Act on the reported `status`, not only on whether the exit code is zero. **No JSON report on stdout105means "pattern check unavailable", whatever the exit code.** That covers a missing runtime (exit 5), a106partial kit, or a missing helper. It is never "no patterns" and never permission to continue dependent107work; see the consumer contract's "Missing runtime" rule. The table applies only when a report was108printed:109110| Exit | Status | Meaning for the workflow |111| --- | --- | --- |112| 0 | `ok`, `ready`, `empty` | Proceed. `empty` means no pattern applies and behavior is unchanged |113| 2 | `invalid` | Fix the input; nothing was written |114| 3 | `needs-context` | Ask for or cite the missing facts; do not guess them |115| 4 | `conflict` | Resolve the named conflict: settings, applicability or mandatory baseline |116| 5 | `unavailable` | A configured source is missing, changed, revoked, retired or unverified. Dependent work stops |117| 6 | `collision` | Another writer, or a stale digest. Re-read and retry deliberately |118| 7 | `review-unmet` | Mandatory clause evidence is missing or failing |119120## Operations121122| Command | Use it to | Notes |123| --- | --- | --- |124| `list`, `show --ref <source:id@version>`, `check` | Inspect catalogs or one pattern; validate a document or all sources | `list` reads no pattern bodies |125| `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 |126| `resolve --lock <path>` | Freeze a ready or empty selection beside the initiative | Never overwrites an existing lock. Conflicts and unknown context never lock |127| `verify-lock --lock --context` | Check pins, lifecycle, revocations and the mandatory baseline before continuing | Never upgrades a pin silently |128| `map`, `project` | Map clauses to existing task IDs, and project one package's clauses | Regrouping never changes the selection |129| `capture --input --scope repo\|personal --name` | Register a new draft | Drafts are never selected for execution |130| `index --source-root` | Re-check registered entries and regenerate their metadata | Never discovers or blesses unregistered files |131| `approve --path --version --approval --expected-digest` | Publish a reviewed, strictly newer approved version | The draft stays unchanged, and every dependency must be approved |132| `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 |133| `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 |134| `apply --change [--write]` | Add, replace or remove one repository binding | Shows the reduced mandatory baseline before a required binding is weakened |135| `remove --ref [--write]` | Unregister an entry nothing references | Files and history are never deleted |136| `resolve`/`verify-lock --attestations` | Supply reviewed source attestations | Needed for URL sources of required patterns and for overdue patterns; renewal never changes the selection |137| `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 |138| `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 |139140Every write follows the same rules: explicit inputs, previews before writes, compare-and-swap141digests, and no silent change to active work.142143## Capture procedure1441451. Read only the sources the operator authorized: documents, policy exports, code, screenshots or146 an interview. Record each one as a source with its `kind`, `root`, `section`, `observed_at`,147 `confidence` and reuse limits. A URL is provenance, not a fetch instruction.1482. Separate what the operator confirmed from what you observed or inferred. Confirmed sources are149 `operator-statement` or `approved-standard` with confidence `confirmed`. Observed or inferred150 ones are `observation` or `inferred`. Observations become `default` or `recommendation`151 clauses unless the operator confirms a `must`.1523. Write a narrow selector from evidenced facts. An empty selector means "everywhere" and must be153 deliberate. Give each clause a `verify` statement that a reviewer can actually check.1544. Capture the pattern as a draft, and show the operator its clauses and provenance. Approve only155 after review, with a new version and an approval reference. Approval records provenance; it156 does not prove the approver's authority.1575. Keep each declared asset, and any `root: pattern` source, next to the draft file you capture,158 or pass `--files-from <dir>`. Every version carries exactly those files, digest-checked. Nothing159 else is copied, and a missing or changed file stops publication.1606. Before a pattern source is tracked in Git, protect its raw bytes with a source-scoped161 `.gitattributes` containing `* -text` beside the catalog, as described in the162 [pattern template](../../../scaffolding/01-foundation/templates/pattern/README.md). Never overwrite163 an existing attributes file. If a repository policy already governs that path, honor it and164 decide explicitly. `-text` stops line-ending conversion only; it does not disable filters, LFS,165 `working-tree-encoding` or `ident`, so check those against the policy as well.1667. Never copy credentials, private source documents or absolute home paths into a pattern, lock167 or export.168169## Workflow consumers170171Phase and generation workflows consume patterns through the shared172[consumer contract](../../../skills/pattern/references/consumer-contract.md).173174- Without configured patterns, those workflows behave exactly as before, and no prompts or files175 are added.176- Direct entry into any phase either resolves the current context or verifies an explicitly177 supplied lock.178- Assets are read with `read_asset`, bound to that selection.179- Pattern clause coverage is supplemental evidence inside the ADR-0028 review contract, never a180 separate pass.