Workflow Kanban - Sistema de Workflow para VibeCForms

Overview

Enable development of a complete Kanban-Workflow management system for VibeCForms v4.0. The system combines visual Kanban boards with dynamic forms that automatically generate workflow processes, featuring AI-powered pattern analysis, automated transitions, and comprehensive analytics.

This skill provides five progressive knowledge levels (fundamentals → implementation), three functional Python scripts (validator, template generator, implementation assistant), and pre-configured templates ready for use.

When to Use This Skill

AUTOMATIC ACTIVATION: This skill should be automatically invoked when the user mentions ANY of these keywords or related concepts:

Primary Keywords:

• •workflow / workflows / fluxo / fluxos
• •kanban / kanbans / quadro kanban
• •regras de negócio / business rules / lógica de negócio
• •transição / transições / transitions / auto-transition
• •processo / processos / process / workflow process
• •estado / estados / state / states / status

Secondary Keywords:

• •pré-requisito / prerequisite / prerequisites
• •automação / automation / automatic
• •padrões de workflow / workflow patterns
• •agente / agentes / AI agents / workflow agents
• •análise de padrões / pattern analysis
• •anomalia / anomaly detection
• •editor visual / visual editor / kanban editor
• •dashboard / analytics / métricas de workflow
• •audit / auditoria / timeline
• •forced transition / transição forçada
• •cascade / cascata / progressão em cascata

Context-Based Activation:

• •Questions about "como implementar" + any workflow-related term
• •References to workflow architecture or design
• •Discussion of business logic tied to form states
• •Planning or reviewing workflow features
• •Troubleshooting workflow issues
• •Creating or validating kanban configurations

Use this skill when:

• •Planning or implementing kanban workflows in VibeCForms
• •Creating kanban JSON definitions
• •Validating kanban configuration files
• •Implementing auto-transition logic
• •Developing AI agents for workflow analysis
• •Building visual editors or analytics dashboards
• •Reviewing workflow architecture decisions
• •Planning implementation phases and testing strategy
• •Discussing business rules and workflow automation
• •Analyzing workflow patterns or anomalies
• •Designing state machines or process flows

Do NOT use for:

• •General form management (not related to workflows)
• •Basic CRUD operations without workflow
• •Non-workflow VibeCForms features
• •Simple data persistence questions
• •UI/UX improvements unrelated to kanban boards

Progressive Disclosure Knowledge Levels

The skill organizes documentation in five progressive levels. Start at Level 1 and advance as needed:

Level 1: Fundamentals (Novice)

Target: Developers new to the project Content: Core concepts, Kanban-Form architecture (1:N), pluggable persistence File: references/level_1_fundamentals.md Use when: Understanding project basics, first time on the project

Level 2: Engine (Competent)

Target: Developers implementing core features Content: AutoTransitionEngine, AI Agents, PatternAnalyzer, complete user flows File: references/level_2_engine.md Use when: Implementing transitions, automation, pattern analysis

Level 3: Interface (Proficient)

Target: Developers working on UI/UX Content: Visual Editor, Analytics Dashboard, Exports, Audit Interface File: references/level_3_interface.md Use when: Building visual interfaces, dashboards, user-facing features

Level 4: Architecture (Advanced)

Target: Architects and tech leads Content: Complete technical architecture, component diagrams, directory structure File: references/level_4_architecture.md Use when: Planning architecture, reviewing technical decisions, integrations

Level 5: Implementation (Master)

Target: Project managers and implementers Content: Complete example (Order Flow), 5 implementation phases (50 days), testing strategy (150+ tests) File: references/level_5_implementation.md Use when: Planning implementation, defining schedules, creating tests

Core Principles

"Warn, Not Block" Philosophy: Prerequisites NEVER block transitions. They warn users and require justification for forced transitions, but maintain user autonomy.

Key Concepts:

• •Kanban = Workflow Definition: Kanbans define business rules and workflow logic
• •1:N Kanban-Form Relationship: One kanban can generate processes from multiple forms
• •Automatic Process Generation: Saving a form automatically creates a workflow process
• •3 Transition Types: Manual (user), System (automatic), Agent (AI-suggested)
• •Pluggable Persistence: TXT (default), SQLite, MySQL, PostgreSQL, MongoDB

Practical Tools

The skill includes three Python scripts for immediate use:

1. Kanban Validator (scripts/kanban_validator.py)

Validate kanban JSON files for correctness and completeness.

Usage:

python3 ~/.claude/skills/workflow_kanban/scripts/kanban_validator.py <kanban.json>

Validates:

• •JSON schema correctness
• •Required fields (id, name, states, transitions)
• •Transition consistency (from/to states exist)
• •Prerequisite types (4 valid types)
• •Infinite cycle detection in auto-transitions
• •Generates detailed error/warning report

Example:

python3 ~/.claude/skills/workflow_kanban/scripts/kanban_validator.py /home/rodrigo/VibeCForms/src/config/kanbans/pedidos.json

2. Template Generator (scripts/template_generator.py)

Generate pre-configured kanban templates ready to use.

Usage:

# List available templates
python3 ~/.claude/skills/workflow_kanban/scripts/template_generator.py --list

# Generate template
python3 ~/.claude/skills/workflow_kanban/scripts/template_generator.py --template order_flow --output pedidos.json

Available Templates:

• •order_flow - Complete order workflow (quote → order → delivery → completed)
• •support_ticket - Support ticket management (new → analysis → resolved)
• •hiring - Hiring process (candidate → interviews → hired)
• •approval - Generic approval flow (pending → review → approved/rejected)

Example:

python3 ~/.claude/skills/workflow_kanban/scripts/template_generator.py --template order_flow --output /home/rodrigo/VibeCForms/src/config/kanbans/pedidos.json

3. Implementation Assistant (scripts/implementation_assistant.py)

Guide implementation phase by phase with checklists and progress tracking.

Usage:

# View overview of all phases
python3 ~/.claude/skills/workflow_kanban/scripts/implementation_assistant.py

# View detailed checklist for Phase 1
python3 ~/.claude/skills/workflow_kanban/scripts/implementation_assistant.py --phase 1

# Check implementation progress
python3 ~/.claude/skills/workflow_kanban/scripts/implementation_assistant.py --check

Shows:

• •Checklist of tasks per phase/day
• •Deliverables for each phase
• •Test counts and targets
• •Implementation progress (which files created)

Example:

# View Phase 2 (AutoTransitionEngine) checklist
python3 ~/.claude/skills/workflow_kanban/scripts/implementation_assistant.py --phase 2

Common Workflows

Workflow 1: Create New Kanban

# Step 1: Generate template
python3 ~/.claude/skills/workflow_kanban/scripts/template_generator.py --template order_flow --output my_kanban.json

# Step 2: Customize JSON as needed (edit file)

# Step 3: Validate configuration
python3 ~/.claude/skills/workflow_kanban/scripts/kanban_validator.py my_kanban.json

# Step 4: If valid, copy to VibeCForms
cp my_kanban.json /home/rodrigo/VibeCForms/src/config/kanbans/

Workflow 2: Plan Implementation

# Step 1: Review overall roadmap
python3 ~/.claude/skills/workflow_kanban/scripts/implementation_assistant.py

# Step 2: View current phase checklist
python3 ~/.claude/skills/workflow_kanban/scripts/implementation_assistant.py --phase 1

# Step 3: Check progress regularly
python3 ~/.claude/skills/workflow_kanban/scripts/implementation_assistant.py --check

Workflow 3: Learn the System

# Step 1: Read Level 1 for fundamentals
cat ~/.claude/skills/workflow_kanban/references/level_1_fundamentals.md

# Step 2: Progress to Level 2 for engine details
cat ~/.claude/skills/workflow_kanban/references/level_2_engine.md

# Step 3: Consult other levels as needed
# Level 3 for UI, Level 4 for architecture, Level 5 for implementation

Workflow 4: Validate Existing Kanban

# Validate a kanban file
python3 ~/.claude/skills/workflow_kanban/scripts/kanban_validator.py /path/to/kanban.json

# If errors found, consult Level 1 for structure reference
# Fix errors and re-validate

System Architecture Quick Reference

Layers:

• •Presentation: Kanban Board, Visual Editor, Analytics Dashboard
• •Application: VibeCForms.py routes, FormTriggerManager, AutoTransitionEngine
• •Business: ProcessFactory, AI Agents, PatternAnalyzer, PrerequisiteChecker
• •Persistence: RepositoryFactory → WorkflowRepository → Adapters (TXT/SQLite/MySQL)
• •Storage: .txt files, SQLite DB, or external databases

Key Components:

• •KanbanRegistry: Bidirectional Kanban↔Form mapping
• •FormTriggerManager: Detects form saves, triggers process creation
• •ProcessFactory: Creates workflow processes from form data
• •AutoTransitionEngine: Handles automatic state transitions
• •PrerequisiteChecker: Validates prerequisites (4 types: field_check, external_api, time_elapsed, custom_script)
• •AI Agents: Analyze context and suggest intelligent transitions
• •PatternAnalyzer: Identifies frequent transition patterns
• •AnomalyDetector: Detects stuck processes and anomalies

Implementation Phases Summary

Phase 1 (10 days): Core Kanban-Form Integration

• •KanbanRegistry, FormTriggerManager, ProcessFactory
• •Basic Kanban Board, Manual transitions
• •30 tests

Phase 2 (10 days): AutoTransitionEngine

• •Auto-transitions, Prerequisites (4 types), Timeouts
• •Cascade progression, Forced transitions
• •40 tests

Phase 3 (10 days): Basic AI

• •PatternAnalyzer, AnomalyDetector
• •AI Agents (Base + 3 concrete), UI suggestions
• •40 tests

Phase 4 (10 days): Visual Editor + Dashboard

• •Visual Kanban Editor (admin)
• •Analytics Dashboard, CSV export
• •30 tests

Phase 5 (10 days): Advanced Features

• •Audit timeline, PDF/Excel export
• •ML models, Notification system
• •10 tests

Total: 50 days, 150+ tests, 80%+ coverage target

Example Kanban Structure

{
  "id": "pedidos",
  "name": "Fluxo de Pedidos",
  "states": [
    {
      "id": "orcamento",
      "name": "Orçamento",
      "color": "#FFA500",
      "is_initial": true,
      "auto_transition_to": null
    },
    {
      "id": "pedido",
      "name": "Pedido Confirmado",
      "color": "#9370DB",
      "auto_transition_to": "em_entrega",
      "timeout_hours": 48
    }
  ],
  "transitions": [
    {
      "from": "orcamento",
      "to": "pedido",
      "type": "manual",
      "prerequisites": [
        {
          "type": "field_check",
          "field": "valor_total",
          "condition": "not_empty",
          "message": "Valor deve estar preenchido"
        }
      ]
    }
  ],
  "linked_forms": ["pedidos", "pedidos_urgentes"]
}

Quick Reference

Most Common Commands:

# Generate and validate a kanban
python3 ~/.claude/skills/workflow_kanban/scripts/template_generator.py --template order_flow --output kanban.json
python3 ~/.claude/skills/workflow_kanban/scripts/kanban_validator.py kanban.json

# View implementation roadmap
python3 ~/.claude/skills/workflow_kanban/scripts/implementation_assistant.py

# View phase checklist
python3 ~/.claude/skills/workflow_kanban/scripts/implementation_assistant.py --phase 1

Progressive Learning Path:

1. •Read references/level_1_fundamentals.md - Understand concepts
2. •Generate example kanban with template_generator.py
3. •Validate example with kanban_validator.py
4. •Consult higher levels as needed (2-5)
5. •Use implementation_assistant.py when implementing

Original Documentation Source: VibeCForms/docs/planning/workflow/workflow_kanban_planejamento_v4_parte*.md