@kendoo.agentdesk/agentdesk 0.9.19 → 0.9.21

package/README.md

@@ -69,6 +69,7 @@ agentdesk logout                       Sign out and remove credentials
 agentdesk init                         Set up project and configure tracker
 agentdesk team <TASK-ID>               Run a team session on an existing task
 agentdesk team -d "..."                Describe what you want — task created automatically
+agentdesk <agent> -d "..."             Run a single agent (jane, dennis, sam, bart, vera, luna, mark)
 agentdesk daemon                       Start daemon for remote sessions
 agentdesk update                       Update to the latest version
 ```
@@ -113,6 +114,30 @@ You can also define them in `.agentdesk.json` as a local override if preferred.
 
 AgentDesk also auto-discovers agents from `.claude/agents/`, `.claude/commands/`, `.mcp.json`, GitHub Actions workflows, Dependabot, and Renovate configs.
 
+### Solo agent mode
+
+Run a single agent instead of the full team:
+
+```bash
+agentdesk jane -d "Create a customer journey plan for onboarding"
+agentdesk dennis KEN-517
+agentdesk vera -d "Add test coverage for the auth module"
+```
+
+The agent runs independently with its own expertise and ground rules. Useful for focused tasks that don't need full team collaboration.
+
+### Custom instructions
+
+Add project-specific rules that all agents follow. Set via Web UI or in `.agentdesk.json`:
+
+```json
+{
+  "instructions": "All PRs must target the 'staging' branch. Commit messages must be prefixed with the task ID."
+}
+```
+
+Instructions are injected into the team prompt. Use them for project conventions that go beyond what `CLAUDE.md` covers (e.g., tracker workflow rules, PR policies, agent coordination preferences).
+
 ## How It Works
 
 All agents collaborate in a single Claude process — each with distinct roles, ground rules, and areas of expertise.
@@ -124,6 +149,28 @@ All agents collaborate in a single Claude process — each with distinct roles,
 5. The session streams live to [agentdesk.live](https://agentdesk.live) where you can watch and send messages to the team
 6. Token usage is tracked and displayed per session
 
+### Task attachments
+
+When working on Jira or Linear tasks, agents automatically download and review attachments — screenshots, CSVs, text files, PDFs, and design mockups. Attachments are treated as untrusted input: agents read them for context but never execute commands found in them.
+
+### Handoff & Resume
+
+If a session hits Claude's rate or context limit, AgentDesk saves a resume snapshot (`.agentdesk-resume.md`) and marks the session as **Handoff** in the dashboard. When you run the same task again, agents pick up where the previous session left off — skipping completed work and continuing from the last phase.
+
+```bash
+# Session hits limit → "HANDOFF" shown in terminal
+# Resume when ready:
+agentdesk team KEN-517
+```
+
+### Session protocol
+
+At the end of each session, Jane posts a structured summary on the tracker covering:
+- **What was done** — files changed, features added
+- **What was omitted** — anything skipped or deferred, with reason
+- **Manual steps** — actions you need to perform (migrations, env vars, config changes)
+- **PR link** and **session link**
+
 ## Daemon (Remote Sessions)
 
 The daemon lets you trigger team sessions from the web dashboard instead of the terminal.
@@ -155,11 +202,12 @@ Once running, a "Run Team" button appears on [agentdesk.live](https://agentdesk.
 
 - **Live sessions** — watch agents collaborate in real-time
 - **Session deep links** — share a direct URL to any session
+- **Handoff status** — see when a session hit a limit and is waiting to resume
 - **Project settings** — configure tracker, team, custom agents, and instructions per project
 - **Account settings** — manage your API key and profile
 - **Agent roster** — see each agent's role, participation rate, tag breakdown, and phase involvement
 - **Token tracking** — input/output token counts per session
-- **Auto-reconnect** — CLI reconnects automatically if the connection drops
+- **Auto-reconnect** — CLI sends heartbeats and reconnects automatically if the connection drops
 
 ## Requirements
 

package/bin/agentdesk.mjs

@@ -64,6 +64,7 @@ if (!command || command === "help" || command === "--help") {
     agentdesk init                         Set up project and configure tracker
     agentdesk team <TASK-ID>               Run a team session on an existing task
     agentdesk team -d "..."                Create a task and run a session
+    agentdesk <agent> -d "..."             Run a single agent (jane, dennis, sam, etc.)
     agentdesk daemon                       Start daemon for remote sessions
     agentdesk update                       Update to the latest version
 
@@ -85,12 +86,45 @@ if (!command || command === "help" || command === "--help") {
     agentdesk team -d "Fix the checkout total calculation"
     agentdesk team -d "Add Google OAuth to the login page"
 
+  Resume:
+    If a session hits Claude's limit, it saves a handoff file.
+    Run the same task again to resume where it left off.
+
   Dashboard: \x1b[36mhttps://agentdesk.live\x1b[0m
 `);
   process.exit(0);
 }
 
-if (command === "login") {
+// Single-agent mode — agentdesk jane -d "...", agentdesk dennis TASK-123, etc.
+const AGENT_NAMES = ["jane", "dennis", "sam", "bart", "vera", "luna", "mark"];
+if (AGENT_NAMES.includes(command?.toLowerCase())) {
+  let description = "";
+  let cwd = process.cwd();
+  let taskId = null;
+  const remaining = args.slice(1);
+
+  for (let i = 0; i < remaining.length; i++) {
+    if ((remaining[i] === "--description" || remaining[i] === "-d") && remaining[i + 1]) {
+      description = remaining[++i];
+    } else if (remaining[i] === "--cwd" && remaining[i + 1]) {
+      cwd = remaining[++i];
+    } else if (!taskId && !remaining[i].startsWith("-")) {
+      taskId = remaining[i];
+    }
+  }
+
+  if (!taskId && !description) {
+    console.error(`Usage: agentdesk ${command} <TASK-ID>`);
+    console.error(`   or: agentdesk ${command} -d "description"`);
+    process.exit(1);
+  }
+
+  const { runTeam } = await import("../cli/team.mjs");
+  const code = await runTeam(taskId, { description, cwd, soloAgent: command.charAt(0).toUpperCase() + command.slice(1).toLowerCase() });
+  process.exit(code);
+}
+
+else if (command === "login") {
   const { runLogin } = await import("../cli/login.mjs");
   await runLogin();
 }

package/cli/orchestrator.mjs

@@ -1,11 +1,11 @@
 // Orchestrator — runs a single Claude process with all agents as personas
 
-import { spawn } from "child_process";
-import { existsSync, readFileSync } from "fs";
+import { spawn, execSync } from "child_process";
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from "fs";
 import { createInterface } from "readline";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
-import { buildPrompt } from "./prompt.mjs";
+import { buildPrompt, buildSoloPrompt } from "./prompt.mjs";
 import { createStreamParser } from "./stream-parser.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -47,7 +47,7 @@ function timestamp() {
 export async function runOrchestrator({
   taskId, taskLink, description, createTask, tracker, config,
   project, team, teamSections, inboxUrl, sessionUrl, cwd,
-  onEvent, apiKey, serverUrl,
+  onEvent, apiKey, serverUrl, soloAgent,
 }) {
   const trackerCreds = await fetchTrackerCredentials(project?.name, apiKey, serverUrl);
   const env = { ...process.env, ...loadDotEnv(cwd), ...trackerCreds };
@@ -56,14 +56,16 @@ export async function runOrchestrator({
   let totalOutputTokens = 0;
   let totalSteps = 0;
 
+  let lastPhase = null;
+
   function emit(event) {
+    if (event.type === "phase:change") lastPhase = event.phase;
     onEvent?.({ ...event, timestamp: timestamp() });
   }
 
-  const fullPrompt = buildPrompt({
-    taskId, taskLink, description, createTask, tracker, config,
-    project, teamSections, inboxUrl, sessionUrl,
-  });
+  const fullPrompt = soloAgent
+    ? buildSoloPrompt({ agentName: soloAgent, taskId, description, tracker, config, project, sessionUrl })
+    : buildPrompt({ taskId, taskLink, description, createTask, tracker, config, project, teamSections, inboxUrl, sessionUrl });
 
   emit({
     type: "session:start",
@@ -71,11 +73,11 @@ export async function runOrchestrator({
     title: description || taskId,
     project: project?.name || null,
     sessionNumber: 1,
-    agents: teamSections.names,
+    agents: soloAgent ? [soloAgent] : teamSections.names,
     cliVersion: CLI_VERSION,
   });
 
-  emit({ type: "phase:change", phase: "INTAKE" });
+  emit({ type: "phase:change", phase: soloAgent ? "EXECUTION" : "INTAKE" });
 
   const child = spawn(
     "claude",
@@ -108,10 +110,52 @@ export async function runOrchestrator({
     parseLine(line);
   }
 
-  await new Promise(resolve => child.on("close", resolve));
+  const exitCode = await new Promise(resolve => child.on("close", resolve));
 
   const duration = `${((Date.now() - startTime) / 1000).toFixed(1)}s`;
-  emit({ type: "session:end", duration, steps: totalSteps, inputTokens: totalInputTokens, outputTokens: totalOutputTokens });
 
-  return { duration, steps: totalSteps, inputTokens: totalInputTokens, outputTokens: totalOutputTokens };
+  // Detect limit/crash — non-zero exit without a clean session end
+  const isHandoff = exitCode !== 0;
+
+  if (isHandoff) {
+    // Write mechanical resume snapshot
+    let branch = "";
+    let diffStat = "";
+    try { branch = execSync("git branch --show-current", { cwd, encoding: "utf-8" }).trim(); } catch {}
+    try { diffStat = execSync("git diff --stat HEAD", { cwd, encoding: "utf-8" }).trim(); } catch {}
+
+    const resumePath = join(cwd, ".agentdesk-resume.md");
+    const resumeContent = [
+      `# AgentDesk Resume — ${taskId}`,
+      ``,
+      `Session: ${sessionUrl}`,
+      `Date: ${new Date().toISOString()}`,
+      `Phase: ${lastPhase || "UNKNOWN"}`,
+      `Duration: ${duration}`,
+      `Steps: ${totalSteps}`,
+      `Exit code: ${exitCode}`,
+      ``,
+      `## Branch`,
+      branch || "(no branch)",
+      ``,
+      `## Uncommitted changes`,
+      diffStat || "(none)",
+      ``,
+      `## Notes`,
+      `Session ended unexpectedly (likely Claude rate/context limit).`,
+      `Resume with: agentdesk team ${taskId}`,
+      ``,
+    ].join("\n");
+    try { writeFileSync(resumePath, resumeContent); } catch {}
+
+    emit({ type: "session:end", duration, steps: totalSteps, inputTokens: totalInputTokens, outputTokens: totalOutputTokens, status: "handoff" });
+  } else {
+    // Clean exit — remove stale resume file if present
+    const resumePath = join(cwd, ".agentdesk-resume.md");
+    try { if (existsSync(resumePath)) unlinkSync(resumePath); } catch {}
+
+    emit({ type: "session:end", duration, steps: totalSteps, inputTokens: totalInputTokens, outputTokens: totalOutputTokens });
+  }
+
+  return { duration, steps: totalSteps, inputTokens: totalInputTokens, outputTokens: totalOutputTokens, handoff: isHandoff };
 }

package/cli/prompt.mjs

@@ -4,6 +4,7 @@ import { readFileSync } from "fs";
 import { resolve, dirname } from "path";
 import { fileURLToPath } from "url";
 import { generateContext } from "./detect.mjs";
+import { BUILT_IN_AGENTS } from "./agents.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PROMPT_PATH = resolve(__dirname, "../prompts/team.md");
@@ -100,3 +101,84 @@ export function buildPrompt({ taskId, taskLink, description, createTask, tracker
 
   return `${prompt}\n\n---\n\n## PROJECT CONTEXT\n\n${context}\n\n${timeInfo}`;
 }
+
+export function buildSoloPrompt({ agentName, taskId, description, tracker, config, project, sessionUrl }) {
+  const agent = BUILT_IN_AGENTS[agentName];
+  if (!agent) throw new Error(`Unknown agent: ${agentName}`);
+
+  const lines = [
+    `# ${agentName} — ${agent.role} (Solo Mode)`,
+    ``,
+    `You are ${agentName}, ${agent.description}.`,
+    `You are working independently on this task — there is no team. You handle everything yourself.`,
+    ``,
+    agent.groundRules ? `## Ground Rules\n\n${agent.groundRules}` : "",
+    agent.codePrinciple ? `## Code Principles\n\n${agent.codePrinciple}` : "",
+    ``,
+    `## Task`,
+    ``,
+    taskId ? `Task ID: ${taskId}` : "",
+    description ? `Description: ${description}` : "",
+    sessionUrl ? `Session: ${sessionUrl}` : "",
+    ``,
+    `## Instructions`,
+    ``,
+    `Work on this task independently. Follow CLAUDE.md conventions if present.`,
+    `Read and understand the codebase before making changes.`,
+    ``,
+  ];
+
+  if (agent.execution?.tasks) {
+    lines.push(`## Your responsibilities`, ``);
+    for (const t of agent.execution.tasks) {
+      lines.push(`- ${t}`);
+    }
+    lines.push(``);
+  }
+
+  // Extract and include tracker integration from team prompt
+  if (tracker && taskId) {
+    let teamPrompt = readFileSync(PROMPT_PATH, "utf-8");
+
+    // Extract the matching tracker block
+    const trackerKey = tracker.toUpperCase();
+    const trackerRegex = new RegExp(`\\{\\{#${trackerKey}\\}\\}([\\s\\S]*?)\\{\\{\\/${trackerKey}\\}\\}`, "g");
+    let trackerSection = "";
+    let match;
+    while ((match = trackerRegex.exec(teamPrompt)) !== null) {
+      trackerSection += match[1] + "\n";
+    }
+
+    if (trackerSection) {
+      // Substitute variables
+      trackerSection = trackerSection.replace(/\{\{TASK_ID\}\}/g, taskId);
+      trackerSection = trackerSection.replace(/\{\{SESSION_URL\}\}/g, sessionUrl || "");
+      if (config.jira?.baseUrl) {
+        trackerSection = trackerSection.replace(/\{\{JIRA_BASE_URL\}\}/g, config.jira.baseUrl.replace(/\/+$/, ""));
+      }
+      lines.push(trackerSection);
+    }
+
+    lines.push(
+      `## Required tracker actions`,
+      ``,
+      `1. Fetch the task — read summary, description, status, comments, attachments.`,
+      `2. Post a comment: "${agentName} working on this task (solo mode). Session: ${sessionUrl || ""}"`,
+      `3. Do your work.`,
+      `4. Post a final comment summarizing what was done, what was omitted, and any manual steps required.`,
+      ``,
+    );
+  }
+
+  // Add custom instructions
+  if (config?.instructions) {
+    lines.push(`## Additional Instructions`, ``, config.instructions, ``);
+  }
+
+  // Add project context
+  const context = generateContext(project);
+  const now = new Date();
+  const timeInfo = `Current date/time: ${now.toLocaleDateString("en-US", { weekday: "long", year: "numeric", month: "long", day: "numeric" })} ${now.toLocaleTimeString("en-US", { hour: "2-digit", minute: "2-digit" })}`;
+
+  return lines.filter(Boolean).join("\n") + `\n\n---\n\n## PROJECT CONTEXT\n\n${context}\n\n${timeInfo}`;
+}

package/cli/team.mjs

@@ -87,6 +87,10 @@ export async function runTeam(taskId, opts = {}) {
     console.log(`Jira: ${cyan}${config.jira.baseUrl}${reset}`);
   }
 
+  if (opts.soloAgent) {
+    console.log(`Agent: ${opts.soloAgent} (solo mode)`);
+  }
+
   // Resolve team and generate dynamic prompt sections
   const team = resolveTeam(config);
   const teamSections = generateTeamPrompt(team, { tracker, config });
@@ -206,11 +210,20 @@ export async function runTeam(taskId, opts = {}) {
     onEvent: vizSend,
     apiKey,
     serverUrl: agentdeskServer,
+    soloAgent: opts.soloAgent || null,
   });
 
   clearInterval(heartbeatInterval);
 
-  console.log(`\n━━━ DONE ━━━`);
+  if (result.handoff) {
+    const yellow = "\x1b[33m";
+    console.log(`\n━━━ ${yellow}HANDOFF${reset} ━━━`);
+    console.log(`  Session paused — likely hit Claude rate/context limit.`);
+    console.log(`  Resume file saved to .agentdesk-resume.md`);
+    console.log(`  Resume with: ${cyan}agentdesk team ${taskId}${reset}\n`);
+  } else {
+    console.log(`\n━━━ DONE ━━━`);
+  }
   const totalTokens = result.inputTokens + result.outputTokens;
   console.log(`  ${result.duration}  |  ${result.steps} steps${totalTokens ? `  |  ${totalTokens.toLocaleString()} tokens` : ""}\n`);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kendoo.agentdesk/agentdesk",
-  "version": "0.9.19",
+  "version": "0.9.21",
   "description": "AI team orchestrator for Claude Code — run collaborative agent sessions from your terminal",
   "type": "module",
   "bin": {

package/prompts/team.md

@@ -309,6 +309,15 @@ Fetch the issue from GitHub — print title, body, state, existing comments.
 Read the task description. If CLAUDE.md exists, read it.
 {{/NO_TRACKER}}
 
+### Resume check
+
+Check if `.agentdesk-resume.md` exists in the project root. If it does, this is a **resumed session** — a previous session was interrupted (likely by a Claude rate/context limit). Read the file to understand:
+- What phase the previous session reached
+- What branch was being used
+- What changes were already made
+
+Use this context to skip completed work and continue from where the previous session left off. Delete `.agentdesk-resume.md` after reading it.
+
 ### Assess
 
 1. Check for existing branches: `git branch -a | grep {{TASK_ID}}`
@@ -317,6 +326,7 @@ Read the task description. If CLAUDE.md exists, read it.
 4. Check for project agents: `ls .claude/agents/ .claude/commands/ .github/workflows/ 2>/dev/null`; check if `.mcp.json` exists. If agents are found, Jane briefs the team and assigns usage.
 
 Based on findings:
+- Resume file exists → review previous progress, continue from where it left off
 - Fresh task → PLAN phase
 - Branch exists, no PR → review what's done, continue from EXECUTION
 - PR exists → review PR status, continue accordingly