Compose LLM Agent Instructions

Problem: Teams need to standardise LLM agent instructions across different repository types (Kotlin services, TypeScript frontends, TDD projects, Hexagonal Architecture projects) whilst allowing each repository to use the appropriate mix of instruction sets for its domain.

Solution: Create modular instruction components for different domains and practices, then compose them in the Typeflows Builder to generate standardised instruction files for each repository type.

Typeflows supports the following LLMs products:

• Agents: AGENTS.md
• Claude: CLAUDE.md, Command MD files, Agents files
• Cursor: Cursor rules files
• Junie: guidelines.md, .aiignore
• Gemini: GEMINI.md

Markdown as Components

Create focused components that can load content from resource files or generate it programmatically, making them easy to version and maintain:

class KotlinInstructions : Builder<MarkdownContent> {
	override fun build() = MarkdownContent.fromResource(KotlinInstructions::class.java, "kotlin.md")
}

class TDDInstructions : Builder<MarkdownContent> {
	override fun build() = MarkdownContent.of("## Test-Driven Development") +
		MarkdownContent.of(
			"""
			- Write tests before implementing functionality
			- Follow the Red-Green-Refactor cycle
			"""
		)
}

class HexagonalInstructions : Builder<MarkdownContent> {
	override fun build() = MarkdownContent.of(
		"""
			## Hexagonal Architecture
			
			- Separate core business logic from external concerns
			- Use ports and adapters for external integrations
			- Keep dependencies pointing inward to the domain
			- Test business logic independently of infrastructure
		"""
	)
}

	class KotlinInstructions implements Builder<MarkdownContent> {
		@Override
		public MarkdownContent build() {
			return MarkdownContent.fromResource(KotlinInstructions.class, "kotlin.md");
		}
	}

	class TDDInstructions implements Builder<MarkdownContent> {
		@Override
		public MarkdownContent build() {
			return MarkdownContent.of("## Test-Driven Development")
				.plus(MarkdownContent.of("""
					- Write tests before implementing functionality
					- Follow the Red-Green-Refactor cycle"""
				));
		}
	}

	class HexagonalInstructions implements Builder<MarkdownContent> {
		@Override
		public MarkdownContent build() {
			return MarkdownContent.of("""
				## Hexagonal Architecture
				
				- Separate core business logic from external concerns
				- Use ports and adapters for external integrations
				- Keep dependencies pointing inward to the domain
				- Test business logic independently of infrastructure
				""");
		}
	}

Composing in Typeflows

Compose instruction components to create AGENTS.md files tailored to a specific repository:

class Typeflows : Builder<TypeflowsGitHubRepo> {
	override fun build() = TypeflowsGitHubRepo {
		files += Agents.of(
			KotlinInstructions().build(),
			TDDInstructions().build(),
			HexagonalInstructions().build()
		)
	}
}

public class Typeflows implements Builder<TypeflowsGitHubRepo> {
	@Override
	public TypeflowsGitHubRepo build() {
		return TypeflowsGitHubRepo.create(repo -> {
			repo.files.add(Agents.of(
				new KotlinInstructions().build(),
				new TDDInstructions().build(),
				new docs.how_to.composing_llm_agent_instructions.Instructions.HexagonalInstructions().build()
			));
		});
	}
}

Exported AGENTS.md

When exported, Typeflows merges the instruction components based on their sections to create a tailored instruction file:

## Kotlin Development

- Use idiomatic Kotlin patterns and conventions
- Prefer data classes for simple data containers
- Use sealed classes for restricted hierarchies
- Leverage extension functions for utility methods
- Follow Kotlin coding conventions for naming

## Test-Driven Development

- Write tests before implementing functionality
- Follow the Red-Green-Refactor cycle
- Aim for high test coverage on business logic
- Use descriptive test names that explain behaviour
- Mock external dependencies in unit tests

...

Benefits

• Standardisation: Each instruction domain (Kotlin, TDD, Hexagonal) is maintained once and shared across relevant repositories
• Composition: Different repository types get exactly the instruction mix they need through flexible composition
• Consistency: Teams working with the same technology stack get identical guidance
• Maintainability: Updates to practices propagate automatically to all repositories using that component
• Extensibility: It’s composition all the way down - instruction components can themselves be composed from smaller parts

Teams can share instruction components as versioned packages, enabling organisation-wide standardisation whilst maintaining the flexibility to compose the right mix for each repository type.