docs/workflow/development.md

metadata

title: Development Workflow
description: Development processes, automation, and workflow patterns for KGraph-MCP

Development Workflow

Comprehensive documentation of KGraph-MCP's development workflow, task management processes, and automated development patterns that enable efficient collaborative development.

🔄 Overview

KGraph-MCP implements a sophisticated development workflow that combines:

• Automated Task Management: GitHub-integrated task tracking with intelligent assignment
• Quality-First Development: Comprehensive CI/CD pipeline with automated quality gates
• AI-Assisted Development: Claude 4.0 integration for autonomous project management
• Rapid Iteration: Justfile automation with 30+ development commands

🚀 Core Development Workflow

Daily Development Process

flowchart TD
    Start([Start Development Day]) --> Check[Check Available Tasks]
    Check --> Select[Select Next Task]
    Select --> Branch[Create Feature Branch]
    
    Branch --> Setup[Setup Development Environment]
    Setup --> Implement[Implement Feature/Fix]
    Implement --> Test[Run Tests]
    
    Test --> Quality{Quality Checks}
    Quality -->|Pass| Commit[Commit Changes]
    Quality -->|Fail| Fix[Fix Issues]
    Fix --> Test
    
    Commit --> Push[Push to GitHub]
    Push --> PR[Create Pull Request]
    PR --> Review[Code Review]
    
    Review --> Approve{Review Approved?}
    Approve -->|Yes| Merge[Merge to Main]
    Approve -->|No| Update[Update Code]
    Update --> Test
    
    Merge --> Deploy[Deploy Changes]
    Deploy --> UpdateTask[Update Task Status]
    UpdateTask --> End([Complete Task])
    
    subgraph "🔧 Development Tools"
        JustCommands[Just Commands<br/>30+ Automation Recipes]
        QualityGates[Quality Gates<br/>Lint, Format, Type, Test]
        GitHubIntegration[GitHub Integration<br/>Issues, Projects, Actions]
    end
    
    Setup --> JustCommands
    Test --> QualityGates
    Push --> GitHubIntegration
    
    style Start fill:#e3f2fd
    style Select fill:#e8f5e8
    style Quality fill:#f3e5f5
    style Merge fill:#fff3e0

Task Management Workflow

sequenceDiagram
    participant Dev as Developer
    participant Local as Local System
    participant GitHub as GitHub Projects
    participant AI as Claude 4.0 PM
    participant Just as Just Commands
    
    Dev->>Local: just task-next
    Local->>GitHub: Query Available Tasks
    GitHub-->>Local: Return Task List
    Local-->>Dev: Display Next Task
    
    Dev->>Just: just task-start <task-id>
    Just->>Local: Update Task Status
    Just->>GitHub: Sync Task Status
    Just-->>Dev: Branch Name Generated
    
    Dev->>Local: git checkout -b <branch>
    Note over Dev: Development Work
    
    Dev->>Just: just pre-commit
    Just->>Local: Run Quality Checks
    Local-->>Just: Quality Report
    Just-->>Dev: Quality Status
    
    Dev->>Local: git commit & push
    Dev->>GitHub: Create Pull Request
    GitHub->>AI: Notify PM System
    
    AI->>GitHub: Review PR
    AI->>Local: Update Task Tracking
    Note over AI: Autonomous PM Actions
    
    Dev->>Just: just task-done <task-id>
    Just->>Local: Complete Task
    Just->>GitHub: Sync Completion
    GitHub-->>Dev: Task Archived

📋 Task Management System

Task Lifecycle Management

stateDiagram-v2
    [*] --> Backlog
    
    Backlog --> Todo : Task Prioritized
    Todo --> InProgress : Developer Starts
    InProgress --> Review : Code Complete
    Review --> Testing : Review Passed
    Testing --> Done : Tests Pass
    
    InProgress --> Blocked : Issue Encountered
    Review --> InProgress : Changes Required
    Testing --> Review : Test Failures
    
    Blocked --> InProgress : Issue Resolved
    Done --> Archived : Task Completed
    Archived --> [*]
    
    state InProgress {
        [*] --> Coding
        Coding --> LocalTesting
        LocalTesting --> Debugging
        Debugging --> Coding
        LocalTesting --> [*]
    }
    
    state Review {
        [*] --> CodeReview
        CodeReview --> FeedbackReview
        FeedbackReview --> ApprovalCheck
        ApprovalCheck --> [*]
    }
    
    state Testing {
        [*] --> UnitTests
        UnitTests --> IntegrationTests
        IntegrationTests --> QualityGates
        QualityGates --> [*]
    }

GitHub Integration Architecture

graph TB
    subgraph "🐙 GitHub Ecosystem"
        Issues[GitHub Issues<br/>Task Tracking]
        Projects[GitHub Projects v2<br/>Kanban Board]
        Actions[GitHub Actions<br/>CI/CD Pipeline]
        PR[Pull Requests<br/>Code Review]
    end
    
    subgraph "🏠 Local Development"
        Just[Just Commands<br/>Automation]
        TaskDB[Local Task DB<br/>SQLite/JSON]
        DevEnv[Development Environment<br/>Python 3.11.8 + uv]
    end
    
    subgraph "🤖 AI Integration"
        Claude[Claude 4.0 PM<br/>Autonomous Management]
        Agent[AI Development Agent<br/>Task Assignment]
        Learning[Learning System<br/>Pattern Recognition]
    end
    
    subgraph "🔄 Sync Mechanisms"
        GHSync[GitHub CLI Sync<br/>Bidirectional]
        APISync[REST API Sync<br/>Real-time Updates]
        WebhookSync[Webhook Integration<br/>Event-driven]
    end
    
    Issues --> GHSync
    Projects --> APISync
    Actions --> WebhookSync
    
    GHSync --> Just
    APISync --> TaskDB
    WebhookSync --> DevEnv
    
    Just --> Claude
    TaskDB --> Agent
    DevEnv --> Learning
    
    Claude --> Issues
    Agent --> Projects
    Learning --> Actions
    
    style Issues fill:#e1f5fe
    style Just fill:#e8f5e8
    style Claude fill:#f3e5f5
    style GHSync fill:#fff3e0

🔧 Development Environment Setup

Environment Initialization Workflow

flowchart TD
    Clone[Clone Repository] --> Check[Check Prerequisites]
    Check --> Install{Install Dependencies}
    
    Install -->|Automated| JustSetup[just setup]
    Install -->|Manual| ManualSetup[Manual Setup Process]
    
    JustSetup --> Python[Install Python 3.11.8]
    Python --> VEnv[Create Virtual Environment]
    VEnv --> Deps[Install Dependencies]
    Deps --> Tasks[Initialize Tasks]
    Tasks --> Complete[Setup Complete]
    
    ManualSetup --> UVInstall[uv python install 3.11.8]
    UVInstall --> VEnvManual[uv venv .venv]
    VEnvManual --> SyncDeps[uv pip sync requirements.lock]
    SyncDeps --> InitTasks[Initialize Task System]
    InitTasks --> Complete
    
    Complete --> Verify[Verify Installation]
    Verify --> Health{Health Checks}
    
    Health -->|Pass| Ready[Development Ready]
    Health -->|Fail| Debug[Debug Issues]
    Debug --> Verify
    
    Ready --> FirstTask[Get First Task]
    FirstTask --> DevStart[Start Development]
    
    subgraph "✅ Verification Steps"
        LintCheck[just lint-check]
        FormatCheck[just format-check]
        TypeCheck[just type-check]
        TestRun[just test]
    end
    
    Verify --> LintCheck
    Verify --> FormatCheck
    Verify --> TypeCheck
    Verify --> TestRun
    
    style Clone fill:#e3f2fd
    style JustSetup fill:#e8f5e8
    style Complete fill:#f3e5f5
    style Ready fill:#c8e6c9

Quality Gates Pipeline

graph LR
    subgraph "📝 Code Quality"
        Lint[Ruff Linting<br/>Auto-fix Available]
        Format[Black Formatting<br/>Consistent Style]
        Type[MyPy Type Checking<br/>Type Safety]
        Security[Bandit Security<br/>Vulnerability Scan]
    end
    
    subgraph "🧪 Testing Pipeline"
        Unit[Unit Tests<br/>pytest]
        Integration[Integration Tests<br/>API & Services]
        Coverage[Test Coverage<br/>80%+ Required]
        Performance[Performance Tests<br/>Load & Stress]
    end
    
    subgraph "📊 Metrics & Reporting"
        CodeQuality[Code Quality Score]
        TestResults[Test Results Report]
        CoverageReport[Coverage Report HTML]
        SecurityReport[Security Assessment]
    end
    
    Lint --> CodeQuality
    Format --> CodeQuality
    Type --> CodeQuality
    Security --> SecurityReport
    
    Unit --> TestResults
    Integration --> TestResults
    Coverage --> CoverageReport
    Performance --> TestResults
    
    CodeQuality --> Pass{All Checks Pass?}
    TestResults --> Pass
    CoverageReport --> Pass
    SecurityReport --> Pass
    
    Pass -->|Yes| Deploy[Ready for Deployment]
    Pass -->|No| Fix[Fix Issues & Retry]
    
    style Lint fill:#e1f5fe
    style Unit fill:#e8f5e8
    style CodeQuality fill:#f3e5f5
    style Deploy fill:#c8e6c9
    style Fix fill:#ffebee

🔄 CI/CD Pipeline Architecture

Continuous Integration Workflow

flowchart TD
    Push[Code Push to GitHub] --> Trigger[Trigger GitHub Actions]
    Trigger --> Checkout[Checkout Code]
    Checkout --> Setup[Setup Environment]
    
    Setup --> Parallel{Parallel Jobs}
    
    Parallel --> Lint[Linting Job]
    Parallel --> Test[Testing Job]
    Parallel --> Security[Security Job]
    Parallel --> Build[Build Job]
    
    Lint --> LintReport[Generate Lint Report]
    Test --> TestReport[Generate Test Report]
    Security --> SecurityReport[Generate Security Report]
    Build --> Artifact[Generate Build Artifact]
    
    LintReport --> Collect[Collect Results]
    TestReport --> Collect
    SecurityReport --> Collect
    Artifact --> Collect
    
    Collect --> QualityGate{Quality Gate}
    QualityGate -->|Pass| Success[CI Success]
    QualityGate -->|Fail| Fail[CI Failure]
    
    Success --> Deploy{Deploy?}
    Deploy -->|Main Branch| Production[Deploy to Production]
    Deploy -->|Feature Branch| Preview[Deploy Preview]
    
    Fail --> Notify[Notify Developer]
    Notify --> Fix[Fix Issues]
    Fix --> Push
    
    subgraph "📊 Quality Metrics"
        CoverageThreshold[Test Coverage ≥ 80%]
        LintScore[Lint Score = 10/10]
        SecurityScore[Security Score = A]
        PerformanceScore[Performance Score ≥ 90%]
    end
    
    QualityGate --> CoverageThreshold
    QualityGate --> LintScore
    QualityGate --> SecurityScore
    QualityGate --> PerformanceScore
    
    style Push fill:#e3f2fd
    style QualityGate fill:#e8f5e8
    style Success fill:#c8e6c9
    style Fail fill:#ffebee

Deployment Strategy

graph TB
    subgraph "🌍 Environments"
        Dev[Development<br/>localhost:7860]
        Staging[Staging<br/>staging.kgraph-mcp.com]
        Prod[Production<br/>kgraph-mcp.com]
    end
    
    subgraph "🚀 Deployment Triggers"
        FeatureBranch[Feature Branch<br/>→ Dev Environment]
        MainBranch[Main Branch<br/>→ Staging Environment]
        Release[Release Tag<br/>→ Production Environment]
    end
    
    subgraph "📋 Deployment Steps"
        Health[Health Check]
        Backup[Backup Current State]
        Deploy[Deploy New Version]
        Verify[Verify Deployment]
        Rollback[Rollback if Failed]
    end
    
    subgraph "📊 Monitoring"
        Metrics[Performance Metrics]
        Logs[Application Logs]
        Alerts[Alert System]
        Dashboard[Monitoring Dashboard]
    end
    
    FeatureBranch --> Dev
    MainBranch --> Staging
    Release --> Prod
    
    Dev --> Health
    Staging --> Health
    Prod --> Health
    
    Health --> Backup
    Backup --> Deploy
    Deploy --> Verify
    Verify --> Rollback
    
    Deploy --> Metrics
    Verify --> Logs
    Rollback --> Alerts
    Metrics --> Dashboard
    
    style Dev fill:#e3f2fd
    style Staging fill:#fff3e0
    style Prod fill:#c8e6c9
    style Rollback fill:#ffebee

🤖 AI-Assisted Development

Claude 4.0 Project Management Integration

sequenceDiagram
    participant Dev as Developer
    participant Claude as Claude 4.0 PM
    participant GitHub as GitHub API
    participant Local as Local System
    participant Tasks as Task System
    
    Dev->>Claude: Request Next Task
    Claude->>Tasks: Analyze Available Tasks
    Tasks-->>Claude: Task List & Priorities
    Claude->>GitHub: Check Project Status
    GitHub-->>Claude: Current Sprint Status
    
    Note over Claude: AI Analysis & Decision
    Claude->>Claude: Analyze Developer Skills
    Claude->>Claude: Consider Project Goals
    Claude->>Claude: Optimize Task Assignment
    
    Claude->>Dev: Recommend Task + Context
    Dev->>Local: Accept Task Assignment
    Local->>Tasks: Update Task Status
    Local->>GitHub: Sync Task Status
    
    Note over Dev: Development Work
    
    Dev->>Local: Commit Progress
    Local->>Claude: Report Progress
    Claude->>GitHub: Update Project Metrics
    
    Claude->>Claude: Learn from Progress
    Note over Claude: Update PM Models
    
    Dev->>Claude: Task Complete
    Claude->>Tasks: Validate Completion
    Claude->>GitHub: Update Project Board
    Claude->>Dev: Next Task Recommendation

Automated Task Assignment Logic

flowchart TD
    TaskPool[Available Tasks] --> Analyze[Analyze Task Requirements]
    Analyze --> Skills[Match Developer Skills]
    Skills --> Workload[Check Current Workload]
    Workload --> Priority[Apply Priority Rules]
    
    Priority --> Score[Calculate Assignment Score]
    Score --> Constraints{Check Constraints}
    
    Constraints -->|Pass| Assign[Assign Task]
    Constraints -->|Fail| Alternative[Find Alternative]
    
    Alternative --> Analyze
    
    Assign --> Notify[Notify Developer]
    Notify --> Track[Track Assignment]
    Track --> Learn[Update Learning Model]
    
    subgraph "🎯 Scoring Factors"
        SkillMatch[Skill Match Score<br/>0.0 - 1.0]
        Complexity[Task Complexity<br/>1-5 Scale]
        Urgency[Task Urgency<br/>High/Medium/Low]
        Dependencies[Dependency Chain<br/>Critical Path]
    end
    
    subgraph "📊 Constraints"
        MaxWorkload[Max Concurrent Tasks<br/>≤ 3 per Developer]
        SkillRequirement[Required Skills<br/>Must Match]
        TimeEstimate[Time Estimate<br/>≤ Available Time]
        Dependencies_Check[Dependencies Met<br/>Prerequisites Complete]
    end
    
    Score --> SkillMatch
    Score --> Complexity
    Score --> Urgency
    Score --> Dependencies
    
    Constraints --> MaxWorkload
    Constraints --> SkillRequirement
    Constraints --> TimeEstimate
    Constraints --> Dependencies_Check
    
    style TaskPool fill:#e3f2fd
    style Analyze fill:#e8f5e8
    style Assign fill:#c8e6c9
    style Alternative fill:#fff3e0

📊 Development Metrics & Analytics

Performance Tracking Dashboard

graph TB
    subgraph "📈 Development Metrics"
        Velocity[Development Velocity<br/>Tasks/Sprint]
        Quality[Code Quality Score<br/>Composite Metric]
        Coverage[Test Coverage<br/>Percentage]
        Bugs[Bug Rate<br/>Bugs/1000 LOC]
    end
    
    subgraph "⏱️ Time Metrics"
        CycleTime[Cycle Time<br/>Idea to Production]
        LeadTime[Lead Time<br/>Request to Delivery]
        MTTR[Mean Time to Repair<br/>Issue Resolution]
        Throughput[Throughput<br/>Features/Week]
    end
    
    subgraph "👥 Team Metrics"
        Productivity[Developer Productivity<br/>Story Points/Day]
        Collaboration[Collaboration Score<br/>PR Reviews/Comments]
        Learning[Learning Rate<br/>Skill Improvements]
        Satisfaction[Developer Satisfaction<br/>Survey Score]
    end
    
    subgraph "🎯 Business Metrics"
        ValueDelivery[Value Delivery<br/>Business Impact]
        TechnicalDebt[Technical Debt<br/>Maintenance Overhead]
        Innovation[Innovation Index<br/>New Features/Total]
        UserSatisfaction[User Satisfaction<br/>Feedback Score]
    end
    
    Velocity --> Dashboard[Analytics Dashboard]
    Quality --> Dashboard
    Coverage --> Dashboard
    Bugs --> Dashboard
    
    CycleTime --> Dashboard
    LeadTime --> Dashboard
    MTTR --> Dashboard
    Throughput --> Dashboard
    
    Productivity --> AI[AI Analysis Engine]
    Collaboration --> AI
    Learning --> AI
    Satisfaction --> AI
    
    ValueDelivery --> Insights[Business Insights]
    TechnicalDebt --> Insights
    Innovation --> Insights
    UserSatisfaction --> Insights
    
    Dashboard --> Reports[Automated Reports]
    AI --> Recommendations[AI Recommendations]
    Insights --> Strategy[Strategy Adjustments]
    
    style Dashboard fill:#e3f2fd
    style AI fill:#e8f5e8
    style Insights fill:#f3e5f5
    style Reports fill:#fff3e0

Continuous Improvement Loop

flowchart TD
    Measure[Measure Performance] --> Analyze[Analyze Patterns]
    Analyze --> Identify[Identify Improvements]
    Identify --> Plan[Plan Changes]
    
    Plan --> Implement[Implement Changes]
    Implement --> Monitor[Monitor Impact]
    Monitor --> Evaluate[Evaluate Results]
    
    Evaluate --> Success{Improvement Success?}
    Success -->|Yes| Adopt[Adopt Changes]
    Success -->|No| Rollback[Rollback Changes]
    
    Adopt --> Share[Share Best Practices]
    Share --> Document[Document Learnings]
    Document --> Measure
    
    Rollback --> Learn[Learn from Failure]
    Learn --> Analyze
    
    subgraph "📊 Data Sources"
        GitMetrics[Git Commit Data]
        IssueTracking[Issue Tracking Data]
        CodeQuality[Code Quality Metrics]
        TestResults[Test Results Data]
    end
    
    subgraph "🔍 Analysis Methods"
        TrendAnalysis[Trend Analysis]
        Correlation[Correlation Analysis]
        Regression[Regression Analysis]
        Clustering[Pattern Clustering]
    end
    
    Measure --> GitMetrics
    Measure --> IssueTracking
    Measure --> CodeQuality
    Measure --> TestResults
    
    Analyze --> TrendAnalysis
    Analyze --> Correlation
    Analyze --> Regression
    Analyze --> Clustering
    
    style Measure fill:#e3f2fd
    style Analyze fill:#e8f5e8
    style Success fill:#f3e5f5
    style Adopt fill:#c8e6c9
    style Rollback fill:#ffebee

🔗 Integration Patterns

Tool Integration Ecosystem

graph TB
    subgraph "💻 Development Tools"
        Cursor[Cursor IDE<br/>AI-Powered Coding]
        Git[Git Version Control<br/>Distributed VCS]
        UV[UV Package Manager<br/>Fast Python Deps]
        Just[Just Task Runner<br/>Command Automation]
    end
    
    subgraph "🔍 Quality Tools"
        Ruff[Ruff Linter<br/>Fast Python Linting]
        Black[Black Formatter<br/>Code Formatting]
        MyPy[MyPy Type Checker<br/>Static Type Analysis]
        Pytest[Pytest Framework<br/>Testing Suite]
    end
    
    subgraph "🤝 Collaboration Tools"
        GitHub[GitHub Platform<br/>Code Hosting & CI/CD]
        Projects[GitHub Projects<br/>Project Management]
        Actions[GitHub Actions<br/>Workflow Automation]
        CLI[GitHub CLI<br/>Command Interface]
    end
    
    subgraph "🤖 AI Tools"
        Claude[Claude 4.0<br/>Project Management]
        Copilot[GitHub Copilot<br/>Code Assistance]
        Agent[AI Development Agent<br/>Task Automation]
    end
    
    Cursor --> Git
    Git --> UV
    UV --> Just
    
    Just --> Ruff
    Just --> Black
    Just --> MyPy
    Just --> Pytest
    
    Git --> GitHub
    GitHub --> Projects
    GitHub --> Actions
    GitHub --> CLI
    
    Cursor --> Claude
    GitHub --> Copilot
    Just --> Agent
    
    %% Integration flows
    Claude -.-> Projects
    Agent -.-> GitHub
    Just -.-> Actions
    
    style Cursor fill:#e1f5fe
    style Just fill:#e8f5e8
    style GitHub fill:#f3e5f5
    style Claude fill:#fce4ec

---

🔗 Related Documentation

• GitHub Workflow - Git and GitHub-specific processes
• Quality Assurance - Quality standards and processes
• Automation - Automated workflows and CI/CD
• Architecture Overview - System architecture
• Task Management - Task management guide

This development workflow documentation provides comprehensive guidance for efficient, quality-focused development using KGraph-MCP's automated development infrastructure.