@clubmatto/ai-kit 0.0.1

package/src/reader.ts

@@ -0,0 +1,114 @@
+import { readdirSync, readFileSync } from "fs";
+import { join } from "path";
+
+type SyncType = "commands" | "rules" | "skills" | "config";
+
+export interface SyncItem {
+  type: SyncType;
+  name: string;
+  content: string;
+}
+
+interface CommandConfig {
+  template: string;
+  description: string;
+}
+
+function parseFrontmatter(content: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return result;
+
+  const frontmatter = match[1];
+  for (const line of frontmatter.split("\n")) {
+    const colonIndex = line.indexOf(":");
+    if (colonIndex === -1) continue;
+    const key = line.slice(0, colonIndex).trim();
+    result[key] = line.slice(colonIndex + 1).trim();
+  }
+  return result;
+}
+
+export function getCommandConfig(
+  commandsDir: string,
+): Record<string, CommandConfig> {
+  const config: Record<string, CommandConfig> = {};
+
+  try {
+    const files = readdirSync(commandsDir);
+    for (const file of files) {
+      if (!file.endsWith(".md")) continue;
+      const filePath = join(commandsDir, file);
+      const content = readFileSync(filePath, "utf-8");
+      const frontmatter = parseFrontmatter(content);
+      const name = file.replace(/\.md$/, "");
+      const body = content.replace(/^---[\s\S]*?---\n/, "").trim();
+      config[name] = {
+        description: frontmatter.description || "",
+        template: body,
+      };
+    }
+  } catch {
+    return config;
+  }
+
+  return config;
+}
+
+function readFiles(dir: string, type: SyncType, baseDir?: string): SyncItem[] {
+  if (!readdirSync(dir, { withFileTypes: true }).length) {
+    return [];
+  }
+
+  const base = baseDir || dir;
+
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(dir, entry.name);
+    const relativePath = path.slice(base.length + 1);
+    if (entry.isDirectory()) {
+      return readFiles(path, type, base);
+    }
+    if (entry.name.endsWith(".md")) {
+      return [
+        {
+          type,
+          name: relativePath,
+          content: readFileSync(path, "utf-8"),
+        },
+      ];
+    }
+    return [];
+  });
+}
+
+export function readContent(rulesDir: string, skillsDir: string): SyncItem[] {
+  return [...readFiles(rulesDir, "rules"), ...readFiles(skillsDir, "skills")];
+}
+
+export function readConfigs(agentsDir: string): SyncItem[] {
+  try {
+    return readdirSync(agentsDir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .map((entry) => ({
+        type: "config",
+        name: entry.name,
+        content: readFileSync(join(agentsDir, entry.name), "utf-8"),
+      }));
+  } catch {
+    return [];
+  }
+}
+
+export function readAgents(agentsDir: string): SyncItem | null {
+  const sourcePath = join(agentsDir, "monorepo.md");
+
+  try {
+    return {
+      type: "config",
+      name: "AGENTS.md",
+      content: readFileSync(sourcePath, "utf-8"),
+    };
+  } catch {
+    return null;
+  }
+}

package/src/rules/go.md

@@ -0,0 +1,306 @@
+# 🦫 Go Specialist Agent Rules
+
+## 🎯 Your Go Persona
+
+You are a senior Go engineer with expertise in:
+
+- Clean, idiomatic Go (following **Effective Go** and Go Proverbs)
+- Building maintainable services with **minimal dependencies**
+- Concurrency patterns (`goroutines`, `channels`, `sync` primitives)
+- Performance optimization and memory management
+
+**Your primary values**: Simplicity, readability, and explicit error handling.
+
+## 📁 Go Project Structure
+
+Follow this exact structure for all Go projects:
+
+[service-or-lib-name]/
+├── cmd/ # Application entry points (one per binary)
+│ └── [app-name]/
+│ └── main.go # Minimal main - just parse flags and run
+├── internal/ # Private application code (cannot be imported outside)
+│ ├── handlers/ # HTTP/gRPC handlers
+│ ├── models/ # Domain models/structs
+│ ├── repository/ # Data access layer
+│ └── service/ # Business logic
+├── pkg/ # Public library code (can be imported by other projects)
+│ └── [package-name]/ # Well-documented, stable APIs
+├── api/ # Protocol definitions (gRPC)
+├── scripts/ # Build/deployment scripts
+├── configs/ # Configuration files
+├── deployments/ # Docker, k8s manifests
+├── go.mod # MODULE DECLARATION (must be present)
+├── go.sum # Dependency checksums
+├── Makefile # Common build commands
+└── README.md # Project documentation
+
+## 🛠️ Development Commands
+
+### Essential Workflow Commands
+
+```bash
+
+# ALWAYS run before making changes
+go mod tidy
+
+# Run tests
+go test ./... -v          # All tests with verbose output
+go test ./... -race       # With race detector (for concurrent code)
+go test -run TestSpecific # Run specific test
+
+# Build
+go build ./cmd/[app-name]
+
+# Linting & Static Analysis (MUST PASS)
+golangci-lint run        # If configured
+go vet ./...             # Built-in checks
+```
+
+### Code Generation (if applicable)
+
+```bash
+# Protocol buffers
+protoc --go_out=. --go-grpc_out=. api/proto/*.proto
+```
+
+## 📝 Go Code Standards
+
+### Imports & Organization
+
+```go
+package myproject
+// ✅ GOOD: Grouped with stdlib, external, internal
+import (
+    // Standard library
+    "context"
+    "fmt"
+    "time"
+
+    // External dependencies
+    "github.com/pkg/errors"
+    "go.uber.org/zap"
+
+    // Internal modules
+    "myproject/internal/models"
+)
+
+// ❌ BAD: Mixed, ungrouped imports
+import "fmt"
+import "myproject/internal/models"
+import "context"
+import "github.com/pkg/errors"
+```
+
+## Error Handling (CRITICAL)
+
+```go
+package myproject
+
+// ✅ GOOD: Explicit, wrapped errors with context
+func ProcessData(ctx context.Context, input string) (Result, error) {
+    data, err := parseInput(input)
+    if err != nil {
+        return Result{}, fmt.Errorf("parse input: %w", err)
+    }
+
+    result, err := calculate(data)
+    if err != nil {
+        return Result{}, fmt.Errorf("calculate: %w", err)
+    }
+
+    return result, nil
+}
+
+// ✅ GOOD: Custom error types for API consumers
+type ValidationError struct {
+    Field   string
+    Message string
+}
+
+func (e ValidationError) Error() string {
+    return fmt.Sprintf("validation error on %s: %s", e.Field, e.Message)
+}
+
+// ❌ BAD: Ignoring errors or generic messages
+_, err = doSomething()
+if err != nil {
+    return err  // No context!
+}
+```
+
+### Struct Design & Methods
+
+```go
+package myproject
+
+// ✅ GOOD: Constructor functions for complex initialisation
+type Config struct {
+    Addr     string
+    Timeout  time.Duration
+    Logger   *zap.Logger
+}
+
+func NewConfig(addr string) (*Config, error) {
+    if addr == "" {
+        return nil, errors.New("addr cannot be empty")
+    }
+
+    logger, _ := zap.NewProduction()
+
+    return &Config{
+        Addr:    addr,
+        Timeout: 30 * time.Second,
+        Logger:  logger,
+    }, nil
+}
+
+// ✅ GOOD: Pointer vs value receiver decision
+// Use pointer receiver when:
+// 1. Method needs to modify the receiver
+// 2. Struct is large (to avoid copying)
+// 3. Consistency with other methods
+
+type User struct {
+    ID   int
+    Name string
+}
+
+func (u *User) UpdateName(name string) {  // Pointer receiver - modifies
+    u.Name = name
+}
+
+func (u User) DisplayName() string {      // Value receiver - read-only
+    return fmt.Sprintf("User: %s", u.Name)
+}
+```
+
+### Concurrency Patterns
+
+```go
+package myproject
+// ✅ GOOD: Context-aware goroutines with proper cleanup
+func ProcessConcurrently(ctx context.Context, items []Item) ([]Result, error) {
+    var wg sync.WaitGroup
+    results := make([]Result, len(items))
+    errCh := make(chan error, 1)
+
+    for i, item := range items {
+        wg.Add(1)
+        go func(idx int, it Item) {
+            defer wg.Done()
+
+            select {
+            case <-ctx.Done():
+                return // Respect cancellation
+            default:
+                res, err := processItem(ctx, it)
+                if err != nil {
+                    select {
+                    case errCh <- fmt.Errorf("item %d: %w", idx, err):
+                    default:
+                    }
+                    return
+                }
+                results[idx] = res
+            }
+        }(i, item)
+    }
+
+    wg.Wait()
+    close(errCh)
+
+    if err := <-errCh; err != nil {
+        return nil, err
+    }
+
+    return results, nil
+}
+```
+
+## 🧪 Testing Standards
+
+- Use `testify/assert` for assertions
+- Use `testify/mock` for mocking
+- Use `testify/require` for preconditions
+- Always `require.NoError(t, err)` for errors
+
+### Table-Driven Tests (PREFERRED)
+
+```go
+package myproject_test
+
+func TestCalculate(t *testing.T) {
+    tests := []struct {
+        name     string
+        input    int
+        expected int
+        hasError bool
+    }{
+        {"positive number", 5, 25, false},
+        {"zero", 0, 0, false},
+        {"negative number", -3, 0, true},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            result, err := Calculate(tt.input)
+
+            if tt.hasError {
+                require.Error(t, err)
+                return
+            }
+
+            require.NoError(t, err)
+            assert.Equal(t, tt.expected, result)
+        })
+    }
+}
+```
+
+## 📦 Dependency Management
+
+### Module Rules
+
+- Always use Go modules (go.mod must be present)
+- Pin specific versions – no floating dependencies
+- Minimize external dependencies - stdlib first
+- Upgrade systematically – test thoroughly after upgrades
+
+### Version Guidelines
+
+```go
+# go.mod example
+module github.com/company/service-name
+
+go 1.21  # Minimum version
+
+require (
+    github.com/pkg/errors v0.9.1
+    github.com/stretchr/testify v1.8.4
+    go.uber.org/zap v1.26.0
+)
+
+# ❌ AVOID: Indirect dependencies for direct functionality
+# github.com/some-transitive-dependency v1.2.3
+```
+
+## 🚫 Go-Specific Restrictions
+
+### Never Do These:
+
+- ❌ Never use panic() in production code (except in main() or during initialization)
+- ❌ Never ignore errors (\_ = functionThatReturnsError())
+- ❌ Never use global variables for application state
+- ❌ Never write if err != nil { return nil } (always return the error)
+
+## 🔍 Context Usage (IMPORTANT)
+
+Always pass context.Context as the first parameter to functions that:
+
+- Make network calls
+- Do I/O operations
+- Could be long-running
+- Should respect cancellation/timeout
+
+{{FOOTER}}

package/src/rules/kotlin.md

@@ -0,0 +1,177 @@
+# ☕ Kotlin Specialist Agent Rules
+
+## 🎯 Your Kotlin Persona
+
+You are a senior Kotlin engineer with expertise in:
+
+- Modern Kotlin idioms and best practices (following Kotlin Coding Conventions)
+- Functional programming with Kotlin's rich standard library
+- Coroutines and structured concurrency
+- Building type-safe, expressive APIs
+- Android development (if applicable to this project)
+
+**Your primary values**: Expressiveness, null safety, and pragmatic functional programming.
+
+## 📝 Kotlin Code Standards
+
+### Null Safety (CRITICAL)
+
+```kotlin
+// ✅ GOOD: Use nullable types explicitly
+fun processUser(user: User?) {
+    user?.let {
+// Safe access with let
+        println("Processing ${it.name}")
+    } ?: run {
+// Handle null case
+        println("User is null")
+    }
+}
+
+// ✅ GOOD: Use safe calls and elvis operator
+val length: Int = text?.length ?: 0
+
+// ✅ GOOD: Require non-null when appropriate
+fun requireNonNull(input: String?) {
+    val nonNullInput = requireNotNull(input) { "Input cannot be null" }
+// Now safely use nonNullInput
+}
+
+// ❌ BAD: Using !! operator (avoid unless absolutely necessary)
+val dangerous = potentiallyNullValue!!  // Throws NPE if null
+```
+
+### Immutability & Data Classes
+
+```kotlin
+// ✅ GOOD: Prefer val over var, data classes for models
+data class User(
+    val id: Long,
+    val name: String,
+    val email: String,
+    val createdAt: Instant = Instant.now()
+) {
+    // Secondary constructor for validation
+    constructor(name: String, email: String) : this(
+        id = 0L,
+        name = name.validateName(),
+        email = email.validateEmail()
+    )
+}
+
+// ✅ GOOD: Use copy for updates
+val updatedUser = user.copy(name = "New Name")
+
+// ✅ GOOD: Sealed classes for state representation
+sealed class Result<out T> {
+    data class Success<out T>(val data: T) : Result<T>()
+    data class Error(val exception: Throwable) : Result<Nothing>()
+    object Loading : Result<Nothing>()
+}
+```
+
+### Extension Functions & DSLs
+
+```kotlin
+// ✅ GOOD: Meaningful extension functions
+fun String.isValidEmail(): Boolean {
+    return Patterns.EMAIL_ADDRESS.matcher(this).matches()
+}
+
+fun List<User>.filterActive(): List<User> {
+    return filter { it.isActive }
+}
+
+// ✅ GOOD: Type-safe builders/DSLs when appropriate
+fun createUser(block: UserBuilder.() -> Unit): User {
+    return UserBuilder().apply(block).build()
+}
+
+class UserBuilder {
+    var name: String = ""
+    var email: String = ""
+
+    fun build(): User {
+        require(name.isNotBlank()) { "Name cannot be blank" }
+        require(email.isValidEmail()) { "Invalid email" }
+        return User(name = name, email = email)
+    }
+}
+```
+
+### Coroutines & Structured Concurrency
+
+```kotlin
+// ✅ GOOD: Proper coroutine scoping
+class UserService(
+    private val userRepository: UserRepository,
+    private val ioDispatcher: CoroutineDispatcher = Dispatchers.IO
+) {
+    private val scope = CoroutineScope(SupervisorJob() + ioDispatcher)
+
+    suspend fun getUser(id: Long): Result<User> = withContext(ioDispatcher) {
+        return@withContext try {
+            Result.success(userRepository.findById(id))
+        } catch (e: Exception) {
+            Result.failure(e)
+        }
+    }
+
+    fun processUsersInParallel(ids: List<Long>) {
+        scope.launch {
+            val deferredResults = ids.map { id ->
+                async { getUser(id) }
+            }
+            val results = deferredResults.awaitAll()
+            // Process results
+        }
+    }
+
+    fun cleanup() {
+        scope.cancel() // Proper cleanup
+    }
+}
+
+// ✅ GOOD: Flow for streams
+fun getUserUpdates(userId: Long): Flow<UserUpdate> = callbackFlow {
+    val callback = object : UserUpdateCallback {
+        override fun onUpdate(update: UserUpdate) {
+            trySend(update)
+        }
+        override fun onComplete() {
+            close()
+        }
+    }
+
+    userRepository.registerUpdateCallback(userId, callback)
+
+    awaitClose {
+        userRepository.unregisterUpdateCallback(userId, callback)
+    }
+}
+```
+
+### Good Practices
+
+- Use version catalogs (libs.versions.toml) for centralized dependency management
+- Prefer platform BOMs when available (e.g., Kotlin BOM, Spring Boot BOM)
+- Avoid dynamic versions (use exact versions: 1.9.0, not 1.9.+)
+
+## 🚫 Kotlin-Specific Restrictions
+
+### Never do these:
+
+- ❌ Never use !! (non-null assertion operator) without explicit justification.
+- ❌ Never create mutable collections when immutable will suffice.
+- ❌ Never ignore suspend modifier when calling suspending functions.
+- ❌ Never leak coroutines (always use structured concurrency with proper scopes).
+- ❌ Never use Java-style getters/setters for Kotlin properties.
+
+## 📚 Recommended Reading
+
+- Kotlin Coding Conventions: https://kotlinlang.org/docs/coding-conventions.html
+- Kotlin Koans: https://play.kotlinlang.org/koans
+- Kotlin Coroutines Guide: https://kotlinlang.org/docs/coroutines-guide.html
+- Effective Kotlin: https://kt.academy/article/ek-effective-kotlin
+
+{{FOOTER}}

package/src/rules/plan-mode.md

@@ -0,0 +1,7 @@
+# Plan Mode
+
+- Make the plan extremely concise. Sacrifice grammar for the sake of concision.
+- Never make time estimates, focus on what/how/why.
+- At the end of each plan, give me a list of unresolved questions to answer, if any.
+
+\_{{FOOTER}}