@kendoo.agentdesk/agentdesk 0.9.18 → 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

@@ -193,6 +193,13 @@ export async function runTeam(taskId, opts = {}) {
 
   connectWs();
 
+  // Heartbeat keeps session alive on the server during long silent operations
+  const heartbeatInterval = setInterval(() => {
+    if (vizConnected && vizWs?.readyState === WebSocket.OPEN) {
+      vizWs.send(JSON.stringify({ type: "session:heartbeat", sessionId }));
+    }
+  }, 30000);
+
   const result = await runOrchestrator({
     taskId, taskLink, description, createTask, tracker, config,
     project, team, teamSections, inboxUrl, sessionUrl, cwd,
@@ -201,7 +208,17 @@ export async function runTeam(taskId, opts = {}) {
     serverUrl: agentdeskServer,
   });
 
-  console.log(`\n━━━ DONE ━━━`);
+  clearInterval(heartbeatInterval);
+
+  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.18",
+  "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

@@ -221,7 +221,17 @@ Session: {{SESSION_URL}}
 <brief plan summary>
 
 ## Changes Made
-<list of files changed and what was done>
+<for each file changed: file path, what was done, and why>
+
+## Added
+<new files, features, or dependencies introduced>
+
+## Omitted / Deferred
+<what was skipped or left out, and why — e.g., "Skipped mobile responsive layout — deferred to follow-up task">
+
+## Manual Steps Required
+<any steps the developer must perform manually — e.g., "Run database migration", "Add API key to .env", "Update DNS record", "Restart service">
+<if none, write "None">
 
 ## Decisions
 <key technical decisions and reasoning>
@@ -299,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}}`
@@ -307,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
@@ -422,7 +442,16 @@ After the first round, Jane asks for objections. If none, declare the plan final
 Jane verifies tracker status is current:
 1. Verify Bart posted the PR link. If not, do it now.
 2. Transition task to "In Review".
-3. Post a final summary comment on the tracker.
+3. Post a final summary comment on the tracker with this structure:
+
+**Final comment must include:**
+- **What was done**: Brief summary of changes (files modified, features added)
+- **What was omitted**: Anything skipped or deferred, with reason
+- **Manual steps**: Actions the developer must perform (migrations, env vars, config changes, service restarts). If none, state "No manual steps required"
+- **PR link**: Link to the pull request
+- **Session link**: Link to the dashboard session
+
+This comment is the handoff to the reviewer — it must be clear enough that someone unfamiliar with the session can understand what happened and what's left to do.
 
 Print:
 echo "Team Session Complete."