Build Tools

AI-powered utilities for automated code generation, documentation processing, and task execution. Embed intelligent workflows into your build processes or run standalone.

Key Components

• DocProcessor — Processes markdown documentation files to generate or update code files. Supports bidirectional documentation-code synchronization via YAML frontmatter.
• FileGenerator — Flexible framework for generating files based on source files and AI assistance. Perfect for test generation and boilerplate creation.
• ExceptionFixer — Analyzes exception stack traces and automatically generates fixes for relevant source files using fuzzy patching.
• PlanHarness — Executes complex multi-step AI plans using cognitive modes for sophisticated task orchestration.
• TaskHarness — Executes single AI tasks with specific configurations for focused, targeted operations.
• UnifiedHarness — Core infrastructure for running AI-assisted operations in server or serverless mode.

DocProcessor

The DocProcessor processes markdown documentation files that specify target files via YAML frontmatter. It supports bidirectional documentation-code synchronization. See frontmatter-schema.md for full key documentation.

Frontmatter Keys

Basic Specification Example

---
specifies: ../src/main/kotlin/MyClass.kt
---
# MyClass Documentation
This class should implement...

Overwrite Modes

FileGenerator

The FileGenerator provides a flexible framework for generating files based on source files and AI assistance.

FileGenerator().run(
    root = projectRoot,
    folder = sourceFolder,
    listFiles = { root, folder ->
        folder.listFilesRecursively()
            .filter { it.extension == "kt" }
    },
    targetFile = { source ->
        File(source.parent, "${source.nameWithoutExtension}Test.kt")
    },
    overwriteMode = OverwriteModes.SkipExisting,
    relatedFiles = { source -> listOf(source.path) },
    generationPrompt = { source, target ->
        "Generate unit tests for ${source.name}"
    }
)

ExceptionFixer

The ExceptionFixer analyzes exception stack traces and automatically generates fixes for the relevant source files.

val fixer = ExceptionFixer(
    projectRoot = File("/project"),
    related_files = listOf("src/main/kotlin/Config.kt")
)
try {
    // Code that might throw
} catch (e: Exception) {
    fixer.fix(e)
}

Features:

• Automatically identifies source files from stack traces
• Searches for Kotlin source files in standard Maven/Gradle layouts
• Includes related files as context for better fixes
• Uses fuzzy patching for safe modifications

PlanHarness

Executes complex multi-step AI plans using cognitive modes.

val harness = PlanHarness(
    prompt = "Create a REST API for user management",
    cognitiveSettings = CognitiveModeConfig(
        type = CognitiveModeType.TaskPlanning
    ),
    fastModel = GeminiModels.GeminiFlash_30_Preview,
    smartModel = GeminiModels.GeminiFlash_30_Preview,
    workspace = File("/project"),
    timeoutMinutes = 30,
    openBrowser = false,
    serverless = true
)
harness.run()

PlanHarness Options

TaskHarness

Executes single AI tasks with specific configurations.

val harness = TaskHarness(
    taskType = FileModification,
    typeConfig = TaskTypeConfig(task_type = "FileModification"),
    executionConfig = FileModificationTaskExecutionConfigData(
        files = listOf("src/main/kotlin/MyClass.kt"),
        task_description = "Add logging to all public methods"
    ),
    workspace = File("/project"),
    timeoutMinutes = 5
)
harness.run()

UnifiedHarness

Core infrastructure supporting both server and serverless modes.

// Helper function for convenient operation
withHarness(
    root = projectRoot,
    testName = "MyOperation",
    fastModel = GeminiModels.GeminiFlash_30_Preview,
    smartModel = GeminiModels.GeminiFlash_30_Preview
) { harness ->
    harness.runTask(...)
}

Integration

Gradle Integration

tasks.register("generateDocs") {
    doLast {
        DocProcessor(
            root = projectDir,
            docsFolder = file("docs"),
            overwriteMode = OverwriteModes.PatchToUpdate
        ).run()
    }
}

Maven Integration

Use the exec-maven-plugin to run the tools:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>exec-maven-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>java</goal>
            </goals>
            <configuration>
                <mainClass>com.simiacryptus.cognotik.util.DocProcessorKt</mainClass>
            </configuration>
        </execution>
    </executions>
</plugin>

GitHub Actions Workflows

Auto-Fixing Build Validator — Triggered on pull requests to main. Automatically fixes failing builds:

1. Runs the test suite and captures output
2. If tests fail, invokes the Code Fixer agent
3. Agent analyzes build log and fixes implementation files
4. Commits fixes automatically

Agentic Issue Handler — Triggered when issues are labeled with agent-help:

1. Analyzes the issue title and description
2. Reviews relevant source files
3. Creates a pull request with proposed changes

Error Handling

PlanHarness.fix = { e ->
    // Custom error handling
    ExceptionFixer(projectRoot).fix(e)
}
TaskHarness.fix = { e ->
    // Custom error handling
    log.error("Task failed", e)
}

Supported AI Providers