@adaptic/maestro 1.1.8 → 1.5.0

package/bin/maestro.mjs

@@ -8,16 +8,21 @@
  *   npx @adaptic/maestro doctor             # Verify installation and configuration
  */
 
-import { resolve, join, dirname } from "node:path";
+import { resolve, join, dirname, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   mkdirSync,
   cpSync,
+  copyFileSync,
   existsSync,
   readFileSync,
   writeFileSync,
+  readdirSync,
+  statSync,
+  lstatSync,
 } from "node:fs";
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const MAESTRO_ROOT = resolve(__dirname, "..");
@@ -81,6 +86,7 @@ function create(targetName) {
     "desktop-control",
     "ingest",
     "mcp",
+    "services",
   ];
 
   for (const dir of frameworkDirs) {
@@ -595,7 +601,6 @@ rubrics: []
       upgrade: "npx @adaptic/maestro upgrade",
     },
     dependencies: {
-      "@anthropic-ai/sdk": "^0.82.0",
       "@google/genai": "^1.42.0",
       dotenv: "^16.4.5",
       execa: "^9.6.1",
@@ -664,68 +669,242 @@ rubrics: []
 }
 
 // ---------------------------------------------------------------------------
-// UPGRADE — update framework files in current agent repo
+// UPGRADE — update framework files in current agent repo (smart merge)
 // ---------------------------------------------------------------------------
+//
+// Upgrade philosophy: by default, never silently overwrite a file the user has
+// modified locally. Detection uses git as the source of truth:
+//
+//   • untracked or has-uncommitted-changes in agent repo ⇒ "locally modified"
+//   • tracked and clean against HEAD ⇒ "vendored, safe to overwrite"
+//
+// For every framework file we'd otherwise overwrite, we classify into:
+//
+//   added     — file doesn't exist in agent repo → copy
+//   updated   — file exists, agent's copy matches HEAD (no local edits) → overwrite
+//   same      — file exists, content already byte-identical to upstream → skip
+//   preserved — file exists with local edits → keep agent's copy, write the
+//               upstream version to .maestro/incoming/<path> for manual review
+//               (unless --force-overwrite is passed)
+//
+// Flags:
+//   --dry-run            preview only; no files written
+//   --force-overwrite    overwrite even locally-modified files (with backup)
+//   --no-incoming        skip writing .maestro/incoming/ shadows
+//   --verbose            list every file's classification
+
+// Paths that get upgraded. Each entry is { path, mode } where mode is:
+//   "smart"  — per-file classification described above
+//   "merge"  — add new files only; never overwrite existing (used for agents/)
+const UPGRADE_PATHS = [
+  { path: "scripts", mode: "smart" },
+  { path: "policies", mode: "smart" },
+  { path: "docs", mode: "smart" },
+  { path: "public/assets", mode: "smart" },
+  { path: "workflows", mode: "smart" },
+  { path: "schedules", mode: "smart" },
+  { path: "desktop-control", mode: "smart" },
+  { path: "ingest", mode: "smart" },
+  { path: "mcp", mode: "smart" },
+  { path: ".claude/commands", mode: "smart" },
+  { path: "plugins/maestro-skills", mode: "smart" },
+  { path: "teams", mode: "smart" },
+  { path: "agents", mode: "merge" },
+];
+
+function sha256File(p) {
+  return createHash("sha256").update(readFileSync(p)).digest("hex");
+}
 
-function upgrade() {
-  const cwd = process.cwd();
-
-  if (!existsSync(join(cwd, "config/agent.ts")) && !existsSync(join(cwd, "CLAUDE.md"))) {
-    fail("Not a Maestro agent directory (config/agent.ts not found)");
-    process.exit(1);
+function walkFiles(root) {
+  const out = [];
+  if (!existsSync(root)) return out;
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    for (const name of readdirSync(dir)) {
+      const full = join(dir, name);
+      // Use lstat first so we can detect (and skip) symlinks — particularly
+      // broken ones, which are common in shared scaffolds.
+      let lst;
+      try { lst = lstatSync(full); }
+      catch { continue; }
+      if (lst.isSymbolicLink()) {
+        // Skip symlinks entirely — agents shouldn't inherit links into paths
+        // that may not exist on the target machine.
+        continue;
+      }
+      if (lst.isDirectory()) stack.push(full);
+      else if (lst.isFile()) out.push(full);
+    }
   }
+  return out;
+}
 
-  log("Upgrading framework files from @adaptic/maestro...");
-
-  // Framework directories that get overwritten on upgrade
-  const frameworkDirs = [
-    "scripts", "policies", "docs", "public/assets",
-    "workflows", "schedules", "desktop-control", "ingest", "mcp",
-  ];
+function isGitRepo(cwd) {
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd, stdio: "pipe" });
+    return true;
+  } catch { return false; }
+}
 
-  let updated = 0;
-  for (const dir of frameworkDirs) {
-    const src = join(MAESTRO_ROOT, dir);
-    if (existsSync(src)) {
-      cpSync(src, join(cwd, dir), { recursive: true, force: true });
-      ok(dir);
-      updated++;
+// Build a Set of repo-relative paths that are dirty (modified, added, untracked).
+// Single git invocation is much faster than per-file checks.
+function dirtyPathSet(cwd) {
+  const set = new Set();
+  try {
+    const out = execFileSync(
+      "git",
+      ["status", "--porcelain=v1", "-z", "--untracked-files=all"],
+      { cwd, encoding: "utf-8" }
+    );
+    // -z separates records with NUL; each record is "XY path" (no quoting).
+    // For renames (R/C) the format is "R  newpath\0oldpath\0" — we only care
+    // about destination, but for safety we treat both as dirty.
+    for (const rec of out.split("\0")) {
+      if (!rec) continue;
+      const status = rec.slice(0, 2);
+      const path = rec.slice(3);
+      // Anything in porcelain output is non-clean by definition.
+      if (status !== "  ") set.add(path);
     }
+  } catch {
+    // Not a git repo or git failed — caller will fall back to caution mode.
   }
+  return set;
+}
 
-  // .claude/commands (NOT settings.json — that's agent-specific)
-  const commandsSrc = join(MAESTRO_ROOT, ".claude", "commands");
-  if (existsSync(commandsSrc)) {
-    cpSync(commandsSrc, join(cwd, ".claude", "commands"), { recursive: true, force: true });
-    ok(".claude/commands");
-    updated++;
+function parseUpgradeFlags(args) {
+  const flags = {
+    dryRun: false,
+    forceOverwrite: false,
+    noIncoming: false,
+    verbose: false,
+  };
+  for (const a of args) {
+    if (a === "--dry-run" || a === "-n") flags.dryRun = true;
+    else if (a === "--force-overwrite" || a === "--force") flags.forceOverwrite = true;
+    else if (a === "--no-incoming") flags.noIncoming = true;
+    else if (a === "--verbose" || a === "-v") flags.verbose = true;
+    else if (a === "--help" || a === "-h") return null;
+    else { fail(`Unknown flag: ${a}`); process.exit(1); }
   }
+  return flags;
+}
 
-  // Plugins
-  const pluginSrc = join(MAESTRO_ROOT, "plugins", "maestro-skills");
-  if (existsSync(pluginSrc)) {
-    cpSync(pluginSrc, join(cwd, "plugins", "maestro-skills"), { recursive: true, force: true });
-    ok("plugins/maestro-skills");
-    updated++;
+function upgrade(args = []) {
+  const flags = parseUpgradeFlags(args);
+  if (flags === null) {
+    console.log(`
+Usage: maestro upgrade [flags]
+
+Flags:
+  --dry-run, -n          Preview changes without writing
+  --force-overwrite      Overwrite even locally-modified files (backs them up)
+  --no-incoming          Don't write .maestro/incoming/ shadows for preserved files
+  --verbose, -v          Print classification for every file
+  --help, -h             Show this help
+`);
+    return;
   }
 
-  // Agent definitions (merge: add new agents, update existing, don't delete custom ones)
-  const agentsSrc = join(MAESTRO_ROOT, "agents");
-  if (existsSync(agentsSrc)) {
-    cpSync(agentsSrc, join(cwd, "agents"), { recursive: true, force: false });
-    ok("agents (merged, custom agents preserved)");
-    updated++;
+  const cwd = process.cwd();
+
+  if (!existsSync(join(cwd, "config/agent.ts")) && !existsSync(join(cwd, "CLAUDE.md"))) {
+    fail("Not a Maestro agent directory (config/agent.ts not found)");
+    process.exit(1);
+  }
+
+  const inGit = isGitRepo(cwd);
+  if (!inGit) {
+    warn("Not in a git repo — cannot detect local modifications.");
+    warn("All existing files will be treated as locally modified and preserved.");
+    warn("Use --force-overwrite to override.");
   }
 
-  // Teams
-  const teamsSrc = join(MAESTRO_ROOT, "teams");
-  if (existsSync(teamsSrc)) {
-    cpSync(teamsSrc, join(cwd, "teams"), { recursive: true, force: true });
-    ok("teams");
-    updated++;
+  const dirty = inGit ? dirtyPathSet(cwd) : null;
+
+  const banner = flags.dryRun ? "DRY RUN — " : "";
+  log(`${banner}Upgrading framework files from @adaptic/maestro...`);
+
+  const counts = { added: 0, updated: 0, same: 0, preserved: 0, mergeKept: 0, forced: 0 };
+  const preservedFiles = [];
+
+  for (const { path: relRoot, mode } of UPGRADE_PATHS) {
+    const srcRoot = join(MAESTRO_ROOT, relRoot);
+    const dstRoot = join(cwd, relRoot);
+    if (!existsSync(srcRoot)) continue;
+
+    const srcFiles = walkFiles(srcRoot);
+    for (const srcFile of srcFiles) {
+      const relFromRoot = relative(srcRoot, srcFile);
+      const dstFile = join(dstRoot, relFromRoot);
+      const repoRel = relative(cwd, dstFile).split(sep).join("/");
+
+      // Case 1: new file (doesn't exist in agent) — always copy.
+      if (!existsSync(dstFile)) {
+        if (!flags.dryRun) {
+          mkdirSync(dirname(dstFile), { recursive: true });
+          copyFileSync(srcFile, dstFile);
+        }
+        counts.added++;
+        if (flags.verbose) ok(`+ ${repoRel}`);
+        continue;
+      }
+
+      // Case 2: byte-identical — nothing to do.
+      const srcHash = sha256File(srcFile);
+      const dstHash = sha256File(dstFile);
+      if (srcHash === dstHash) {
+        counts.same++;
+        if (flags.verbose) console.log(`  = ${repoRel}`);
+        continue;
+      }
+
+      // Case 3: merge-mode never overwrites existing files.
+      if (mode === "merge") {
+        counts.mergeKept++;
+        if (flags.verbose) console.log(`  ~ ${repoRel} (merge-mode, kept)`);
+        continue;
+      }
+
+      // Case 4: locally modified? Determine via git dirty set.
+      const locallyModified = inGit ? dirty.has(repoRel) : true;
+
+      if (locallyModified && !flags.forceOverwrite) {
+        counts.preserved++;
+        preservedFiles.push(repoRel);
+        if (!flags.dryRun && !flags.noIncoming) {
+          const shadow = join(cwd, ".maestro", "incoming", repoRel);
+          mkdirSync(dirname(shadow), { recursive: true });
+          copyFileSync(srcFile, shadow);
+        }
+        if (flags.verbose) console.log(`  ~ ${repoRel} (local edits, preserved)`);
+        continue;
+      }
+
+      // Case 5: overwrite (clean tracked file, or --force).
+      if (locallyModified && flags.forceOverwrite) {
+        // Back up the about-to-be-clobbered file.
+        if (!flags.dryRun) {
+          const backup = join(cwd, ".maestro", "backup", repoRel);
+          mkdirSync(dirname(backup), { recursive: true });
+          copyFileSync(dstFile, backup);
+        }
+        counts.forced++;
+        if (flags.verbose) warn(`! ${repoRel} (forced; backup written)`);
+      } else {
+        counts.updated++;
+        if (flags.verbose) console.log(`  > ${repoRel}`);
+      }
+      if (!flags.dryRun) {
+        mkdirSync(dirname(dstFile), { recursive: true });
+        copyFileSync(srcFile, dstFile);
+      }
+    }
   }
 
-  // Create any missing directories from the expanded list
+  // Ensure standard runtime directories exist.
   const ensureDirs = [
     "state/handoffs", "state/huddle", "state/indexes", "state/rag",
     "state/sessions", "state/slack-responded", "state/slack-thread-tracker",
@@ -739,15 +918,32 @@ function upgrade() {
   for (const dir of ensureDirs) {
     const dirPath = join(cwd, dir);
     if (!existsSync(dirPath)) {
-      mkdirSync(dirPath, { recursive: true });
+      if (!flags.dryRun) mkdirSync(dirPath, { recursive: true });
       newDirs++;
     }
   }
-  if (newDirs > 0) ok(`Created ${newDirs} new directories`);
+
+  // Summary
+  console.log();
+  console.log(`${C.bold}Upgrade summary${C.reset}${flags.dryRun ? " (dry run, nothing written)" : ""}`);
+  if (counts.added)     ok(`${counts.added} added (new files)`);
+  if (counts.updated)   ok(`${counts.updated} updated (vendored, no local edits)`);
+  if (counts.same)      console.log(`  = ${counts.same} already up-to-date`);
+  if (counts.mergeKept) console.log(`  ~ ${counts.mergeKept} merge-mode kept (agents/ custom files preserved)`);
+  if (counts.preserved) warn(`${counts.preserved} preserved (local edits — kept your version)`);
+  if (counts.forced)    warn(`${counts.forced} force-overwritten (backups in .maestro/backup/)`);
+  if (newDirs)          ok(`${newDirs} new directories created`);
+
+  if (preservedFiles.length && !flags.noIncoming && !flags.dryRun) {
+    console.log();
+    log("Upstream versions of your locally-modified files saved to .maestro/incoming/");
+    log("Review with:  diff <path> .maestro/incoming/<path>");
+    for (const p of preservedFiles.slice(0, 5)) console.log(`    ${p}`);
+    if (preservedFiles.length > 5) console.log(`    … and ${preservedFiles.length - 5} more`);
+  }
 
   console.log();
-  ok(`Upgraded ${updated} framework components.`);
-  log("Agent-specific files (config/, CLAUDE.md, knowledge/, memory/) were NOT modified.");
+  log("Agent-specific paths (config/, CLAUDE.md, knowledge/, memory/, state/, outputs/, logs/, .env) were NOT touched.");
 }
 
 // ---------------------------------------------------------------------------
@@ -820,16 +1016,22 @@ const [, , command, ...args] = process.argv;
 
 switch (command) {
   case "create": create(args[0]); break;
-  case "upgrade": upgrade(); break;
+  case "upgrade": upgrade(args); break;
   case "doctor": doctor(); break;
   case "--help": case "-h": case undefined:
     console.log(`
 Maestro — Autonomous AI Agent Operating System
 
 Usage:
-  npx @adaptic/maestro create <dirname>   Create a new agent repo
-  npx @adaptic/maestro upgrade            Update framework files
-  npx @adaptic/maestro doctor             Verify installation
+  npx @adaptic/maestro create <dirname>           Create a new agent repo
+  npx @adaptic/maestro upgrade [--dry-run]        Update framework files
+  npx @adaptic/maestro doctor                     Verify installation
+
+Upgrade flags:
+  --dry-run, -n          Preview changes without writing
+  --force-overwrite      Overwrite even locally-modified files (backs them up)
+  --no-incoming          Don't write .maestro/incoming/ shadows
+  --verbose, -v          List classification for every file
 
 Workflow:
   1. npx @adaptic/maestro create my-agent

package/docs/guides/agents-observe-setup.md

@@ -0,0 +1,64 @@
+# Agents Observe — Multi-Agent Observability Dashboard
+
+Real-time dashboard for monitoring Claude Code agent teams. Captures tool calls, agent hierarchy, and session state via background hooks with SQLite storage.
+
+## Why It Matters
+
+Maestro agents run parallel backlog execution with multiple subagents. Currently debugging relies on post-hoc JSONL log scanning. Agents Observe provides real-time visibility into:
+
+- **Live tool calls** across all active agents
+- **Agent hierarchy trees** showing parent/child relationships
+- **Search and filter** across sessions and tool invocations
+- **WebSocket-streamed UI** with 3-5ms latency
+
+## Installation
+
+### Via install-dev-tools (recommended)
+
+```bash
+./scripts/setup/install-dev-tools.sh --tool agents-observe
+```
+
+### Manual
+
+```bash
+# As Claude Code plugin
+claude plugin install agents-observe
+
+# Or global npm
+npm install -g agents-observe
+```
+
+## Usage
+
+### Start the dashboard
+
+```bash
+agents-observe serve
+# Opens dashboard at http://localhost:3847
+```
+
+### View active agent sessions
+
+Navigate to the dashboard URL. Active sessions appear automatically when Claude Code agents run with the plugin enabled.
+
+### Query session history
+
+```bash
+agents-observe query --session <id>
+agents-observe query --tool Write --last 1h
+```
+
+## Integration with Maestro
+
+Best used during:
+- **Backlog executor cycles** — monitor parallel agent performance
+- **Debugging agent failures** — trace tool call sequences leading to errors
+- **Performance profiling** — identify slow or redundant tool calls
+
+Not recommended as always-on in production (SQLite write overhead). Enable on-demand for debugging and profiling sessions.
+
+## Repository
+
+- GitHub: https://github.com/simple10/agents-observe
+- License: MIT

package/docs/guides/ccxray-diagnostics.md

@@ -0,0 +1,65 @@
+# ccxray Diagnostics Guide
+
+ccxray provides X-ray vision into Claude Code sessions via a transparent HTTP proxy and live dashboard. It intercepts all API calls between Claude Code and Anthropic, giving you detailed token/cost analysis, timing breakdowns, and system prompt visibility.
+
+## When to Use
+
+- Debugging expensive sessions (high token burn, unexpectedly long runs)
+- Understanding which tool calls consumed the most tokens
+- Comparing system prompts across main agent and sub-agents
+- Investigating context window utilisation and heatmaps
+- Post-incident analysis of failed or timed-out sessions
+
+## What It Shows
+
+- Real-time timeline of agent turns with thinking durations
+- Per-turn token and cost breakdown with burn rate tracking
+- Context window heatmaps showing what's consuming space
+- System prompt diffs across main agent and sub-agents
+- Multi-project hub: multiple terminals share one dashboard
+- Full JSON logging of every request/response to `~/.ccxray/logs/`
+
+## Technical Details
+
+- Zero-config transparent HTTP proxy
+- Launches Claude Code through the proxy automatically
+- Web dashboard for live monitoring
+- JSON log files for post-hoc analysis
+- npx-based — no permanent installation required
+
+## Usage
+
+### Quick start
+
+```bash
+# Launch Claude Code through the ccxray proxy
+npx ccxray claude
+```
+
+This starts the proxy, opens the dashboard, and launches Claude Code. All API traffic flows through ccxray for inspection.
+
+### With an existing session
+
+```bash
+# Start the proxy on a specific port
+npx ccxray --port 8080
+```
+
+### Viewing logs
+
+Logs are stored at `~/.ccxray/logs/` as JSON files, one per session. These can be analysed post-hoc for cost attribution.
+
+## Repository
+
+- GitHub: https://github.com/lis186/ccxray
+- License: MIT
+
+## Integration with Maestro
+
+ccxray is a diagnostic tool, not a runtime dependency. It is not installed by default via `init-agent.sh` but is available on-demand via npx.
+
+Use cases for Maestro operators:
+- **Token budget audit**: Run a backlog cycle through ccxray to see per-task token costs
+- **Sub-agent analysis**: Compare token usage across spawned background agents
+- **Prompt debugging**: Inspect what system prompts sub-agents actually receive
+- **Cost optimisation**: Identify which tool calls are disproportionately expensive

package/docs/guides/claude-mem-setup.md

@@ -0,0 +1,79 @@
+# Claude-Mem Setup Guide
+
+Claude-Mem is a persistent session memory plugin for Claude Code. It automatically captures tool usage, generates semantic summaries, and injects relevant context into future sessions — giving your agent continuity of knowledge across session boundaries.
+
+## What Claude-Mem Does
+
+- **Automatic capture**: 6 lifecycle hooks (SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd, PreCompact) record agent activity without manual intervention
+- **AI-powered compression**: Captured actions are summarised via Claude's agent-sdk into semantic memory
+- **Vector search**: Relevant past context is retrieved and injected at session start using Chroma vector search
+- **Local storage**: All data stays on-machine in `~/.claude-mem/` (SQLite + Chroma)
+
+## Installation
+
+### Via init-agent (recommended)
+
+If you ran `scripts/setup/init-agent.sh`, Claude-Mem was installed automatically. Verify:
+
+```bash
+npx claude-mem status
+```
+
+### Manual installation
+
+```bash
+npx claude-mem install
+```
+
+This registers the plugin hooks and starts the worker service (port 37777).
+
+### Via Claude Code plugin commands
+
+```bash
+claude plugin marketplace add thedotmack/claude-mem
+claude plugin install claude-mem
+# Restart Claude Code
+```
+
+## Configuration
+
+Settings live at `~/.claude-mem/settings.json` (auto-created with defaults on first run):
+
+- **AI model**: Which model compresses captured data
+- **Worker port**: Default 37777
+- **Data directory**: Where SQLite and vector indices are stored
+- **Context injection**: How much past context to inject per session
+- **Log level**: Verbosity of worker logs
+
+## Verification
+
+```bash
+# Check worker is running
+npx claude-mem status
+
+# View captured sessions
+npx claude-mem sessions list
+
+# View memory stats
+npx claude-mem stats
+```
+
+## How It Complements Maestro's Memory
+
+Maestro already has:
+- **Interaction memory** (`memory/interactions/`) — conversation transcripts by channel/date
+- **User profiles** (`memory/profiles/`) — per-person preferences and standing instructions
+- **Knowledge base** (`knowledge/`) — entities, decisions, syntheses
+
+Claude-Mem adds:
+- **Session-level recall** — what tools were used, what worked, what failed
+- **Semantic search across sessions** — find past sessions where similar tasks were done
+- **Automatic context injection** — no manual "read the last session" needed
+
+Together they provide comprehensive memory: Maestro handles *what was communicated*, Claude-Mem handles *what was done*.
+
+## Troubleshooting
+
+- **Worker not starting**: Check `~/.claude-mem/logs/` for errors. Ensure port 37777 is free.
+- **No context injected**: Verify hooks are registered: check `~/.claude/settings.json` for claude-mem entries
+- **High memory usage**: Claude-Mem's Chroma index grows over time. Run `npx claude-mem compact` to optimise.

package/docs/guides/claude-pace-setup.md

@@ -0,0 +1,56 @@
+# Claude-Pace Setup Guide
+
+Claude-Pace is a real-time rate limit tracker for Claude Code. It displays a status line showing your 5-hour and 7-day quota usage, reset countdowns, and a pace delta indicator (green = headroom, red = burning too fast).
+
+## Why It Matters
+
+Maestro agents run continuously on 10-minute backlog cycles. Without rate limit visibility, sessions hit quota walls mid-task — the backlog executor stalls, scheduled workflows fail silently, and recovery requires manual intervention. Claude-Pace makes quota state visible so agents (and operators) can pace work intelligently.
+
+## What It Shows
+
+- 5-hour and 7-day quota usage percentages
+- Reset countdown timers
+- Pace delta: whether current burn rate will exhaust quota before reset
+- Current model, effort level, git branch, diff stats
+
+## Technical Details
+
+- Pure Bash + jq — no npm, no Node, no network calls
+- ~10ms runtime per status line refresh
+- Single file: `claude-pace.sh`
+- Reads Claude Code's local quota cache
+
+## Installation
+
+### Via init-agent (recommended)
+
+If you ran `scripts/setup/init-agent.sh`, Claude-Pace was installed automatically. Verify:
+
+```bash
+# Check if the plugin is installed
+claude plugin list | grep claude-pace
+```
+
+### Via Claude Code plugin system
+
+```bash
+claude plugin marketplace add Astro-Han/claude-pace
+claude plugin install claude-pace
+# Restart Claude Code or run /reload-plugins
+claude-pace:setup
+```
+
+### Manual installation
+
+Download `claude-pace.sh` from the repository and add to `~/.claude/settings.json` under `statusLine`.
+
+## Repository
+
+- GitHub: https://github.com/Astro-Han/claude-pace
+- License: MIT
+
+## Integration with Maestro
+
+Claude-Pace complements Maestro's existing rate-limit detection (see `project_rate_limit_detection` memory). While Maestro detects rate limits reactively via workflow log analysis ("started" without "completed"), Claude-Pace provides proactive visibility — operators see quota state before it becomes a problem.
+
+For agents running heavy backlog cycles, the pace delta indicator is the key signal: if it's red, defer non-urgent queue items to the next cycle rather than risk a mid-task stall.