agent-session-starting

name	agent-session-starting
description	Start an agent session correctly in KanbAgent. Activates when an agent needs to begin work, when user says "start a session", "launch agent X", "begin session", or when an agent role is invoked and no active session exists. Ensures correct startup sequence: dbstart → read tasks → begin work.

Agent Session Starting Skill

Handles the full startup sequence for any agent in the KanbAgent multi-agent workflow.

When to Use

• An agent is about to begin work on a task
• User says "start session", "launch agent X"
• A new Claude Code session opens and the context references an agent role
• After a session interruption that needs to be resumed

Startup Sequence

Step 1 — Run dbstart

node scripts/dbstart.js [type] [scope]

This single call:

• Registers the agent if not yet in DB
• Creates a new session row (status: started)
• Displays agent_id + session_id — save both for all subsequent SQL
• Shows assigned tasks (status: todo)
• Exits with code 2 if the 3-session parallel limit is reached

If exit code is 2: stop. Do not start work. Report the limit to the user. The limit is configurable per agent via agents.max_sessions in the DB (default 3, -1 = unlimited). To check or change: node scripts/dbq.js "SELECT name, max_sessions FROM agents WHERE name = ''" To raise the limit: node scripts/dbw.js "UPDATE agents SET max_sessions = WHERE name = ''" (or -1 for unlimited)

Step 1b — Log session start

Insert a session_start entry in agent_logs immediately after dbstart succeeds. This step is mandatory for all agents.

INSERT INTO agent_logs (session_id, agent_id, level, action, detail, created_at)
VALUES (:session_id, :agent_id, 'info', 'session_start', 'Session started', CURRENT_TIMESTAMP);

Step 2 — Read Your Assigned Tasks

SELECT id, title, description, priority, effort FROM tasks WHERE agent_assigned_id = :agent_id AND status = 'todo' ORDER BY priority DESC, created_at ASC;

If tasks exist → proceed to Step 3 immediately (no questions). If no tasks → ask the user what to work on, or wait for review to create tickets.

Step 3 — Read Task Details + Comments

SELECT title, description FROM tasks WHERE id = :task_id;

SELECT tc.content, a.name, tc.created_at FROM task_comments tc JOIN agents a ON a.id = tc.agent_id WHERE tc.task_id = :task_id ORDER BY tc.created_at DESC LIMIT 5;

Step 4 — Take the Ticket

UPDATE tasks SET status = 'in_progress', started_at = CURRENT_TIMESTAMP, updated_at = CURRENT_TIMESTAMP WHERE id = :task_id;

Agent Roles Reference

Name	Scope
dev-front-vuejs	renderer/ — Vue 3 + TS + Vuetify 3 (Material Design 3)
dev-back-electron	main/ — Electron + Node + SQLite
test-front-vuejs	tests renderer
test-back-electron	tests main
ux-front-vuejs	UX/design renderer
review / review-master	global audit + ticket creation
arch	ADR, IPC contracts, CLAUDE.md changes
doc	README, JSDoc
devops	CI/CD, GitHub Actions

Rules

• Parallel session limit per agent — enforced by dbstart (exit 2). Default is 3, configurable via agents.max_sessions (-1 = unlimited)
• Always use node scripts/dbq.js for reads, node scripts/dbw.js for writes
• SQL with backticks, $(), or quotes → use heredoc syntax (see WORKFLOW.md)
• Never modify files outside your declared scope