@kendoo.agentdesk/agentdesk 0.9.19 → 0.9.20

package/README.md

@@ -113,6 +113,18 @@ 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.
 
+### 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 +136,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 +189,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

@@ -85,6 +85,10 @@ 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);

package/cli/orchestrator.mjs

@@ -1,7 +1,7 @@
 // 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";
@@ -56,7 +56,10 @@ 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() });
   }
 
@@ -108,10 +111,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/team.mjs

@@ -210,7 +210,15 @@ export async function runTeam(taskId, opts = {}) {
 
   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.20",
   "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