Idea: per-molecule additional instructions in config

[techygarg]

This came out of #46 (one product, two native apps), but I think it applies more broadly.

The problem

Lattice molecules (requirement-forge, design-blueprint, code-forge, etc.) follow a fixed workflow on top of atoms and refiners. That's on purpose: levels, approval gates and contracts are the core, and they shouldn't change per project.

But every setup has small habits that sit outside that core:

• "Suffix the blueprint with the platform: {feature}-ios / {feature}-android."
• "Before designing, also look at the backend repo in ../api."
• "Our requirements live in Jira, always link the ticket ID."

Today you either repeat these in every session, or you're tempted to edit the skill itself. Neither is great. They're too small and too local for a refiner, and they definitely don't belong in the framework.

The idea

A small, optional section in .lattice/config.yaml where you add a few lines of your own instructions per molecule. The molecule reads them alongside its standard rules.

additional_instructions:
  requirement_forge:
    - One requirement per feature, shared by iOS and Android. Never platform-specific.
  design_blueprint:
    - Suffix the blueprint with the platform: {feature}-ios or {feature}-android.
    - Before designing, read the other platform's blueprint and decision log if it exists.
  code_forge:
    - If a change affects what the product does, flag it so the requirement gets updated.

What it is, and what it isn't

It's a light touch: a bit of local context on top of how a molecule already works.

• Adds to the core, never replaces it. It can't skip a level, bypass an approval gate or override a STOP rule. If an instruction conflicts with the core, the core wins.
• Molecules only. Atoms are shared by many molecules, so tweaking one would quietly change all of them. Keeping this at molecule level keeps the effect visible and predictable.
• Not a replacement for refiners. Refiners hold your durable standards (architecture, clean code, DDD). This is for workflow habits. If it starts looking like a rule set, it probably belongs in a refiner.
• Short by design. These lines load every time the molecule runs, so a few lines per molecule, not pages.

Open questions

Haven't thought about implementation yet. I'd like to hear from you first:

1. What would you actually put here? Real examples from your setup would help the most.
2. Is molecule level enough, or do you find yourself wanting this for something else?
3. Any case where this would make things worse, e.g. teams drifting from each other's workflows?

Drop your thoughts below 👇

[ShuratCode]

I checked this idea against our team's lattice data, so the examples below are real. The numbers come from one project: 231 design context docs, 319 specs, our learnings file, and the agent instruction files in the repo.

1. What we would put here

Most of it already exists in our repo's AGENTS.md. The agent loads that file in every session, even when no molecule runs. So for us the main gain is cost: these lines would load only when the molecule runs.

additional_instructions:
  design_blueprint:
    - In the handoff, name the plan reviews this change needs: eng review always, design review if it has a UI, devex review if it has an API or CLI.
    - Frontend designs build on the baseline mocks in design/baseline/.
    - Never write a learning without a clear yes for each bullet.
  code_forge:
    - Branch first, named feat/<name>-R-<ticket>.
    - Run the PR size check before review. If it is large, split first.
    - Never write a learning without a clear yes for each bullet.

Two things surprised me.

First, our most common per-session instruction was "start at Level 2, the spec already covers Level 1". 30 of the 36 entry decisions in our design docs start at Level 2. #49 makes this the default, so we no longer need a line for it.

Second, requirement_forge gets almost nothing. Our one repeated habit there is "every spec carries the ticket ID" (304 of 319 specs). That rule already sits in our requirement standards, written by the refiner. Your Jira example landed in the same place for us. This gave me a simple test for the line between the two: if it shapes the artifact, it goes in a refiner. If it shapes the session (what to read first, which reviews to run, how to hand off), it goes here.

2. Is molecule level enough?

Mostly yes. I agree it should not reach atoms. One gap: some lines apply to several molecules. "Commit the artifact and hand off in one sentence" and "never write a learning without approval" apply to design-blueprint, code-forge and bug-fix. A shared key such as all_molecules would save copying them three times. It still loads only when a molecule runs, so it keeps your reason for leaving atoms out.

Folder scope came up too. The baseline mocks line matters only for frontend work. Our folder-level AGENTS.md handles that well today, so I would not add path scoping now.

3. Where this could make things worse

Gates. As I wrote on #49, one person on our team takes a ticket end to end, often within a few hours. The context is fresh, so owners sometimes see the per-level stops as extra round trips. In 2 of our 231 design docs, the owner asked to run Levels 2 to 4 with no stop between them. In 6 more, the owner approved all levels in one go (5 features of one epic in one batch, and one "L1 to L4 in one pass"). The core says to stop at every level. The agent followed the owner each time. So in practice the person in the session already wins over the core.

What happened next matters. In one of the two no-stop docs, later reviews corrected two design decisions (one at Level 2, one at Level 3). Neither no-stop session recorded an eng plan review. Skipping the stops worked only because review steps after the design caught the mistakes.

So I think "the core wins" is right for config. A config line applies to every run and every teammate, and nobody sees it. It should never relax a gate. It should be able to add one: our team adds gates, not removes them (code-forge stops unless the doc is approved, and each learning needs a yes). But the session case is real, and I would make it official. Let the owner ask for batch mode in the session. The molecule logs it in the Decisions Log with the reason, and it still asks for the final approval. Our two no-stop docs did exactly this by hand.

Three smaller risks:

• A third source. We already keep AGENTS.md and a pipeline doc, with a line that says which wins when they differ. Config would be a third place. It would help if lattice-init or review warned when a line repeats a refiner or an agent file.
• Growth. Our learnings file also loads in every session. We tried to tighten it in place, and it grew past its starting size in 26 days. Only moving entries into standards kept it small. Expect the same here. A hard limit per molecule, plus a hint to move repeated lines to a refiner, would help.
• Visibility. The molecule should say at the start which extra lines it loaded. Otherwise a teammate cannot tell why two sessions behaved differently.

4. The review step from #49

On #49 I said what we need most is a way to bring a second person into the design review when it matters. The data adds two things.

First, a teammate's review leaves no trace in the design. For big decisions we share a doc with the team, but that happens outside lattice. Only one of our 231 design docs records a draft shared before code. The other human reviews we record happen on the PR, after the code exists.

Second, a line in an agent file is not enough, even for the self-review. We wrote "eng review always" into our agent file on 2026-09-22. Since then, 23 of 30 designs record one, and 7 record no plan review at all. The 7 include both no-stop sessions. When a session skips the stops, the review gets skipped too.

A line in additional_instructions can say who should review and when. It cannot make the molecule wait for that person, record what they said, or send a changed requirement back to the spec. So I think this needs a hook point, not a new molecule. The review is a step of design, not a workflow of its own. I picture a named review step after Level 4 and before code-forge starts. The team chooses what runs there: a teammate, a plan review skill, or both. The owner can mark a design for team review, and then the molecule waits. It logs the reviewer and the result in the Decisions Log. If the review changed the requirement, it points to the spec update, so we stop doing it by hand.

additional_instructions and this hook fit together. The instruction says who reviews what. The hook makes the review happen and leaves a record.

[techygarg]

@kkumawat333 : do you have any perspective from your team usage ?

[kkumawat333]

@techygarg Thank you for asking. I went through the #46 discussion and kind of understand the problem OP came up with.

We have taken this totally differently in our use case. We have created a Wrapper skill around requirement-forge and it helps us to get the specs written in a specific format that we can use it to share with larger team for Architecture Design Review session against the new requirement. We are doing this all in a mono-repo. We are then creating requirements for each repo based on the earlier session & then run a lattice's SDLC pipeline.

As what you have suggested about adding additional instructions block. I think this will be very helpful not sure how much it would help them. I would be definitely using this in my setup for other usecases though.

1. What we would put here

We would put instructions of all the repos it should consider before running a molecule + naming conventions to follow for the epics and feature.

2. Is molecule level enough?

Yes, I think this is perfect sweet spot and shouldn't expand to atoms. This will make atoms more complex & may affect molecules.

3. Where this could make things worse

I think this could go worse if Devs start using this space as a replacement for Agents.md file. Maybe a clear guidance on how and when to use it would help devs to only use it when required.