@clubmatto/ai-kit 0.0.6 → 0.0.7

package/.agents/disabled/spring-boot.md

@@ -0,0 +1,5 @@
+# Spring Boot
+
+Follow Spring Boot best practices.
+
+{{FOOTER}}

package/CHANGELOG.md

@@ -20,4 +20,4 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
-- Initial release
+- Initial release

package/README.md

@@ -4,13 +4,15 @@
 [![npm version](https://img.shields.io/npm/v/@clubmatto/ai-kit)](https://www.npmjs.com/package/@clubmatto/ai-kit)
 [![License: MIT](https://img.shields.io/npm/l/@clubmatto%2Fai-kit)](/LICENSE)
 
-The AI configuration CLI from Club Matto. Sync rules, skills, and commands to power up your AI coding workflow.
+The AI configuration CLI from Club Matto. Sync rules, skills, and commands to
+power up your AI coding workflow.
 
 ## Features
 
 - **Language Rules** — TypeScript, Go, Kotlin, and more
 - **Skills** — Reusable AI capabilities like Playwright automation
-- **Commands** — Pre-built prompts for common tasks (commit messages, PR reviews)
+- **Commands** — Pre-built prompts for common tasks (commit messages, PR
+  reviews)
 
 ## Quick Start
 
@@ -30,16 +32,33 @@ ai-kit sync
 
 # Skip installing opencode.json to project root
 ai-kit sync --skip-opencode
+
+# Language detection & filtering
+ai-kit sync --all-rules              # Install all language rules
+ai-kit sync --languages=go,kotlin    # Install specific language rules
+ai-kit sync --monorepo               # Force monorepo AGENTS.md template
+ai-kit sync --single-repo            # Force single-repo AGENTS.md template
 ```
 
+The CLI automatically detects project languages and installs only relevant
+rules:
+
+- **TypeScript/JavaScript**: `package.json` or `.ts`/`.js` files
+- **Go**: `go.mod` or `.go` files
+- **Kotlin**: `build.gradle`, `build.gradle.kts`, `pom.xml` or `.kt` files
+- **Spring Boot**: `application.properties`/`.yml` + Kotlin/Java files
+
+Multiple languages → monorepo mode (all rules + monorepo AGENTS.md).
+Single language → single-repo mode (language-specific AGENTS.md).
+
 ## What's Installed
 
-| Location          | Description                       |
-| ----------------- | --------------------------------- |
-| `.agents/rules/`  | Language/framework rules          |
-| `.agents/skills/` | Reusable AI capabilities          |
-| `opencode.json`   | Opencode configuration (optional) |
-| `AGENTS.md`       | Agent instructions                |
+| Location          | Description                               |
+| ----------------- | ----------------------------------------- |
+| `.agents/rules/`  | Language/framework rules (auto-detected)  |
+| `.agents/skills/` | Reusable AI capabilities                  |
+| `opencode.json`   | Opencode configuration (optional)         |
+| `AGENTS.md`       | Agent instructions (monorepo/single-repo) |
 
 ## Commands
 
@@ -63,6 +82,9 @@ ai-kit sync
 ## Release
 
 ```bash
+# Bump version in package.json first
+git add package.json && git commit -m "release: bump version to <version>"
+
 # Create git tag with prefix (triggers automated release)
 git tag ai-kit/v<version>
 git push origin ai-kit/v<version>

package/dist/src/cmd/sync.js

@@ -7,6 +7,8 @@ const reader_1 = require("../reader");
 const manifest_1 = require("../manifest");
 const template_1 = require("../template");
 const output_1 = require("../output");
+const detect_1 = require("../detection/detect");
+const language_detectors_1 = require("../detection/language-detectors");
 const rootDir = (0, path_1.join)(__dirname, "..", "..", "..");
 const defaultSourceDirs = {
     rules: (0, path_1.join)(rootDir, "src", "rules"),
@@ -44,8 +46,46 @@ async function doSync(cwd, version, options, logger, sourceDirs) {
     }
     const contentFiles = (0, reader_1.readContent)(sourceDirs.rules, sourceDirs.skills);
     const rootFiles = (0, reader_1.readConfigs)(sourceDirs.agents);
-    const agentsFile = (0, reader_1.readAgents)(sourceDirs.agents);
-    const rules = contentFiles.filter((f) => f.type === "rules");
+    // Detect languages and determine project type
+    const detectionResult = (0, detect_1.detectLanguages)(cwd);
+    let languages = detectionResult.languages;
+    let isMonorepo = detectionResult.isMonorepo;
+    const primaryLanguage = detectionResult.primaryLanguage;
+    // Apply overrides from options
+    if (options.allRules) {
+        languages = language_detectors_1.detectors.map((d) => d.name);
+        isMonorepo = true;
+    }
+    else if (options.monorepo) {
+        isMonorepo = true;
+    }
+    else if (options.singleRepo) {
+        isMonorepo = false;
+    }
+    if (options.languages && options.languages.length > 0) {
+        languages = options.languages;
+        isMonorepo = languages.length > 1;
+    }
+    // If no languages detected and no overrides, fall back to all rules (monorepo)
+    if (languages.length === 0) {
+        languages = language_detectors_1.detectors.map((d) => d.name);
+        isMonorepo = true;
+    }
+    const agentsFile = (0, reader_1.readAgents)(sourceDirs.agents, isMonorepo, primaryLanguage);
+    // Filter rules based on detected languages
+    const ruleFilesToInclude = options.allRules
+        ? (0, detect_1.getAllRuleFiles)()
+        : (0, detect_1.getRuleFilesForLanguages)(languages);
+    const rules = contentFiles.filter((f) => {
+        if (f.type !== "rules")
+            return false;
+        // Always include non-language-specific rules (plan-mode.md, unsure.md, etc.)
+        if (!(0, detect_1.isLanguageSpecificRule)(f.name)) {
+            return true;
+        }
+        // For language-specific rules, check if they're in the include list
+        return ruleFilesToInclude.includes(f.name);
+    });
     const stats = { rules: 0, skills: 0, commands: 0 };
     const installedRootFiles = [];
     if (!options.skipOpencode) {

package/dist/src/detection/detect.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectLanguages = detectLanguages;
+exports.getRuleFilesForLanguages = getRuleFilesForLanguages;
+exports.getAllRuleFiles = getAllRuleFiles;
+exports.isLanguageSpecificRule = isLanguageSpecificRule;
+const language_detectors_1 = require("./language-detectors");
+const scanner_1 = require("./scanner");
+function detectLanguages(cwd) {
+    const detected = new Set();
+    for (const detector of language_detectors_1.detectors) {
+        if ((0, scanner_1.hasAnyConfigFile)(cwd, detector.configFiles)) {
+            detected.add(detector.name);
+        }
+    }
+    if (detected.size === 0) {
+        for (const detector of language_detectors_1.detectors) {
+            if ((0, scanner_1.hasAnySourceFile)(cwd, detector.extensions, 2)) {
+                detected.add(detector.name);
+            }
+        }
+    }
+    const languages = Array.from(detected);
+    const isMonorepo = languages.length > 1;
+    const primaryLanguage = languages.length > 0 ? languages[0] : undefined;
+    return { languages, isMonorepo, primaryLanguage };
+}
+function getRuleFilesForLanguages(languages) {
+    const ruleFiles = new Set();
+    for (const language of languages) {
+        const detector = language_detectors_1.detectors.find((d) => d.name === language);
+        if (detector) {
+            ruleFiles.add(detector.ruleFile);
+        }
+    }
+    return Array.from(ruleFiles);
+}
+function getAllRuleFiles() {
+    return language_detectors_1.detectors.map((detector) => detector.ruleFile);
+}
+function isLanguageSpecificRule(ruleFile) {
+    return language_detectors_1.detectors.some((detector) => detector.ruleFile === ruleFile);
+}

package/dist/src/detection/language-detectors.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectors = void 0;
+//TODO this is a good first implementation
+//but we clearly want each detector to come with a detect function
+exports.detectors = [
+    {
+        name: "typescript",
+        ruleFile: "typescript.md",
+        configFiles: ["package.json", "tsconfig.json"],
+        extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"],
+    },
+    {
+        name: "go",
+        ruleFile: "go.md",
+        configFiles: ["go.mod"],
+        extensions: [".go"],
+    },
+    {
+        name: "kotlin",
+        ruleFile: "kotlin.md",
+        configFiles: ["build.gradle", "build.gradle.kts", "pom.xml"],
+        extensions: [".kt", ".kts", ".java"],
+    },
+];

package/dist/src/detection/scanner.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasAnyConfigFile = hasAnyConfigFile;
+exports.hasAnySourceFile = hasAnySourceFile;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const IGNORE_DIRS = [
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "target",
+    ".next",
+    ".nuxt",
+];
+function hasAnyConfigFile(cwd, configFiles) {
+    for (const configFile of configFiles) {
+        if ((0, fs_1.existsSync)((0, path_1.join)(cwd, configFile))) {
+            return true;
+        }
+    }
+    return false;
+}
+function hasAnySourceFile(cwd, extensions, maxDepth = 2) {
+    return scanForExtensions(cwd, extensions, maxDepth, 0);
+}
+function scanForExtensions(dir, extensions, maxDepth, currentDepth) {
+    if (currentDepth > maxDepth) {
+        return false;
+    }
+    try {
+        const entries = (0, fs_1.readdirSync)(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = (0, path_1.join)(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!IGNORE_DIRS.includes(entry.name) && !entry.name.startsWith(".")) {
+                    if (scanForExtensions(fullPath, extensions, maxDepth, currentDepth + 1)) {
+                        return true;
+                    }
+                }
+            }
+            else if (entry.isFile()) {
+                if (extensions.some((ext) => entry.name.endsWith(ext))) {
+                    return true;
+                }
+            }
+        }
+    }
+    catch {
+        // If we can't read the directory, skip it
+    }
+    return false;
+}

package/dist/src/index.js

@@ -15,5 +15,17 @@ program
 program
     .command("sync")
     .description("Initialize or update AI configuration")
-    .action(() => (0, sync_1.sync)(process.cwd(), version, program.opts()));
+    .option("--all-rules", "Install all language rules regardless of detection")
+    .option("--monorepo", "Force treat project as monorepo")
+    .option("--single-repo", "Force treat project as single repository")
+    .option("--languages <languages>", "Specify languages to install rules for (comma-separated)")
+    .action((cmdOptions) => {
+    const options = { ...program.opts(), ...cmdOptions };
+    if (options.languages && typeof options.languages === "string") {
+        options.languages = options.languages
+            .split(",")
+            .map((lang) => lang.trim());
+    }
+    (0, sync_1.sync)(process.cwd(), version, options);
+});
 program.parse();

package/dist/src/reader.js

@@ -84,13 +84,20 @@ function readConfigs(agentsDir) {
         return [];
     }
 }
-function readAgents(agentsDir) {
-    const sourcePath = (0, path_1.join)(agentsDir, "monorepo.md");
+function readAgents(agentsDir, isMonorepo = true, primaryLanguage) {
+    const templateName = isMonorepo ? "monorepo.md" : "single-repo.md";
+    const sourcePath = (0, path_1.join)(agentsDir, templateName);
     try {
+        let content = (0, fs_1.readFileSync)(sourcePath, "utf-8");
+        if (!isMonorepo && primaryLanguage) {
+            content = content
+                .replace(/{{LANGUAGE}}/g, primaryLanguage)
+                .replace(/{{LANGUAGE_RULE_FILE}}/g, `${primaryLanguage}.md`);
+        }
         return {
             type: "config",
             name: "AGENTS.md",
-            content: (0, fs_1.readFileSync)(sourcePath, "utf-8"),
+            content,
         };
     }
     catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubmatto/ai-kit",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "The AI configuration CLI from Club Matto",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
     "prettier:check": "prettier --check .",
     "format": "prettier --write .",
     "lint": "eslint . && knip",
-    "ci": "npm run typecheck && npm run lint && npm run test && npm run test:integration"
+    "ci": "npm run prettier:check && npm run typecheck && npm run lint && npm run test && npm run test:integration"
   },
   "dependencies": {
     "commander": "^14.0.3",

package/src/agents/monorepo.md

@@ -1,6 +1,6 @@
 # Agents.md
 
-This is a monorepo containing apps in many languages.
+This is a monorepo containing projects in many languages.
 
 You MUST follow the specific rules for each language. **ALWAYS** start from
 checking out the closest README.md.

package/src/agents/single-repo.md

@@ -0,0 +1,15 @@
+# Agents.md
+
+This project uses {{LANGUAGE}}. Follow these rules when working with {{LANGUAGE}} code. **ALWAYS** start from
+checking out the closest README.md.
+
+## Primary Rules
+
+Navigate to `.agents/rules/` and open `{{LANGUAGE_RULE_FILE}}`.
+
+## Additional Guidelines
+
+- [Plan Mode](.agents/rules/plan-mode.md)
+- [When You're Unsure](.agents/rules/unsure.md)
+
+_{{AGENTS_FOOTER}}_

package/src/rules/spring-boot.md

@@ -1,549 +0,0 @@
-# ☕ Spring Boot Specialist Agent Rules
-
-## 🎯 Your Spring Boot Persona
-
-You are a senior Spring Boot engineer with expertise in:
-
-- Modern Spring Boot 3.x with Kotlin
-- Spring Boot starters (web, graphql, oauth2, data, etc.)
-- Gradle with Kotlin DSL and version catalogs
-- Coroutines and structured concurrency
-- Repository pattern with JOOQ
-- GraphQL with Netflix DGS
-- Type-safe configuration with `@ConfigurationProperties`
-- Testing with JUnit 5, Kotest, and Testcontainers
-
-**Your primary values**: Type safety, convention over configuration, and pragmatic functional programming.
-
-## 📁 Spring Boot Project Structure
-
-Follow this exact structure for all Spring Boot projects:
-
-```
-[project-name]/
-├── src/
-│   ├── main/
-│   │   ├── kotlin/
-│   │   │   └── com/[company]/[project]/
-│   │   │       ├── [ApplicationName].kt           # Main application class
-│   │   │       ├── config/                        # Configuration classes
-│   │   │       ├── controller/                    # REST/GraphQL controllers
-│   │   │       ├── service/                       # Business logic
-│   │   │       ├── repository/                    # Data access layer
-│   │   │       ├── model/                         # Domain models
-│   │   │       ├── dto/                           # Data transfer objects
-│   │   │       ├── mapper/                        # Mappers between layers
-│   │   │       ├── errors/                        # Custom exceptions
-│   │   │       └── security/                      # Security configuration
-│   │   └── resources/
-│   │       ├── application.yml                    # Main configuration
-│   │       ├── application-dev.yml                # Development config
-│   │       ├── application-test.yml               # Test config
-│   │       └── graphql/                           # GraphQL schemas (if applicable)
-│   └── test/
-│       ├── kotlin/
-│       │   └── com/[company]/[project]/           # Unit tests
-│       └── resources/
-├── build.gradle.kts                               # Build configuration
-└── settings.gradle.kts                            # Project settings
-```
-
-## 🛠️ Development Commands
-
-### Essential Workflow Commands
-
-```bash
-# Run the application
-./gradlew :api:bootRun
-
-# Run tests
-./gradlew test                                    # All unit tests
-./gradlew test --info                            # With detailed output
-./gradlew integrationTest                        # Integration tests
-
-# Build
-./gradlew bootBuildImage                         # Build Docker image
-./gradlew bootJar                                # Build JAR
-
-# Code quality
-./gradlew spotlessCheck                          # Check formatting
-./gradlew spotlessApply                          # Apply formatting
-
-# Dependency updates
-./gradlew useLatestVersions                      # Update dependencies
-```
-
-### Common Build Configuration
-
-```kotlin
-// build.gradle.kts
-plugins {
-    alias(libs.plugins.kotlin.jvm)
-    alias(libs.plugins.kotlin.spring)
-    alias(libs.plugins.spring)
-    alias(libs.plugins.spring.dependency.management)
-    alias(libs.plugins.spotless)
-}
-
-java {
-    sourceCompatibility = JavaVersion.VERSION_21
-    targetCompatibility = JavaVersion.VERSION_21
-}
-
-dependencies {
-    implementation(libs.spring.boot.starter.web)
-    implementation(libs.spring.boot.starter.graphql)
-    implementation(libs.spring.boot.starter.oauth2.resourceserver)
-    implementation(libs.kotlinx.coroutines.core)
-    implementation(libs.kotlinx.coroutines.slf4j)
-
-    testImplementation(libs.spring.boot.starter.test)
-    testImplementation(libs.bundles.junit5)
-    testImplementation(libs.kotest.assertions)
-    testImplementation(libs.mockk)
-    testImplementation(libs.testcontainers)
-}
-
-tasks.test {
-    useJUnitPlatform {
-        excludeTags("integration")
-    }
-}
-```
-
-## 📝 Spring Boot Code Standards
-
-### Application Class
-
-```kotlin
-// ✅ GOOD: Clean application class with config properties scan
-@SpringBootApplication
-@ConfigurationPropertiesScan
-class ActoApiApplication
-
-fun main(args: Array<String>) {
-    runApplication<ActoApiApplication>(*args)
-}
-
-// ❌ BAD: Bloated application class
-@SpringBootApplication
-class ActoApiApplication {
-    @Bean
-    fun someBean() = ...
-
-    @PostConstruct
-    fun init() { ... }
-}
-```
-
-### Configuration Properties
-
-```kotlin
-// ✅ GOOD: Type-safe configuration properties
-@ConfigurationProperties(prefix = "app.feature-flags")
-@ConstructorBinding
-data class FeatureFlagProperties(
-    val newDashboardEnabled: Boolean = false,
-    val betaFeatures: List<String> = emptyList(),
-)
-
-// ✅ GOOD: Validate configuration
-@ConfigurationProperties(prefix = "mail")
-@Validated
-data class MailConfiguration(
-    @NotBlank val host: String,
-    @NotNull val port: Int,
-    val credentials: MailCredentials,
-)
-
-data class MailCredentials(
-    @NotBlank val username: String,
-    @NotBlank val password: String,
-)
-```
-
-### Service Layer
-
-```kotlin
-// ✅ GOOD: Constructor injection with repository pattern
-@Service
-class TeamService(
-    private val repositoryProvider: RepositoryProvider,
-    private val employeeService: EmployeeService,
-    private val analyticsServiceClient: AnalyticsServiceClient,
-    private val clock: Clock,
-) {
-    fun getManagedEmployees(
-        authentication: JwtTenantUserAuthentication,
-        first: Int,
-        after: EmployeeCursor?,
-    ): PagedResult<ManagedEmployee> {
-        val (regions, branches) = authentication.user.managerAccessFilters
-        val userRepository = repositoryProvider.get<UserRepository>()
-
-        // Implementation
-    }
-
-    // ✅ GOOD: Coroutine suspend functions for async operations
-    suspend fun getTeamKpiSummaries(
-        authentication: JwtTenantUserAuthentication,
-        period: StandardPeriod,
-        granularity: Granularity,
-        kpis: List<Kpi>,
-    ): KpiSummaries? {
-        // Implementation with coroutines
-    }
-}
-
-// ❌ BAD: Field injection
-@Service
-class UserService {
-    @Autowired
-    lateinit var repository: UserRepository
-}
-```
-
-### Repository Pattern
-
-```kotlin
-// ✅ GOOD: Repository interface with JOOQ
-@Repository
-class UserRepository(
-    private val dsl: DSLContext,
-) {
-    fun findById(id: UUID): User? {
-        return dsl.selectFrom(USER)
-            .where(USER.ID.eq(id))
-            .fetchOneInto(User::class.java)
-    }
-
-    fun findManagedUsers(
-        managerRegions: List<String>,
-        managerBranches: List<String>,
-        limit: Int,
-        afterUserDetailsId: Int?,
-    ): PagedResult<User> {
-        // Implementation with cursor pagination
-    }
-}
-
-// ✅ GOOD: Repository provider for dependency injection
-@Service
-class TeamService(
-    private val repositoryProvider: RepositoryProvider,
-) {
-    fun someMethod() {
-        val userRepository = repositoryProvider.get<UserRepository>()
-        // Use repository
-    }
-}
-```
-
-### Controller Layer (GraphQL)
-
-```kotlin
-// ✅ GOOD: GraphQL controller with batch mapping
-@Controller
-class TeamController(
-    private val teamService: TeamService,
-    private val cursorService: CursorService,
-    private val repositoryProvider: RepositoryProvider,
-) {
-    @QueryMapping
-    fun team(authentication: JwtTenantUserAuthentication): Team? {
-        val role = TenantUserRole.getMostPowerful(authentication.roles)
-        if (role == null || !role.isManager) {
-            return null
-        }
-        return Team
-    }
-
-    // ✅ GOOD: Schema mapping for nested fields
-    @SchemaMapping(typeName = "Team", field = "employees")
-    suspend fun employees(
-        @Argument first: Int?,
-        @Argument after: String?,
-        authentication: JwtTenantUserAuthentication,
-    ): EmployeeConnection {
-        val cursorData = after?.let { cursorService.decode(it, cursorStrategy) }
-        val result = teamService.getSortedManagedEmployees(
-            authentication = authentication,
-            first = first ?: 10,
-            after = cursorData,
-        )
-        // Return connection
-    }
-
-    // ✅ GOOD: Batch mapping to solve N+1 problem
-    @BatchMapping(typeName = "Employee", field = "meetings")
-    fun meetings(
-        employees: List<Employee>,
-        authentication: JwtTenantUserAuthentication,
-    ): Map<Employee, MeetingConnection> {
-        val employeeUuids = employees.map { UUID.fromString(it.id.toString()) }
-        // Batch fetch meetings
-    }
-}
-
-// ❌ BAD: No batch mapping causing N+1 queries
-```
-
-### Pagination
-
-```kotlin
-// ✅ GOOD: Cursor-based pagination
-data class EmployeeCursor(
-    val userDetailsId: Int,
-    val orderBy: String,
-    val sortValue: Double?,
-    val sortName: String,
-)
-
-data class PagedResult<T>(
-    val items: List<T>,
-    val hasMore: Boolean,
-)
-
-// ✅ GOOD: Pagination options
-data class PaginationOptions<T>(
-    val first: Int,
-    val after: T?,
-)
-```
-
-### Coroutines & Structured Concurrency
-
-```kotlin
-// ✅ GOOD: Parallel execution with coroutines
-suspend fun getEmployeeData(
-    employeeIds: List<UUID>,
-): EmployeeData = coroutineScope {
-    val employeesDeferred = async {
-        employeeService.getEmployees(employeeIds)
-    }
-
-    val kpisDeferred = async {
-        analyticsService.getKpis(employeeIds)
-    }
-
-    val employees = employeesDeferred.await()
-    val kpis = kpisDeferred.await()
-
-    // Combine results
-}
-
-// ✅ GOOD: WithContext for dispatcher switching
-suspend fun fetchData(): Data = withContext(Dispatchers.IO) {
-    repository.findAll()
-}
-
-// ❌ BAD: Blocking calls in coroutines
-suspend fun badExample() {
-    val result = Thread.sleep(1000) // Never do this
-}
-```
-
-### Error Handling
-
-```kotlin
-// ✅ GOOD: Custom exceptions
-sealed class ApiError(message: String) : Exception(message) {
-    data class EntityNotFoundError(val entityType: String, val id: UUID) :
-        ApiError("$entityType with ID: $id not found")
-
-    data class AuthorizationError(val user: User, val action: String) :
-        ApiError("User ${user.id} not authorized for $action")
-}
-
-// ✅ GOOD: Global exception handler
-@ControllerAdvice
-class GlobalExceptionHandler {
-    @ExceptionHandler(ApiError::class)
-    fun handleApiError(error: ApiError): ResponseEntity<ErrorResponse> {
-        return ResponseEntity
-            .status(HttpStatus.BAD_REQUEST)
-            .body(ErrorResponse(error.message))
-    }
-}
-```
-
-### Logging
-
-```kotlin
-// ✅ GOOD: Structured logging with context
-@Service
-class TeamService(
-    private val repositoryProvider: RepositoryProvider,
-) {
-    private val logger = LoggerFactory.getLogger(TeamService::class.java)
-
-    fun getManagedEmployees(...): PagedResult<ManagedEmployee> {
-        logger.debug(
-            "Fetching managed employees: regions={}, branches={}",
-            regions, branches
-        )
-
-        WideEventContext.addContext(
-            mapOf(
-                "operation" to "team.employees",
-                "first" to first,
-                "has_cursor" to (after != null),
-            )
-        )
-
-        // Implementation
-    }
-}
-```
-
-## 🧪 Testing Standards
-
-### Unit Tests
-
-```kotlin
-// ✅ GOOD: JUnit 5 with Kotest assertions
-class TeamServiceTest {
-    private lateinit var teamService: TeamService
-    private val repositoryProvider = mockk<RepositoryProvider>()
-    private val employeeService = mockk<EmployeeService>()
-
-    @BeforeEach
-    fun setup() {
-        teamService = TeamService(
-            repositoryProvider = repositoryProvider,
-            employeeService = employeeService,
-            analyticsServiceClient = mockk(),
-            clock = Clock.systemDefaultZone(),
-        )
-    }
-
-    @Test
-    fun `getManagedEmployees returns empty list when no employees`() {
-        // Given
-        val authentication = createTestAuthentication()
-        every { repositoryProvider.get<UserRepository>() } returns mockk {
-            every { findManagedUsers(...) } returns PagedResult(emptyList(), false)
-        }
-
-        // When
-        val result = teamService.getManagedEmployees(authentication, 10, null)
-
-        // Then
-        result.items shouldBeEmpty()
-        result.hasMore shouldBe false
-    }
-}
-```
-
-### Integration Tests
-
-```kotlin
-// ✅ GOOD: Integration test with testcontainers
-@IntegrationTest
-class UserRepositoryIntegrationTest {
-    private lateinit var repository: UserRepository
-    private val postgresContainer = PostgreSQLContainer<Nothing>("postgres:16")
-
-    @BeforeEach
-    fun setup() {
-        postgresContainer.start()
-        val datasource = DataSourceBuilder.create()
-            .url(postgresContainer.jdbcUrl)
-            .username(postgresContainer.username)
-            .password(postgresContainer.password)
-            .build()
-
-        repository = UserRepository(DSLContextFactory.from(datasource))
-    }
-
-    @Test
-    fun `findById returns user when exists`() {
-        // Given
-        val user = createTestUser()
-        repository.save(user)
-
-        // When
-        val result = repository.findById(user.id)
-
-        // Then
-        result shouldBeEqualTo user
-    }
-}
-
-// Tag integration tests
-@Tag("integration")
-class IntegrationTests { ... }
-```
-
-### Test Helpers
-
-```kotlin
-// ✅ GOOD: Reusable test extensions
-@ExtendWith(PostgresLifecycleExtension::class)
-class PostgresTest {
-    // Access to postgresContainer via ExtensionContext
-}
-
-// ✅ GOOD: Test fixtures
-object TestFixtures {
-    fun createTestUser(
-        id: UUID = UUID.randomUUID(),
-        name: String = "Test User",
-    ) = User(id = id, name = name)
-}
-```
-
-## 📦 Dependency Management
-
-### Version Catalogs (libs.versions.toml)
-
-```toml
-[versions]
-spring-boot = "3.5.10"
-kotlin = "2.3.0"
-kotest = "5.9.1"
-
-[plugins]
-kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
-kotlin-spring = { id = "org.jetbrains.kotlin.plugin.spring", version.ref = "kotlin" }
-spring = { id = "org.springframework.boot", version.ref = "spring-boot" }
-
-[libraries]
-spring-boot-starter-web = { group = "org.springframework.boot", name = "spring-boot-starter-web" }
-spring-boot-starter-graphql = { group = "org.springframework.boot", name = "spring-boot-starter-graphql" }
-kotest-assertions = { group = "io.kotest", name = "kotest-assertions-core", version.ref = "kotest" }
-
-[bundles]
-kotlin = ["kotlin-reflect", "kotlinx-coroutines-core"]
-testing = ["junit5-jupiter", "kotest-assertions", "mockk"]
-```
-
-### Dependency Rules
-
-- Use version catalogs for centralized dependency management
-- Pin exact versions – avoid floating dependencies like `1.+`
-- Use Spring Boot BOM for transitive dependency versions
-- Prefer platform-specific starters over generic dependencies
-
-## 🚫 Spring Boot-Specific Restrictions
-
-### Never Do These:
-
-- ❌ Never use field injection (`@Autowired lateinit var`) – use constructor injection
-- ❌ Never block coroutines with `.get()` or `.join()` – use suspend functions
-- ❌ Never commit transactions in service layer – keep transactions at repository level
-- ❌ Never return JPA entities from controllers – use DTOs
-- ❌ Never ignore nullable types – use `?` and safe calls
-- ❌ Never use `any` in Kotlin code – use proper types
-- ❌ Never hardcode configuration – use `application.yml`
-- ❌ Never write business logic in controllers – delegate to services
-
-### Avoid These When Possible:
-
-- ⚠️ Avoid circular dependencies between services
-- ⚠️ Avoid monolithic controllers – delegate to services
-- ⚠️ Avoid mutable data classes – use `val` properties
-- ⚠️ Avoid `!!` operator – use safe calls or `requireNotNull`
-- ⚠️ Avoid complex inheritance hierarchies – prefer composition
-
-{{FOOTER}}