Kanban Board Integration System#

Table of Contents#

  1. System Overview

  2. Architecture

  3. Marcus Ecosystem Integration

  4. Workflow Integration

  5. What Makes This Special

  6. Technical Implementation

  7. Provider Implementations

  8. AI Analysis Engine

  9. Natural Language Processing

  10. Task Complexity Handling

  11. Board-Specific Considerations

  12. Pros and Cons

  13. Why This Approach

  14. Future Evolution

  15. Analytics Integration

System Overview#

The Kanban Board Integration system is Marcus’s bridge to external project management platforms, enabling the AI project manager to create, read, update, and manage tasks across different kanban providers. This system transforms Marcus from a theoretical AI manager into a practical tool that can interact with real project management workflows.

Core Responsibilities#

  • Task Management: CRUD operations on tasks across different kanban platforms

  • Board State Synchronization: Keeping Marcus’s internal state aligned with external boards

  • Multi-Provider Support: Unified interface across Planka, Linear, and GitHub Projects

  • Natural Language Processing: Converting descriptions into structured tasks

  • AI-Enhanced Task Assignment: Intelligent task matching and instruction generation

Architecture#

The system follows a layered architecture with clear separation of concerns:

┌─────────────────────────────────────────────────────────────────┐
│                        MCP Tools Layer                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │  request_next   │  │ report_progress │  │  report_blocker │ │
│  │     _task       │  │                 │  │                 │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────────┐
│                  Natural Language Layer                        │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │ NLP Tools       │  │ Pipeline Track  │  │ Safety Checker  │ │
│  │ (create_proj,   │  │ (Visualization) │  │ (Dependencies)  │ │
│  │  add_feature)   │  │                 │  │                 │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────────┐
│                    AI Analysis Engine                          │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │ Task Assignment │  │ Blocker Resolve │  │ Risk Analysis   │ │
│  │ Optimization    │  │ AI Suggestions  │  │ Health Monitor  │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────────┐
│                     Abstraction Layer                          │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │ KanbanInterface │  │ KanbanFactory   │  │ KanbanClient    │ │
│  │ (Abstract Base) │  │ (Provider Sel.) │  │ (MCP Wrapper)   │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────────┐
│                    Provider Layer                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │ Planka Provider │  │ Linear Provider │  │ GitHub Provider │ │
│  │ (MCP via        │  │ (Direct API)    │  │ (GraphQL API)   │ │
│  │  kanban-mcp)    │  │                 │  │                 │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────────┐
│                   External Services                            │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │ Planka Board    │  │ Linear Project  │  │ GitHub Project  │ │
│  │ (Self-hosted)   │  │ (SaaS)          │  │ (Cloud/Enter.)  │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Marcus Ecosystem Integration#

The Kanban integration sits at the heart of Marcus’s operational ecosystem:

Data Flow#

  1. Inbound: External board state → Internal Marcus models

  2. Processing: AI analysis → Task optimization → Dependency resolution

  3. Outbound: Marcus decisions → External board updates

Key Integration Points#

  • Core Models: Task, ProjectState, WorkerStatus objects

  • Error Framework: Structured error handling with proper context

  • Context System: Dependency tracking and interface recommendations

  • Cost Tracking: AI usage monitoring and token accounting

  • Event Pipeline: Visualization and monitoring of all operations

Workflow Integration#

The kanban system is invoked at specific points in the typical Marcus workflow:

create_project → register_agent → request_next_task → report_progress → report_blocker → finish_task
      ↓              ↓                    ↓                 ↓               ↓            ↓
    [CREATE]      [INIT]            [READ/ASSIGN]        [UPDATE]       [ANALYZE]    [UPDATE]
      │              │                    │                 │               │            │
      ├─ NLP Tools   ├─ Board Setup      ├─ AI Matching    ├─ Progress     ├─ AI       ├─ Status
      ├─ Task Gen    ├─ Client Init      ├─ Task Filter    ├─ Comments     ├─ Suggest  ├─ Complete
      └─ Batch       └─ Config Load      └─ Assignment     └─ Status       └─ Resolve  └─ Move
         Create                             API Call         Update           Steps       Card

Invocation Points#

1. Project Creation (create_project)#

  • Tool: src.marcus_mcp.tools.nlp.create_project

  • Kanban Action: Batch task creation via KanbanClientWithCreate

  • AI Integration: PRD parsing, task decomposition, dependency mapping

2. Agent Registration (register_agent)#

  • Tool: mcp__marcus__register_agent

  • Kanban Action: Board configuration validation

  • AI Integration: Skill-based board analysis

3. Task Assignment (request_next_task)#

  • Tool: mcp__marcus__request_next_task

  • Kanban Action: get_available_tasks() → AI analysis → assign_task()

  • AI Integration: Optimal task-agent matching with context awareness

4. Progress Reporting (report_progress)#

  • Tool: mcp__marcus__report_task_progress

  • Kanban Action: add_comment() + status updates

  • AI Integration: Progress analysis and bottleneck detection

5. Blocker Resolution (report_blocker)#

  • Tool: mcp__marcus__report_blocker

  • Kanban Action: report_blocker() → AI analysis → suggestions

  • AI Integration: Context-aware resolution strategies

6. Task Completion (finish_task)#

  • Tool: Task completion via progress reporting

  • Kanban Action: complete_task() → move_task_to_column()

  • AI Integration: Completion validation and next task recommendations

What Makes This Special#

1. Multi-Provider Abstraction#

Unlike typical integrations that are tightly coupled to one platform, Marcus provides a unified interface across three major kanban providers with completely different APIs and data models.

2. AI-Native Design#

Every operation is enhanced by AI analysis:

  • Task assignment considers skills, capacity, and project context

  • Blocker resolution provides intelligent, agent-specific suggestions

  • Risk analysis identifies patterns across project history

3. MCP-First Architecture#

Built specifically for the Model Context Protocol, enabling:

  • Secure, sandboxed external service access

  • Standardized tool interfaces for AI agents

  • Robust error handling and recovery mechanisms

4. Natural Language Processing#

Converts human descriptions into structured project plans:

  • PRD parsing with requirement extraction

  • Feature decomposition with dependency mapping

  • Safety checks for logical task ordering

5. Pipeline Visualization#

Every operation is tracked and visualized:

  • Real-time progress monitoring

  • Performance bottleneck identification

  • Quality assessment metrics

Technical Implementation#

Core Interfaces#

KanbanInterface (Abstract Base Class)#

class KanbanInterface(ABC):
    @abstractmethod
    async def get_available_tasks(self) -> List[Task]
    @abstractmethod
    async def assign_task(self, task_id: str, assignee_id: str) -> bool
    @abstractmethod
    async def update_task_progress(self, task_id: str, progress_data: Dict[str, Any]) -> bool
    @abstractmethod
    async def report_blocker(self, task_id: str, blocker_description: str, severity: str) -> bool

KanbanClient (MCP Implementation)#

class KanbanClient:
    """Simple MCP client following proven reliability patterns"""

    async def get_available_tasks(self) -> List[Task]:
        # Creates new MCP session for each operation
        server_params = StdioServerParameters(
            command="node",
            args=["../kanban-mcp/dist/index.js"],
            env=os.environ.copy()
        )
        async with stdio_client(server_params) as (read, write):
            async with ClientSession(read, write) as session:
                # Fetch and filter tasks

Design Patterns#

1. Session-Per-Operation Pattern#

Each kanban operation creates a fresh MCP session rather than maintaining persistent connections. This approach has proven more reliable in practice, eliminating connection timeouts and state corruption issues.

2. Graceful Degradation#

All AI-enhanced features have fallback implementations:

async def match_task_to_agent(self, tasks, agent, project_state):
    if not self.client:  # AI unavailable
        return self._fallback_task_matching(tasks, agent)
    # ... AI logic

3. Error Context Enrichment#

Structured error handling with Marcus Error Framework:

from src.core.error_framework import KanbanIntegrationError, ErrorContext

raise KanbanIntegrationError(
    board_name=self.board_id,
    operation="task_creation",
    context=ErrorContext(
        operation="create_task",
        integration_name="kanban_client",
        custom_context={"task_name": task.name}
    )
)

4. Dependency Injection#

All components are loosely coupled via interfaces:

# Can inject any KanbanInterface implementation
creator = NaturalLanguageProjectCreator(
    kanban_client=kanban_interface,  # SQLite, Planka, Linear, or GitHub
    ai_engine=ai_analysis_engine,
    subtask_manager=None,     # optional
    complexity="standard"     # optional
)

Provider Implementations#

Planka Provider#

  • Technology: MCP via kanban-mcp server

  • Strengths: Full MCP compliance, self-hosted control, web UI for visual board management

  • Architecture: Node.js MCP server → Planka REST API

  • Special Features: Rich comment system, custom fields support

  • When to use: Team environments where a visual board UI is needed

Linear Provider#

  • Technology: Direct GraphQL API

  • Strengths: Native API integration, rich metadata

  • Architecture: Python client → Linear GraphQL

  • Special Features: Workflow automation, team synchronization

GitHub Provider#

  • Technology: GitHub Projects v2 API

  • Strengths: Code integration, enterprise features

  • Architecture: REST + GraphQL hybrid

  • Special Features: Repository linking, milestone tracking

AI Analysis Engine#

The AIAnalysisEngine provides intelligent enhancement to all kanban operations:

Task Assignment Optimization#

async def match_task_to_agent(self, available_tasks, agent, project_state):
    # AI prompt considers:
    # 1. Agent skills vs task requirements
    # 2. Current capacity and workload
    # 3. Task priority and dependencies
    # 4. Project timeline and critical path

    prompt = """Analyze and recommend the SINGLE BEST task for this agent..."""
    response = await self._call_claude(prompt)
    return self._find_recommended_task(response, available_tasks)

Blocker Resolution#

async def analyze_blocker(self, task_id, description, severity, agent, task):
    # Generates agent-specific resolution steps
    # Considers skill level and provides learning opportunities
    # Recommends collaborators based on expertise gaps

    return {
        "root_cause": "analysis",
        "resolution_steps": ["step1 tailored to agent skills"],
        "learning_opportunities": ["skill gaps identified"],
        "recommended_collaborators": ["team members with needed skills"]
    }

Project Risk Analysis#

async def analyze_project_risks(self, project_state, recent_blockers, team_status):
    # Identifies patterns in blockers
    # Assesses team capacity and velocity trends
    # Predicts potential bottlenecks

    return [
        ProjectRisk(
            risk_type="timeline",
            description="Critical path delay risk",
            mitigation_strategy="Reallocate resources to blocked tasks"
        )
    ]

Natural Language Processing#

The NLP system converts human descriptions into structured project plans:

Project Creation Pipeline#

  1. Context Detection: Analyze board state and recommend processing mode

  2. PRD Parsing: Extract functional/non-functional requirements

  3. Task Generation: Decompose requirements into actionable tasks

  4. Safety Checking: Apply logical dependencies (testing after implementation)

  5. Board Creation: Batch create tasks with proper metadata

Feature Addition Pipeline#

  1. Feature Analysis: Classify feature type and complexity

  2. Integration Detection: Find existing tasks that need integration

  3. Task Enrichment: Add context-aware metadata and dependencies

  4. Dependency Mapping: Link to existing project infrastructure

Task Classification System#

class TaskType(Enum):
    DESIGN = "design"
    IMPLEMENTATION = "implementation"
    TESTING = "testing"
    DEPLOYMENT = "deployment"
    DOCUMENTATION = "documentation"
    INTEGRATION = "integration"
    INFRASTRUCTURE = "infrastructure"
    OTHER = "other"

class TaskClassifier:
    @classmethod
    def classify(cls, task: Task) -> TaskType:
        # Analyzes task name, description, and labels
        # Returns appropriate task type for workflow ordering

Task Complexity Handling#

The system handles different task complexities through multiple strategies:

Simple Tasks (1-4 hours)#

  • Processing: Direct assignment with minimal AI analysis

  • Instructions: Template-based with basic context

  • Dependencies: Simple prerequisite checking

  • Example: “Fix button styling on login page”

Complex Tasks (8+ hours)#

  • Processing: Full AI analysis with decomposition suggestions

  • Instructions: Detailed, step-by-step guidance with architectural context

  • Dependencies: Deep dependency analysis with interface recommendations

  • Example: “Implement user authentication system with JWT tokens”

Project-Level Tasks (20+ hours)#

  • Processing: Automatic decomposition into subtasks

  • Instructions: Architectural guidance with design phase separation

  • Dependencies: Full project timeline analysis

  • Example: “Build e-commerce platform with payment processing”

Adaptive Strategies#

Simple Task Fast-Path#

if task.estimated_hours <= 4:
    # Skip AI analysis for speed
    return self._simple_assignment_algorithm(task, available_agents)

Complex Task Deep Analysis#

if task.estimated_hours >= 8:
    # Full AI context analysis
    instructions = await self.ai_engine.generate_task_instructions(
        task, agent, project_context
    )
    dependencies = await self.ai_engine.analyze_task_dependencies(
        task, project_tasks
    )

Board-Specific Considerations#

Planka Boards#

  • Strength: Full control, custom workflows

  • Limitation: Requires self-hosting and maintenance

  • Best For: Internal teams, custom business processes

  • MCP Integration: Native via kanban-mcp server

Linear Boards#

  • Strength: Developer-optimized, great API

  • Limitation: SaaS pricing, limited customization

  • Best For: Software teams, sprint planning

  • Integration Pattern: Direct API calls with caching

GitHub Projects#

  • Strength: Tight code integration, enterprise features

  • Limitation: Complex API, frequent changes

  • Best For: Open source projects, development workflows

  • Integration Pattern: Hybrid REST/GraphQL with webhook support

Board State Synchronization#

Each provider handles state differently:

# Planka: Explicit list-based states
"TODO" → "In Progress" → "Done"

# Linear: Workflow-based with custom states
"Backlog" → "Ready" → "In Development" → "Review" → "Done"

# GitHub: Custom column-based
Configurable workflow states with automation rules

Pros and Cons#

Pros#

Technical Advantages#

  1. Multi-Provider Support: Single codebase supports three major platforms

  2. AI Enhancement: Every operation benefits from intelligent analysis

  3. MCP Native: Built specifically for AI agent interactions

  4. Graceful Degradation: Works even when AI services are unavailable

  5. Error Resilience: Comprehensive error handling with context preservation

  6. Pipeline Visualization: Full operational transparency

Business Advantages#

  1. Vendor Independence: Not locked into single kanban provider

  2. Cost Optimization: AI usage tracking and optimization

  3. Team Adaptation: Matches existing team workflows

  4. Learning Integration: Provides growth opportunities for team members

Cons#

Technical Limitations#

  1. Complexity: Multi-layer architecture increases maintenance overhead

  2. Performance: Session-per-operation adds latency

  3. Dependencies: Requires external MCP servers and AI services

  4. Sync Challenges: Real-time board synchronization is limited

Operational Challenges#

  1. Setup Complexity: Initial configuration requires technical expertise

  2. Provider Differences: Feature parity varies across providers

  3. API Limitations: Constrained by external service capabilities

  4. Cost Accumulation: AI calls can become expensive at scale

Why This Approach#

Design Decisions#

1. Multi-Provider Strategy#

Decision: Support multiple kanban providers rather than focusing on one Rationale: Organizations have different tool preferences and constraints Trade-off: Increased complexity for broader adoption

2. Session-Per-Operation Pattern#

Decision: Create fresh MCP sessions for each operation Rationale: Persistent connections proved unreliable in testing Trade-off: Higher latency for improved reliability

3. AI-First Design#

Decision: Make AI analysis the primary path with fallbacks Rationale: Maximize intelligent behavior while maintaining functionality Trade-off: Higher operational cost for better decision quality

4. Abstract Interface Pattern#

Decision: Use abstract base classes with concrete implementations Rationale: Enable provider swapping without code changes Trade-off: Additional abstraction layers for flexibility

5. Natural Language Integration#

Decision: Support both programmatic and natural language task creation Rationale: Lower barrier to entry for non-technical users Trade-off: Increased system complexity for broader usability

Future Evolution#

Short-Term Improvements (3-6 months)#

  1. Real-Time Sync: WebSocket-based board synchronization

  2. Batch Operations: Optimize multiple task operations

  3. Advanced Caching: Reduce API calls with intelligent caching

  4. Provider Parity: Ensure feature consistency across providers

Medium-Term Enhancements (6-12 months)#

  1. Workflow Automation: Custom workflow creation and management

  2. Advanced Analytics: Predictive project health monitoring

  3. Team Optimization: AI-driven team composition recommendations

  4. Integration Expansion: Support for Jira, Asana, Notion

Long-Term Vision (1-2 years)#

  1. Autonomous Management: Fully AI-driven project management

  2. Cross-Platform Workflows: Unified workflows across multiple tools

  3. Predictive Planning: AI-powered project planning and estimation

  4. Enterprise Features: Advanced security, audit trails, compliance

Architectural Evolution#

Performance Optimization#

  • Connection pooling for frequently accessed boards

  • Intelligent prefetching of related tasks

  • Background synchronization processes

AI Capabilities#

  • Multi-modal understanding (code, images, documents)

  • Continuous learning from project outcomes

  • Advanced risk prediction and mitigation

Integration Ecosystem#

  • Plugin architecture for custom integrations

  • Marketplace for community-contributed providers

  • Enterprise connectors for SAP, ServiceNow, etc.

Analytics Integration#

NOTE: Cato (the dashboard) reads kanban state directly from the board (SQLite/Planka/etc.) rather than through a callable analytics class inside Marcus. There is no CatoClient class inside Marcus that exposes methods like analyze_project_description(), generate_project_structure(), or analyze_task_complexity() — those examples in the snippets below are illustrative of where Cato could plug in, not a current API.

The kanban integration contributes data to Marcus’s broader intelligence systems through existing components:

Data Contributions#

  1. Task Metrics: Completion rates, velocity trends, quality indicators

  2. Team Performance: Individual and collective productivity data

  3. Project Health: Risk indicators, bottleneck identification

  4. Process Efficiency: Workflow optimization opportunities

This document provides a comprehensive technical overview of Marcus’s Kanban Board Integration system. For implementation details, see the source code in /src/integrations/. For configuration guidance, see /docs/user-guide/kanban-setup.md.

On this page
Edit on GitHub
Show Source