Build Tools

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

View Demo Repository Documentation

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.

Frontmatter Keys

Key	Description
`specifies`	Glob pattern(s) for files to generate/update based on this documentation
`documents`	Glob pattern(s) for source files this documentation describes
`transforms`	Pattern-based file transformations using regex with capture groups
`generates`	Non-pattern-based generation with explicit output and input files
`related`	Additional files to include as context

Basic Specification Example

yaml

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

Overwrite Modes

Mode	Behavior
`SkipExisting`	Never modify existing files
`OverwriteExisting`	Always replace existing files
`OverwriteToUpdate`	Replace only if source is newer
`PatchExisting`	Apply incremental patches to existing files
`PatchToUpdate`	Apply patches only if source is newer

FileGenerator

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

Usage Example

kotlin

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.

kotlin

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.

kotlin

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

Parameter	Description	Default
`prompt`	The task description for the AI	Required
`cognitiveSettings`	Cognitive mode configuration	Required
`fastModel`	Model for quick operations	GeminiFlash_30_Preview
`smartModel`	Model for complex reasoning	GeminiFlash_30_Preview
`timeoutMinutes`	Maximum execution time	30
`serverless`	Run without web server	true

TaskHarness

Executes single AI tasks with specific configurations.

kotlin

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.

kotlin

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

Gradle Integration

kotlin

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:

xml

<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:

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

🎫 Agentic Issue Handler

Triggered when issues are labeled with agent-help:

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

Error Handling

kotlin

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

Supported AI Providers

Provider	Model Example	Environment Variable
Google	Gemini 3.0	`GOOGLE_API_KEY`
OpenAI	GPT-4o	`OPENAI_API_KEY`
Anthropic	Claude 4.5	`ANTHROPIC_API_KEY`
Groq	Llama 3 70B	`GROQ_API_KEY`