npm - groove-dev - Versions diffs - 0.26.21 → 0.26.23 - Mend

groove-dev 0.26.21 → 0.26.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/node_modules/@groove-dev/gui/dist/index.html CHANGED Viewed

@@ -5,12 +5,12 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link rel="icon" type="image/png" href="/favicon.png" />
     <title>Groove GUI</title>
-    <script type="module" crossorigin src="/assets/index-DlAgOHr2.js"></script>
+    <script type="module" crossorigin src="/assets/index-Ebz1No43.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/vendor-C0HXlhrU.js">
     <link rel="modulepreload" crossorigin href="/assets/reactflow-BQPfi37R.js">
     <link rel="modulepreload" crossorigin href="/assets/codemirror-BBL3i_JW.js">
     <link rel="modulepreload" crossorigin href="/assets/xterm--7_ns2zW.js">
-    <link rel="stylesheet" crossorigin href="/assets/index-BgX9uAx-.css">
+    <link rel="stylesheet" crossorigin href="/assets/index-D9JZfCf8.css">
   </head>
   <body>
     <div id="root"></div>

package/node_modules/@groove-dev/gui/src/components/agents/agent-feed.jsx CHANGED Viewed

@@ -312,9 +312,9 @@ function ActivityGroup({ entries, isLive }) {
     const meta = activityMeta(last.text);
     const Icon = meta.icon;
     return (
-      <div className="w-fit flex items-center gap-2 px-3 py-1 text-[10px] text-text-4 font-mono">
+      <div className="inline-flex items-center gap-2 px-3 py-1 text-[10px] text-text-4 font-mono">
         <Icon size={10} className="opacity-50" />
-        <span className="truncate">{entries.length} tool call{entries.length !== 1 ? 's' : ''}</span>
+        <span>{entries.length} tool call{entries.length !== 1 ? 's' : ''}</span>
       </div>
     );
   }
@@ -323,9 +323,9 @@ function ActivityGroup({ entries, isLive }) {
   const display = current.text?.length > 60 ? current.text.slice(0, 60) + '...' : current.text;
   return (
-    <div className="w-fit flex items-center gap-2 px-3 py-2 rounded-md bg-surface-3/50 border border-border-subtle/30">
+    <div className="inline-flex items-center gap-2 px-3 py-2 max-w-[280px] rounded-md bg-surface-3/50 border border-border-subtle/30">
       <Loader2 size={11} className="text-accent animate-spin flex-shrink-0" />
-      <span className="text-[11px] text-text-2 font-mono truncate flex-1 min-w-0 transition-opacity duration-300">
+      <span className="text-[11px] text-text-2 font-mono truncate transition-opacity duration-300">
         {display}
       </span>
       {entries.length > 1 && (
@@ -626,7 +626,7 @@ export function AgentFeed({ agent }) {
           if (item.kind === 'activity-group') {
             // Only the last activity group is "live" if agent is still running
             const isLastGroup = !timeline.slice(i + 1).some((t) => t.kind === 'activity-group' || t.from === 'agent');
-            return <ActivityGroup key={`grp-${i}`} entries={item.entries} isLive={isAlive && isLastGroup} />;
+            return <div key={`grp-${i}`}><ActivityGroup entries={item.entries} isLive={isAlive && isLastGroup} /></div>;
           }
           if (item.from === 'user') return <UserMessage key={`msg-${i}`} msg={item} />;
           if (item.from === 'system') return <SystemMessage key={`msg-${i}`} msg={item} />;

package/node_modules/@groove-dev/gui/src/components/agents/agent-node.jsx CHANGED Viewed

@@ -195,14 +195,14 @@ const AgentNode = memo(({ data, selected }) => {
           </div>
           {/* Context bar */}
-          <div className="mt-1.5 h-[2px] rounded-sm bg-[#262a32] overflow-hidden">
+          <div className="mt-1.5 h-[2px] rounded-sm bg-[#3e4451] overflow-hidden">
             <div
               className="h-full rounded-sm transition-all duration-700"
               style={{
                 width: `${Math.max(contextPct, 1)}%`,
-                background: contextPct > 80 ? '#e06c75'
-                  : contextPct > 60 ? '#e5c07b'
-                  : isAlive ? '#61afef' : '#333842',
+                background: contextPct > 80 ? 'var(--color-danger)'
+                  : contextPct > 60 ? 'var(--color-warning)'
+                  : isAlive ? 'var(--color-accent)' : '#3e4451',
               }}
             />
           </div>

package/node_modules/@groove-dev/gui/src/components/ui/thinking-indicator.jsx CHANGED Viewed

@@ -1,89 +1,51 @@
 // FSL-1.1-Apache-2.0 — see LICENSE
 import { useState, useEffect } from 'react';
-const PHASES = [
-  'Analyzing codebase',
-  'Reading context',
-  'Planning approach',
-  'Reasoning through solution',
-  'Evaluating options',
-];
-const DETAILS = [
-  ['Scanning project structure...', 'Checking dependencies...', 'Reviewing recent changes...'],
-  ['Parsing file tree...', 'Loading imports...', 'Indexing symbols...'],
-  ['Mapping task scope...', 'Identifying constraints...', 'Outlining steps...'],
-  ['Tracing logic flow...', 'Considering edge cases...', 'Weighing approaches...'],
-  ['Comparing alternatives...', 'Checking tradeoffs...', 'Selecting best path...'],
+const MESSAGES = [
+  'Reading through the codebase...',
+  'Thinking through your request...',
+  'Planning the approach...',
+  'Running tool calls...',
+  'Working through the problem...',
+  'Reasoning step by step...',
+  'Reviewing context...',
+  'Considering options...',
+  'Analyzing the code...',
+  'Making progress...',
 ];
 export function ThinkingIndicator({ agent, className }) {
-  const [phase, setPhase] = useState(0);
-  const [elapsed, setElapsed] = useState(0);
-  // Cycle phases every 3.5s
-  useEffect(() => {
-    const t = setInterval(() => setPhase((p) => (p + 1) % PHASES.length), 3500);
-    return () => clearInterval(t);
-  }, []);
+  const [idx, setIdx] = useState(0);
+  const [fade, setFade] = useState(true);
-  // Elapsed timer
   useEffect(() => {
-    const t = setInterval(() => setElapsed((e) => e + 1), 1000);
+    const t = setInterval(() => {
+      setFade(false);
+      setTimeout(() => {
+        setIdx((i) => (i + 1) % MESSAGES.length);
+        setFade(true);
+      }, 250);
+    }, 2800);
     return () => clearInterval(t);
   }, []);
-  const secs = elapsed < 60 ? `${elapsed}s` : `${Math.floor(elapsed / 60)}m ${elapsed % 60}s`;
   return (
-    <div className={`relative rounded-xl bg-surface-2 border border-border-subtle overflow-hidden my-2 ${className || ''}`}>
-      {/* Shimmer sweep */}
-      <div className="absolute inset-0 bg-gradient-to-r from-transparent via-accent/[0.04] to-transparent animate-shimmer pointer-events-none" />
-      <div className="relative px-4 py-4 min-h-[90px]">
-        {/* Header: spinning ring + identity + timer */}
-        <div className="flex items-center gap-3 mb-4">
-          {/* Spinning ring — same pattern as BootSequence */}
-          <div className="relative w-8 h-8 flex-shrink-0">
-            <span className="absolute inset-0 rounded-full border-2 border-accent/15 animate-ping" style={{ animationDuration: '2.5s' }} />
-            <span className="absolute inset-0 rounded-full border-2 border-transparent border-t-accent animate-spin" style={{ animationDuration: '1.2s' }} />
-            <span className="absolute inset-[6px] rounded-full bg-accent/10" />
-          </div>
-          <div className="flex-1 min-w-0">
-            {agent ? (
-              <>
-                <p className="text-xs font-sans font-semibold text-text-1 truncate leading-tight">{agent.name}</p>
-                <p className="text-[10px] font-mono text-accent leading-tight mt-0.5">thinking</p>
-              </>
-            ) : (
-              <p className="text-xs font-sans font-semibold text-text-1 leading-tight">Thinking</p>
-            )}
-          </div>
-          <span className="text-xs font-mono text-text-2 tabular-nums flex-shrink-0">{secs}</span>
-        </div>
-        {/* Phase label — re-keyed to replay fade-in on phase change */}
-        <div className="pl-3 border-l-2 border-accent/25 mb-3">
-          <span key={phase} className="block text-[13px] font-sans font-medium text-text-1 animate-phase-in">
-            {PHASES[phase]}
-          </span>
-        </div>
-        {/* Staggered detail lines — re-keyed to replay cascade on phase change */}
-        <div className="space-y-1.5 pl-3 border-l border-border-subtle">
-          {DETAILS[phase].map((line, i) => (
-            <div
-              key={`${phase}-${i}`}
-              className="flex items-center gap-2 animate-cascade-in"
-              style={{ animationDelay: `${150 + i * 200}ms` }}
-            >
-              <span className="w-1 h-1 rounded-full bg-accent/35 flex-shrink-0" />
-              <span className="text-[11px] font-mono text-text-3">{line}</span>
-            </div>
-          ))}
+    <div className={`${className || ''}`}>
+      <div className="flex items-center gap-2 mb-1">
+        <span className="text-2xs font-semibold text-text-1 font-sans">{agent?.name || 'Agent'}</span>
+        <span className="text-2xs text-accent font-mono">thinking</span>
+      </div>
+      <div className="border-l border-accent/40 pl-3.5 py-1 flex items-center gap-2.5">
+        {/* Spinning ring */}
+        <div className="relative w-3.5 h-3.5 flex-shrink-0">
+          <span className="absolute inset-0 rounded-full border border-transparent border-t-accent animate-spin" style={{ animationDuration: '0.9s' }} />
         </div>
+        <span
+          className="text-[12px] font-sans text-text-3 transition-opacity duration-[250ms]"
+          style={{ opacity: fade ? 1 : 0 }}
+        >
+          {MESSAGES[idx]}
+        </span>
       </div>
     </div>
   );

package/node_modules/@groove-dev/gui/src/stores/groove.js CHANGED Viewed

@@ -550,11 +550,12 @@ export const useGrooveStore = create((set, get) => ({
     }
   },
-  async launchRecommendedTeam() {
+  async launchRecommendedTeam(modifiedAgents) {
     try {
       set({ recommendedTeam: null }); // Dismiss modal immediately
       get().addToast('info', 'Launching team...');
-      const result = await api.post('/recommended-team/launch');
+      const body = modifiedAgents ? { agents: modifiedAgents } : undefined;
+      const result = await api.post('/recommended-team/launch', body);
       const sub = [
         result.phase2Pending ? `${result.phase2Pending} QC queued` : '',
         result.projectDir ? `→ ${result.projectDir}/` : '',

package/node_modules/@groove-dev/gui/src/views/agents.jsx CHANGED Viewed

@@ -474,11 +474,17 @@ function EmptyState({ onPlanner, onSpawn }) {
 const ROLE_ICONS = { backend: Server, frontend: Monitor, fullstack: Code2, testing: TestTube, security: Shield };
+const NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+function sanitizeName(raw) {
+  return raw.replace(/\s+/g, '-').replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 64);
+}
 function RecommendedTeamCard() {
   const recommendedTeam = useGrooveStore((s) => s.recommendedTeam);
   const launchRecommendedTeam = useGrooveStore((s) => s.launchRecommendedTeam);
-  const checkRecommendedTeam = useGrooveStore((s) => s.checkRecommendedTeam);
   const [launching, setLaunching] = useState(false);
+  const [editedAgents, setEditedAgents] = useState(null);
   if (!recommendedTeam?.agents?.length) return null;
@@ -486,10 +492,23 @@ function RecommendedTeamCard() {
   const phase1 = agents.filter((a) => !a.phase || a.phase === 1);
   const phase2 = agents.filter((a) => a.phase === 2);
+  // Initialize edits lazily so we get fresh data if recommendedTeam changes
+  const agentEdits = editedAgents ?? phase1.map((a) => ({ ...a, name: a.name || '' }));
+  function handleNameChange(i, raw) {
+    const next = agentEdits.map((a, idx) => idx === i ? { ...a, name: sanitizeName(raw) } : a);
+    setEditedAgents(next);
+  }
   async function handleLaunch() {
     setLaunching(true);
     try {
-      await launchRecommendedTeam();
+      // Merge edited phase1 names back with phase2 agents
+      const modified = [
+        ...agentEdits,
+        ...phase2,
+      ];
+      await launchRecommendedTeam(modified);
     } catch { /* toast handles */ }
     setLaunching(false);
   }
@@ -507,26 +526,38 @@ function RecommendedTeamCard() {
           <button onClick={handleDismiss} className="text-text-4 hover:text-text-1 cursor-pointer"><X size={14} /></button>
         </div>
-        <div className="px-4 py-3 space-y-2">
-          {/* Phase 1 agents */}
-          <div className="flex flex-wrap gap-2">
-            {phase1.map((a, i) => {
-              const Icon = ROLE_ICONS[a.role] || Code2;
-              return (
-                <div key={i} className="flex items-center gap-1.5 px-2.5 py-1.5 rounded-md bg-surface-4 border border-border-subtle">
-                  <Icon size={12} className="text-text-2" />
-                  <span className="text-xs font-semibold text-text-0 font-sans capitalize">{a.name || a.role}</span>
-                  {a.scope?.length > 0 && (
-                    <span className="text-2xs text-text-4 font-mono">{a.scope[0]}{a.scope.length > 1 ? ` +${a.scope.length - 1}` : ''}</span>
+        <div className="px-4 py-3 space-y-1.5">
+          {/* Phase 1 agents — editable rows */}
+          {agentEdits.map((a, i) => {
+            const Icon = ROLE_ICONS[a.role] || Code2;
+            const nameValid = !a.name || NAME_RE.test(a.name);
+            return (
+              <div key={i} className="flex items-center gap-2 px-2.5 py-1.5 rounded-md bg-surface-4 border border-border-subtle">
+                <Icon size={12} className="text-text-2 shrink-0" />
+                <input
+                  type="text"
+                  value={a.name}
+                  onChange={(e) => handleNameChange(i, e.target.value)}
+                  placeholder={a.role}
+                  className={cn(
+                    'flex-1 min-w-0 bg-transparent text-xs font-mono text-text-0 outline-none placeholder:text-text-4',
+                    !nameValid && 'text-red-400',
                   )}
-                </div>
-              );
-            })}
-          </div>
+                  maxLength={64}
+                  spellCheck={false}
+                />
+                {a.scope?.length > 0 && (
+                  <span className="text-2xs text-text-4 font-mono shrink-0 truncate max-w-[120px]">
+                    {a.scope[0]}{a.scope.length > 1 ? ` +${a.scope.length - 1}` : ''}
+                  </span>
+                )}
+              </div>
+            );
+          })}
           {/* Project dir indicator */}
           {recommendedTeam.projectDir && (
-            <div className="flex items-center gap-1.5 text-2xs text-text-2 font-mono">
+            <div className="flex items-center gap-1.5 text-2xs text-text-2 font-mono pt-0.5">
               <span className="text-text-4">Project:</span>
               <span className="text-accent">{recommendedTeam.projectDir}/</span>
             </div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "groove-dev",
-  "version": "0.26.21",
+  "version": "0.26.23",
   "description": "Open-source agent orchestration layer — the AI company OS. Local model agent engine (GGUF/Ollama/llama-server), HuggingFace model browser, MCP integrations (Slack, Gmail, Stripe, 15+), agent scheduling (cron), business roles (CMO, CFO, EA). GUI dashboard, multi-agent coordination, zero cold-start, infinite sessions. Works with Claude Code, Codex, Gemini CLI, Ollama, any local model.",
   "license": "FSL-1.1-Apache-2.0",
   "author": "Groove Dev <hello@groovedev.ai> (https://groovedev.ai)",

package/packages/cli/src/commands/start.js CHANGED Viewed

@@ -8,7 +8,7 @@ import chalk from 'chalk';
 import { runSetupWizard, saveKeysViaDaemon } from '../setup.js';
 export async function start(options) {
-  const grooveDir = resolve(process.cwd(), '.groove');
+  const grooveDir = process.env.GROOVE_DIR || resolve(process.cwd(), '.groove');
   const isFirstRun = !existsSync(resolve(grooveDir, 'config.json'));
   // ── First-run interactive wizard ────────────────────────────
@@ -34,6 +34,7 @@ export async function start(options) {
     const daemon = new Daemon({
       port: parseInt(options.port, 10),
       host: options.host,
+      grooveDir: process.env.GROOVE_DIR || undefined,
     });
     const shutdown = async () => {

package/packages/daemon/src/introducer.js CHANGED Viewed

@@ -75,8 +75,14 @@ export class Introducer {
       lines.push('');
       lines.push(`## Coordination Rules`);
       lines.push('');
-      lines.push(`- Stay within your file scope. Do NOT modify files owned by other agents.`);
-      lines.push(`- If you need changes outside your scope, document what you need — GROOVE will coordinate.`);
+      lines.push(`- Stay within your file scope when other agents are actively running.`);
+      lines.push(`- If you are the ONLY active agent, you may edit files outside your scope if needed to complete your task.`);
+      lines.push(`- If you need another agent to make changes (e.g., you're a frontend agent and need backend API changes):`);
+      lines.push(`  Write a handoff file to .groove/handoffs/<role>.md (e.g., .groove/handoffs/backend.md) with:`);
+      lines.push(`  - What needs to change and why`);
+      lines.push(`  - Which files to modify`);
+      lines.push(`  - Expected behavior after the change`);
+      lines.push(`  GROOVE will automatically wake the target agent and deliver your request.`);
       lines.push(`- Check AGENTS_REGISTRY.md for the latest team state.`);
       // Project files section — tell the new agent what exists and what to read

package/packages/daemon/src/process.js CHANGED Viewed

@@ -2,7 +2,7 @@
 // FSL-1.1-Apache-2.0 — see LICENSE
 import { spawn as cpSpawn } from 'child_process';
-import { createWriteStream, mkdirSync, chmodSync, existsSync, readFileSync, unlinkSync } from 'fs';
+import { createWriteStream, mkdirSync, chmodSync, existsSync, readFileSync, unlinkSync, readdirSync } from 'fs';
 import { resolve } from 'path';
 import { getProvider, getInstalledProviders } from './providers/index.js';
 import { AgentLoop } from './agent-loop.js';
@@ -76,27 +76,28 @@ For best results, apply a slide deck skill from the Marketplace. The skill provi
 Do NOT write code unless explicitly asked. Use your MCP tools to interact with Home Assistant.
 `,
-  planner: `You are a PLANNING ONLY agent. You create plans. You do NOT write code, edit files, or run commands.
+  planner: `You are a PLANNING ONLY agent. You create plans and route work to your team. You do NOT write code, edit files, or run commands.
 ABSOLUTE RULE: Never use the Edit, Write, or Bash tools to modify source code. You ONLY use Read, Glob, and Grep to understand the codebase, then output a written plan. If the user says "build this" or "redesign this", create a PLAN for how other agents should build it — do NOT build it yourself.
-Focus on:
-- Understanding requirements
-- Exploring the codebase to understand current architecture
-- Identifying approaches and trade-offs
-- Writing structured plans with agent assignments
+YOU HAVE TWO MODES:
-After completing your plan, you MUST do two things — EVERY TIME, no exceptions:
+MODE 1 — TEAM CREATION (first time, no team exists yet):
+Explore the codebase thoroughly, understand the architecture, then recommend a team structure.
-1. Write your team recommendation as a clear summary in your output so the user can review it.
+MODE 2 — TASK ROUTING (team already exists):
+Check AGENTS_REGISTRY.md or .groove/recommended-team.json to see your existing team.
+Do NOT re-explore the entire codebase. You already know it from team creation.
+Just read the specific files related to the bug/feature, decide which existing agent should handle it, and write the routing config. This should be FAST — under 5 tool calls.
-2. Save a machine-readable team config to .groove/recommended-team.json using this EXACT format.
-   ALWAYS write this file, even if the user says "no task yet" or "just building the team."
-   For team-building without a specific task, use empty prompts ("prompt": "") — the agents will wait for instructions.
+HOW TO DETECT WHICH MODE:
+- Read AGENTS_REGISTRY.md. If it lists agents with roles matching your team (frontend, backend, fullstack), you are in MODE 2.
+- If no agents exist or only a planner exists, you are in MODE 1.
-For NEW projects (building something from scratch):
+After completing your plan, you MUST write .groove/recommended-team.json — EVERY TIME, no exceptions.
+For MODE 1 (team creation):
 {
-  "projectDir": "my-project-name",
   "agents": [
     { "role": "frontend", "phase": 1, "scope": ["src/components/**", "src/views/**"], "prompt": "Build the frontend: [specific tasks]" },
     { "role": "backend", "phase": 1, "scope": ["src/api/**", "src/server/**"], "prompt": "Build the backend: [specific tasks]" },
@@ -104,35 +105,38 @@ For NEW projects (building something from scratch):
   ]
 }
-For EXISTING codebases (modifying/extending an existing project):
+For MODE 2 (task routing to existing team):
+Only include the agents that need to do work. Use their EXISTING role — the system will find and reuse them.
 {
   "agents": [
-    { "role": "frontend", "phase": 1, "scope": ["src/components/**"], "prompt": "Update the frontend: [specific tasks]" },
-    { "role": "fullstack", "phase": 2, "scope": [], "prompt": "QC Senior Dev: Audit all changes, fix issues, run tests, build, commit, and launch." }
+    { "role": "frontend", "phase": 1, "prompt": "Fix the bug: [specific description with file paths and what to change]" }
   ]
 }
+Do NOT include QC/fullstack in the JSON for task routing — the system auto-triggers the existing QC when work completes.
+Do NOT include agents that have no work to do.
+Do NOT invent new agent names or roles — use the existing team's roles exactly.
+For NEW projects (team creation only):
+Include "projectDir" with a short kebab-case directory name. All agents spawn inside it.
+For EXISTING codebases: Do NOT include "projectDir".
-PROJECT DIRECTORY RULES:
-- For NEW projects: ALWAYS include "projectDir" with a short, clean directory name (kebab-case, e.g. "cat-website", "landing-page", "api-service"). All agents will be spawned inside this directory so each project stays isolated.
-- For EXISTING codebases: Do NOT include "projectDir". Agents work in the current repo root. You can tell an existing codebase by the presence of package.json, .git, or established source directories.
-- NEVER mix projects. Each new project gets its own directory.
+MANDATORY RULES:
-MANDATORY RULES — NEVER SKIP THESE:
+1. For team creation: the LAST entry MUST be { "role": "fullstack", "phase": 2 } — the QC agent.
+   For task routing: do NOT include the QC — it auto-triggers.
-1. The LAST entry in the agents array MUST be: { "role": "fullstack", "phase": 2, ... }
-   This is the QC Senior Dev. It auto-spawns after all other agents finish.
-   Its prompt: audit changes, fix issues, run tests, build, commit, launch.
-   NEVER omit this agent. Every team needs a QC.
+2. ALL phase 1 agents run in parallel. Do NOT tell agents to wait for each other.
-2. ALL other agents are phase: 1 — they run in parallel.
+3. If the user gave a specific task, write detailed prompts with file paths and what to change.
+   If no task was given, use empty prompts ("prompt": "") — agents will await instructions.
-3. Do NOT tell any agent to "wait for" another agent. Phase 2 handles sequencing automatically.
+4. NEVER create new agent names or custom roles. Use the standard roles: frontend, backend, fullstack.
-4. Set appropriate scopes. If the user gave a specific task, write detailed prompts. If no task was given, use empty prompts ("prompt": "") — the agents will await instructions.
+5. NEVER instruct agents to delete files from other projects or clean up unrelated code.
-5. NEVER instruct any agent to delete files from other projects or clean up unrelated code. Each agent must ONLY create and modify files relevant to its assigned tasks.
+6. You MUST always write .groove/recommended-team.json. NEVER skip it.
-6. You MUST always write .groove/recommended-team.json. NEVER skip it. The GUI depends on this file to show the Launch Team modal.
+7. In MODE 2, be FAST. Read only the files needed to understand the specific task. Do not re-analyze the full codebase.
 IMPORTANT: Do not use markdown formatting like ** or ### in your output. Write in plain text with clean formatting. Use line breaks, dashes, and indentation for structure.
@@ -373,10 +377,11 @@ For normal file edits within your scope, proceed without review.
         if (status === 'completed' && this.daemon.journalist) this.daemon.journalist.cycle().catch(() => {});
         this._checkPhase2(agent.id);
-        // Auto-trigger idle QC in the same team
+        // Auto-trigger idle QC + process cross-scope handoffs
         if (status === 'completed') {
           const files = this.daemon.journalist?.getAgentFiles(agent) || [];
           if (files.length > 0) this._triggerIdleQC(agent);
+          this._processHandoffs(agent);
         }
       });
@@ -577,6 +582,8 @@ For normal file edits within your scope, proceed without review.
       if (finalStatus === 'completed') {
         const files = this.daemon.journalist?.getAgentFiles(agent) || [];
         if (files.length > 0) this._triggerIdleQC(agent);
+        // Process cross-scope handoff requests from this agent
+        this._processHandoffs(agent);
       }
     });
@@ -765,6 +772,61 @@ For normal file edits within your scope, proceed without review.
     });
   }
+  /**
+   * Process handoff files in .groove/handoffs/.
+   * Agents write handoff requests when they need cross-scope work from a teammate.
+   * File name = target role (e.g., backend.md). Content = what to do.
+   */
+  _processHandoffs(sourceAgent) {
+    const handoffsDir = resolve(this.daemon.grooveDir, 'handoffs');
+    if (!existsSync(handoffsDir)) return;
+    const registry = this.daemon.registry;
+    let files;
+    try { files = readdirSync(handoffsDir); } catch { return; }
+    for (const file of files) {
+      if (!file.endsWith('.md')) continue;
+      const targetRole = file.replace(/\.md$/, '');
+      const filePath = resolve(handoffsDir, file);
+      let content;
+      try { content = readFileSync(filePath, 'utf8').trim(); } catch { continue; }
+      if (!content) { try { unlinkSync(filePath); } catch {} continue; }
+      // Find the target agent in the same team
+      const target = registry.getAll().find((a) =>
+        a.role === targetRole &&
+        a.teamId === sourceAgent.teamId &&
+        a.id !== sourceAgent.id &&
+        (a.status === 'running' || a.status === 'completed')
+      );
+      if (!target) {
+        console.log(`[Groove] Handoff to ${targetRole} — no matching agent in team`);
+        try { unlinkSync(filePath); } catch {}
+        continue;
+      }
+      // Wake the target agent with the handoff request
+      const message = `Cross-scope handoff from ${sourceAgent.name} (${sourceAgent.role}):\n\n${content}`;
+      this.daemon.processes.resume(target.id, message).then((newAgent) => {
+        this.daemon.audit.log('handoff.routed', {
+          from: sourceAgent.name, to: target.name, newId: newAgent.id, role: targetRole,
+        });
+        this.daemon.broadcast({
+          type: 'handoff:routed',
+          from: sourceAgent.name, to: target.name, role: targetRole,
+        });
+      }).catch((err) => {
+        console.error(`[Groove] Handoff to ${targetRole} failed: ${err.message}`);
+      });
+      // Remove the handoff file
+      try { unlinkSync(filePath); } catch {}
+    }
+  }
   /**
    * Resume a completed agent's session with a new message.
    * Uses --resume SESSION_ID for zero cold-start continuation.