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
