Choosing Your Methodology

LumenFlow is opinionated by default but flexible by design. The software_delivery.methodology configuration lets you choose how strict your testing and architecture practices should be.

Why Methodology Configuration?

Different teams have different needs:

• Greenfield projects benefit from strict TDD and hexagonal architecture
• Legacy migrations may need a gentler test-after approach during transition
• Prototype/spike work may temporarily disable enforcement

Rather than fight the framework, configure it to match your current situation.

Testing Methodologies

TDD (Default)

Test-Driven Development: write tests before implementation.

software_delivery:
  methodology:
    testing: 'tdd'

Characteristics:

• Tests written BEFORE implementation code
• RED-GREEN-REFACTOR cycle enforced in agent prompts
• 90% coverage threshold (blocks on failure)
• Automated test diff evidence defaults to block for feature and bug WUs

Best for:

• New features with clear requirements
• Teams committed to test-first development
• Production-critical code paths

Test-After

Write implementation first, then add tests as the change stabilizes.

software_delivery:
  methodology:
    testing: 'test-after'

Characteristics:

• Implementation can proceed without tests
• 70% coverage threshold (warns but does not block)
• Automated test diff evidence defaults to off
• Test gates still run when configured; add tests as you touch code
• More flexible for exploratory work

Best for:

• Legacy code migration
• Teams transitioning to TDD
• Rapid prototyping with deferred test coverage

None

Minimal testing enforcement.

software_delivery:
  methodology:
    testing: 'none'

Characteristics:

• No testing methodology in agent prompts
• 0% coverage threshold (no enforcement)
• Automated test diff evidence defaults to off
• Tests optional but still recommended

Best for:

• Spike/research work
• Documentation-only projects
• Non-production experiments

Caution

Even with testing: 'none', the test ratchet may prevent regressions if enabled. New test failures can still block gates regardless of methodology.

Architecture Methodologies

Hexagonal (Default)

Ports and Adapters architecture with strict dependency rules.

software_delivery:
  methodology:
    architecture: 'hexagonal'

Characteristics:

• Agent prompts include hexagonal architecture guidance
• Ports-first development encouraged
• Application layer never imports infrastructure

Best for:

• Complex domain logic
• Projects requiring extensive testing
• Teams familiar with DDD patterns

Layered

Traditional layered architecture.

software_delivery:
  methodology:
    architecture: 'layered'

Characteristics:

• Simpler three-tier structure guidance
• Less strict about dependency direction
• Easier to understand for newcomers

Best for:

• Simpler CRUD applications
• Teams new to architecture patterns
• Rapid development without complex domain logic

None

No architecture guidance.

software_delivery:
  methodology:
    architecture: 'none'

Characteristics:

• No architecture-specific prompting
• Full flexibility in code organization

Best for:

• Small scripts and utilities
• Projects with existing architecture
• Teams with strong internal conventions

Overriding Template Defaults

Each methodology sets sensible defaults, but you can fine-tune them:

software_delivery:
  methodology:
    testing: 'tdd'
    architecture: 'hexagonal'
    overrides:
      coverage_threshold: 85 # Slightly lower than TDD default of 90
      coverage_mode: 'warn' # Warn instead of block

Override Fields

Field	Description
coverage_threshold	Minimum coverage percentage (0-100)
coverage_mode	block (fail gates), warn, or off

Methodology vs Gates

The methodology section gives you defaults. For fine-grained control, tune software_delivery.gates directly:

software_delivery:
  methodology:
    testing: 'test-after'

  gates:
    enableCoverage: true
    minCoverage: 75
    tdd_diff_evidence:
      mode: block
      applies_to_types:
        - feature
      exempt_paths:
        - '.github/workflows/**'

Precedence (highest to lowest):

1. CLI flags (e.g., --coverage-mode=warn)
2. Explicit gates.* configuration
3. methodology.overrides
4. Methodology template defaults

Automated Test Diff Evidence Defaults

Methodology and the automated test diff gate are related, but they are not the same thing. software_delivery.methodology.testing chooses the default behavior for software_delivery.gates.tdd_diff_evidence:

• tdd => mode: block
• test-after => mode: off
• none => mode: off

Teams can then override the gate directly if they want changed-test evidence for only some WU types or only some paths.

Migration Examples

From Strict TDD to Test-After

Gradually relaxing enforcement for a legacy migration:

# Phase 1: Keep TDD but warn instead of block
software_delivery:
  methodology:
    testing: 'tdd'
    overrides:
      coverage_mode: 'warn'

# Phase 2: Switch to test-after
software_delivery:
  methodology:
    testing: 'test-after'

# Phase 3: Return to TDD once migration complete
software_delivery:
  methodology:
    testing: 'tdd'

Enterprise Strictness

Maximum enforcement for regulated environments:

software_delivery:
  methodology:
    testing: 'tdd'
    architecture: 'hexagonal'
    overrides:
      coverage_threshold: 95

  gates:
    enableSafetyCriticalTests: true
    enableInvariants: true

Minimal Setup for Prototypes

Quick exploration without ceremony:

software_delivery:
  methodology:
    testing: 'none'
    architecture: 'none'

  gates:
    enableCoverage: false

Summary

Methodology	Coverage	Coverage Mode	Test Diff Evidence Default	Use Case
tdd	90%	block	block	Production code
test-after	70%	warn	off	Legacy migration
none	0%	off	off	Spikes and prototypes

---

Next Steps

• Configuration Reference - All configuration options
• Gates Reference - Gate commands and flags
• Team Workflow - Multi-developer patterns