@adaptic/maestro 1.1.8 → 1.4.1

package/docs/guides/webhook-relay-setup.md

@@ -0,0 +1,349 @@
+# Webhook Relay Setup Guide (Railway)
+
+How to deploy each agent's per-instance webhook relay to Railway. The relay is the canonical pattern for receiving inbound webhooks from Slack and Twilio without requiring a stable inbound connection from the Mac mini.
+
+**Prerequisites**: Complete the [Mac Mini Bootstrap](../runbooks/mac-mini-bootstrap.md). The agent needs:
+- A Slack app already created (see `slack-setup.md`) so we have `SLACK_SIGNING_SECRET`
+- A Twilio account (or sub-account) and number purchased so we have `TWILIO_AUTH_TOKEN`
+- Admin rights in the company's Railway workspace (e.g., "Adaptic")
+
+---
+
+## Why a relay?
+
+Maestro agents run on a Mac mini that doesn't have a stable public IP. External services need a permanent HTTPS URL for webhooks. Cloudflare Quick Tunnels work but the URL changes on restart, and named tunnels require Cloudflare DNS configuration.
+
+Railway gives every agent a permanent `*.up.railway.app` domain with HTTPS and zero infrastructure. The pattern: Slack/Twilio send to Railway → Railway buffers in memory → Mac mini polls Railway every 5 seconds → events land in `state/inbox/`.
+
+```
+┌─────────────┐                 ┌──────────────────────┐
+│   Slack     │──webhook──────▶│  {agent}-webhook-relay │
+│   Twilio    │                 │  (Railway, in {Org})   │
+└─────────────┘                 │  in-memory buffers     │
+                                └──────┬─────────────────┘
+                                       │ /events, /sms/messages, /whatsapp/messages
+                                       ▼
+                              ┌──────────────────┐
+                              │  Mac mini        │
+                              │  poll-relay.sh   │
+                              │  every 5 sec     │
+                              └────────┬─────────┘
+                                       ▼
+                              state/inbox/{slack,sms,whatsapp}/
+```
+
+---
+
+## 1. Source code
+
+The relay source is at `services/webhook-relay/` in every agent's repo (copied from the maestro framework at create time). It's a single ~250-line Node 20 HTTP server, no dependencies, deployable straight to Railway.
+
+```
+services/webhook-relay/
+├── server.mjs       # The HTTP server with all endpoints
+├── package.json     # Node 20+, type: module, no deps
+├── railway.json     # NIXPACKS builder, /health check, restart-on-failure
+├── .gitignore
+└── README.md
+```
+
+### Endpoints
+
+#### Webhook receivers (called by external services)
+
+| Path | Method | Caller | Notes |
+|---|---|---|---|
+| `/slack/events` | POST | Slack Events API | HMAC verified via `SLACK_SIGNING_SECRET`. Echoes `url_verification` challenges. |
+| `/sms` | POST | Twilio SMS | HMAC verified via `TWILIO_AUTH_TOKEN`. Returns empty TwiML. |
+| `/whatsapp` | POST | Twilio WhatsApp | Same. |
+| `/whatsapp/status` | POST | Twilio WhatsApp status callback | Same. |
+
+#### Drain endpoints (called by the local Mac mini)
+
+| Path | Method | Returns |
+|---|---|---|
+| `/events` | GET | All buffered Slack events, drains buffer |
+| `/sms/messages` | GET | All buffered SMS events, drains buffer |
+| `/whatsapp/messages` | GET | All buffered WhatsApp events |
+| `/whatsapp/statuses` | GET | All buffered WhatsApp delivery status events |
+| `/health` | GET | Service status, buffer sizes, signature flags |
+
+---
+
+## 2. Install Railway CLI
+
+```bash
+brew install railway 2>/dev/null || true
+railway --version  # should be 4.x
+```
+
+Then log in (interactive — opens browser):
+
+```bash
+railway login
+```
+
+Confirm with `railway whoami`. If you don't see the company workspace in `railway list`, ask an existing admin to grant you access.
+
+---
+
+## 3. Create the project
+
+Run from the agent's repo:
+
+```bash
+cd services/webhook-relay
+railway init --name {firstname-lower}-webhook-relay --workspace {Company}
+```
+
+For Lucas, this is `lucas-webhook-relay` in the `Adaptic` workspace.
+
+The CLI will print a project URL — note it for reference.
+
+---
+
+## 4. Deploy
+
+```bash
+railway up --service {firstname-lower}-webhook-relay --detach
+```
+
+This packages the local directory, uploads it to Railway, and triggers a Nixpacks build. Build typically takes 30–60 seconds. Watch the build logs in the URL the CLI prints.
+
+---
+
+## 5. Generate a public domain
+
+```bash
+railway domain --service {firstname-lower}-webhook-relay
+```
+
+Prints something like:
+```
+🚀 https://lucas-webhook-relay-production.up.railway.app
+```
+
+Save this URL — you'll use it everywhere.
+
+---
+
+## 6. Set environment variables
+
+```bash
+source ../../.env
+railway variables --service {firstname-lower}-webhook-relay \
+  --set "SLACK_SIGNING_SECRET=$SLACK_SIGNING_SECRET" \
+  --set "TWILIO_AUTH_TOKEN=$TWILIO_AUTH_TOKEN" \
+  --set "PUBLIC_HOSTNAME={firstname-lower}-webhook-relay-production.up.railway.app" \
+  --set "BUFFER_TTL_MS=600000" \
+  --set "MAX_BUFFER_SIZE=1000"
+```
+
+| Var | Required | Source | Purpose |
+|---|---|---|---|
+| `SLACK_SIGNING_SECRET` | yes | Slack app → Basic Information | HMAC verify Slack webhooks |
+| `TWILIO_AUTH_TOKEN` | yes | Twilio Console → Account | HMAC verify Twilio webhooks |
+| `PUBLIC_HOSTNAME` | yes | Railway domain (without https://) | Used in Twilio HMAC base string |
+| `BUFFER_TTL_MS` | no | default 600000 (10 min) | Drop events older than this |
+| `MAX_BUFFER_SIZE` | no | default 1000 | Max events per channel |
+| `POLL_AUTH_TOKEN` | no | (unset) | If set, GET endpoints require Bearer token |
+
+The `PORT` variable is provided automatically by Railway — don't set it.
+
+After setting variables, **trigger a redeploy** so the running container picks them up. The variables exist in the project but the running container was built with the previous values:
+
+```bash
+railway up --service {firstname-lower}-webhook-relay --detach
+```
+
+---
+
+## 7. Verify deployment
+
+```bash
+for i in 1 2 3 4 5 6 7 8 9 10 11 12; do
+  RESP=$(curl -sf -m 5 https://{firstname-lower}-webhook-relay-production.up.railway.app/health)
+  if echo "$RESP" | grep -q '"slack_signature":true' && echo "$RESP" | grep -q '"twilio_signature":true'; then
+    echo "✅ Relay live with signature verification"
+    break
+  fi
+  sleep 10
+done
+```
+
+Expected output of `/health`:
+
+```json
+{
+  "ok": true,
+  "service": "{firstname-lower}-webhook-relay",
+  "uptime_sec": 12.3,
+  "buffers": {
+    "slack": { "events": 0, "seen": 0 },
+    "sms": { "events": 0, "seen": 0 },
+    "whatsapp": { "events": 0, "seen": 0 },
+    "whatsapp_status": { "events": 0, "seen": 0 }
+  },
+  "config": {
+    "slack_signature": true,
+    "twilio_signature": true,
+    "poll_auth": false,
+    "buffer_ttl_ms": 600000,
+    "max_buffer_size": 1000
+  }
+}
+```
+
+If `slack_signature` or `twilio_signature` is `false`, the env vars didn't reach the running container — re-run `railway up`.
+
+---
+
+## 8. Configure external services to point at the relay
+
+### Slack Events Subscription
+
+Update via the App Manifest editor (more reliable than the events page):
+
+1. Navigate to `https://app.slack.com/app-settings/{TEAM_ID}/{APP_ID}/app-manifest`
+2. Read the JSON, add this block to `settings`:
+
+   ```json
+   "event_subscriptions": {
+     "request_url": "https://{firstname-lower}-webhook-relay-production.up.railway.app/slack/events",
+     "bot_events": [
+       "app_mention",
+       "message.channels",
+       "message.groups",
+       "message.im",
+       "message.mpim"
+     ]
+   }
+   ```
+
+3. Click **Save Changes**
+4. Navigate to `https://api.slack.com/apps/{APP_ID}/event-subscriptions` and click **Click here to verify** if the yellow banner appears
+5. **Reinstall the app** at `https://api.slack.com/apps/{APP_ID}/install-on-team` so the new event scopes activate
+
+### Twilio SMS webhook
+
+```bash
+RELAY_URL="https://{firstname-lower}-webhook-relay-production.up.railway.app"
+curl -s -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" -X POST \
+  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/IncomingPhoneNumbers/$TWILIO_PHONE_SID.json" \
+  --data-urlencode "SmsUrl=$RELAY_URL/sms" --data-urlencode "SmsMethod=POST"
+```
+
+### Twilio WhatsApp sandbox
+
+This requires a per-agent Twilio sub-account (the WhatsApp sandbox webhook is account-wide). See `docs/guides/twilio-subaccounts-setup.md`.
+
+Once you have the sub-account credentials, configure the sandbox via the Twilio Console UI (no API support):
+
+1. Navigate to `https://console.twilio.com/us1/develop/sms/try-it-out/whatsapp-learn?frameUrl=%2Fconsole%2Fsms%2Fwhatsapp%2Flearn`
+2. Click the **Sandbox settings** tab
+3. Set the inbound webhook URL to `https://{firstname-lower}-webhook-relay-production.up.railway.app/whatsapp` (HTTP POST)
+4. Set the status callback URL to `https://{firstname-lower}-webhook-relay-production.up.railway.app/whatsapp/status` (HTTP POST)
+5. Save
+
+---
+
+## 9. Local poll job
+
+The Mac mini runs a launchd job that polls the relay every 5 seconds. Install it:
+
+```bash
+# 1. Update scripts/poll-slack-events.sh — set EVENTS_URL to your relay's /events endpoint
+# 2. Update scripts/comms-monitor.sh — set RAILWAY_URL similarly
+# 3. Install the launchd plist:
+
+cat > scripts/local-triggers/plists/ai.adaptic.{firstname-lower}-poll-relay.plist <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key><string>ai.adaptic.{firstname-lower}-poll-relay</string>
+    <key>ProgramArguments</key><array>
+        <string>/bin/bash</string>
+        <string>{REPO_ROOT}/scripts/poll-slack-events.sh</string>
+    </array>
+    <key>WorkingDirectory</key><string>{REPO_ROOT}</string>
+    <key>StartInterval</key><integer>5</integer>
+    <key>RunAtLoad</key><true/>
+    <key>StandardOutPath</key><string>{REPO_ROOT}/logs/polling/poll-relay-stdout.log</string>
+    <key>StandardErrorPath</key><string>{REPO_ROOT}/logs/polling/poll-relay-stderr.log</string>
+</dict>
+</plist>
+EOF
+
+cp scripts/local-triggers/plists/ai.adaptic.{firstname-lower}-poll-relay.plist ~/Library/LaunchAgents/
+launchctl load ~/Library/LaunchAgents/ai.adaptic.{firstname-lower}-poll-relay.plist
+launchctl list | grep poll-relay  # verify loaded
+```
+
+---
+
+## 10. End-to-end test
+
+1. Have a teammate (or yourself, from a separate Slack account) send a DM to the agent's bot in Slack, OR @-mention the bot in a public channel where the bot is a member
+2. Within ~5 seconds:
+   - `railway logs --service {firstname-lower}-webhook-relay` should show `[slack] buffered message...`
+   - `state/inbox/slack/` should contain a new YAML file
+   - `logs/polling/poll-relay-stdout.log` should show the inbox write
+3. The inbox processor (running as launchd `ai.adaptic.{firstname-lower}-inbox-processor`) picks up the YAML and routes it through the daemon
+
+---
+
+## Troubleshooting
+
+### `railway up` returns "Service not found"
+
+Run `railway add --service {firstname-lower}-webhook-relay` first to create the service container. The flag is required even when the project exists.
+
+### `railway init` returns "Unauthorized"
+
+Your Railway account doesn't have admin rights in the workspace. Ask an existing admin (or your principal) to grant you Admin role in the workspace's Members settings.
+
+### `slack_signature: false` in /health after deploy
+
+The env vars exist in the project but the running container was built before they were set. Re-run `railway up --service {firstname-lower}-webhook-relay --detach` to redeploy.
+
+### Slack URL verification fails with "URL didn't respond"
+
+The relay is reachable but signature verification fails. Causes:
+
+- `SLACK_SIGNING_SECRET` mismatch (check Slack app → Basic Information vs. Railway env var)
+- The relay is responding correctly to `url_verification` (returns the challenge), but Slack's caching layer hasn't flushed. Re-save the manifest, or click "Click here to verify" on the event subscriptions page.
+
+### Twilio webhook returns 401 "invalid signature"
+
+`PUBLIC_HOSTNAME` env var is wrong. It must match the actual host Twilio sends to (typically `{firstname-lower}-webhook-relay-production.up.railway.app`, no scheme, no trailing slash). Twilio includes the full URL in its signature base string.
+
+### Buffer fills up but Mac mini doesn't drain
+
+Check the launchd job:
+
+```bash
+launchctl list | grep poll-relay   # should show the label with a non-error exit code
+tail logs/polling/poll-relay-stderr.log
+```
+
+Also check `EVENTS_URL` in `scripts/poll-slack-events.sh` matches the deployed Railway domain.
+
+### The relay restarts and loses buffered events
+
+In-memory buffers are TTL'd at 10 minutes. If the relay restarts (Railway redeploy, instance recycle, OOM), buffered events are lost. The local Slack poller (`scripts/poller/slack-poller.mjs`) runs every 60 seconds as a fallback and will catch any missed channel/DM messages — at most a 60s gap. For SMS/WhatsApp this is acceptable because Twilio retries on failure.
+
+If you need persistence, add a Postgres or Redis service in the same Railway project and persist buffers there. Not currently necessary at our message volume.
+
+---
+
+## Why one service per agent?
+
+Each agent has its own Slack signing secret and Twilio account/sub-account. A shared relay would have to multiplex by header or path, which adds complexity and a single point of failure. Per-agent deployment is simpler, isolated, and gives independent scaling/restarts.
+
+## Related guides
+
+- [Slack Setup](slack-setup.md) — Slack app creation and OAuth
+- [Voice & SMS Setup](voice-sms-setup.md) — Twilio account, SMS handlers
+- [WhatsApp Setup](whatsapp-setup.md) — WhatsApp sandbox / production
+- [Twilio Subaccounts Setup](twilio-subaccounts-setup.md) — per-agent isolation for WhatsApp

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaptic/maestro",
-  "version": "1.1.8",
+  "version": "1.4.1",
   "description": "Maestro — Autonomous AI agent operating system. Deploy AI employees on dedicated Mac minis.",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "./tools": "./lib/tool-definitions.js",
     "./executor": "./lib/action-executor.js",
     "./singleton": "./lib/singleton.js",
+    "./tts": "./lib/tts.mjs",
     "./package.json": "./package.json"
   },
   "files": [

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