Add comprehensive documentation for the plan package

[Copilot]

Overview

This PR adds comprehensive developer documentation for the webui/src/main/kotlin/com/simiacryptus/cognotik/plan package, which is the core orchestration layer of Cognotik responsible for AI-driven task planning, decomposition, and execution.

What's New

Added docs/2.0.8/plan_package.md - a 928-line comprehensive guide covering:

Package Components Documented

Core Classes:

• Planner - Converts user requests into structured task plans using AI models
• TaskOrchestrator - Manages execution of task plans with dependency ordering and concurrency
• OrchestrationConfig - Central configuration hub for orchestration behavior
• PlanUtil - Utility functions for visualization, validation, and dependency resolution

Task System:

• AbstractTask - Base class for all task implementations with lifecycle management
• TaskType - Dynamic enum registry for extensible task types
• TaskConfigBase - Base configuration with polymorphic JSON serialization
• TaskSettingsBase - Per-task-type settings and enablement
• ExecutionState - Mutable state tracking during execution
• TaskBreakdownWithPrompt - Data structure bridging planning and execution phases

Cognitive Modes:

• Overview of 5 planning strategies (Waterfall, DependencyGraph, Hierarchical, Adaptive, Conversational)
• Interface definitions and usage guidance

Task Tools:

• File operations (modification, analysis, search)
• Software graph operations (generation, modification, planning)
• Knowledge management (indexing, vector search)
• Online tasks (web crawling, search APIs)
• Session tasks (shell commands, browser automation)

Documentation Features

• Architecture diagrams showing component relationships and data flow
• 4 complete usage examples with working Kotlin code
• Best practices covering planning, execution, task implementation, configuration, debugging, and performance
• Cross-references to related documentation (task_types.md, cognitive-tasks.md, websocket_ui.md)
• Clear API documentation with method signatures and property descriptions

Why This Matters

The plan package is one of the most complex and powerful parts of Cognotik, but lacked dedicated documentation. This makes it difficult for:

• New contributors to understand the architecture
• Developers to implement custom task types
• Users to effectively configure and use the orchestration features

This documentation provides a single comprehensive resource that explains how all the components work together, with practical examples that developers can adapt for their needs.

Examples from the Documentation

The guide includes practical examples like implementing a custom task:

// Define configuration
data class MyCustomTaskConfigData(
    val customParam: String,
    task_description: String? = null,
    task_dependencies: List<String>? = null
) : TaskConfigBase(...)

// Implement task
class MyCustomTask(...) : AbstractTask<MyCustomTaskConfigData>(...) {
    override fun promptSegment() = "Performs custom operation"
    override fun run(...) { /* implementation */ }
}

// Register task type
TaskType.registerConstructor(MyCustomTaskType) { config, task ->
    MyCustomTask(config, task as? MyCustomTaskConfigData)
}

And using the orchestration system:

val orchestrator = TaskOrchestrator(user, session, storage, config, root)
val breakdown = planner.initialPlan(
    codeFiles = orchestrator.codeFiles,
    userMessage = "Refactor authentication to use OAuth2",
    orchestrationConfig = config
)
val executionState = orchestrator.executePlan(breakdown.plan, task, userMessage)

Resolves the documentation gap for the plan package and provides developers with the knowledge needed to effectively work with Cognotik's task orchestration system.

Original prompt

document webui/src/main/kotlin/com/simiacryptus/cognotik/plan

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.