/architecture-refiner

name: architecture-refiner
description: "Facilitate a structured conversation to define architecture principles for a repository. Supports multiple architecture styles: clean architecture (default), hexagonal / ports & adapters, modular monolith, or custom. Produces a formal architecture document that the corresponding atom will use. Use when setting up a new project, defining architecture standards, or when the user says 'setup architecture', 'define layers', 'architecture principles', 'help me define my architecture', 'hexagonal architecture', 'modular monolith', 'ports and adapters', or 'define my architecture style'."

Architecture Refiner

Step 0: Style Selection

Before anything else, ask the user which architecture style their team uses:

"What architecture style does your team use?

1. **Clean Architecture** (default) — layers (Domain, Application, Interface, Infrastructure), dependency inversion, command/query separation 2. **Hexagonal / Ports & Adapters** — core domain surrounded by ports, adapters on the outside 3. **Modular Monolith** — vertical slices, each module owns its own layers 4. **Custom / Define from scratch** — you describe the layers and rules"

**Branching:**

• **Option 1** → proceed to the clean architecture flow below (existing interview). Template: `./assets/template-clean-arch.md`. Output: `.lattice/standards/architecture.md`. Config key: `paths.architecture`. No `architecture_mode` key needed (defaults to `clean`).
• **Options 2–4** → proceed to the generic architecture flow. Template: `./assets/template-generic.md`. Output: `.lattice/standards/architecture.md`. Config key: `paths.architecture`. Additionally, set `architecture_mode: custom` in `.lattice/config.yaml`.

The rest of this document describes the **clean architecture flow** (Option 1). For the **generic flow** (Options 2–4), read `./assets/template-generic.md` and follow its `<!-- INTERVIEW GUIDANCE: -->` comments. The facilitation approach, conversation style, output assembly, and document quality checks below apply to both flows — substitute the appropriate template, output path, and config key.

What This Produces

**For clean architecture (Option 1):**

• **Output**: `.lattice/standards/architecture.md` (or custom path from `.lattice/config.yaml` → `paths.architecture`)
• **Two modes**:
• **Overlay** (`mode: overlay`): A slim document containing only sections that differ from the defaults. The architecture atom reads its embedded clean-architecture defaults first, then applies this document's sections on top. This is the expected common case.
• **Override** (`mode: override`): A comprehensive standalone document that fully replaces the atom's embedded defaults. For teams that want to define clean architecture from scratch.
• **Default mode**: Overlay -- produces only what the user wants to change
• **Config key**: `paths.architecture` in `.lattice/config.yaml`
• **Template**: Read `./assets/template-clean-arch.md` for the full document structure, default content, and interview guidance comments

**For other styles (Options 2–4):**

• **Output**: `.lattice/standards/architecture.md` (or custom path from `.lattice/config.yaml` → `paths.architecture`)
• **Mode**: Always `override` — there are no embedded defaults to overlay onto for non-clean-architecture styles
• **Config key**: `paths.architecture` in `.lattice/config.yaml`
• **Additional config**: Sets `architecture_mode: custom` in `.lattice/config.yaml`
• **Template**: Read `./assets/template-generic.md` for the document structure and interview guidance comments

Before You Begin

Check for existing documents

Before starting the interview, check whether a custom document already exists:

1. Read `.lattice/config.yaml` — check `paths.architecture`. 2. If the relevant path exists (based on the style selected in Step 0), read that file. Ask the user:

• "You already have a custom architecture document. Would you like to **revise** it (update specific sections), **start fresh** (new interview), or **add to it** (add new sections)?"
• Revise: Load the existing document, walk through only the sections the user wants to change, and update in place.
• Start fresh: Proceed with the full interview flow below.
• Add to it: Skip to the "New Sections" part of the interview.

3. If no config or no existing document, proceed with the full interview flow.

Scan the repository

Look for signals that inform the conversation:

• **Directory structure**: Does `src/` (or equivalent) already have layers? What are they named?
• **Existing patterns**: Are there existing controllers, services, repositories, providers? What naming conventions are in use?
• **DI patterns**: Is there a DI container, manual injection, or framework-provided injection?
• **Architecture docs**: Any existing architecture documentation (ADRs, README sections)?
• **Framework**: What framework is in use? (NestJS, Spring, Django, etc.) This affects naming conventions and common patterns.

Share relevant findings with the user at the start: "I noticed your project already has [X structure]. I'll use that as context."

If the project is new with no code, proceed with pure defaults as the starting point.

Choosing the Mode

The first decision in the conversation. Present the three options:

"How would you like to define your architecture principles?

1. **Customize specific sections** (overlay) — Keep the defaults and change only what differs for your project. This produces a slim document. Most teams choose this. 2. **Define everything from scratch** (override) — Walk through all sections and produce a comprehensive standalone document. 3. **Add project-specific sections only** (overlay with additions) — Keep all defaults as-is and add new sections for your team's specific rules.

The defaults cover standard clean architecture well. Option 1 is recommended unless your architecture is fundamentally different."

Map the choice:

• Options 1 and 3 → `mode