@adaptic/maestro 1.1.7 → 1.4.1

package/scripts/setup/install-dev-tools.sh

@@ -0,0 +1,150 @@
+#!/bin/bash
+# install-dev-tools.sh — Install and configure approved dev tooling for Maestro agents
+#
+# Approved tools (audited 2026-04-18 from #dev-tooling channel):
+#   - claude-pace     — Rate limit status line tracker (Bash plugin)
+#   - agents-observe  — Multi-agent observability dashboard (CC plugin)
+#   - ccxray          — Claude Code token/cost observability proxy
+#   - ClawTeam        — Git worktree swarm orchestrator (CLI)
+#   - code-review-graph — Tree-sitter codebase knowledge graph (MCP)
+#
+# Skipped:
+#   - Superset        — GUI-only, Elastic License v2, not automatable
+#   - claudraband     — Evaluate later; overlaps with maestro session mgmt
+#
+# Usage: ./scripts/setup/install-dev-tools.sh [--all | --tool <name>]
+# Examples:
+#   ./scripts/setup/install-dev-tools.sh --all
+#   ./scripts/setup/install-dev-tools.sh --tool claude-pace
+#   ./scripts/setup/install-dev-tools.sh --tool ccxray
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+AGENT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+info()  { echo "  [INFO]  $1"; }
+ok()    { echo "  [OK]    $1"; }
+skip()  { echo "  [SKIP]  $1"; }
+fail()  { echo "  [FAIL]  $1" >&2; }
+
+# ── Tool installers ─────────────────────────────────────────────────────────
+
+install_claude_pace() {
+  info "Installing claude-pace (rate limit status line tracker)..."
+  if command -v claude >/dev/null 2>&1; then
+    # Install as Claude Code plugin
+    claude plugin install claude-pace 2>/dev/null && ok "claude-pace plugin installed" || {
+      info "Plugin install failed, trying npx setup..."
+      npx claude-pace setup 2>/dev/null && ok "claude-pace configured via npx" || skip "claude-pace: manual setup needed — see https://github.com/Astro-Han/claude-pace"
+    }
+  else
+    skip "claude-pace: Claude Code CLI not found"
+  fi
+}
+
+install_agents_observe() {
+  info "Installing agents-observe (multi-agent observability dashboard)..."
+  if command -v claude >/dev/null 2>&1; then
+    claude plugin install agents-observe 2>/dev/null && ok "agents-observe plugin installed" || {
+      info "Plugin install failed, trying npm global..."
+      npm install -g agents-observe 2>/dev/null && ok "agents-observe installed globally" || skip "agents-observe: manual setup needed — see https://github.com/simple10/agents-observe"
+    }
+  else
+    skip "agents-observe: Claude Code CLI not found"
+  fi
+}
+
+install_ccxray() {
+  info "Installing ccxray (Claude Code token/cost observability)..."
+  # ccxray is zero-install via npx — just verify it's accessible
+  if npx ccxray --version >/dev/null 2>&1; then
+    ok "ccxray available via npx"
+  else
+    info "ccxray will be available via: npx ccxray claude"
+    ok "ccxray: zero-install, run with 'npx ccxray claude' when needed"
+  fi
+
+  # Create a convenience wrapper
+  cat > "$AGENT_DIR/scripts/ccxray-session.sh" << 'WRAPPER'
+#!/bin/bash
+# Launch Claude Code through ccxray observability proxy
+# Usage: ./scripts/ccxray-session.sh [claude args...]
+exec npx ccxray claude "$@"
+WRAPPER
+  chmod +x "$AGENT_DIR/scripts/ccxray-session.sh"
+  ok "Created scripts/ccxray-session.sh convenience wrapper"
+}
+
+install_clawteam() {
+  info "Installing ClawTeam (git worktree swarm orchestrator)..."
+  if command -v pip3 >/dev/null 2>&1; then
+    pip3 install clawteam 2>/dev/null && ok "ClawTeam installed via pip" || {
+      info "pip install failed, trying git clone..."
+      if [ ! -d "$HOME/.clawteam" ]; then
+        git clone https://github.com/win4r/ClawTeam-OpenClaw.git "$HOME/.clawteam" 2>/dev/null && ok "ClawTeam cloned to ~/.clawteam" || skip "ClawTeam: manual setup needed — see https://github.com/win4r/ClawTeam-OpenClaw"
+      else
+        ok "ClawTeam already present at ~/.clawteam"
+      fi
+    }
+  else
+    skip "ClawTeam: pip3 not found"
+  fi
+}
+
+install_code_review_graph() {
+  info "Installing code-review-graph (Tree-sitter codebase knowledge graph)..."
+  if npx code-review-graph --version >/dev/null 2>&1; then
+    ok "code-review-graph available via npx"
+  else
+    npm install -g code-review-graph 2>/dev/null && ok "code-review-graph installed globally" || {
+      info "code-review-graph: available via npx when needed"
+      ok "Run with: npx code-review-graph"
+    }
+  fi
+}
+
+# ── Main ─────────────────────────────────────────────────────────────────────
+
+echo "=========================================="
+echo "  Maestro Dev Tooling Installer"
+echo "  Agent dir: $AGENT_DIR"
+echo "=========================================="
+echo ""
+
+TOOL="${2:-}"
+case "${1:-}" in
+  --all)
+    install_claude_pace
+    install_agents_observe
+    install_ccxray
+    install_clawteam
+    install_code_review_graph
+    ;;
+  --tool)
+    case "$TOOL" in
+      claude-pace)       install_claude_pace ;;
+      agents-observe)    install_agents_observe ;;
+      ccxray)            install_ccxray ;;
+      clawteam)          install_clawteam ;;
+      code-review-graph) install_code_review_graph ;;
+      *) echo "Unknown tool: $TOOL"; echo "Available: claude-pace, agents-observe, ccxray, clawteam, code-review-graph"; exit 1 ;;
+    esac
+    ;;
+  *)
+    echo "Usage: $0 [--all | --tool <name>]"
+    echo ""
+    echo "Available tools:"
+    echo "  claude-pace        — Rate limit status line tracker"
+    echo "  agents-observe     — Multi-agent observability dashboard"
+    echo "  ccxray             — Token/cost observability proxy"
+    echo "  clawteam           — Git worktree swarm orchestrator"
+    echo "  code-review-graph  — Tree-sitter codebase knowledge graph"
+    exit 0
+    ;;
+esac
+
+echo ""
+echo "Done. See docs/guides/dev-tooling.md for usage details."

package/scripts/spawn-session.sh

@@ -67,16 +67,31 @@ YAML
 echo "[$TIMESTAMP] Spawning session $SESSION_ID (budget: ${TIME_BUDGET}s)" | tee -a "$LOG_FILE"
 
 # Spawn Claude Code session in background with timeout
-(
-    timeout "$TIME_BUDGET" claude -p "$TASK_CONTENT
+# Supports two backends:
+#   MAESTRO_SESSION_BACKEND=claude      (default) — direct claude -p
+#   MAESTRO_SESSION_BACKEND=claudraband — persistent sessions via claudraband daemon
+SESSION_BACKEND="${MAESTRO_SESSION_BACKEND:-claude}"
+
+SESSION_PROMPT="$TASK_CONTENT
 
-IMPORTANT: You are a sub-session spawned by Sophie Nguyen, Chief of Staff at Adaptic.ai.
+IMPORTANT: You are a sub-session spawned for an Adaptic AI agent.
 Write your output to: $SESSION_DIR/output.md
 When complete, write 'DONE' to: $SESSION_DIR/complete
 Working directory: $SOPHIE_AI_DIR
-Do NOT send any communications. Only produce the requested output." \
-    --output-format text \
-    >> "$LOG_FILE" 2>&1
+Do NOT send any communications. Only produce the requested output."
+
+(
+    if [ "$SESSION_BACKEND" = "claudraband" ]; then
+        # Use claudraband for persistent, resumable sessions
+        timeout "$TIME_BUDGET" npx @halfwhey/claudraband "$SESSION_PROMPT" \
+            --output-format text \
+            >> "$LOG_FILE" 2>&1
+    else
+        # Default: direct claude -p
+        timeout "$TIME_BUDGET" claude -p "$SESSION_PROMPT" \
+            --output-format text \
+            >> "$LOG_FILE" 2>&1
+    fi
 
     EXIT_CODE=$?
 

package/workflows/continuous/backlog-executor.yaml

@@ -0,0 +1,141 @@
+# Backlog Executor — Continuous Execution Loop
+# Runs every 10 minutes via launchd
+# This is the "getting shit done" engine — items move from open → resolved → closed
+
+name: backlog-executor
+type: continuous
+schedule: "*/10 * * * *"
+timezone: Asia/Dubai
+description: >
+  The core execution engine. Every 10 minutes: check quota, read all queues,
+  select top actionable items, spawn parallel agents to execute, review results,
+  update queues. Items continuously move forward — not sitting in queues.
+
+steps:
+  # ── Gate: Check API quota before spawning agents ──
+  - id: quota-gate
+    skill: claude-pace
+    action: check-quota-headroom
+    description: >
+      Check Claude API rate limit quota before spawning parallel agents.
+      Determines execution batch size based on pace delta zone.
+    timeout: 30
+    outputs:
+      pace_delta: green|yellow|red
+      max_parallel_agents: 5|2|1
+      recommendation: proceed|reduce|critical-only
+    on_result:
+      green:
+        max_parallel: 5
+        include_improvement_backlog: true
+      yellow:
+        max_parallel: 2
+        include_improvement_backlog: false
+      red:
+        max_parallel: 1
+        include_improvement_backlog: false
+        skip_non_critical: true
+
+  # ── Read all queues and select actionable items ──
+  - id: queue-scan
+    agent: pmo-execution
+    action: scan-all-queues
+    description: Read all 15 operational queues, select top actionable items by priority
+    timeout: 120
+    depends_on: [quota-gate]
+    inputs:
+      queues_dir: state/queues/
+      max_items: "{quota-gate.outputs.max_parallel_agents}"
+      include_improvement_backlog: "{quota-gate.outputs.on_result.include_improvement_backlog}"
+      status_filter: [open, in_progress, blocked]
+      sort_by: [priority, sla_deadline, created_at]
+    outputs:
+      selected_items: []
+      queue_summary: {}
+
+  # ── Spawn parallel execution agents ──
+  - id: parallel-execution
+    agent: session-spawner
+    action: spawn-execution-agents
+    description: >
+      Spawn one background agent per selected item. Each agent gets full context
+      and executes independently. Quota-gated parallelism.
+    timeout: 1800 # 30 minutes max for the batch
+    depends_on: [queue-scan]
+    inputs:
+      items: "{queue-scan.outputs.selected_items}"
+      max_concurrent: "{quota-gate.outputs.max_parallel_agents}"
+      mode: background
+    outputs:
+      agent_sessions: []
+      results: []
+
+  # ── Monitor running agents (if agents-observe is active) ──
+  - id: agent-monitoring
+    skill: agents-observe
+    action: monitor-parallel-execution
+    description: >
+      Monitor spawned agents for failures, hangs, or resource contention.
+      Only runs if agents-observe dashboard is active — otherwise skipped.
+    timeout: 60
+    depends_on: [parallel-execution]
+    optional: true # Skip if agents-observe is not running
+    inputs:
+      session_ids: "{parallel-execution.outputs.agent_sessions}"
+      check_for: [hung_agents, error_patterns, resource_contention]
+    outputs:
+      health_report: {}
+      failed_agents: []
+
+  # ── Review results and update queues ──
+  - id: results-review
+    agent: pmo-execution
+    action: review-execution-results
+    description: >
+      Review agent outputs, update queue item statuses, mark completed items
+      as resolved, flag failures for investigation.
+    timeout: 120
+    depends_on: [parallel-execution, agent-monitoring]
+    inputs:
+      results: "{parallel-execution.outputs.results}"
+      health_report: "{agent-monitoring.outputs.health_report}"
+      failed_agents: "{agent-monitoring.outputs.failed_agents}"
+    outputs:
+      items_resolved: []
+      items_failed: []
+      items_requeued: []
+
+  # ── Update executive summary ──
+  - id: dashboard-update
+    agent: pmo-execution
+    action: update-executive-summary
+    description: Refresh executive summary dashboard with cycle results
+    timeout: 60
+    depends_on: [results-review]
+    inputs:
+      resolved: "{results-review.outputs.items_resolved}"
+      failed: "{results-review.outputs.items_failed}"
+      requeued: "{results-review.outputs.items_requeued}"
+      dashboard: state/dashboards/executive-summary.yaml
+
+  # ── Log cycle ──
+  - id: cycle-log
+    action: log
+    description: Append cycle summary to backlog executor log
+    depends_on: [dashboard-update]
+    inputs:
+      file: logs/workflows/{date}-backlog-executor.jsonl
+      data:
+        cycle_time: "{timestamp}"
+        pace_delta: "{quota-gate.outputs.pace_delta}"
+        items_selected: "{queue-scan.outputs.selected_items.length}"
+        items_resolved: "{results-review.outputs.items_resolved.length}"
+        items_failed: "{results-review.outputs.items_failed.length}"
+
+on_failure:
+  action: log-and-notify
+  message: "Backlog executor cycle failed at step {failed_step}"
+  notify: sophie-chief-of-staff
+  severity: high
+  # If quota-gate fails, the entire cycle is skipped — this is by design
+  quota_gate_failure: skip_cycle

package/workflows/daily/evening-wrap.yaml

@@ -41,18 +41,58 @@ steps:
     outputs:
       file: outputs/briefs/daily/{date}/still-open.md
 
+  # ── Daily agent performance summary via agents-observe ──
+  - id: agent-performance-summary
+    skill: agents-observe
+    action: daily-performance-summary
+    description: >
+      Summarise today's agent execution — sessions run, items completed,
+      failures, and total token spend. Feeds into the evening wrap so
+      the CEO sees system operational health alongside business outcomes.
+    timeout: 120
+    parallel_with: still-open
+    inputs:
+      time_range: today
+      metrics:
+        - sessions_count
+        - items_resolved
+        - items_failed
+        - total_duration
+        - failure_details
+    outputs:
+      file: outputs/briefs/daily/{date}/agent-performance.md
+      summary:
+        sessions_today: 0
+        items_resolved: 0
+        items_failed: 0
+        total_agent_hours: ""
+
+  # ── EOD quota status via claude-pace ──
+  - id: eod-quota-status
+    skill: claude-pace
+    action: eod-quota-check
+    description: Report end-of-day quota position for overnight capacity planning
+    timeout: 30
+    parallel_with: still-open
+    outputs:
+      pace_delta: green|yellow|red
+      overnight_capacity_note: ""
+
   - id: synthesise-wrap
     agent: ceo-briefing
     action: produce-evening-wrap
     description: Produce the evening wrap document
     timeout: 300
-    depends_on: [completed-today, comms-review, still-open]
+    depends_on: [completed-today, comms-review, still-open, agent-performance-summary, eod-quota-status]
     inputs:
       morning_brief: outputs/briefs/daily/{date}/ceo-morning-brief.md
+      agent_performance: "{agent-performance-summary.outputs.summary}"
+      quota_status: "{eod-quota-status.outputs}"
       components:
         - outputs/briefs/daily/{date}/completed-today.md
         - outputs/briefs/daily/{date}/comms-review.md
         - outputs/briefs/daily/{date}/still-open.md
+        - outputs/briefs/daily/{date}/agent-performance.md
     outputs:
       file: outputs/briefs/daily/{date}/ceo-evening-wrap.md
 

package/workflows/daily/morning-brief.yaml

@@ -11,11 +11,26 @@ description: >
 
 # Workflow steps execute sequentially
 steps:
+  # ── System health gate — check API quota before the day's workload ──
+  - id: quota-status
+    skill: claude-pace
+    action: morning-quota-check
+    description: >
+      Check overnight quota consumption and current headroom. Reports pace
+      delta zone so the morning brief can flag capacity constraints early.
+    timeout: 30
+    outputs:
+      pace_delta: green|yellow|red
+      five_hour_pct: 0
+      seven_day_pct: 0
+      capacity_note: "" # included in the morning brief if yellow/red
+
   - id: market-sweep
     agent: market-research
     action: overnight-market-summary
     description: Gather overnight market movements, key indices, relevant asset class performance
     timeout: 300 # 5 minutes
+    parallel_with: quota-status
     inputs:
       scope: [equities, crypto, forex, fixed-income]
       regions: [us, emea, apac]
@@ -105,6 +120,7 @@ steps:
     timeout: 300
     depends_on:
       [
+        quota-status,
         market-sweep,
         news-intelligence,
         comms-triage,
@@ -114,6 +130,7 @@ steps:
         calendar-review,
       ]
     inputs:
+      quota_status: "{quota-status.outputs}" # included as system health section
       components:
         - outputs/briefs/daily/{date}/market-sweep.md
         - outputs/briefs/daily/{date}/news-intelligence.md

package/workflows/event-driven/agent-failure-investigation.yaml

@@ -0,0 +1,137 @@
+# Agent Failure Investigation
+# Event-driven — triggered when a backlog executor agent fails or hangs
+# Uses agents-observe for session analysis and ccxray for token diagnostics
+
+name: agent-failure-investigation
+type: event-driven
+trigger:
+  event: agent_failure
+  source: backlog-executor # or any workflow that spawns agents
+  conditions:
+    - agent_exit_code: non-zero
+    - agent_timeout: exceeded
+    - agent_output: error_pattern
+description: >
+  Automated post-mortem when an agent fails. Pulls the full session trace
+  via agents-observe, analyses token/cost via ccxray logs, determines root
+  cause, and recommends remediation. Prevents recurring failures.
+
+steps:
+  # ── Pull session trace via agents-observe ──
+  - id: session-trace
+    skill: agents-observe
+    action: query-failed-session
+    description: >
+      Retrieve the full tool call sequence, timing data, and error state
+      for the failed agent session. Identify the last successful action
+      before failure.
+    timeout: 120
+    inputs:
+      session_id: "{trigger.session_id}"
+      agent_name: "{trigger.agent_name}"
+      query:
+        - full_tool_call_sequence
+        - last_successful_tool
+        - error_message
+        - timing_breakdown
+        - resource_state_at_failure
+    outputs:
+      file: outputs/investigations/{date}/{session_id}/session-trace.md
+      summary:
+        last_successful_tool: ""
+        error_type: "" # timeout|rate_limit|permission|context_overflow|unknown
+        duration_before_failure: ""
+        tool_call_count: 0
+
+  # ── Token analysis via ccxray ──
+  - id: token-analysis
+    skill: ccxray-diagnostics
+    action: analyse-failed-session
+    description: >
+      Check if the failure was token-related — context window overflow,
+      excessive input from tool reads, or cost runaway. Cross-reference
+      with session trace timing.
+    timeout: 120
+    parallel_with: session-trace
+    inputs:
+      session_id: "{trigger.session_id}"
+      log_dir: ~/.ccxray/logs/
+      checks:
+        - context_window_utilisation
+        - input_token_spike # large file reads or tool outputs
+        - output_token_pattern # repetitive or runaway generation
+        - cost_vs_average # compared to similar agent sessions
+    outputs:
+      file: outputs/investigations/{date}/{session_id}/token-analysis.md
+      summary:
+        context_peak_pct: 0
+        token_anomaly_detected: false
+        cost_vs_average: ""
+
+  # ── Quota state at time of failure ──
+  - id: quota-state
+    skill: claude-pace
+    action: check-quota-at-failure
+    description: >
+      Determine whether the failure was caused by or correlated with
+      API rate limiting. Check pace delta at the time of failure.
+    timeout: 30
+    parallel_with: session-trace
+    inputs:
+      timestamp: "{trigger.failure_timestamp}"
+      check:
+        - was_rate_limited
+        - pace_delta_at_time
+        - concurrent_sessions_count
+    outputs:
+      rate_limited: false
+      pace_delta: ""
+      concurrent_sessions: 0
+
+  # ── Root cause analysis ──
+  - id: root-cause-analysis
+    agent: engineering-oversight
+    action: determine-root-cause
+    description: >
+      Synthesise session trace, token analysis, and quota state to determine
+      the root cause. Classify the failure and recommend remediation.
+    timeout: 300
+    depends_on: [session-trace, token-analysis, quota-state]
+    inputs:
+      session_trace: outputs/investigations/{date}/{session_id}/session-trace.md
+      token_analysis: outputs/investigations/{date}/{session_id}/token-analysis.md
+      quota_state: "{quota-state.outputs}"
+      trigger_context: "{trigger}"
+    outputs:
+      file: outputs/investigations/{date}/{session_id}/root-cause.md
+      classification:
+        root_cause: "" # rate_limit|context_overflow|tool_error|prompt_bug|external_service|unknown
+        severity: "" # low|medium|high|critical
+        recurrence_risk: "" # low|medium|high
+        remediation: "" # specific fix recommendation
+
+  # ── Update tech debt / improvement backlog if systemic ──
+  - id: queue-remediation
+    agent: pmo-execution
+    action: queue-fix-if-systemic
+    description: >
+      If the root cause indicates a systemic issue (recurrence_risk: high),
+      create an item in tech-debt or improvement-backlog queue.
+    timeout: 60
+    depends_on: [root-cause-analysis]
+    condition: "{root-cause-analysis.outputs.classification.recurrence_risk} == high"
+    inputs:
+      root_cause: outputs/investigations/{date}/{session_id}/root-cause.md
+      target_queue: state/queues/tech-debt.yaml
+      item:
+        title: "Agent failure: {trigger.agent_name} — {root-cause-analysis.outputs.classification.root_cause}"
+        priority: high
+        source: "auto:agent-failure-investigation"
+
+on_failure:
+  action: log-and-notify
+  message: "Agent failure investigation failed for session {trigger.session_id}"
+  notify: sophie-chief-of-staff
+  severity: medium
+
+final_output: outputs/investigations/{date}/{session_id}/root-cause.md

package/workflows/event-driven/pr-review.yaml

@@ -0,0 +1,104 @@
+# PR Review Workflow
+# Event-driven — triggered when a new PR is opened or updated in a tracked repo
+# Uses code-review-graph for structural analysis before human/agent review
+
+name: pr-review
+type: event-driven
+trigger:
+  event: pull_request
+  actions: [opened, synchronize]
+  repos: # from config/repo-registry.yaml
+    - adapticai/engine
+    - adapticai/backend
+    - adapticai/frontend
+    - adapticai/maestro
+    - adapticai/sophie-ai
+description: >
+  Automated PR review pipeline. When a PR is opened or updated, runs structural
+  blast radius analysis via code-review-graph, then produces a review brief.
+  Engineering agents use this to make informed review decisions.
+
+steps:
+  # ── Structural blast radius analysis ──
+  - id: blast-radius
+    skill: code-review-graph
+    action: blast-radius-analysis
+    description: >
+      Analyse the PR diff through the tree-sitter knowledge graph. Map which
+      functions, modules, and entry points are affected by the changes.
+      Determine risk level based on dependency depth and consumer count.
+    timeout: 300
+    inputs:
+      repo: "{trigger.repo}"
+      pr_number: "{trigger.pr_number}"
+      base_branch: "{trigger.base_ref}"
+      head_branch: "{trigger.head_ref}"
+      analysis:
+        - changed_functions
+        - direct_dependents
+        - transitive_impact
+        - affected_entry_points
+        - untouched_related_functions # functions that probably should have changed
+    outputs:
+      file: outputs/reviews/{repo}/{pr_number}/blast-radius.md
+      summary:
+        risk_level: low|medium|high|critical
+        direct_dependents: 0
+        transitive_impact: 0
+        missing_changes: [] # related functions not in the diff
+
+  # ── Review context enrichment ──
+  - id: review-context
+    skill: code-review-graph
+    action: review-context
+    description: >
+      Pull structural context for each changed file — what calls them, what
+      they call, hot paths, and critical modules. Provides the reviewer with
+      the "why this matters" context for every changed file.
+    timeout: 180
+    parallel_with: blast-radius
+    inputs:
+      repo: "{trigger.repo}"
+      changed_files: "{trigger.changed_files}"
+    outputs:
+      file: outputs/reviews/{repo}/{pr_number}/review-context.md
+
+  # ── Produce review brief ──
+  - id: review-brief
+    agent: engineering-oversight
+    action: produce-pr-review-brief
+    description: >
+      Synthesise blast radius and review context into a concise review brief.
+      Highlights risk areas, suggests review focus, and flags missing changes.
+    timeout: 180
+    depends_on: [blast-radius, review-context]
+    inputs:
+      blast_radius: outputs/reviews/{repo}/{pr_number}/blast-radius.md
+      review_context: outputs/reviews/{repo}/{pr_number}/review-context.md
+      pr_metadata:
+        repo: "{trigger.repo}"
+        pr_number: "{trigger.pr_number}"
+        author: "{trigger.author}"
+        title: "{trigger.title}"
+    outputs:
+      file: outputs/reviews/{repo}/{pr_number}/review-brief.md
+
+  # ── Post review brief as PR comment ──
+  - id: post-review
+    agent: github-operator
+    action: post-pr-comment
+    description: Post the review brief as a PR comment for the reviewer
+    depends_on: [review-brief]
+    inputs:
+      repo: "{trigger.repo}"
+      pr_number: "{trigger.pr_number}"
+      content: outputs/reviews/{repo}/{pr_number}/review-brief.md
+      format: markdown
+
+on_failure:
+  action: log-and-notify
+  message: "PR review workflow failed for {trigger.repo}#{trigger.pr_number} at step {failed_step}"
+  notify: sophie-chief-of-staff
+  severity: low # PR review failure is inconvenient but not critical
+
+final_output: outputs/reviews/{repo}/{pr_number}/review-brief.md