@adaptic/maestro 1.1.7 → 1.4.1

package/plugins/maestro-skills/plugin.json

@@ -50,6 +50,22 @@
     {
       "name": "schedule-meeting",
       "description": "Schedule a meeting using Google Calendar MCP or Calendly. Handle timezone conversion, find availability, send invites."
+    },
+    {
+      "name": "claude-pace",
+      "description": "Check Claude API rate limit quota — 5-hour/7-day usage, reset countdowns, pace delta. Use before heavy backlog cycles or when quota warnings appear."
+    },
+    {
+      "name": "ccxray-diagnostics",
+      "description": "Run token/cost X-ray diagnostics on Claude API sessions — per-turn breakdown, context window heatmaps, system prompt diffs. Use for debugging expensive sessions."
+    },
+    {
+      "name": "code-review-graph",
+      "description": "Structural code analysis via tree-sitter knowledge graph — blast radius, review context, architecture overview, semantic search. Use for PR reviews and refactoring."
+    },
+    {
+      "name": "agents-observe",
+      "description": "Multi-agent observability dashboard — monitor parallel agent teams, tool calls, session state, and performance in real time. Use when debugging agent failures."
     }
   ]
 }

package/plugins/maestro-skills/skills/agents-observe.md

@@ -0,0 +1,110 @@
+---
+name: agents-observe
+description: Multi-agent observability dashboard — monitor parallel agent teams, tool calls, session state, and performance in real time. Use when debugging agent failures or profiling backlog execution.
+---
+
+# Multi-Agent Observability (agents-observe)
+
+You are a Maestro agent. Use agents-observe to monitor, debug, and profile Claude Code agent teams in real time.
+
+## When to Invoke
+
+- **Monitoring parallel execution** — watching multiple backlog executor agents running simultaneously
+- **Debugging agent failures** — an agent crashed, hung, or produced unexpected results
+- **Performance profiling** — identifying which agents or tool calls are slow
+- **Post-mortem analysis** — reviewing what happened in a completed session
+- **Orchestrator oversight** — the orchestrator agent needs visibility into sub-agent activity
+
+## Background
+
+agents-observe captures tool calls, agent hierarchy, and session state via background hooks. Data is stored in SQLite and streamed to a WebSocket-powered dashboard with 3-5ms latency. It is NOT always-on due to SQLite write overhead — enable on demand for specific debugging sessions.
+
+## Steps
+
+### Starting Observation
+
+1. **Launch the dashboard**:
+   ```bash
+   agents-observe serve
+   ```
+   Opens the dashboard at `http://localhost:3847`. Active Claude Code sessions appear automatically.
+
+2. **Monitor live sessions** — the dashboard shows:
+   - Agent hierarchy (parent orchestrator and child sub-agents)
+   - Real-time tool call stream with timing
+   - Session state (active, idle, completed, errored)
+   - Per-agent resource usage
+
+### Querying Historical Data
+
+3. **Query by session** — inspect a specific session's full history:
+   ```bash
+   agents-observe query --session <session-id>
+   ```
+
+4. **Query by tool** — find all uses of a specific tool in a time window:
+   ```bash
+   agents-observe query --tool Write --last 1h
+   ```
+
+5. **Query by agent** — filter to a specific agent's activity:
+   ```bash
+   agents-observe query --agent backlog-executor --last 2h
+   ```
+
+### Analysis Workflows
+
+6. **Debugging a failed agent**:
+   - Find the session ID from workflow logs or the dashboard
+   - Query the session to see the full tool call sequence
+   - Identify the last successful tool call before failure
+   - Check for error patterns: timeout, rate limit, permission denied, context overflow
+
+7. **Performance profiling**:
+   - Compare tool call durations across agents
+   - Identify bottleneck tools (slow reads, large writes)
+   - Check for redundant tool calls (same file read multiple times)
+   - Measure time-to-first-action for each sub-agent
+
+8. **Parallel execution monitoring**:
+   - Verify all expected sub-agents launched successfully
+   - Watch for agents blocking on shared resources (file locks, API limits)
+   - Detect agents that completed quickly vs those that are stuck
+   - Identify ordering issues in agent dependencies
+
+## Output
+
+Report findings appropriate to the workflow:
+
+**For debugging:**
+```
+## Agent Failure Analysis: [session-id]
+- Agent: [name]
+- Failed at: [timestamp]
+- Last successful tool: [tool name] at [timestamp]
+- Error: [error message or pattern]
+- Root cause: [analysis]
+- Recommendation: [fix]
+```
+
+**For performance profiling:**
+```
+## Agent Performance Profile
+| Agent | Duration | Tool Calls | Slowest Tool | Outcome |
+|---|---|---|---|---|
+| [name] | [Xs] | [N] | [tool, Xms] | [success/fail] |
+
+### Bottlenecks
+- [Specific finding, e.g., "Agent X read config.yaml 7 times — cache recommended"]
+
+### Recommendations
+- [Actionable optimization]
+```
+
+## Integration Notes
+
+- Do NOT leave agents-observe running permanently — SQLite writes add overhead to every tool call
+- Enable for specific debugging sessions, then shut down
+- Dashboard port is 3847 — ensure no conflicts with other local services
+- Pairs well with ccxray for combined tool-call and token-level analysis
+- Session data persists in SQLite after the dashboard is closed — queryable later

package/plugins/maestro-skills/skills/ccxray-diagnostics.md

@@ -0,0 +1,91 @@
+---
+name: ccxray-diagnostics
+description: Run token/cost X-ray diagnostics on Claude API sessions — per-turn breakdown, context window heatmaps, system prompt diffs. Use for debugging expensive sessions or comparing sub-agent efficiency.
+---
+
+# Token/Cost X-Ray Diagnostics (ccxray)
+
+You are a Maestro agent. Use ccxray to diagnose token usage, cost, and context window utilization across agent sessions.
+
+## When to Invoke
+
+- **Debugging expensive sessions** — a backlog cycle consumed unexpectedly high tokens
+- **Sub-agent efficiency comparison** — comparing token cost across parallel agents doing similar work
+- **Context window analysis** — investigating whether agents are hitting context limits or carrying stale context
+- **System prompt auditing** — diffing system prompts across agents to find bloat
+- **Post-incident analysis** — understanding what went wrong in a failed or degraded session
+
+## Background
+
+ccxray is a transparent HTTP proxy that intercepts all Claude API calls and provides a live dashboard with per-turn token/cost breakdowns. It is an on-demand diagnostic tool, not always-on infrastructure.
+
+- Proxy + dashboard: `npx ccxray claude`
+- Logs stored at: `~/.ccxray/logs/`
+- Dashboard shows live data during the session
+
+## Steps
+
+1. **Launch a diagnostic session** — run the target agent through ccxray:
+   ```bash
+   npx ccxray claude
+   ```
+   This wraps the Claude Code session in the ccxray proxy. All API calls are intercepted and logged.
+
+2. **Open the dashboard** — ccxray serves a local dashboard showing:
+   - Per-turn input/output token counts
+   - Cumulative cost tracking
+   - Context window heatmap (what is filling the window)
+   - System prompt content and diffs between turns
+
+3. **Analyze token distribution** — identify where tokens are being spent:
+   - Large system prompts eating context budget
+   - Repeated tool outputs inflating input tokens
+   - Verbose agent responses consuming output tokens
+   - Context window near capacity causing cache misses
+
+4. **Compare sub-agents** — if multiple agents ran in parallel, compare their ccxray logs:
+   - Which agent consumed the most tokens per unit of work?
+   - Are any agents carrying unnecessary context?
+   - Are system prompts appropriately sized for each agent's role?
+
+5. **Review historical logs** — check `~/.ccxray/logs/` for past session data:
+   ```bash
+   ls -lt ~/.ccxray/logs/
+   ```
+
+6. **Produce findings** — summarize token/cost insights and recommend optimizations.
+
+## Output
+
+Report the following:
+
+```
+## Token/Cost X-Ray Report
+
+### Session Summary
+- Total input tokens: [N]
+- Total output tokens: [N]
+- Estimated cost: $[X.XX]
+- Turns: [N]
+- Context window peak: [N]% utilization
+
+### Top Token Consumers
+1. [Turn/phase] — [N] tokens ([reason])
+2. [Turn/phase] — [N] tokens ([reason])
+
+### Optimization Recommendations
+- [Specific recommendation, e.g., "Reduce system prompt by removing unused policy sections"]
+- [Specific recommendation, e.g., "Cache tool outputs instead of re-reading files"]
+
+### Sub-Agent Comparison (if applicable)
+| Agent | Input Tokens | Output Tokens | Cost | Efficiency |
+|---|---|---|---|---|
+| [name] | [N] | [N] | $[X] | [notes] |
+```
+
+## Integration Notes
+
+- This is an on-demand tool — do NOT run ccxray on every session, only when diagnosing issues
+- ccxray adds minimal overhead (~5ms per request) but writes logs to disk
+- Use for periodic token budget audits per backlog cycle (e.g., weekly)
+- Pair with claude-pace to correlate token usage with quota consumption

package/plugins/maestro-skills/skills/claude-pace.md

@@ -0,0 +1,61 @@
+---
+name: claude-pace
+description: Check Claude API rate limit quota — 5-hour/7-day usage, reset countdowns, pace delta. Use before heavy backlog cycles, when quota warnings appear, or to decide whether to defer non-urgent work.
+---
+
+# Rate Limit Monitoring (claude-pace)
+
+You are a Maestro agent. Use the claude-pace status line plugin to monitor API quota and make informed scheduling decisions.
+
+## When to Invoke
+
+- **Before heavy backlog cycles** — check headroom before spawning parallel agents
+- **When quota warnings appear** — "hit your limit" or rate-limit errors in logs
+- **Capacity planning** — deciding whether to defer improvement-backlog or non-urgent items
+- **Post-incident** — confirming quota has recovered after a rate-limit outage
+
+## Background
+
+claude-pace is a Claude Code status line plugin (Bash + jq, ~10ms latency). It is auto-installed by `init-agent.sh` via `claude plugin marketplace add Astro-Han/claude-pace`. It displays real-time quota data in the Claude Code status bar.
+
+The key signal is **pace delta**:
+- **Green** — headroom available, safe to proceed with full parallelism
+- **Yellow** — approaching limits, reduce parallel agent count
+- **Red** — near or at limit, defer all non-urgent work immediately
+
+## Steps
+
+1. **Read the status line** — claude-pace displays 5-hour window usage, 7-day rolling usage, and time until next reset directly in the Claude Code status bar.
+
+2. **Evaluate pace delta** — determine current capacity:
+   - **Green (>40% remaining)**: Proceed normally. Full parallel agent spawning is safe.
+   - **Yellow (15-40% remaining)**: Reduce to 2 parallel agents max. Defer improvement-backlog items.
+   - **Red (<15% remaining)**: Critical items only. No parallel spawning. Defer all non-urgent work.
+
+3. **Check reset countdown** — if quota is constrained, note when the 5-hour window resets. Schedule deferred work for after reset.
+
+4. **Adjust execution plan** based on findings:
+   - Prioritize critical/high-priority queue items only when constrained
+   - Move improvement-backlog and low-priority items to next cycle
+   - Reduce `parallel_with` fan-out in workflow steps
+   - Log the capacity decision in the session audit
+
+5. **If rate-limit outage is suspected**, check workflow logs for the pattern: `"started"` entry without a matching `"completed"` entry, and inspect `.log` files for `"hit your limit"` strings.
+
+## Output
+
+Report the following to the calling agent or session:
+
+```
+## Quota Status
+- 5-hour window: [X]% used — resets in [T]
+- 7-day rolling: [X]% used
+- Pace delta: [green/yellow/red]
+- Recommendation: [proceed normally / reduce parallelism / critical-only mode]
+```
+
+## Integration Notes
+
+- Complements Maestro's reactive rate-limit detection (checking logs post-facto) with proactive visibility
+- Does NOT require launching a separate process — data is in the status bar
+- When pace delta is red, the backlog executor should automatically shrink its batch size from 3-5 items to 1-2

package/plugins/maestro-skills/skills/code-review-graph.md

@@ -0,0 +1,99 @@
+---
+name: code-review-graph
+description: Structural code analysis via tree-sitter knowledge graph — blast radius, review context, architecture overview, semantic search. Use for PR reviews, refactoring, and engineering health checks.
+---
+
+# Structural Code Analysis (code-review-graph)
+
+You are a Maestro agent. Use code-review-graph to build and query a tree-sitter-based knowledge graph of any codebase for structural analysis.
+
+## When to Invoke
+
+- **PR reviews** — assess blast radius of changes before approving
+- **Refactoring** — understand call chains, import graphs, and dependencies before making changes
+- **Engineering health checks** — generate architecture overviews for repos in the portfolio
+- **Pre-change analysis** — determine what will break if a function/class is modified
+- **Semantic code search** — find functions, patterns, or relationships across a codebase
+
+## Background
+
+code-review-graph uses tree-sitter to parse source code and build a knowledge graph mapping functions, classes, imports, and call relationships. It provides both CLI tools and an MCP server with specialized analysis tools.
+
+## Steps
+
+### One-Time Setup
+
+1. **Index the target repository**:
+   ```bash
+   npx code-review-graph index /path/to/repo
+   ```
+   This parses all source files and builds the knowledge graph. Re-run after significant changes.
+
+2. **Configure as MCP server** (optional, for persistent access):
+   Add to `.claude/settings.json` under `mcpServers`:
+   ```json
+   {
+     "code-review-graph": {
+       "command": "npx",
+       "args": ["code-review-graph", "serve", "--port", "3848"]
+     }
+   }
+   ```
+
+### Analysis Workflows
+
+3. **Blast radius analysis** — before approving a PR or making a change:
+   - Query which functions/modules depend on the changed code
+   - Identify downstream consumers that may break
+   - Map the full call chain from changed function to entry points
+   - Tool: `blast_radius` (via MCP) or CLI equivalent
+
+4. **Review context** — when reviewing a PR:
+   - Pull structural context for changed files (what calls them, what they call)
+   - Identify if changes touch hot paths or critical modules
+   - Surface related functions that should have been changed but were not
+   - Tool: `review_context` (via MCP)
+
+5. **Architecture overview** — for engineering health checks:
+   - Generate module dependency graph
+   - Identify circular dependencies
+   - Map public API surface vs internal implementation
+   - Surface orphaned code (defined but never called)
+   - Tool: `architecture_overview` (via MCP)
+
+6. **Semantic search** — finding code by intent:
+   - Search for functions matching a description or pattern
+   - Find all implementations of a given interface
+   - Locate similar code patterns across the codebase
+   - Tool: `semantic_search` (via MCP)
+
+## Output
+
+Report findings appropriate to the workflow:
+
+**For blast radius:**
+```
+## Blast Radius: [function/file]
+- Direct dependents: [N] functions in [N] files
+- Transitive impact: [N] modules
+- Risk level: [low/medium/high]
+- Affected entry points: [list]
+```
+
+**For architecture overview:**
+```
+## Architecture: [repo]
+- Modules: [N]
+- Key dependency chains: [list top 3]
+- Circular dependencies: [list or "none"]
+- Orphaned exports: [count]
+- Hottest module (most dependents): [name]
+```
+
+## Integration Notes
+
+- Recommended for coding-oriented agents (engineering, platform, product)
+- Optional for operational agents (comms, hiring, strategy) — they rarely need code-level analysis
+- Re-index after merging significant PRs to keep the graph current
+- The MCP server runs on port 3848 by default — ensure no conflicts
+- Graph build time scales with repo size; large monorepos may take 30-60 seconds

package/scaffold/CLAUDE.md

@@ -131,6 +131,70 @@ npm run gen:list                      # List available prompt specs
 
 - 5-layer defence defined in `policies/prompt-injection-defence.yaml`
 
+### Persistent Session Memory (Claude-Mem)
+
+- **Claude-Mem** automatically captures tool usage, generates semantic summaries, and injects relevant context into future sessions
+- Lifecycle hooks: SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd
+- Storage: Local SQLite database with Chroma vector search at `~/.claude-mem/`
+- Configuration: `~/.claude-mem/settings.json`
+- Install/update: `npx claude-mem install`
+
+### Rate Limit Awareness (Claude-Pace)
+
+- **Claude-Pace** displays real-time quota usage (5-hour + 7-day), reset countdowns, and burn rate in the status line
+- Pace delta indicator: green = headroom, red = burning too fast
+- Pure Bash + jq — ~10ms runtime, no network calls
+- Install: `claude plugin marketplace add Astro-Han/claude-pace && claude plugin install claude-pace`
+- See `docs/guides/claude-pace-setup.md`
+
+### Token Diagnostics (ccxray)
+
+- **ccxray** provides X-ray vision into Claude Code sessions via HTTP proxy + live dashboard
+- Per-turn token/cost breakdown, context window heatmaps, system prompt diffs
+- On-demand diagnostic tool (not default runtime): `npx ccxray claude`
+- See `docs/guides/ccxray-diagnostics.md`
+
+### Persistent Sessions (Claudraband)
+
+- **Claudraband** adds persistent, resumable sessions and daemon mode with HTTP API to Claude Code
+- Daemon mode: `npx @halfwhey/claudraband serve --port 7842`
+- Prompt injection into running sessions: `npx @halfwhey/claudraband prompt --session <id> "keep going"`
+- Enable as session backend: set `MAESTRO_SESSION_BACKEND=claudraband` in `.env`
+- See `docs/guides/claudraband-sessions.md`
+
+### Swarm Orchestration (ClawTeam) [optional]
+
+- **ClawTeam** orchestrates multi-agent coding swarms using git worktrees + tmux + filesystem messaging
+- Leader/worker pattern with task dependencies and auto-unblocking
+- Each worker gets its own worktree branch — no file conflicts between agents
+- Enable: set `MAESTRO_ENABLE_SWARM=1` before running `init-agent.sh`
+- See `docs/guides/clawteam-swarm.md`
+
+### Multi-Agent Observability (Agents Observe) [optional]
+
+- **Agents Observe** provides a real-time dashboard for monitoring Claude Code agent teams
+- WebSocket-streamed UI showing live tool calls, agent hierarchy trees, and session state
+- 3-5ms latency via background hooks with SQLite storage
+- Best for debugging parallel agent execution and performance profiling
+- Install: `./scripts/setup/install-dev-tools.sh --tool agents-observe`
+- See `docs/guides/agents-observe-setup.md`
+
+### Codebase Knowledge Graph (code-review-graph) [optional]
+
+- **code-review-graph** builds a Tree-sitter-powered structural knowledge graph of codebases
+- MCP tools: blast-radius analysis, review context, architecture overview, semantic search, refactor planning
+- Auto-updates on file changes — persistent structural awareness
+- Best for coding-oriented agents doing PR reviews, engineering health checks, and refactoring
+- Install: `./scripts/setup/install-dev-tools.sh --tool code-review-graph`
+- See `docs/guides/code-review-graph-setup.md`
+
+### Self-Optimization Pattern (AutoAgent-inspired) [optional]
+
+- Standardized framework for agents to autonomously improve their own configuration via benchmark-driven iteration
+- Define scoring rubrics → run scenarios → propose changes → compare scores → keep if better
+- Experiment log: `self-optimization/experiments.jsonl`
+- See `docs/guides/self-optimization-pattern.md`
+
 ### Audit & Hooks
 
 - Pre-send audit hook gates all outbound Slack/Gmail communications

package/scaffold/config/agent.ts.example

@@ -57,7 +57,8 @@ export const agent = {
   /** Agent's phone number (E.164 format) — used for Twilio SMS/voice/WhatsApp */
   phone: '+16282656712',
 
-  /** Agent's Slack member ID (e.g. U097N5R0M7U) — used for mentions and DM routing */
+  /** Agent's Slack member ID (e.g. U097N5R0M7U) — used for mentions, DM routing,
+   *  and cross-agent message filtering (see config/known-agents.json) */
   slackMemberId: '',
 
   // ---------------------------------------------------------------------------

package/scaffold/config/caller-id-map.yaml

@@ -0,0 +1,46 @@
+# Caller ID to user mapping for voice/SMS authorization
+#
+# Used by: sms-handler.mjs, parse-voice-transcript.mjs, user-context-search.py
+# Maps phone numbers, Slack IDs, and emails to user identities with access levels.
+#
+# Access levels:
+#   ceo        — Full access to all paths (memory, knowledge, state, outputs, docs, logs, all interactions)
+#   leadership — Company knowledge + docs + research/briefs + own interaction logs
+#   partner    — Public knowledge + research + own interaction logs
+#   default    — Unknown callers — public company knowledge only (knowledge/sources/)
+#
+# Hot-reloaded every 60 seconds by sms-handler.mjs — no restart needed after edits.
+#
+# Setup: See docs/guides/voice-sms-setup.md for full configuration instructions.
+
+users:
+  # ── Principal (the person this agent reports to) ──────────────────────────
+  # Replace with your principal's details. This entry should have access_level: ceo.
+  principal:
+    name: "Principal Full Name"
+    phone: ["+1XXXXXXXXXX"]
+    whatsapp: ["+1XXXXXXXXXX"]
+    slack_id: "UXXXXXXXXXX"
+    email: "principal@company.com"
+    access_level: ceo
+
+  # ── Leadership / Team ─────────────────────────────────────────────────────
+  # Add team members who should be recognized by the SMS handler and voice parser.
+  # Each entry needs at minimum: name, slack_id, email, and access_level.
+  # Phone numbers are only needed if the person will contact the agent via SMS/voice.
+
+  # example-leader:
+  #   name: "Example Leader"
+  #   phone: []
+  #   slack_id: "UXXXXXXXXXX"
+  #   email: "leader@company.com"
+  #   access_level: leadership
+
+  # ── Partners / External ───────────────────────────────────────────────────
+
+  # example-partner:
+  #   name: "External Partner"
+  #   phone: []
+  #   slack_id: ""
+  #   email: "partner@external.com"
+  #   access_level: partner

package/scaffold/config/known-agents.json

@@ -0,0 +1,35 @@
+{
+  "_comment": "Registry of all AI agents in the organisation. Used by the daemon classifier to prevent cross-agent message interception — when a message @-mentions a specific agent, only that agent's daemon should respond. Each agent repo should have its own copy of this file. Update when agents are added or removed.",
+  "agents": [
+    {
+      "name": "Sophie",
+      "slackId": "U099N1JFPRQ",
+      "role": "Chief of Staff",
+      "repo": "sophie-ai"
+    },
+    {
+      "name": "Ravi",
+      "slackId": "U099N1JE0LA",
+      "role": "CTO",
+      "repo": "ravi-ai"
+    },
+    {
+      "name": "Lucas",
+      "slackId": "U099N17LVCJ",
+      "role": "Head of Legal Ops",
+      "repo": "lucas-ai"
+    },
+    {
+      "name": "Jacob",
+      "slackId": "U099N19NXT4",
+      "role": "Head of Engineering",
+      "repo": "jacob-ai"
+    },
+    {
+      "name": "Hessa",
+      "slackId": "U0ALUES7ERY",
+      "role": "Head of AI Research",
+      "repo": "hessa-surface"
+    }
+  ]
+}