# Workflow System Design ## Overview A **Workflow** defines the lifecycle of **task sessions** on a board through a sequence of **Steps**. Each step maps to a column and defines: - **Behavior**: What happens when a session enters the step (auto-start agent, append prompts, etc.) - **Transitions**: Rules for moving to next/previous steps ### Session-Level Workflows **Important**: Workflows operate at the **session level**, not the task level. A task can have multiple sessions (different attempts, different agents, parallel work), and each session progresses through the workflow independently. ``` Task ├── Session 1 (Claude) ──▶ Planning ──▶ Review ──▶ Implementation ──▶ Done ✓ ├── Session 2 (Codex) ──▶ Planning ──▶ Review ──▶ (rejected, abandoned) └── Session 3 (Claude) ──▶ Planning ──▶ (in progress...) ← PRIMARY ``` **Rationale**: - A task might need multiple attempts before completion - Different agents can work on the same task in parallel - Review feedback and approval are per-session (each attempt is reviewed independently) - Session history provides audit trail of all attempts ### Primary Session Each task has a **primary session** - the session that represents the task's current workflow position and state. - **Default**: The latest created session automatically becomes primary - **User can change**: Pin a different session as primary if needed - **Determines task display**: Task card appears in the column of the primary session's step - **Default for operations**: Approve/reject buttons operate on the primary session ``` Task: "Implement auth" ├── Session 1 (done) → archived, was primary before ├── Session 2 (abandoned) → user abandoned after rejection └── Session 3 (active) → PRIMARY - task appears in this session's column ``` When a new session is created, it automatically becomes the primary session (latest attempt is most relevant). Other sessions become "alternative attempts" - viewable but not the main path. ## Design Decisions ### Columns ARE Workflow Steps Simplify the model: **columns and workflow steps are the same entity**. The `columns` table is replaced by `workflow_steps`. ``` Board → Workflow (required) → Workflow Steps (these ARE the columns) ``` **Rationale**: - **Simplicity**: One entity instead of two with a relationship - **No indirection**: Step behavior is directly on the column - **Cleaner data model**: Every board has a workflow, every column is a step ### Rejection Behavior: Stay in Review When a user rejects at a review step, the **session stays in the same step** but gets marked with "changes requested" status. This enables iterative review cycles without moving the session back and forth. **How it works**: 1. User clicks "Request Changes" and provides feedback 2. Session stays in the review step 3. Session metadata is updated with rejection info 4. Agent can be re-triggered to address the feedback 5. User reviews again, can approve or request more changes 6. On approval, session moves to the configured `onApproval` step **Session metadata on rejection**: ```json { "review_status": "changes_requested", "review_feedback": [ { "id": "fb-1", "message": "Need to handle edge case X", "created_at": "2024-01-15T10:30:00Z", "resolved": false }, { "id": "fb-2", "message": "Add unit tests for the new function", "created_at": "2024-01-15T11:00:00Z", "resolved": true } ], "review_iteration": 2 } ``` ### Custom Workflows Supported Users can: 1. **Use a template as-is** - Quick start with pre-configured workflow 2. **Customize a template** - Clone a template and modify steps 3. **Create from scratch** - Blank workflow, add steps manually The `workflow_templates` table has `is_system` flag: - `is_system = 1`: Built-in templates (read-only, can be cloned) - `is_system = 0`: User-created templates (fully editable) --- ## Key Concepts ### 1. Workflow Template A pre-defined workflow type that boards can adopt. Examples: | Template | Description | Steps | |----------|-------------|-------| | `dev` | Software development | Backlog → Planning → Implementation → Review → Done | | `architecture` | System design | Backlog → Research → Design → Review → Approved | | `bug-fix` | Bug resolution | Triage → Reproduce → Fix → Verify → Done | | `simple` | Basic kanban | Todo → In Progress → Done | ### 2. Workflow Step Each step has: ```typescript interface WorkflowStep { id: string; name: string; // Display name (e.g., "Planning") position: number; // Order in workflow stepType: WorkflowStepType; // Semantic type (see below) // Behavior configuration behavior: { autoStartAgent: boolean; // Auto-start agent when task enters promptPrefix?: string; // Prepended to user/task prompt promptSuffix?: string; // Appended to user/task prompt systemPromptOverride?: string; // Override agent's system prompt planMode?: boolean; // Use plan mode (no execution) requireApproval?: boolean; // Require user approval before proceeding }; // Transition rules transitions: { onComplete?: string; // Step ID to move to on agent completion onApproval?: string; // Step ID to move to on user approval allowManualMove?: boolean; // Can user drag to any column? }; // Visual color: string; taskState: TaskState; // Maps to existing TaskState enum } ``` ### 3. Step Types Semantic step types that define default behaviors: | Type | Default Behavior | |------|------------------| | `backlog` | No auto-action. Tasks wait here. | | `planning` | Auto-start agent in plan mode. Produces `plan.md`. | | `implementation` | Auto-start agent with implementation prompt. Uses plan if available. | | `review` | Agent paused. Awaits user review of changes. | | `verification` | Auto-start agent to verify/test changes. | | `done` | Terminal state. No actions. | | `blocked` | Task is blocked. No auto-actions. | ## Workflow Templates ### Dev Workflow (Default) ```yaml id: dev name: Development description: Standard software development workflow with planning phase steps: - id: backlog name: Backlog stepType: backlog position: 0 taskState: TODO color: bg-neutral-400 behavior: autoStartAgent: false transitions: allowManualMove: true - id: planning name: Planning stepType: planning position: 1 taskState: IN_PROGRESS color: bg-purple-500 behavior: autoStartAgent: true planMode: true promptPrefix: | [PLANNING PHASE] Analyze this task and create a detailed implementation plan. Do NOT make any code changes yet - only analyze and plan. Create a plan that includes: 1. Understanding of the requirements 2. Files that need to be modified or created 3. Step-by-step implementation approach 4. Potential risks or considerations Save your plan to `.kandev/plans/{task_id}.md` transitions: onComplete: review-plan allowManualMove: true - id: review-plan name: Review Plan stepType: review position: 2 taskState: REVIEW color: bg-yellow-500 behavior: autoStartAgent: false requireApproval: true transitions: onApproval: implementation allowManualMove: true - id: implementation name: Implementation stepType: implementation position: 3 taskState: IN_PROGRESS color: bg-blue-500 behavior: autoStartAgent: true promptPrefix: | [IMPLEMENTATION PHASE] Implement the task according to the plan in `.kandev/plans/{task_id}.md`. Follow the plan step by step. transitions: onComplete: review-code allowManualMove: true - id: review-code name: Code Review stepType: review position: 4 taskState: REVIEW color: bg-orange-500 behavior: autoStartAgent: false requireApproval: true transitions: onApproval: done allowManualMove: true - id: done name: Done stepType: done position: 5 taskState: COMPLETED color: bg-green-500 behavior: autoStartAgent: false transitions: allowManualMove: true ``` ### Architecture Workflow ```yaml id: architecture name: Architecture description: System design and architecture workflow steps: - id: backlog name: Ideas stepType: backlog position: 0 taskState: TODO behavior: autoStartAgent: false - id: research name: Research stepType: planning position: 1 taskState: IN_PROGRESS behavior: autoStartAgent: true planMode: true promptPrefix: | [RESEARCH PHASE] Research this architecture topic. Analyze: 1. Current state of the codebase 2. Industry best practices 3. Trade-offs of different approaches Document your findings in `.kandev/research/{task_id}.md` transitions: onComplete: design - id: design name: Design stepType: planning position: 2 taskState: IN_PROGRESS behavior: autoStartAgent: true planMode: true promptPrefix: | [DESIGN PHASE] Based on research in `.kandev/research/{task_id}.md`, create a design: 1. High-level architecture 2. Component diagram 3. API contracts 4. Migration path (if applicable) Save design to `.kandev/designs/{task_id}.md` transitions: onComplete: review - id: review name: Review stepType: review position: 3 taskState: REVIEW behavior: requireApproval: true transitions: onApproval: approved - id: approved name: Approved stepType: done position: 4 taskState: COMPLETED ``` ## Data Model ### Schema ```sql -- Workflow templates (system + user-defined) -- These are blueprints that can be used when creating a board CREATE TABLE workflow_templates ( id TEXT PRIMARY KEY, name TEXT NOT NULL, description TEXT, is_system INTEGER DEFAULT 0, -- System templates are read-only steps JSON NOT NULL, -- Array of step definitions (blueprint) created_at TIMESTAMP, updated_at TIMESTAMP ); -- Boards now require a workflow -- The workflow_template_id tracks which template was used (for reference only) CREATE TABLE boards ( id TEXT PRIMARY KEY, workspace_id TEXT NOT NULL REFERENCES workspaces(id), name TEXT NOT NULL, description TEXT, workflow_template_id TEXT REFERENCES workflow_templates(id), -- Template used (nullable for custom) created_at TIMESTAMP, updated_at TIMESTAMP ); -- Workflow steps replace columns entirely -- Each step IS a column with behavior attached CREATE TABLE workflow_steps ( id TEXT PRIMARY KEY, board_id TEXT NOT NULL REFERENCES boards(id) ON DELETE CASCADE, name TEXT NOT NULL, step_type TEXT NOT NULL, -- backlog, planning, implementation, review, done, blocked position INTEGER NOT NULL, color TEXT NOT NULL, -- Behavior configuration auto_start_agent INTEGER DEFAULT 0, plan_mode INTEGER DEFAULT 0, require_approval INTEGER DEFAULT 0, prompt_prefix TEXT, prompt_suffix TEXT, -- Transition rules on_complete_step_id TEXT REFERENCES workflow_steps(id), -- Step to move to on agent completion on_approval_step_id TEXT REFERENCES workflow_steps(id), -- Step to move to on approval allow_manual_move INTEGER DEFAULT 1, created_at TIMESTAMP, updated_at TIMESTAMP ); -- Tasks remain simple - workflow progress is tracked per-session CREATE TABLE tasks ( id TEXT PRIMARY KEY, workspace_id TEXT NOT NULL REFERENCES workspaces(id), board_id TEXT NOT NULL REFERENCES boards(id), title TEXT NOT NULL, description TEXT, priority INTEGER DEFAULT 0, position INTEGER DEFAULT 0, metadata JSON, created_at TIMESTAMP, updated_at TIMESTAMP ); -- Task sessions track workflow progress (each session goes through workflow independently) -- Extends existing task_sessions table with workflow fields CREATE TABLE task_sessions ( id TEXT PRIMARY KEY, task_id TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE, -- Primary session flag (NEW) is_primary BOOLEAN DEFAULT FALSE, -- Only one session per task should be primary -- Workflow tracking (NEW) workflow_step_id TEXT REFERENCES workflow_steps(id), -- Current step in workflow review_status TEXT, -- NULL, 'pending', 'changes_requested', 'approved' review_feedback JSON, -- Array of feedback items -- Existing fields agent_profile_id TEXT NOT NULL, executor_id TEXT, environment_id TEXT, repository_id TEXT, base_branch TEXT, agent_profile_snapshot JSON, executor_snapshot JSON, environment_snapshot JSON, repository_snapshot JSON, state TEXT NOT NULL DEFAULT 'CREATED', -- CREATED, RUNNING, COMPLETED, etc. error_message TEXT, metadata JSON, started_at TIMESTAMP NOT NULL, completed_at TIMESTAMP, updated_at TIMESTAMP NOT NULL ); -- Index to quickly find primary session for a task CREATE INDEX idx_task_sessions_primary ON task_sessions(task_id, is_primary) WHERE is_primary = TRUE; -- Session step history (audit trail per session) CREATE TABLE session_step_history ( id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL REFERENCES task_sessions(id) ON DELETE CASCADE, from_step_id TEXT REFERENCES workflow_steps(id), to_step_id TEXT NOT NULL REFERENCES workflow_steps(id), trigger TEXT NOT NULL, -- manual, auto_complete, approval actor_id TEXT, -- User or system metadata JSON, created_at TIMESTAMP ); ``` ### Key Changes from Current Schema | Current | New | |---------|-----| | `columns` table | Replaced by `workflow_steps` | | `task.column_id` | Removed (tasks don't track workflow position) | | No workflow on sessions | `task_sessions.workflow_step_id` tracks session's position | | No review status | `task_sessions.review_status` + `review_feedback` | | Column has `state` field | Step has `step_type` + behavior fields | | No workflow concept | `workflow_templates` + board has `workflow_template_id` | | No primary session | `task_sessions.is_primary` flag (one per task) | ### Primary Session and Task Display ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ Task: "Implement user authentication" │ │ Board: Development Board │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ Session 1 (completed) │ │ ├── is_primary: FALSE │ │ ├── workflow_step: "Done" ✓ │ │ └── review_status: "approved" │ │ │ │ Session 2 (abandoned) │ │ ├── is_primary: FALSE │ │ ├── workflow_step: "Review Plan" │ │ └── review_status: "changes_requested" │ │ │ │ Session 3 (active) ← PRIMARY │ │ ├── is_primary: TRUE │ │ ├── workflow_step: "Implementation" │ │ └── review_status: NULL │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ Task's kanban position = PRIMARY session's workflow_step (latest session is automatically primary; user can change) ``` ## Backend Components ### 1. Workflow Service (`internal/workflow/`) ```go package workflow type Service struct { repo Repository sessionService *task.SessionService orchestrator *orchestrator.Service eventBus *events.Bus } // Core operations func (s *Service) CreateWorkflowFromTemplate(ctx, boardID, templateID string) error func (s *Service) GetBoardWorkflow(ctx, boardID string) (*Workflow, error) func (s *Service) GetStepForColumn(ctx, columnID string) (*WorkflowStep, error) // Primary session operations func (s *Service) GetPrimarySession(ctx, taskID string) (*TaskSession, error) func (s *Service) SetPrimarySession(ctx, taskID, sessionID string) error // Unsets previous primary // Session transitions (workflow operates at session level) func (s *Service) StartSession(ctx, taskID string, stepID string) (*TaskSession, error) // Auto-sets as primary func (s *Service) MoveSessionToStep(ctx, sessionID, toStepID string) error func (s *Service) OnAgentComplete(ctx, sessionID string) error func (s *Service) ApproveSession(ctx, sessionID string) error func (s *Service) RejectSession(ctx, sessionID, reason string) error func (s *Service) GetSessionStep(ctx, sessionID string) (*WorkflowStep, error) ``` ### 2. Step Executor (`internal/workflow/executor/`) Handles step-specific behaviors for sessions: ```go type StepExecutor struct { orchestrator *orchestrator.Service } func (e *StepExecutor) ExecuteStep(ctx, session *TaskSession, task *Task, step *WorkflowStep) error { // 1. Apply prompt modifications prompt := e.buildPrompt(task, session, step) // 2. Start agent if autoStartAgent if step.Behavior.AutoStartAgent { return e.orchestrator.StartSession(ctx, session.ID, prompt, step.Behavior.PlanMode) } return nil } func (e *StepExecutor) buildPrompt(task *Task, session *TaskSession, step *WorkflowStep) string { var sb strings.Builder if step.Behavior.PromptPrefix != "" { sb.WriteString(e.interpolate(step.Behavior.PromptPrefix, task, session)) sb.WriteString("\n\n") } sb.WriteString(task.Description) // Include previous feedback if session has changes_requested if session.ReviewStatus == "changes_requested" && len(session.ReviewFeedback) > 0 { sb.WriteString("\n\n[FEEDBACK TO ADDRESS]\n") for _, fb := range session.ReviewFeedback { if !fb.Resolved { sb.WriteString("- " + fb.Message + "\n") } } } if step.Behavior.PromptSuffix != "" { sb.WriteString("\n\n") sb.WriteString(e.interpolate(step.Behavior.PromptSuffix, task, session)) } return sb.String() } ``` ### 3. Transition Handler Listens for events and triggers session transitions: ```go func (s *Service) handleAgentComplete(event *events.AgentCompleteEvent) { // Workflow operates at session level, not task level step := s.GetSessionStep(ctx, event.SessionID) if step.Transitions.OnComplete != "" { nextStep := s.GetStep(ctx, step.Transitions.OnComplete) s.MoveSessionToStep(ctx, event.SessionID, nextStep.ID) } } ``` ## Frontend Design Diagrams ### User Flow: Board Creation with Workflow ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ BOARD CREATION FLOW │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────────────┐ ┌───────────────────┐ ┌──────────────────────────┐ │ Click "New │────▶│ Board Creation │────▶│ Select Workflow │ │ Board" │ │ Dialog Opens │ │ Template │ └──────────────┘ └───────────────────┘ └──────────────────────────┘ │ ┌────────────────────────────────────┼────────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ "Development" │ │ "Architecture" │ │ "Custom" │ │ │ │ │ │ │ │ Backlog │ │ Ideas │ │ (Empty board, │ │ Planning │ │ Research │ │ add steps │ │ Review Plan │ │ Design │ │ manually) │ │ Implementation │ │ Review │ │ │ │ Code Review │ │ Approved │ │ │ │ Done │ │ │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ └────────────────────────────────────┼────────────────┘ │ ▼ ┌──────────────────────────┐ │ Preview Workflow Steps │ │ (icons show behaviors) │ │ │ │ 🤖 = auto-start agent │ │ ✓ = requires approval │ │ 📋 = plan mode │ └──────────────────────────┘ │ ▼ ┌──────────────────────────┐ │ Click "Create Board" │ │ │ │ → Creates board │ │ → Creates workflow_steps│ │ → Redirects to board │ └──────────────────────────┘ ``` ### User Flow: Session Lifecycle Through Workflow ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ SESSION LIFECYCLE (Development Workflow) │ │ │ │ Note: Each SESSION progresses through steps independently. │ │ A task can have multiple sessions at different steps. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────┐ ┌──────────┐ ┌─────────────┐ ┌──────────────┐ ┌──────────┐ ┌──────┐ │ BACKLOG │───▶│ PLANNING │───▶│ REVIEW PLAN │───▶│IMPLEMENTATION│───▶│CODE REVIEW│───▶│ DONE │ └─────────┘ └──────────┘ └─────────────┘ └──────────────┘ └──────────┘ └──────┘ │ │ │ │ │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ ▼ ┌─────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────┐ │ User │ │ 🤖 Agent │ │ ✓ User │ │ 🤖 Agent │ │ ✓ User │ │ Session │ │ starts │ │ auto- │ │ reviews │ │ auto- │ │ reviews │ │ complete│ │ new │ │ starts │ │ plan │ │ starts │ │ code │ │ │ │ session │ │ (plan │ │ │ │ (uses │ │ │ │ │ │ │ │ mode) │ │ │ │ plan) │ │ │ │ │ └─────────┘ └───────────┘ └───────────┘ └───────────┘ └───────────┘ └─────────┘ │ │ │ │ ▼ │ ▼ │ ┌───────────┐ │ ┌───────────┐ │ │ Creates │ │ │ Makes │ │ │ plan.md │ │ │ code │ │ │ in work- │ │ │ changes │ │ │ tree │ │ │ │ │ └───────────┘ │ └───────────┘ │ │ │ │ ▼ ▼ ▼ ┌───────────┐ ┌─────────────┐ ┌─────────────┐ │ On agent │ │ Approve │ │ Approve │ │ complete │ │ session? │ │ session? │ │ → session │ │ │ │ │ │ moves to │ │ YES → next │ │ YES → Done │ │ Review │ │ NO → stay │ │ NO → stay │ │ Plan │ │ + feedback │ + feedback └───────────┘ └─────────────┘ └─────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ MULTIPLE SESSIONS EXAMPLE: │ │ │ │ Task: "Implement auth" │ │ ├── Session 1: ────▶ Planning ────▶ Review ────▶ Implementation ── (done) │ │ ├── Session 2: ────▶ Planning ────▶ Review (rejected, abandoned) │ │ └── Session 3: ────▶ Planning (in progress...) ← PRIMARY │ │ │ │ Task card shows in column of PRIMARY session (Session 3 → "Planning") │ │ User can change primary session if needed (e.g., pin Session 1 as primary) │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ### User Flow: Session Review and Rejection Cycle ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ SESSION REVIEW & REJECTION FLOW │ │ │ │ Review and approval happen per-SESSION, not per-task. │ │ Each session's plan/work is reviewed independently. │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────┐ │ Session in REVIEW │ │ PLAN step │ └─────────────────────┘ │ ▼ ┌─────────────────────┐ │ User opens task │ │ → selects session │ │ to review │ └─────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ SESSION REVIEW PANEL │ │ ┌─────────────────────────────────┐ │ │ │ Session: #3 (Claude 3.5) │ │ │ │ Step: Review Plan │ │ │ │ ───────────────────────────── │ │ │ │ 📋 Implementation Plan │ │ │ │ ## Overview │ │ │ │ This task will implement... │ │ │ │ ## Steps │ │ │ │ 1. Create new component │ │ │ │ 2. Add API endpoint │ │ │ │ ... │ │ │ └─────────────────────────────────┘ │ │ │ │ ┌──────────────┐ ┌──────────────────┐ │ │ │ ✓ Approve │ │ ✗ Request │ │ │ │ Session │ │ Changes │ │ │ └──────────────┘ └──────────────────┘ │ └─────────────────────────────────────────┘ │ ┌────────────────┴────────────────┐ │ │ ▼ ▼ ┌─────────────────┐ ┌─────────────────────┐ │ APPROVE │ │ REQUEST CHANGES │ │ │ │ │ │ Session moves │ │ Feedback dialog │ │ to next step │ │ opens │ │ (IMPLEMENTATION)│ │ │ └─────────────────┘ └─────────────────────┘ │ ▼ ┌─────────────────────┐ │ Enter feedback: │ │ ┌─────────────────┐│ │ │ "Need to handle ││ │ │ edge case X" ││ │ └─────────────────┘│ │ [Submit Feedback] │ └─────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ Session stays in REVIEW PLAN step │ │ with "Changes Requested" status │ │ │ │ ┌─────────────────────────────────┐ │ │ │ Session #3: Claude 3.5 │ │ │ │ ┌─────────────────────────────┐ │ │ │ │ │ 🔴 Changes Requested (1) │ │ │ │ │ └─────────────────────────────┘ │ │ │ └─────────────────────────────────┘ │ └─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ SESSION REVIEW PANEL (updated) │ │ │ │ ⚠️ Session Feedback History │ │ ┌─────────────────────────────────┐ │ │ │ 🟡 "Need to handle edge case X" │ │ │ │ 2 minutes ago │ │ │ │ [Mark Resolved] │ │ │ └─────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────┐ │ │ │ 🤖 Re-run Session Agent │ │ │ │ to Address Feedback │ │ │ └─────────────────────────────────┘ │ │ │ │ ⚠️ 1 unresolved feedback item. │ │ Resolve all before approving. │ └─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ User clicks "Re-run Session Agent" │ │ → Agent restarts in same session │ │ → Agent sees previous plan + feedback │ │ → Agent updates plan file │ │ → On complete, user reviews again │ └─────────────────────────────────────────┘ ``` ### UI Component Layout: Kanban Board ``` ┌─────────────────────────────────────────────────────────────────────────────────────────────┐ │ 📋 My Project Board [⚙️ Settings] │ ├─────────────────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ ○ Backlog │ │ ○ Planning │ │ ○ Review │ │ ○ Implement │ │ ○ Done │ │ │ │ │ │ 🤖 📋 │ │ ✓ │ │ 🤖 │ │ │ │ │ ├─────────────┤ ├─────────────┤ ├─────────────┤ ├─────────────┤ ├─────────────┤ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌─────────┐ │ │ ┌─────────┐ │ │ ┌─────────┐ │ │ ┌─────────┐ │ │ ┌─────────┐ │ │ │ │ │ Task A │ │ │ │ Task B │ │ │ │ Task D │ │ │ │ Task E │ │ │ │ Task G │ │ │ │ │ │ (no │ │ │ │ ●●○○○○ │ │ │ │ 🔴 (1) │ │ │ │ ●●●●○○ │ │ │ │ ●●●●●● │ │ │ │ │ │ session)│ │ │ │ 🤖 S#1 │ │ │ │ S#2 │ │ │ │ 🤖 S#3 │ │ │ │ ✓ S#1 │ │ │ │ │ └─────────┘ │ │ └─────────┘ │ │ └─────────┘ │ │ └─────────┘ │ │ └─────────┘ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌─────────┐ │ │ ┌─────────┐ │ │ │ │ │ │ ┌─────────┐ │ │ │ │ │ Task C │ │ │ │ Task F │ │ │ │ │ │ │ │ Task H │ │ │ │ │ │ (no │ │ │ │ ●●○○○○ │ │ │ │ │ │ │ │ ●●●●●● │ │ │ │ │ │ session)│ │ │ │ S#1 │ │ │ │ │ │ │ │ ✓ S#2 │ │ │ │ │ └─────────┘ │ │ └─────────┘ │ │ │ │ │ │ └─────────┘ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ [+ Add] │ │ │ │ │ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────────────────┘ LEGEND: ○ Column color indicator 🤖 Agent auto-starts in this column 📋 Plan mode enabled ✓ Requires approval ●●●○○○ Session workflow progress 🔴 (1) Changes requested (on session) 🤖 S#1 Active session running S#2 Session indicator (shows primary session) ★ Primary session indicator NOTE: Task card position in column = PRIMARY session's workflow step Latest session is automatically primary; user can change Click task → select specific session to view/manage ``` ### UI Component Layout: Task Detail Panel (Session-Based) ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ ← Back [⋮ More] │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ Implement user authentication │ │ ════════════════════════════════════════════════════════════════════════ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ Sessions [+ New Session]│ │ │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ │ │ │ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │ │ │ │ ● Session #3 │ │ ○ Session #2 │ │ ○ Session #1 │ │ │ │ │ │ Claude 3.5 │ │ Codex │ │ Claude 3.5 │ │ │ │ │ │ In: Review │ │ Abandoned │ │ ✓ Completed │ │ │ │ │ │ 🔴 (1 issue) │ │ │ │ │ │ │ │ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ ═══════════════════════════════════════════════════════════════════════ │ │ SESSION #3 DETAILS │ │ ═══════════════════════════════════════════════════════════════════════ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ Session Workflow Progress │ │ │ │ │ │ │ │ ✓ Backlog → ✓ Planning → ● Review → ○ Implement → ○ Done │ │ │ │ Plan │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ ⚠️ Session Feedback History │ │ │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ │ │ │ │ ┌───────────────────────────────────────────────────────────────┐ │ │ │ │ │ 🟡 "Consider using httpOnly cookies for refresh tokens" │ │ │ │ │ │ 5 minutes ago │ │ │ │ │ │ [Mark Resolved] │ │ │ │ │ └───────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ ┌───────────────────────────────────────────────────────────────┐ │ │ │ │ │ ✅ "Add rate limiting to login endpoint" │ │ │ │ │ │ 1 hour ago Resolved │ │ │ │ │ └───────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ ⚠️ 1 unresolved feedback item. Resolve all before approving. │ │ │ │ │ │ │ │ ┌─────────────────────────┐ ┌─────────────────────────────────┐ │ │ │ │ │ 🤖 Re-run Session │ │ [Abandon Session] │ │ │ │ │ │ Agent │ │ │ │ │ │ │ └─────────────────────────┘ └─────────────────────────────────┘ │ │ │ │ │ │ │ │ ┌─────────────────────────┐ ┌─────────────────────────────────┐ │ │ │ │ │ ✓ Approve Session │ │ ✗ Request Changes │ │ │ │ │ │ (disabled) │ │ │ │ │ │ │ └─────────────────────────┘ └─────────────────────────────────┘ │ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ### UI Component Layout: Workflow Editor (Board Settings) ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ ⚙️ Board Settings │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ General │ Workflow │ Permissions │ │ ──────── ════════ ─────────── │ │ │ │ Workflow Steps [+ Add Step] │ │ ═══════════════════════════════════════════════════════════════════════ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ ⋮⋮ │ 🟢 │ Backlog │ backlog ▼ │ │ 🗑️ │ ▼ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ ⋮⋮ │ 🔵 │ Planning │ planning ▼ │ 🤖 📋 │ 🗑️ │ ▼ │ │ │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ │ │ │ │ ☑️ Auto-start agent ☑️ Plan mode (no execution) │ │ │ │ ☐ Require approval │ │ │ │ │ │ │ │ Prompt Prefix: │ │ │ │ ┌───────────────────────────────────────────────────────────────┐ │ │ │ │ │ [PLANNING PHASE] Analyze the task and create a detailed │ │ │ │ │ │ implementation plan. Do NOT write any code yet. │ │ │ │ │ └───────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ On Completion, move to: [ Review Plan ▼ ] │ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ ⋮⋮ │ 🟡 │ Review Plan │ review ▼ │ ✓ │ 🗑️ │ ▶ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ ⋮⋮ │ 🟣 │ Implementation │ implement ▼ │ 🤖 │ 🗑️ │ ▶ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ ⋮⋮ │ 🟠 │ Code Review │ review ▼ │ ✓ │ 🗑️ │ ▶ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ ⋮⋮ │ ⬜ │ Done │ done ▼ │ │ 🗑️ │ ▶ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ LEGEND: │ │ ⋮⋮ = Drag handle 🤖 = Auto-start agent 📋 = Plan mode │ │ ✓ = Requires approval ▼/▶ = Expand/collapse step details │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ### State Diagram: Session in Review Step ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ SESSION STATE IN REVIEW STEP │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────────────────────┐ │ │ │ PENDING_REVIEW │◀─────────────────────────┐ │ │ │ └──────────────────────┘ │ │ │ ┌───────────────┴───────────────┐ │ │ │ │ ▼ ▼ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ │ │ │ │ APPROVED │ │ CHANGES_REQUESTED│ │ │ │ │ │ │ └──────────────────┘ └──────────────────┘ │ │ │ │ │ │ │ ▼ ▼ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ │ │ │ │ Move session to │ │ Agent re-runs │──────────────┘ │ next step │ │ with feedback │ │ │ │ │ └──────────────────┘ └──────────────────┘ Session Fields (in task_sessions table): ┌─────────────────────────────────────────────────────────────────────┐ │ workflow_step_id: "step-review-plan" -- Current workflow position │ │ review_status: "changes_requested" -- pending | approved | ... │ │ review_feedback: [ │ │ { │ │ "id": "fb-1", │ │ "message": "Need to handle edge case X", │ │ "created_at": "2024-01-15T10:30:00Z", │ │ "resolved": false │ │ }, │ │ { │ │ "id": "fb-2", │ │ "message": "Add error handling", │ │ "created_at": "2024-01-15T09:00:00Z", │ │ "resolved": true, │ │ "resolved_at": "2024-01-15T10:00:00Z" │ │ } │ │ ] │ └─────────────────────────────────────────────────────────────────────┘ NOTE: Each session tracks its own workflow position independently. A task's position on the kanban board is derived from its most advanced active session. ``` ### Data Flow: Session Start with Agent Auto-Start ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ DATA FLOW: SESSION START WITH AGENT AUTO-START │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────────────┐ │ Frontend │ │ (Task Panel) │ └──────────────┘ │ │ 1. User clicks "New Session" or "Start" on task │ (selects target step, e.g., "Planning") │ ▼ ┌──────────────┐ 2. WS: session.create ┌──────────────┐ │ WebSocket │ ──────────────────────────────────────▶ │ Backend │ │ Client │ { task_id, step_id } │ (WS GW) │ └──────────────┘ └──────────────┘ │ │ 3. WorkflowService.StartSession() ▼ ┌──────────────┐ │ Workflow │ │ Service │ │ │ │ Creates new │ │ TaskSession │ │ with step_id │ └──────────────┘ │ │ 4. Get target step config ▼ ┌──────────────┐ │ WorkflowStep │ │ auto_start: │ │ true │ │ plan_mode: │ │ true │ │ prompt_ │ │ prefix:... │ └──────────────┘ │ │ 5. Publish event ▼ ┌──────────────┐ │ Event Bus │ │ │ │ session. │ │ created │ └──────────────┘ │ │ 6. Orchestrator handles event ▼ ┌──────────────┐ │ Orchestrator │ │ │ │ if step. │ │ auto_start: │ │ LaunchAgent│ └──────────────┘ │ │ 7. Build prompt with prefix + feedback ▼ ┌──────────────────────────────┐ │ Prompt = step.prompt_prefix │ │ + task.description │ │ + session.feedback │ │ + step.prompt_suffix │ │ │ │ "[PLANNING PHASE] Analyze │ │ the task and create a │ │ detailed implementation │ │ plan. Do NOT write code.\n" │ │ + "Implement user auth..." │ │ + "[FEEDBACK TO ADDRESS]..."│ └──────────────────────────────┘ │ │ 8. Start agent for session ▼ ┌──────────────┐ │ Lifecycle │ │ Manager │ │ │ │ StartSession │ │ (session has │ │ workflow_ │ │ step_id) │ └──────────────┘ │ ┌────────────────────────────────────────────────────────┘ │ 9. WS: session.started, session.update (streaming) ▼ ┌──────────────┐ │ Frontend │ │ (Updates │ │ session in │ │ task panel │ │ with 🤖) │ └──────────────┘ NOTE: Task card position on kanban = PRIMARY session's workflow step ``` ## Frontend Integration ### Board Creation with Workflow Selection When creating a new board, users select a workflow template that determines the columns and their behaviors. **Dialog Flow**: 1. User clicks "New Board" 2. Dialog opens with board name input and workflow template selector 3. Selecting a template shows a preview of the workflow steps 4. User can choose "Custom" to start with a blank workflow 5. On create, columns are generated from the workflow steps ```tsx Create Board
Standard Todo → Plan → Implementation → Done
Architecture Ideas → Research → Design → Review → Approved
Simple Kanban Todo → In Progress → Done (no automation)
Custom Start with a blank workflow and add steps manually
{/* Workflow Preview */} {selectedTemplate && selectedTemplate !== 'custom' && (
{templateSteps.map((step, i) => (
{step.name} {step.behavior.autoStartAgent && ( )} {step.behavior.requireApproval && ( )}
{i < templateSteps.length - 1 && ( )} ))}
Auto-starts agent Requires approval
)}
``` ### Kanban Board with Workflow Columns The kanban board displays columns based on workflow steps. Each column header shows: - Column name - Step type indicator (icon) - Auto-start badge if enabled ```tsx
{columns.map((column) => (
{/* Column Header */}
{column.name} {column.step?.stepType}
{column.step?.behavior.autoStartAgent && ( )} {column.step?.behavior.requireApproval && ( )}
{/* Task Cards */}
{column.tasks.map((task) => ( ))}
))}
``` ### Task Card with Primary Session Workflow Status Task cards show workflow-specific information based on the **primary session**: - Primary session workflow progress dots - Review status badge (if primary session has changes requested) - Primary session indicator (★ marker) - Agent status (running, waiting, etc.) ```tsx function TaskCard({ task, step }: { task: Task; step: WorkflowStep }) { // Get the primary session for display (latest session by default) const primarySession = usePrimarySession(task.id); const sessionStep = primarySession?.workflow_step_id; const hasChangesRequested = primarySession?.review_status === 'changes_requested'; const feedbackCount = primarySession?.review_feedback?.filter(f => !f.resolved).length ?? 0; const sessionCount = task.sessions?.length ?? 0; return ( {/* Header */}

{task.title}

{hasChangesRequested && ( Changes Requested ({feedbackCount}) )}
{/* Primary Session Workflow Progress Dots */} {primarySession && (
{workflowSteps.map((s, i) => (
currentStepIndex && "bg-gray-300" // Future )} /> ))}
)} {/* Primary Session Indicator */}
{primarySession ? ( <> ★ Session #{primarySession.number} {sessionCount > 1 && ( +{sessionCount - 1} more )} ) : ( No sessions )}
{/* Primary Session Agent Status */} {primarySession && (
{primarySession.state === 'RUNNING' && ( <> Agent working... )} {primarySession.state === 'WAITING_FOR_INPUT' && ( <> Waiting for input )}
)} ); } ``` ### Review Step UI - Session Review Panel When a **session** is in a review step, the session detail panel shows: 1. Previous feedback (if any) 2. Approval actions ```tsx // Session-based review panel - operates on a specific session, not the task function SessionReviewPanel({ session, task, step }: { session: TaskSession; task: Task; step: WorkflowStep }) { return (
{/* Session Info Header */}
Session #{session.number} • {session.agent_profile?.name ?? 'Agent'} {session.review_status ?? 'pending'}
{/* Session Feedback History */} {existingFeedback.length > 0 && (
{existingFeedback.map((fb) => (

{fb.message}

{fb.resolved ? ( Resolved ) : ( )}
{formatRelativeTime(fb.created_at)}
))}
)} {/* Session Approval Actions */}
{!showFeedbackInput ? (
) : (