latticerb 0.1.0

data/lib/lattice/resources/claude/lattice-workflow/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: lattice-workflow
+description: Use when planning or testing behavior or variant surfaces with interacting states, roles, permissions, feature flags, modes, providers, optional fields, component props, rendering branches, template variants, config matrices, lifecycle states, combinatorial edge cases, pairwise coverage, or t-way coverage. Extract a Lattice schema, run the local Lattice CLI, and use generated rows to strengthen plans, tests, fixtures, rendered variants, or review matrices.
+---
+
+# Lattice Workflow
+
+Use this skill to keep Claude on extraction and interpretation while Lattice handles the combinatorics.
+
+## When To Use It
+
+- derive a combinatorial model from a feature or PRD
+- derive a test matrix from existing code
+- derive a variant matrix from a component, partial, template, design-system story, or config surface
+- convert edge cases into explicit parameter/value constraints
+- generate pairwise or 3-way scenarios without hand-enumerating combinations
+- render a compact visual review matrix instead of every possible variant
+- review a plan involving roles, permissions, modes, providers, feature flags, optional fields, component props, rendering branches, template variants, config matrices, or lifecycle states
+- find coverage gaps where bugs hide in interactions rather than single branches
+
+## When NOT To Use It
+
+- **Small enumerable spaces.** Fewer than ~10 total combinations — enumerate by hand.
+- **Independent dimensions.** No interactions can surface a bug; each parameter affects behavior independently.
+- **Non-deterministic systems.** The same input row won't produce repeatable output (e.g., testing LLM responses).
+
+## Minimal Example
+
+A schema (YAML on stdin):
+
+```yaml
+model_name: checkout
+parameters:
+  user: [signed_in, guest]
+  payment: [card, apple_pay, paypal]
+  cart: [empty, single, multi]
+constraints:
+  - invalid_pair: {payment: apple_pay, cart: empty}
+```
+
+One generated row (JSON):
+
+```json
+{"user": "guest", "payment": "card", "cart": "multi"}
+```
+
+The schema is the contract. The generated rows are the source of truth. The schema file is optional transport.
+
+## Preflight
+
+```bash
+command -v lattice >/dev/null 2>&1 && lattice --help >/dev/null
+```
+
+If it fails, install the Ruby gem from RubyGems (or add `gem "latticerb"` to the project Gemfile):
+
+```bash
+gem install latticerb
+```
+
+The Python implementation (`pipx install lattice-cli` from PyPI) is interchangeable — both produce byte-identical output for the same schema and seed.
+
+## Workflow
+
+1. **Extract the schema.** Choose one coherent interaction surface — one feature, one workflow, one service behavior, one endpoint family, one component's variant space, one template family, or one config matrix. Parameters represent independent decisions or state partitions. Values are meaningful partitions, not every literal in the codebase.
+
+2. **Encode constraints.** Use the smallest constraint type that matches the rule (see [Constraint Selection](#constraint-selection) below). Encode true impossibilities — do not strip them and mark invalid rows downstream.
+
+3. **Validate.**
+
+   ```bash
+   cat schema.json | lattice validate
+   ```
+
+4. **Generate.** Default to pairwise unless explicitly asked for higher strength.
+
+   ```bash
+   cat schema.json | lattice generate
+   ```
+
+5. **Interpret the output.** Plan mode: rows become plan revisions, missing decisions, review scenarios. Test mode: rows become assertions (see [Test Mode Discipline](#test-mode-discipline) below). Variant mode: rows become fixtures, rendered variants, screenshots, visual-diff inputs.
+
+## Constraint Selection
+
+| Rule shape | Use |
+|---|---|
+| Two assignments cannot coexist | `invalid_pair` |
+| One-to-one pairing (if A then B and if B then A) | `bidirectional` |
+| A requires B, but B may appear elsewhere | `forward_dep` |
+| Child parameter only applies for some parent values | `conditional` |
+| This assignment set must appear in at least one row | `forced` |
+| Rule only breaks under three or more antecedents | `higher_order` |
+
+Prefer the smallest constraint type that matches. Use `conditional` instead of hand-writing `N/A` values.
+
+## Test Mode Discipline
+
+Source expected behavior from intent — the user's request, a spec, a PRD, a ticket, or explicit reasoning about what the system *should* do. **The code under test is evidence, not truth.** If intent is ambiguous for a row, stop and ask the user.
+
+Do not silently encode current behavior and hedge with `bug_signal:`-style annotations. That produces characterization tests, which lock in the implementation (bugs included) instead of catching divergence from intent. The asymmetries Lattice is designed to expose disappear when the test suite mirrors the same mental model as the code.
+
+## Common Pitfalls
+
+❌ Strip constraints to make generation easier, then mark impossible rows invalid after the fact.
+✅ Encode the constraint in the schema, regenerate. Encoding constraints changes the coverage universe to valid interactions — that's the point.
+
+❌ Write tests that assert what the code currently does.
+✅ Write tests that assert what the spec, PRD, or user requested. If intent is ambiguous, ask before writing.
+
+❌ Separate parameters for two fields where one determines the other (e.g., `currency` and `currency_symbol`).
+✅ One parameter plus a constraint expressing the dependency.
+
+❌ Brittle, prose-y value names (`payment_with_apple_pay_using_new_token_flow`).
+✅ Compact partitions: `apple_pay`, `apple_pay_new_token`.
+
+❌ Manually add or remove rows after `lattice generate`.
+✅ If the generated set is wrong, fix the schema. Hand-editing rows breaks the coverage guarantee.
+
+## References
+
+- [references/modeling-rules.md](references/modeling-rules.md) — extraction heuristics, parameter selection, value partitioning, constraint guidance
+- [references/worked-examples.md](references/worked-examples.md) — concrete examples in this repo
+
+## Development Fallback
+
+In a checkout of the Lattice source where the package is not installed:
+
+```bash
+# Ruby checkout
+cat schema.json | ruby -Ilib exe/lattice validate
+cat schema.json | ruby -Ilib exe/lattice generate
+
+# Python checkout
+cat schema.json | PYTHONPATH=src python3 -m lattice validate
+cat schema.json | PYTHONPATH=src python3 -m lattice generate
+```
+
+To install or refresh this skill from the installed package:
+
+```bash
+lattice agent install-claude-skill
+```

data/lib/lattice/resources/claude/lattice-workflow/references/modeling-rules.md

@@ -0,0 +1,52 @@
+# Modeling Rules
+
+Use this file when you are extracting a schema from code or prose and need tighter guardrails than the main skill body provides.
+
+## Parameter Selection
+
+- Scope one schema to one coherent behavior or rendering surface.
+  Good scopes: one feature, one service behavior, one workflow, one endpoint family, one state-machine slice, one component's variant space, one template family.
+  Bad default scope: the whole app.
+- Model the decisions that change behavior, not every field in a payload.
+- Prefer parameters that are visible in tests, UI branches, rendering branches, validation logic, template variants, component props, or feature flags.
+- Split large raw domains into behavioral partitions.
+  Good: `pay_range = present|absent`
+  Bad: every exact salary string
+- Avoid separate parameters for values that are already implied by another parameter unless the implication is partial and needs a constraint.
+
+## Value Selection
+
+- Values should be mutually exclusive and collectively useful for testing.
+- Keep domains small and meaningful. Most parameters should land in the 2-5 value range.
+- Normalize booleans as `true` and `false`.
+- For optional subordinate parameters, let `conditional` introduce `N/A`. Do not hand-add `N/A` unless the schema genuinely needs it as a first-class value.
+
+## Constraint Choice
+
+- `invalid_pair`: two assignments cannot coexist
+- `bidirectional`: one-to-one pairing; if A then B and if B then A
+- `forward_dep`: A requires B, but B may appear elsewhere
+- `conditional`: a child parameter only applies for some parent values
+- `forced`: this assignment set must appear in at least one generated row
+- `higher_order`: the invalid rule only appears when two or more antecedents are true
+
+Choose the smallest expressive type. If a rule can be represented as `invalid_pair`, do not use `higher_order`.
+
+Do not strip true constraints to get a smaller or easier unconstrained run. Do not generate nonsensical rows and mark them invalid downstream. Lattice's coverage accounting should run over valid interactions, so impossible combinations belong in the schema as `invalid_pair`, `forward_dep`, `bidirectional`, `conditional`, or `higher_order` constraints.
+
+## Extraction Process
+
+1. Choose the behavior or rendering surface you are modeling.
+2. Start from branches, validations, and business rules inside that scope.
+3. Convert prose like "only when", "must", "cannot", and "except" into candidate constraints.
+4. Remove cosmetic parameters that do not affect behavior.
+5. Check whether a missing value is really a separate partition or just noise.
+6. Validate the schema.
+7. Only after validation, generate scenarios.
+
+## Interpretation
+
+- Plan mode: each row becomes a review scenario or a missing decision in the plan.
+- Test mode: each row becomes a candidate setup matrix. Source the expected behavior from intent — user request, spec, PRD, or ticket — not from the code under test. If you cannot determine intent for a row, stop and surface the ambiguity to the user. Do not encode the current behavior and label it `bug_signal:` to hedge: characterization tests pass for the wrong reasons and hide the asymmetries Lattice is designed to expose. Example: if a mailbox accepts a spoofed `From:` header today, the assertion is still "rejects spoofed sender" — let the test fail and fix the code, do not invert the assertion to match the bug.
+- Variant mode: each row becomes a rendered variant, fixture, screenshot, visual diff input, contact-sheet item, or review checklist item.
+- Generated rows are not test names by themselves. The agent still needs to map them to application-specific assertions.

data/lib/lattice/resources/claude/lattice-workflow/references/worked-examples.md

@@ -0,0 +1,59 @@
+# Worked Examples
+
+These examples live in the repo-level `examples/` directory.
+
+## `examples/plan-mode-saved-search`
+
+Use when the agent starts from a feature discussion or PRD and needs a review checklist.
+
+- Input: `feature.md`
+- Schema transport: `model.yaml`
+- Output: `scenarios.json`
+
+## `examples/test-mode-checkout`
+
+Use when the agent starts from code and an existing test surface and needs missing cases.
+
+- Input: `code-notes.md`
+- Schema transport: `model.json`
+- Output: `scenarios.json`
+
+## `examples/three-way-notifications`
+
+Use when pairwise is not enough and the user explicitly wants 3-way coverage.
+
+- Input: `brief.md`
+- Schema transport: `model.yaml`
+- Output: `scenarios.json`
+
+## `examples/component-variant-matrix`
+
+Use when the agent starts from a visual component, rendering surface, template, or design-system story and needs compact review variants instead of every possible combination.
+
+- Input: `brief.md`
+- Schema transport: `model.yaml`
+- Output: `scenarios.json`
+
+## `examples/lattice-self-test`
+
+Use when you want a meta example of the harness extracting a schema for Lattice's own CLI surface and then using generated rows to drive CLI smoke tests.
+
+- Input: `brief.md`
+- Schema transport: `model.yaml`
+- Output: `scenarios.json`
+
+## `examples/agent-bootstrap-matrix`
+
+Use when you want a meta example of Lattice testing its own agent skill bootstrap behavior across harness detection, force/skip directives, target modes, and output formats.
+
+- Input: `brief.md`
+- Schema transport: `model.yaml`
+- Output: `scenarios.json`
+
+## `examples/schema-guidance-matrix`
+
+Use when you want a meta example of Lattice testing its own schema-discoverability guidance across help text, agent instructions, installed skill files, and validation errors.
+
+- Input: `brief.md`
+- Schema transport: `model.yaml`
+- Output: `scenarios.json`

data/lib/lattice/resources/codex/lattice-workflow/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: lattice-workflow
+description: Use when planning or testing behavior or variant surfaces with interacting states, roles, permissions, feature flags, modes, providers, optional fields, component props, rendering branches, template variants, config matrices, lifecycle states, combinatorial edge cases, pairwise coverage, or t-way coverage. Extract a Lattice schema, run the local Lattice CLI, and use generated rows to strengthen plans, tests, fixtures, rendered variants, or review matrices.
+---
+
+# Lattice Workflow
+
+Use this skill to keep the agent on extraction and interpretation while Lattice handles the combinatorics.
+
+## When To Use It
+
+- derive a combinatorial model from a feature or PRD
+- derive a test matrix from existing code
+- derive a variant matrix from a component, partial, template, design-system story, or config surface
+- convert edge cases into explicit parameter/value constraints
+- generate pairwise or 3-way scenarios without hand-enumerating combinations
+- render a compact visual review matrix instead of every possible variant
+- review a plan involving roles, permissions, modes, providers, feature flags, optional fields, component props, rendering branches, template variants, config matrices, or lifecycle states
+- find coverage gaps where bugs hide in interactions rather than single branches
+
+## When NOT To Use It
+
+- **Small enumerable spaces.** Fewer than ~10 total combinations — enumerate by hand.
+- **Independent dimensions.** No interactions can surface a bug; each parameter affects behavior independently.
+- **Non-deterministic systems.** The same input row won't produce repeatable output (e.g., testing LLM responses).
+
+## Minimal Example
+
+A schema (YAML on stdin):
+
+```yaml
+model_name: checkout
+parameters:
+  user: [signed_in, guest]
+  payment: [card, apple_pay, paypal]
+  cart: [empty, single, multi]
+constraints:
+  - invalid_pair: {payment: apple_pay, cart: empty}
+```
+
+One generated row (JSON):
+
+```json
+{"user": "guest", "payment": "card", "cart": "multi"}
+```
+
+The schema is the contract. The generated rows are the source of truth. The schema file is optional transport.
+
+## Preflight
+
+```bash
+command -v lattice >/dev/null 2>&1 && lattice --help >/dev/null
+```
+
+If it fails, install the Ruby gem from RubyGems (or add `gem "latticerb"` to the project Gemfile):
+
+```bash
+gem install latticerb
+```
+
+The Python implementation (`pipx install lattice-cli` from PyPI) is interchangeable — both produce byte-identical output for the same schema and seed.
+
+## Workflow
+
+1. **Extract the schema.** Choose one coherent interaction surface — one feature, one workflow, one service behavior, one endpoint family, one component's variant space, one template family, or one config matrix. Parameters represent independent decisions or state partitions. Values are meaningful partitions, not every literal in the codebase.
+
+2. **Encode constraints.** Use the smallest constraint type that matches the rule (see [Constraint Selection](#constraint-selection) below). Encode true impossibilities — do not strip them and mark invalid rows downstream.
+
+3. **Validate.**
+
+   ```bash
+   cat schema.json | lattice validate
+   ```
+
+4. **Generate.** Default to pairwise unless explicitly asked for higher strength.
+
+   ```bash
+   cat schema.json | lattice generate
+   ```
+
+5. **Interpret the output.** Plan mode: rows become plan revisions, missing decisions, review scenarios. Test mode: rows become assertions (see [Test Mode Discipline](#test-mode-discipline) below). Variant mode: rows become fixtures, rendered variants, screenshots, visual-diff inputs.
+
+## Constraint Selection
+
+| Rule shape | Use |
+|---|---|
+| Two assignments cannot coexist | `invalid_pair` |
+| One-to-one pairing (if A then B and if B then A) | `bidirectional` |
+| A requires B, but B may appear elsewhere | `forward_dep` |
+| Child parameter only applies for some parent values | `conditional` |
+| This assignment set must appear in at least one row | `forced` |
+| Rule only breaks under three or more antecedents | `higher_order` |
+
+Prefer the smallest constraint type that matches. Use `conditional` instead of hand-writing `N/A` values.
+
+## Test Mode Discipline
+
+Source expected behavior from intent — the user's request, a spec, a PRD, a ticket, or explicit reasoning about what the system *should* do. **The code under test is evidence, not truth.** If intent is ambiguous for a row, stop and ask the user.
+
+Do not silently encode current behavior and hedge with `bug_signal:`-style annotations. That produces characterization tests, which lock in the implementation (bugs included) instead of catching divergence from intent. The asymmetries Lattice is designed to expose disappear when the test suite mirrors the same mental model as the code.
+
+## Common Pitfalls
+
+❌ Strip constraints to make generation easier, then mark impossible rows invalid after the fact.
+✅ Encode the constraint in the schema, regenerate. Encoding constraints changes the coverage universe to valid interactions — that's the point.
+
+❌ Write tests that assert what the code currently does.
+✅ Write tests that assert what the spec, PRD, or user requested. If intent is ambiguous, ask before writing.
+
+❌ Separate parameters for two fields where one determines the other (e.g., `currency` and `currency_symbol`).
+✅ One parameter plus a constraint expressing the dependency.
+
+❌ Brittle, prose-y value names (`payment_with_apple_pay_using_new_token_flow`).
+✅ Compact partitions: `apple_pay`, `apple_pay_new_token`.
+
+❌ Manually add or remove rows after `lattice generate`.
+✅ If the generated set is wrong, fix the schema. Hand-editing rows breaks the coverage guarantee.
+
+## References
+
+- [references/modeling-rules.md](references/modeling-rules.md) — extraction heuristics, parameter selection, value partitioning, constraint guidance
+- [references/worked-examples.md](references/worked-examples.md) — concrete examples in this repo
+
+## Development Fallback
+
+In a checkout of the Lattice source where the package is not installed:
+
+```bash
+# Ruby checkout
+cat schema.json | ruby -Ilib exe/lattice validate
+cat schema.json | ruby -Ilib exe/lattice generate
+
+# Python checkout
+cat schema.json | PYTHONPATH=src python3 -m lattice validate
+cat schema.json | PYTHONPATH=src python3 -m lattice generate
+```
+
+To install or refresh this skill from the installed package:
+
+```bash
+lattice agent install-codex-skill
+```

data/lib/lattice/resources/codex/lattice-workflow/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Lattice Workflow"
+  short_description: "Generate pairwise coverage for plans, tests, and variants"
+  default_prompt: "Use $lattice-workflow to model interacting states or variant dimensions, extract a Lattice schema, validate it, generate pairwise rows, and use the rows to strengthen the plan, tests, fixtures, or visual review."
+
+policy:
+  allow_implicit_invocation: true

data/lib/lattice/resources/codex/lattice-workflow/references/modeling-rules.md

@@ -0,0 +1,52 @@
+# Modeling Rules
+
+Use this file when you are extracting a schema from code or prose and need tighter guardrails than the main skill body provides.
+
+## Parameter Selection
+
+- Scope one schema to one coherent behavior or rendering surface.
+  Good scopes: one feature, one service behavior, one workflow, one endpoint family, one state-machine slice, one component's variant space, one template family.
+  Bad default scope: the whole app.
+- Model the decisions that change behavior, not every field in a payload.
+- Prefer parameters that are visible in tests, UI branches, rendering branches, validation logic, template variants, component props, or feature flags.
+- Split large raw domains into behavioral partitions.
+  Good: `pay_range = present|absent`
+  Bad: every exact salary string
+- Avoid separate parameters for values that are already implied by another parameter unless the implication is partial and needs a constraint.
+
+## Value Selection
+
+- Values should be mutually exclusive and collectively useful for testing.
+- Keep domains small and meaningful. Most parameters should land in the 2-5 value range.
+- Normalize booleans as `true` and `false`.
+- For optional subordinate parameters, let `conditional` introduce `N/A`. Do not hand-add `N/A` unless the schema genuinely needs it as a first-class value.
+
+## Constraint Choice
+
+- `invalid_pair`: two assignments cannot coexist
+- `bidirectional`: one-to-one pairing; if A then B and if B then A
+- `forward_dep`: A requires B, but B may appear elsewhere
+- `conditional`: a child parameter only applies for some parent values
+- `forced`: this assignment set must appear in at least one generated row
+- `higher_order`: the invalid rule only appears when two or more antecedents are true
+
+Choose the smallest expressive type. If a rule can be represented as `invalid_pair`, do not use `higher_order`.
+
+Do not strip true constraints to get a smaller or easier unconstrained run. Do not generate nonsensical rows and mark them invalid downstream. Lattice's coverage accounting should run over valid interactions, so impossible combinations belong in the schema as `invalid_pair`, `forward_dep`, `bidirectional`, `conditional`, or `higher_order` constraints.
+
+## Extraction Process
+
+1. Choose the behavior or rendering surface you are modeling.
+2. Start from branches, validations, and business rules inside that scope.
+3. Convert prose like "only when", "must", "cannot", and "except" into candidate constraints.
+4. Remove cosmetic parameters that do not affect behavior.
+5. Check whether a missing value is really a separate partition or just noise.
+6. Validate the schema.
+7. Only after validation, generate scenarios.
+
+## Interpretation
+
+- Plan mode: each row becomes a review scenario or a missing decision in the plan.
+- Test mode: each row becomes a candidate setup matrix. Source the expected behavior from intent — user request, spec, PRD, or ticket — not from the code under test. If you cannot determine intent for a row, stop and surface the ambiguity to the user. Do not encode the current behavior and label it `bug_signal:` to hedge: characterization tests pass for the wrong reasons and hide the asymmetries Lattice is designed to expose. Example: if a mailbox accepts a spoofed `From:` header today, the assertion is still "rejects spoofed sender" — let the test fail and fix the code, do not invert the assertion to match the bug.
+- Variant mode: each row becomes a rendered variant, fixture, screenshot, visual diff input, contact-sheet item, or review checklist item.
+- Generated rows are not test names by themselves. The agent still needs to map them to application-specific assertions.

data/lib/lattice/resources/codex/lattice-workflow/references/worked-examples.md

@@ -0,0 +1,59 @@
+# Worked Examples
+
+These examples live in the repo-level `examples/` directory.
+
+## `examples/plan-mode-saved-search`
+
+Use when the agent starts from a feature discussion or PRD and needs a review checklist.
+
+- Input: `feature.md`
+- Schema transport: `model.yaml`
+- Output: `scenarios.json`
+
+## `examples/test-mode-checkout`
+
+Use when the agent starts from code and an existing test surface and needs missing cases.
+
+- Input: `code-notes.md`
+- Schema transport: `model.json`
+- Output: `scenarios.json`
+
+## `examples/three-way-notifications`
+
+Use when pairwise is not enough and the user explicitly wants 3-way coverage.
+
+- Input: `brief.md`
+- Schema transport: `model.yaml`
+- Output: `scenarios.json`
+
+## `examples/component-variant-matrix`
+
+Use when the agent starts from a visual component, rendering surface, template, or design-system story and needs compact review variants instead of every possible combination.
+
+- Input: `brief.md`
+- Schema transport: `model.yaml`
+- Output: `scenarios.json`
+
+## `examples/lattice-self-test`
+
+Use when you want a meta example of the harness extracting a schema for Lattice's own CLI surface and then using generated rows to drive CLI smoke tests.
+
+- Input: `brief.md`
+- Schema transport: `model.yaml`
+- Output: `scenarios.json`
+
+## `examples/agent-bootstrap-matrix`
+
+Use when you want a meta example of Lattice testing its own agent skill bootstrap behavior across harness detection, force/skip directives, target modes, and output formats.
+
+- Input: `brief.md`
+- Schema transport: `model.yaml`
+- Output: `scenarios.json`
+
+## `examples/schema-guidance-matrix`
+
+Use when you want a meta example of Lattice testing its own schema-discoverability guidance across help text, agent instructions, installed skill files, and validation errors.
+
+- Input: `brief.md`
+- Schema transport: `model.yaml`
+- Output: `scenarios.json`

data/lib/lattice/resources/generic/lattice-workflow/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: lattice-workflow
+description: Use when planning or testing behavior or variant surfaces with interacting states, roles, permissions, feature flags, modes, providers, optional fields, component props, rendering branches, template variants, config matrices, lifecycle states, combinatorial edge cases, pairwise coverage, or t-way coverage. Extract a Lattice schema, run the local Lattice CLI, and use generated rows to strengthen plans, tests, fixtures, rendered variants, or review matrices.
+---
+
+# Lattice Workflow
+
+Use this skill to keep the agent on extraction and interpretation while Lattice handles the combinatorics.
+
+## When To Use It
+
+- derive a combinatorial model from a feature or PRD
+- derive a test matrix from existing code
+- derive a variant matrix from a component, partial, template, design-system story, or config surface
+- convert edge cases into explicit parameter/value constraints
+- generate pairwise or 3-way scenarios without hand-enumerating combinations
+- render a compact visual review matrix instead of every possible variant
+- review a plan involving roles, permissions, modes, providers, feature flags, optional fields, component props, rendering branches, template variants, config matrices, or lifecycle states
+- find coverage gaps where bugs hide in interactions rather than single branches
+
+## When NOT To Use It
+
+- **Small enumerable spaces.** Fewer than ~10 total combinations — enumerate by hand.
+- **Independent dimensions.** No interactions can surface a bug; each parameter affects behavior independently.
+- **Non-deterministic systems.** The same input row won't produce repeatable output (e.g., testing LLM responses).
+
+## Minimal Example
+
+A schema (YAML on stdin):
+
+```yaml
+model_name: checkout
+parameters:
+  user: [signed_in, guest]
+  payment: [card, apple_pay, paypal]
+  cart: [empty, single, multi]
+constraints:
+  - invalid_pair: {payment: apple_pay, cart: empty}
+```
+
+One generated row (JSON):
+
+```json
+{"user": "guest", "payment": "card", "cart": "multi"}
+```
+
+The schema is the contract. The generated rows are the source of truth. The schema file is optional transport.
+
+## Preflight
+
+```bash
+command -v lattice >/dev/null 2>&1 && lattice --help >/dev/null
+```
+
+If it fails, install the Ruby gem from RubyGems (or add `gem "latticerb"` to the project Gemfile):
+
+```bash
+gem install latticerb
+```
+
+The Python implementation (`pipx install lattice-cli` from PyPI) is interchangeable — both produce byte-identical output for the same schema and seed.
+
+## Workflow
+
+1. **Extract the schema.** Choose one coherent interaction surface — one feature, one workflow, one service behavior, one endpoint family, one component's variant space, one template family, or one config matrix. Parameters represent independent decisions or state partitions. Values are meaningful partitions, not every literal in the codebase.
+
+2. **Encode constraints.** Use the smallest constraint type that matches the rule (see [Constraint Selection](#constraint-selection) below). Encode true impossibilities — do not strip them and mark invalid rows downstream.
+
+3. **Validate.**
+
+   ```bash
+   cat schema.json | lattice validate
+   ```
+
+4. **Generate.** Default to pairwise unless explicitly asked for higher strength.
+
+   ```bash
+   cat schema.json | lattice generate
+   ```
+
+5. **Interpret the output.** Plan mode: rows become plan revisions, missing decisions, review scenarios. Test mode: rows become assertions (see [Test Mode Discipline](#test-mode-discipline) below). Variant mode: rows become fixtures, rendered variants, screenshots, visual-diff inputs.
+
+## Constraint Selection
+
+| Rule shape | Use |
+|---|---|
+| Two assignments cannot coexist | `invalid_pair` |
+| One-to-one pairing (if A then B and if B then A) | `bidirectional` |
+| A requires B, but B may appear elsewhere | `forward_dep` |
+| Child parameter only applies for some parent values | `conditional` |
+| This assignment set must appear in at least one row | `forced` |
+| Rule only breaks under three or more antecedents | `higher_order` |
+
+Prefer the smallest constraint type that matches. Use `conditional` instead of hand-writing `N/A` values.
+
+## Test Mode Discipline
+
+Source expected behavior from intent — the user's request, a spec, a PRD, a ticket, or explicit reasoning about what the system *should* do. **The code under test is evidence, not truth.** If intent is ambiguous for a row, stop and ask the user.
+
+Do not silently encode current behavior and hedge with `bug_signal:`-style annotations. That produces characterization tests, which lock in the implementation (bugs included) instead of catching divergence from intent. The asymmetries Lattice is designed to expose disappear when the test suite mirrors the same mental model as the code.
+
+## Common Pitfalls
+
+❌ Strip constraints to make generation easier, then mark impossible rows invalid after the fact.
+✅ Encode the constraint in the schema, regenerate. Encoding constraints changes the coverage universe to valid interactions — that's the point.
+
+❌ Write tests that assert what the code currently does.
+✅ Write tests that assert what the spec, PRD, or user requested. If intent is ambiguous, ask before writing.
+
+❌ Separate parameters for two fields where one determines the other (e.g., `currency` and `currency_symbol`).
+✅ One parameter plus a constraint expressing the dependency.
+
+❌ Brittle, prose-y value names (`payment_with_apple_pay_using_new_token_flow`).
+✅ Compact partitions: `apple_pay`, `apple_pay_new_token`.
+
+❌ Manually add or remove rows after `lattice generate`.
+✅ If the generated set is wrong, fix the schema. Hand-editing rows breaks the coverage guarantee.
+
+## References
+
+- [references/modeling-rules.md](references/modeling-rules.md) — extraction heuristics, parameter selection, value partitioning, constraint guidance
+- [references/worked-examples.md](references/worked-examples.md) — concrete examples in this repo
+
+## Development Fallback
+
+In a checkout of the Lattice source where the package is not installed:
+
+```bash
+# Ruby checkout
+cat schema.json | ruby -Ilib exe/lattice validate
+cat schema.json | ruby -Ilib exe/lattice generate
+
+# Python checkout
+cat schema.json | PYTHONPATH=src python3 -m lattice validate
+cat schema.json | PYTHONPATH=src python3 -m lattice generate
+```
+
+To install or refresh a copy of this skill from the installed package:
+
+```bash
+lattice agent install-skill /path/to/harness/skills/lattice-workflow
+```
+
+For harnesses that don't use skill directories, copy the output of:
+
+```bash
+lattice agent instructions
+```
+
+into the harness memory, system instruction, rule file, or project instruction mechanism.