Configuration Reference

.lattice/config.yaml is the central config file for a Lattice-enabled project. It maps logical keys to project-specific documents that atoms and molecules load at runtime. The file is optional — all skills work out of the box with embedded defaults. Add keys only when you want to customize a skill's behavior. See how-it-works.md for how the resolution algorithm works.

File Structure

version: 1
language: go
paths:
  language_idioms: .lattice/standards/language-idioms.md
  knowledge_base: .lattice/standards/knowledge-base.md
  clean_code: .lattice/standards/clean-code.md
  architecture: .lattice/standards/architecture.md
  ddd_principles: .lattice/standards/ddd-principles.md
  test_quality: .lattice/standards/test-quality.md
  secure_coding: .lattice/standards/secure-coding.md
  review_standards: .lattice/standards/review-standards.md
  requirement_standards: .lattice/standards/requirement-standards.md
  context_base: .lattice/context/
  operational_learnings: .lattice/learnings/operational-learnings.md

architecture_mode: clean
requirements_layout: sharded

additional_instructions:
  design_blueprint:
    - Suffix the context doc name with the platform: {feature}-ios or {feature}-android.

Top-level Fields

Field	Type	Description
version	integer	Schema version. Currently 1.
language	string	Project's primary language identifier (e.g., go, rust, python, java, typescript, csharp). Set by lattice-init or language-idioms-refiner; informational metadata describing the project. Atoms do not read this key — language adaptation is driven entirely by paths.language_idioms.
paths	map	Logical key → file path mappings. All keys are optional.
architecture_mode	string	Architecture enforcement mode. clean (default) or custom. See below.
requirements_layout	string	Requirements folder layout. sharded (current) or flat (legacy, pre-migration). See below.
additional_instructions	map	Molecule key → list of short workflow instructions, applied with highest priority when that molecule runs. See below.

paths Keys

Key	Purpose	Produced by	Default path	Consumed by	Mode
language_idioms	Language-specific patterns — error handling philosophy, type system, naming conventions, testing idioms, parameter design, dependency management. Cross-cutting: consumed by multiple atoms.	language-idioms-refiner	.lattice/standards/language-idioms.md	clean-code, test-quality, secure-coding, domain-driven-design, architecture atoms	standalone (no overlay/override — always complete)
knowledge_base	Project identity — tech stack, architecture, conventions, trusted sources. No embedded default; every project is unique.	knowledge-priming-refiner	.lattice/standards/knowledge-base.md	knowledge-priming atom	override (standard)
clean_code	Code craftsmanship rules — function size, naming, complexity, error handling.	clean-code-refiner	.lattice/standards/clean-code.md	clean-code atom	overlay (recommended)
architecture	Architecture standards — layer structure, dependency rules, structural validation. Used by both clean architecture mode and custom architecture mode.	architecture-refiner	.lattice/standards/architecture.md	architecture atom	overlay (clean mode) or override (custom mode)
ddd_principles	Tactical DDD patterns — aggregate design, entity/value object rules, domain services, domain events.	ddd-refiner	.lattice/standards/ddd-principles.md	domain-driven-design atom	overlay (recommended)
test_quality	Test structure and quality rules — AAA structure, isolation, assertion patterns, naming conventions.	No refiner — write by hand or via /knowledge-priming-refiner for general conventions	.lattice/standards/test-quality.md	test-quality atom	overlay (recommended)
secure_coding	Trust boundaries and injection prevention — input validation, secrets management, authorization, error message policies.	No refiner — write by hand or via /knowledge-priming-refiner for general conventions	.lattice/standards/secure-coding.md	secure-coding atom	overlay (recommended)
review_standards	Review process configuration — atom loading policy, severity classification, report format, insight capture. Molecule-level config, not atom-level.	review-refiner	.lattice/standards/review-standards.md	review molecule	overlay (recommended)
requirement_standards	Requirement standards — epic/feature definitions, scenario structure, AC format, priority notation, status workflow, and naming conventions. Consumed by the requirement-quality atom via config resolution; the requirement-forge molecule composes that atom.	requirement-forge-refiner	.lattice/standards/requirement-standards.md	requirement-quality atom	overlay (recommended)
context_base	Directory path for per-feature living documents. Unlike all other keys, this is a directory, not a file.	(none — managed by context-anchoring atom)	.lattice/context/	context-anchoring atom	N/A
operational_learnings	Operational learnings file — accumulated patterns from practice (design, implementation, review, repair). Living document managed by learning-harvest atom, not a standards doc.	(none — managed by learning-harvest atom)	.lattice/learnings/operational-learnings.md	learning-harvest atom	N/A (append-only living document, no overlay/override)

Path values: relative paths resolve from the repo root. Absolute paths and ~ work too, including locations outside the repo — your agent host must allow reading and writing there. The requirements folder and the review log have no paths key; to move them, add a line under additional_instructions for the molecule that writes them (recipes in docs/practical-guide.md).

architecture_mode Key

Controls which enforcement rules the architecture atom loads internally. This key determines the atom's behavior — it does not affect what other atoms or molecules do.

Value	Behavior
clean (default if absent)	The architecture atom loads clean architecture enforcement rules (references/clean-architecture.md) and uses references/clean-architecture-defaults.md as the base content. If paths.architecture is set, the custom document is applied as overlay or override on top of the clean-architecture defaults.
custom	The architecture atom loads custom architecture enforcement rules (references/custom-architecture.md) and reads the team's document at paths.architecture as the sole content. No embedded defaults — the document IS the standard.

When to use each:

• Team uses clean architecture (default, no config needed): Atom loads built-in clean-arch rules. No setup required.
• Team uses clean architecture with customizations: Run /architecture-refiner, choose "Clean Architecture", customize sections. Produces a document with mode: overlay or mode: override. Config: paths.architecture set, architecture_mode absent (defaults to clean).
• Team uses hexagonal, modular monolith, or custom style: Run /architecture-refiner, choose the appropriate style. Produces a document with mode: override. Config: paths.architecture set, architecture_mode: custom.

The architecture-refiner sets architecture_mode automatically based on the user's style choice.

requirements_layout Key

Controls whether requirement-forge treats .lattice/requirements/ as sharded-by-epic or expects the legacy flat form.

Value	Behavior
sharded (current)	index.md is a thin apex; each epic has its own file at epics/{epic-slug}.md with a generated feature table listing name and summary only — no status, priority, or dependency columns. requirement-forge writes only feature files during normal work — epic and index rollups regenerate only when a feature is added, removed, or renamed under an epic, never on a status/priority/dependency change; those fields live solely in each feature file's own frontmatter.
flat / absent with a pre-existing index.md	Legacy layout — every epic's feature table lives inline in index.md itself. requirement-forge will not attempt migration; it points the user at /lattice-init to check for and apply available upgrades.

Set automatically — by requirement-forge when it creates the first epic in a new project, or by lattice-init's migration step for existing projects. Not intended to be hand-edited.

Requirements do not have to live in this repo at all — see docs/practical-guide.md for teams that keep specs in a separate repo or track requirements in an external system instead.

additional_instructions Key

A few lines of your own workflow habits for a molecule — what to read first, how to name its output, which extra check to run — loaded only when that molecule runs. One line or a list. Supported keys: requirement_forge, design_blueprint, code_forge, refactor_safely, bug_fix, review, architecture_compass. Setup molecules (lattice-init, refiners-update) do not read it.

additional_instructions:
  design_blueprint:
    - Suffix the context doc name with the platform: {feature}-ios or {feature}-android.
    - Before designing, read the other platform's context doc if it exists.
    - In the handoff, name the reviews this design needs: eng review always, design review if it has a UI.

Rule	Behavior
Highest priority	These lines sit on top of every other layer — the molecule's own steps, approval gates, and STOP rules, the atoms it composes, your standards documents, and operational learnings. On conflict, the line wins. A line can add a gate or remove one; that is your call.
Visible	The molecule shows the loaded lines verbatim at session start, so anyone reading the session can see what changed its behavior.
Molecules only	Atoms are shared by many molecules; changing one would quietly change all of them. There is no atom-level key; a line can still override an atom's rule, but only inside that molecule's sessions.

Nothing below is enforced — the molecule applies whatever you write. It is advice for keeping the file useful.

Choosing where an instruction goes

The three places load at different times and serve different purposes. Pick by asking two questions, in order:

1. Does it need to apply when this molecule is not running? (a plain chat, a quick edit, another molecule) → AGENTS.md / CLAUDE.md. Your agent instruction file loads in every session, cross-cutting. Lattice never reads or replaces it.
2. Does it shape the artifact or the session? If it changes what the output contains (spec format, ticket ID on every spec, coding or architecture rules) → usually a standards document under .lattice/standards/, via the matching refiner, so every molecule using that atom picks it up; a short rule meant only for this molecule's runs can live here. If it changes how this molecule's session runs (what to read first, how to name the output, which extra check or review to call for) → additional_instructions.{molecule}.

	AGENTS.md / CLAUDE.md	additional_instructions.{molecule}	.lattice/standards/*.md
Scope	Every agent session, cross-cutting	One molecule's sessions only	The atom(s) that read the document, in every molecule that composes them
Loads	Always	Only when that molecule runs	When the atom runs
Holds	Repo-wide habits: build/test commands, commit and branch rules, tone, "never touch X"	Workflow habits for that molecule: inputs to read, output naming, extra checks, handoff steps	Durable rules for what the artifact must look like
Size	Whatever your host tolerates	A handful of lines — they load on every run	A full document
Example	"Run make test before saying done."	"Before designing, read the other platform's context doc if it exists."	"Every spec carries the Jira ticket ID."

Common mistakes

• Copying AGENTS.md / CLAUDE.md lines here. If the agent already loads it every session, repeating it costs tokens and creates a second source that drifts.
• Moving cross-cutting rules here to save tokens. A line under design_blueprint is invisible to every other session — the agent will not follow it during a quick fix or a different molecule.
• Growing a full rule set here. A few standard lines are fine; once it reads like a standards document, a refiner's document is easier to maintain and shared by every molecule that uses the atom.
• Same line under several molecules. If it applies to every Lattice workflow and beyond, it belongs in AGENTS.md / CLAUDE.md.

Not hand-edited by any skill — write and maintain it yourself.

Custom Document Frontmatter

Standards documents (the files pointed to by paths keys) declare their merge mode in YAML frontmatter:

---
mode: overlay
---

Mode	Behavior
overlay (default)	Custom document's sections are applied on top of the atom's embedded defaults. Sections are matched by heading — a custom section replaces the matching default section; new sections are appended.
override	Custom document fully replaces the atom's embedded defaults. Use when your standards are fundamentally different and you want complete control.

knowledge_base is always override — project identity is unique and replaces generic defaults entirely. Custom architecture documents (architecture_mode: custom) are also always override — there are no defaults to overlay onto. language_idioms is always standalone — there are no embedded language defaults in atoms; the document provides the complete language context that atoms reference by section heading.

Creating and Updating Config

Via a refiner (recommended): Run the corresponding refiner skill (e.g., /architecture-refiner). The guided interview produces the standards document and writes the config key automatically.

By hand: Create .lattice/config.yaml at the repo root and add keys pointing to documents you have written or will write. Re-run a refiner or edit the standards document directly whenever your standards evolve.