+ {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 ? (
+
+
+
+
+ ) : (
+
+ )}
+
+ {unresolvedFeedback.length > 0 && (
+
+ โ ๏ธ {unresolvedFeedback.length} unresolved feedback item(s).
+ Resolve all feedback before approving this session.
+
+ )}
+
+ {/* Re-run Session Agent Button */}
+ {unresolvedFeedback.length > 0 && (
+
+ )}
+
+ {/* Abandon Session Option */}
+
+
+
+ );
+}
+```
+
+### Workflow Editor (Settings)
+
+Users can customize workflows in the board settings. This allows:
+- Reordering steps
+- Editing step behaviors (prompts, auto-start, etc.)
+- Adding/removing steps
+- Changing step colors
+
+```tsx
+function WorkflowEditor({ boardId }: { boardId: string }) {
+ const { workflow, updateStep, addStep, removeStep, reorderSteps } = useWorkflow(boardId);
+
+ return (
+
+
+
Workflow Steps
+
+
+
+
+ s.id)}>
+ {workflow.steps.map((step, index) => (
+ updateStep(step.id, updates)}
+ onRemove={() => removeStep(step.id)}
+ />
+ ))}
+
+
+
+ );
+}
+
+function SortableStepCard({ step, index, onUpdate, onRemove }) {
+ const [expanded, setExpanded] = useState(false);
+
+ return (
+
+
+
+
+
+
+
onUpdate({ name: e.target.value })}
+ className="flex-1"
+ />
+
+
+
+
+
+
+
+
+ {expanded && (
+
+ {/* Behavior Settings */}
+
+
+ onUpdate({ behavior: { ...step.behavior, autoStartAgent: v }})}
+ />
+
+
+
+ onUpdate({ behavior: { ...step.behavior, planMode: v }})}
+ />
+
+
+
+ onUpdate({ behavior: { ...step.behavior, requireApproval: v }})}
+ />
+
+
+
+
+ {/* Prompt Prefix */}
+
+
+
+
+ {/* Transition Settings */}
+
+
+
+
+
+ )}
+
+ );
+}
+```
+
+### Drag-and-Drop Behavior
+
+When a task is dragged to a new column:
+
+1. **Check if manual move is allowed** - Some steps may restrict manual moves
+2. **Trigger step entry behavior** - If the new step has `autoStartAgent: true`, start the agent
+3. **Show confirmation for review steps** - If moving to a review step, confirm the user wants to submit for review
+
+```tsx
+function handleTaskDrop(taskId: string, fromColumnId: string, toColumnId: string) {
+ const fromStep = getStepForColumn(fromColumnId);
+ const toStep = getStepForColumn(toColumnId);
+
+ // Check if move is allowed
+ if (!toStep.transitions.allowManualMove) {
+ toast.error(`Cannot manually move tasks to "${toStep.name}"`);
+ return;
+ }
+
+ // Confirm if moving to review
+ if (toStep.stepType === 'review' && fromStep.stepType !== 'review') {
+ const confirmed = await confirm({
+ title: 'Submit for Review?',
+ description: 'This will submit the task for review. The agent will stop working.',
+ });
+ if (!confirmed) return;
+ }
+
+ // Execute move
+ await moveTask(taskId, toColumnId);
+
+ // Backend handles step entry behavior (auto-start agent, etc.)
+}
+
+## API Endpoints
+
+### HTTP Endpoints
+
+```
+# Workflow Templates & Board Workflows
+GET /api/v1/workflow-templates # List available templates
+GET /api/v1/workflow-templates/:id # Get template details
+POST /api/v1/boards/:id/workflow # Apply workflow to board
+GET /api/v1/boards/:id/workflow # Get board's workflow
+GET /api/v1/boards/:id/workflow/steps # Get workflow steps
+
+# Session Workflow Operations (workflow operates at session level)
+POST /api/v1/sessions/:id/workflow/approve # Approve session's current step
+POST /api/v1/sessions/:id/workflow/reject # Reject session / request changes
+POST /api/v1/sessions/:id/workflow/move # Move session to a different step
+GET /api/v1/sessions/:id/step # Get session's current workflow step
+
+# Primary Session Operations
+GET /api/v1/tasks/:id/primary-session # Get task's primary session
+PUT /api/v1/tasks/:id/primary-session # Set primary session { session_id }
+```
+
+### WebSocket Actions
+
+```
+# Session-level workflow actions
+session.workflow.approve { session_id } # Approve session step
+session.workflow.reject { session_id, reason } # Reject session with feedback
+session.workflow.move { session_id, step_id } # Move session to step
+
+# Primary session actions
+task.primary_session.set { task_id, session_id } # Change primary session
+
+# Notifications
+session.step.changed { session_id, step_id, ... } # Session moved to new step
+session.review.requested { session_id, ... } # Session entered review step
+session.approved { session_id, ... } # Session was approved
+task.primary_session.changed { task_id, session_id } # Primary session changed
+```
+
+## Resolved Design Decisions
+
+| Decision | Resolution | Rationale |
+|----------|------------|-----------|
+| **Columns vs Steps** | Columns ARE steps (`workflow_steps` replaces `columns`) | Simplicity - one entity instead of two with a relationship |
+| **Plan Storage** | Files in worktree (`.kandev/plans/{session_id}.md`) | Simple, no database storage needed, accessible in editor |
+| **Custom Workflows** | Full support (templates + from scratch) | Users can use templates, customize them, or create entirely new workflows |
+| **Rejection Behavior** | Stay in review + mark "changes requested" | Enables iterative review cycles without moving cards back and forth |
+| **Backward Compatibility** | None required | Implementing from scratch, following current patterns and abstractions |
+| **Workflow Level** | Session-level (not task-level) | Multiple sessions can work on a task independently, each progressing through the workflow |
+| **Task Display** | Primary session determines kanban column | Latest session is auto-primary; user can change. Simpler than "most advanced" logic |
+
+## Open Questions
+
+1. **Step Skipping**: Should users be able to skip steps when starting a new session?
+ - Currently: Sessions can start at any step
+ - Consider: Add `allowedStartSteps` array for more control
+
+---
+
+## Next Steps
+
+### Phase 1: Database Schema
+1. [ ] Create `workflow_templates` table with seed data (dev, architecture, simple)
+2. [ ] Create `workflow_steps` table (replaces `columns`)
+3. [ ] Update `boards` table with `workflow_template_id`
+4. [ ] Update `task_sessions` table: add `is_primary`, `workflow_step_id`, `review_status`, `review_feedback`
+5. [ ] Create `session_step_history` table
+
+### Phase 2: Backend Services
+6. [ ] Implement `WorkflowService` (CRUD for templates and steps)
+7. [ ] Update `SessionService` with workflow step operations (`MoveSessionToStep`, etc.)
+10. [ ] Implement primary session operations (`GetPrimarySession`, `SetPrimarySession`)
+11. [ ] Add workflow event handlers (on session created โ auto-set as primary, on agent complete)
+12. [ ] Add session approval/rejection endpoints
+
+### Phase 3: Frontend - Board Creation
+13. [ ] Add workflow template selector to board creation dialog
+14. [ ] Show workflow preview when template selected
+15. [ ] Create workflow steps when board is created
+
+### Phase 4: Frontend - Session Workflow
+16. [ ] Display task card based on primary session's step
+17. [ ] Add primary session indicator (โ
) to task cards
+18. [ ] Add session selector to task detail panel with "Set as Primary" action
+19. [ ] Add session workflow progress indicator
+20. [ ] Add session review status badge to task cards
+21. [ ] Implement session review panel with approval/rejection UI
+22. [ ] Add session feedback input and history display
+23. [ ] Implement "Re-run Session Agent" button for addressing feedback
+24. [ ] Add "Start New Session" flow (new session auto-becomes primary)
+
+### Phase 5: Frontend - Workflow Editor
+25. [ ] Add workflow editor to board settings
+26. [ ] Implement step reordering (drag and drop)
+27. [ ] Implement step behavior editing (prompts, auto-start, etc.)
+28. [ ] Add step add/remove functionality