@hivehub/rulebook 1.2.0

package/templates/languages/JULIA.md

@@ -0,0 +1,97 @@
+<!-- JULIA:START -->
+# Julia Project Rules
+
+## Agent Automation Commands
+
+**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
+
+```bash
+# Complete quality check sequence:
+julia -e 'using JuliaFormatter; format(".", overwrite=false)'  # Format check
+julia -e 'using Lint; lintpkg(".")'  # Linting
+julia --project=. -e 'using Pkg; Pkg.test()'  # All tests
+
+# Security audit:
+julia -e 'using Pkg; Pkg.update()'  # Update deps
+```
+
+## Julia Configuration
+
+**CRITICAL**: Use Julia 1.9+ with JuliaFormatter and testing.
+
+- **Version**: Julia 1.9+
+- **Formatter**: JuliaFormatter.jl
+- **Linter**: Lint.jl
+- **Testing**: Test.jl (standard library)
+- **Documentation**: Documenter.jl
+
+### Project.toml Requirements
+
+```toml
+name = "YourPackage"
+uuid = "12345678-1234-1234-1234-123456789012"
+authors = ["Your Name <you@example.com>"]
+version = "0.1.0"
+
+[deps]
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+
+[compat]
+julia = "1.9"
+
+[extras]
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[targets]
+test = ["Test"]
+```
+
+## Code Quality Standards
+
+### Mandatory Quality Checks
+
+**IMPORTANT**: These commands MUST match your GitHub Actions workflows!
+
+```bash
+# Pre-Commit Checklist (MUST match .github/workflows/*.yml)
+
+# 1. Format check (matches workflow)
+julia -e 'using JuliaFormatter; format(".", overwrite=false)'
+
+# 2. Lint (matches workflow)
+julia -e 'using Lint; lintpkg("YourPackage")'
+
+# 3. Run all tests (MUST pass 100% - matches workflow)
+julia --project=. -e 'using Pkg; Pkg.test()'
+
+# 4. Check coverage (matches workflow)
+julia --project=. --code-coverage=user -e 'using Pkg; Pkg.test()'
+
+# If ANY fails: ❌ DO NOT COMMIT - Fix first!
+```
+
+**Why This Matters:**
+- Example: Using `format(..., overwrite=true)` locally but `overwrite=false` in CI = failure
+
+### Testing Example
+
+```julia
+using Test
+using YourPackage
+
+@testset "DataProcessor tests" begin
+    @testset "process function" begin
+        @test process([1, 2, 3]) == [2, 4, 6]
+        @test process([]) == []
+        @test_throws ArgumentError process(nothing)
+    end
+    
+    @testset "validate function" begin
+        @test validate("test") == true
+        @test validate("") == false
+    end
+end
+```
+
+<!-- JULIA:END -->
+

package/templates/languages/KOTLIN.md

@@ -0,0 +1,511 @@
+<!-- KOTLIN:START -->
+# Kotlin Project Rules
+
+## Agent Automation Commands
+
+**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
+
+```bash
+# Complete quality check sequence (Gradle):
+./gradlew ktlintCheck     # Format check
+./gradlew detekt          # Linting
+./gradlew test            # All tests (100% pass)
+./gradlew build           # Build verification
+./gradlew koverVerify     # Coverage (95%+ required)
+
+# Security audit:
+./gradlew dependencyCheckAnalyze  # Vulnerability scan
+./gradlew dependencyUpdates       # Check outdated deps
+```
+
+## Kotlin Configuration
+
+**CRITICAL**: Use Kotlin 2.0+ with strict null safety.
+
+- **Version**: Kotlin 2.0+
+- **JVM Target**: 17+
+- **Language Features**: All enabled
+- **Compiler**: K2 compiler
+- **Null Safety**: Strict
+
+### build.gradle.kts Requirements
+
+```kotlin
+plugins {
+    kotlin("jvm") version "2.0.0"
+    id("org.jetbrains.dokka") version "1.9.20"
+    id("io.gitlab.arturbosch.detekt") version "1.23.5"
+    id("org.jlleitschuh.gradle.ktlint") version "12.1.0"
+    `maven-publish`
+    signing
+}
+
+group = "io.github.your-username"
+version = "1.0.0"
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation(kotlin("stdlib"))
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")
+    
+    testImplementation(kotlin("test"))
+    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.0")
+    testImplementation("io.mockk:mockk:1.13.9")
+}
+
+kotlin {
+    jvmToolchain(17)
+    
+    compilerOptions {
+        freeCompilerArgs.add("-Xjsr305=strict")
+        freeCompilerArgs.add("-Xcontext-receivers")
+        allWarningsAsErrors.set(true)
+    }
+}
+
+tasks.test {
+    useJUnitPlatform()
+}
+
+tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
+    kotlinOptions {
+        jvmTarget = "17"
+        freeCompilerArgs = listOf(
+            "-Xjsr305=strict",
+            "-Xcontext-receivers"
+        )
+        allWarningsAsErrors = true
+    }
+}
+
+detekt {
+    config.setFrom(files("$rootDir/detekt.yml"))
+    buildUponDefaultConfig = true
+    allRules = false
+}
+
+ktlint {
+    version.set("1.1.0")
+    android.set(false)
+    ignoreFailures.set(false)
+}
+```
+
+## Code Quality Standards
+
+### Mandatory Quality Checks
+
+**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.
+
+**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!
+
+```bash
+# Pre-Commit Checklist (MUST match .github/workflows/*.yml)
+
+# 1. Format check (matches workflow - use Check, not Format!)
+./gradlew ktlintCheck
+
+# 2. Lint (matches workflow)
+./gradlew detekt
+
+# 3. Build (MUST pass with no warnings - matches workflow)
+./gradlew build -x test
+
+# 4. Run all tests (MUST pass 100% - matches workflow)
+./gradlew test
+
+# 5. Check coverage (MUST meet threshold)
+./gradlew koverVerify
+
+# If ANY fails: ❌ DO NOT COMMIT - Fix first!
+```
+
+**If ANY of these fail, you MUST fix the issues before committing.**
+
+**Why This Matters:**
+- CI/CD failures happen when local commands differ from workflows
+- Example: Using `ktlintFormat` locally but `ktlintCheck` in CI = failure
+- Example: Using `koverHtmlReport` locally but `koverVerify` in CI = coverage failures
+
+### Code Style
+
+Use ktlint with `.editorconfig`:
+
+```ini
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+max_line_length = 120
+tab_width = 4
+
+[*.{kt,kts}]
+ij_kotlin_allow_trailing_comma = true
+ij_kotlin_allow_trailing_comma_on_call_site = true
+
+# Imports
+ij_kotlin_imports_layout = *,java.**,javax.**,kotlin.**,^
+
+# Wrapping
+ij_kotlin_line_break_after_multiline_when_entry = true
+ij_kotlin_wrap_expression_body_functions = 1
+ij_kotlin_wrap_first_method_in_call_chain = false
+
+# Spacing
+ij_kotlin_space_after_type_colon = true
+ij_kotlin_space_before_type_colon = false
+```
+
+### Static Analysis
+
+Use Detekt. Configuration in `detekt.yml`:
+
+```yaml
+build:
+  maxIssues: 0
+  weights:
+    complexity: 2
+    LongParameterList: 1
+    style: 1
+    comments: 1
+
+complexity:
+  active: true
+  ComplexMethod:
+    threshold: 15
+  LongMethod:
+    threshold: 60
+  LongParameterList:
+    functionThreshold: 6
+  TooManyFunctions:
+    thresholdInFiles: 15
+
+naming:
+  active: true
+  FunctionNaming:
+    active: true
+  ClassNaming:
+    active: true
+  VariableNaming:
+    active: true
+
+style:
+  active: true
+  MagicNumber:
+    active: true
+  ReturnCount:
+    max: 3
+
+coroutines:
+  active: true
+  GlobalCoroutineUsage:
+    active: true
+  SuspendFunWithFlowReturnType:
+    active: true
+```
+
+### Testing
+
+- **Framework**: JUnit 5 (Jupiter)
+- **Mocking**: MockK
+- **Coroutines**: kotlinx-coroutines-test
+- **Coverage**: Kover
+- **Coverage Threshold**: 95%+
+
+Example test:
+
+```kotlin
+import io.mockk.*
+import kotlinx.coroutines.test.runTest
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.assertThrows
+import kotlin.test.assertEquals
+
+class DataProcessorTest {
+    
+    @Test
+    fun `process valid input returns uppercase`() {
+        val processor = DataProcessor()
+        val result = processor.process("hello")
+        
+        assertEquals("HELLO", result)
+    }
+    
+    @Test
+    fun `process empty input throws exception`() {
+        val processor = DataProcessor()
+        
+        assertThrows<IllegalArgumentException> {
+            processor.process("")
+        }
+    }
+    
+    @Test
+    fun `processAsync works correctly`() = runTest {
+        val processor = DataProcessor()
+        val result = processor.processAsync("test")
+        
+        assertEquals("TEST", result)
+    }
+    
+    @Test
+    fun `test with mocking`() {
+        val repository = mockk<UserRepository>()
+        every { repository.findById(1) } returns User(1, "John")
+        
+        val service = UserService(repository)
+        val user = service.getUser(1)
+        
+        assertEquals("John", user?.name)
+        verify { repository.findById(1) }
+    }
+}
+```
+
+### Null Safety
+
+- Use non-null types by default
+- Use `?` for nullable types
+- Use safe calls `?.` and Elvis operator `?:`
+- Avoid `!!` operator (use only when absolutely necessary)
+
+Example:
+
+```kotlin
+data class User(
+    val id: Int,
+    val name: String,
+    val email: String?,
+    val phone: String? = null
+)
+
+class UserService(private val repository: UserRepository) {
+    
+    fun findUser(id: Int): User? {
+        return repository.findById(id)
+    }
+    
+    fun getUserName(id: Int): String {
+        val user = findUser(id) ?: throw UserNotFoundException(id)
+        return user.name
+    }
+    
+    fun getUserEmail(id: Int): String {
+        val user = findUser(id) ?: return "unknown@example.com"
+        return user.email ?: "no-email@example.com"
+    }
+    
+    fun processUsers(ids: List<Int>): List<String> {
+        return ids.mapNotNull { id ->
+            findUser(id)?.name
+        }
+    }
+}
+```
+
+### Coroutines
+
+- Use structured concurrency
+- Prefer `suspend` functions over callbacks
+- Use `Flow` for reactive streams
+- Handle cancellation properly
+
+Example:
+
+```kotlin
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+
+class DataService(private val api: ApiClient) {
+    
+    suspend fun fetchData(id: Int): Result<Data> = withContext(Dispatchers.IO) {
+        try {
+            val data = api.getData(id)
+            Result.success(data)
+        } catch (e: Exception) {
+            Result.failure(e)
+        }
+    }
+    
+    fun observeData(id: Int): Flow<Data> = flow {
+        while (currentCoroutineContext().isActive) {
+            val data = api.getData(id)
+            emit(data)
+            delay(1000)
+        }
+    }.flowOn(Dispatchers.IO)
+    
+    suspend fun fetchMultiple(ids: List<Int>): List<Data> = coroutineScope {
+        ids.map { id ->
+            async { fetchData(id).getOrNull() }
+        }.awaitAll().filterNotNull()
+    }
+}
+```
+
+### Data Classes & Sealed Classes
+
+- Use `data class` for value objects
+- Use `sealed class`/`sealed interface` for restricted hierarchies
+- Use `value class` for single-property wrappers
+
+Example:
+
+```kotlin
+// Data class for DTOs
+data class User(
+    val id: Int,
+    val name: String,
+    val email: String
+)
+
+// Sealed hierarchy for results
+sealed interface Result<out T> {
+    data class Success<T>(val data: T) : Result<T>
+    data class Error(val exception: Exception) : Result<Nothing>
+    data object Loading : Result<Nothing>
+}
+
+// Value class for type safety
+@JvmInline
+value class UserId(val value: Int)
+
+@JvmInline
+value class Email(val value: String) {
+    init {
+        require(value.contains("@")) { "Invalid email format" }
+    }
+}
+```
+
+### Documentation
+
+- Use KDoc for documentation
+- Document all public APIs
+- Include examples with `@sample`
+
+Example:
+
+```kotlin
+/**
+ * A processor that transforms input data.
+ *
+ * This class provides methods for processing strings synchronously and asynchronously.
+ * All processing is done in a thread-safe manner.
+ *
+ * @property config Configuration for the processor
+ * @constructor Creates a processor with the given configuration
+ */
+class DataProcessor(private val config: ProcessorConfig = ProcessorConfig()) {
+    
+    /**
+     * Processes the input string synchronously.
+     *
+     * @param input The string to process. Must not be empty.
+     * @return The processed string in uppercase.
+     * @throws IllegalArgumentException if [input] is empty.
+     * @sample samples.DataProcessorSamples.processExample
+     */
+    fun process(input: String): String {
+        require(input.isNotEmpty()) { "Input cannot be empty" }
+        return input.uppercase()
+    }
+    
+    /**
+     * Processes the input string asynchronously.
+     *
+     * This is a suspending function that can be called from a coroutine.
+     *
+     * @param input The string to process.
+     * @return The processed string in uppercase.
+     */
+    suspend fun processAsync(input: String): String = withContext(Dispatchers.Default) {
+        process(input)
+    }
+}
+
+// Sample code for documentation
+object samples {
+    object DataProcessorSamples {
+        fun processExample() {
+            val processor = DataProcessor()
+            val result = processor.process("hello")
+            println(result) // Prints: HELLO
+        }
+    }
+}
+```
+
+## Project Structure
+
+```
+project/
+├── build.gradle.kts        # Gradle build configuration
+├── settings.gradle.kts     # Gradle settings
+├── detekt.yml              # Detekt configuration
+├── .editorconfig           # EditorConfig for ktlint
+├── README.md               # Project overview (allowed in root)
+├── CHANGELOG.md            # Version history (allowed in root)
+├── LICENSE                 # Project license (allowed in root)
+├── src/
+│   ├── main/
+│   │   └── kotlin/
+│   │       └── com/yourorg/yourproject/
+│   │           └── YourClass.kt
+│   └── test/
+│       └── kotlin/
+│           └── com/yourorg/yourproject/
+│               └── YourClassTest.kt
+└── docs/                   # Project documentation
+```
+
+## CI/CD Requirements
+
+Must include GitHub Actions workflows for:
+
+1. **Testing** (`kotlin-test.yml`):
+   - Test on ubuntu-latest, windows-latest
+   - Test on Java 17, 21
+   - Upload coverage reports
+
+2. **Linting** (`kotlin-lint.yml`):
+   - Detekt: `./gradlew detekt`
+   - ktlint: `./gradlew ktlintCheck`
+   - Build with warnings as errors
+
+## Package Publication
+
+### Publishing to Maven Central
+
+Same process as Java (see JAVA.md), but with Kotlin-specific configuration.
+
+**Publishing Checklist:**
+
+- ✅ All tests passing
+- ✅ Detekt passes
+- ✅ ktlint passes
+- ✅ Build succeeds with warnings as errors
+- ✅ Version updated in build.gradle.kts
+- ✅ CHANGELOG.md updated
+- ✅ README.md up to date
+- ✅ LICENSE file present
+- ✅ Dokka documentation generated
+- ✅ Artifacts signed with GPG
+
+**Dokka Documentation:**
+
+```kotlin
+tasks.dokkaHtml.configure {
+    outputDirectory.set(buildDir.resolve("dokka"))
+}
+```
+
+<!-- KOTLIN:END -->
+

package/templates/languages/LISP.md

@@ -0,0 +1,100 @@
+<!-- LISP:START -->
+# Common Lisp Project Rules
+
+## Agent Automation Commands
+
+**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
+
+```bash
+# Complete quality check sequence:
+sbcl --eval '(ql:quickload :sblint)' --eval '(sblint:run-lint "src/")'  # Linting
+sbcl --load tests/run-tests.lisp  # All tests
+sbcl --eval '(asdf:make :your-system)'  # Build with ASDF
+```
+
+## Common Lisp Configuration
+
+**CRITICAL**: Use SBCL 2.3+ or CCL with ASDF3 and modern tooling.
+
+- **Implementation**: SBCL 2.3+ (recommended) or CCL
+- **Build System**: ASDF3
+- **Testing**: FiveAM or Prove
+- **Linter**: sblint
+
+### System Definition (your-system.asd)
+
+```lisp
+(defsystem "your-system"
+  :description "Your system description"
+  :version "0.1.0"
+  :author "Your Name <you@example.com>"
+  :license "MIT"
+  :depends-on (:alexandria
+               :cl-ppcre
+               :str)
+  :components ((:module "src"
+                :components
+                ((:file "package")
+                 (:file "main" :depends-on ("package")))))
+  :in-order-to ((test-op (test-op "your-system/tests"))))
+
+(defsystem "your-system/tests"
+  :depends-on ("your-system"
+               "fiveam")
+  :components ((:module "tests"
+                :components
+                ((:file "package")
+                 (:file "main-tests" :depends-on ("package")))))
+  :perform (test-op (o c) (symbol-call :fiveam :run! :your-system-tests)))
+```
+
+## Code Quality Standards
+
+### Mandatory Quality Checks
+
+**IMPORTANT**: These commands MUST match your GitHub Actions workflows!
+
+```bash
+# Pre-Commit Checklist (MUST match .github/workflows/*.yml)
+
+# 1. Lint (matches workflow)
+sblint your-system.asd
+
+# 2. Load system (check for errors - matches workflow)
+sbcl --non-interactive --load your-system.asd \
+     --eval '(ql:quickload :your-system)' \
+     --eval '(quit)'
+
+# 3. Run tests (matches workflow)
+sbcl --non-interactive \
+     --eval '(ql:quickload :your-system/tests)' \
+     --eval '(asdf:test-system :your-system)' \
+     --eval '(quit)'
+
+# If ANY fails: ❌ DO NOT COMMIT - Fix first!
+```
+
+### Testing Example (FiveAM)
+
+```lisp
+(in-package :your-system/tests)
+
+(def-suite your-system-tests
+  :description "Main test suite")
+
+(in-suite your-system-tests)
+
+(test process-data-test
+  "Test data processing"
+  (is (equal '(2 4 6) (process-data '(1 2 3))))
+  (is (null (process-data '())))
+  (signals error (process-data nil)))
+
+(test validate-input-test
+  "Test input validation"
+  (is-true (validate-input "test"))
+  (is-false (validate-input "")))
+```
+
+<!-- LISP:END -->
+