@adaptic/maestro 1.1.8 → 1.4.1

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

package/workflows/weekly/engineering-health.yaml

@@ -0,0 +1,154 @@
+# Weekly Engineering Health Check
+# Runs every Wednesday at 10:00 GST — before the weekly execution review
+# Uses ccxray and code-review-graph for data-driven engineering insights
+
+name: engineering-health
+schedule: "0 10 * * 3" # Wednesday 10:00
+timezone: Asia/Dubai
+description: >
+  Weekly engineering health assessment. Audits token spend across agent sessions,
+  scans codebase architecture for structural drift, and produces an engineering
+  health dashboard update. Feeds into the weekly strategic memo.
+
+steps:
+  # ── Token budget audit via ccxray ──
+  - id: token-budget-audit
+    skill: ccxray-diagnostics
+    action: weekly-token-audit
+    description: >
+      Analyse the past week's Claude API token consumption across all agent
+      sessions. Identify expensive sessions, cost trends, and optimisation
+      opportunities. Uses ccxray historical logs.
+    timeout: 300
+    inputs:
+      time_range: 7d
+      log_dir: ~/.ccxray/logs/
+      breakdown_by: [agent, workflow, day]
+      compare_to: previous_week
+    outputs:
+      file: outputs/engineering/weekly/{date}/token-audit.md
+      summary:
+        total_tokens: 0
+        total_cost: 0
+        most_expensive_agent: ""
+        week_over_week_delta: ""
+        optimisation_recommendations: []
+
+  # ── Codebase architecture scan via code-review-graph ──
+  - id: architecture-scan
+    skill: code-review-graph
+    action: architecture-overview
+    description: >
+      Run tree-sitter structural analysis across key repositories. Detect
+      circular dependencies, orphaned exports, and architectural drift from
+      the intended design. Compares against previous week's baseline.
+    timeout: 600
+    parallel_with: token-budget-audit
+    inputs:
+      repos:
+        - path: ~/adapticai/engine
+          name: adaptic-engine
+        - path: ~/adapticai/backend
+          name: adaptic-backend
+        - path: ~/maestro
+          name: maestro
+      checks:
+        - circular_dependencies
+        - orphaned_exports
+        - module_coupling_score
+        - public_api_surface_changes
+      baseline: outputs/engineering/weekly/latest/architecture-baseline.json
+    outputs:
+      file: outputs/engineering/weekly/{date}/architecture-scan.md
+      baseline_update: outputs/engineering/weekly/{date}/architecture-baseline.json
+      summary:
+        repos_scanned: 0
+        circular_deps_found: 0
+        orphaned_exports: 0
+        api_surface_changes: []
+
+  # ── Agent performance profile via agents-observe ──
+  - id: agent-performance-review
+    skill: agents-observe
+    action: weekly-performance-profile
+    description: >
+      Review agent execution patterns from the past week. Identify slowest
+      agents, most-used tools, failure patterns, and efficiency trends.
+      Uses agents-observe SQLite historical data.
+    timeout: 300
+    parallel_with: token-budget-audit
+    inputs:
+      time_range: 7d
+      metrics:
+        - agent_duration_distribution
+        - tool_call_frequency
+        - failure_rate_by_agent
+        - bottleneck_tools
+      compare_to: previous_week
+    outputs:
+      file: outputs/engineering/weekly/{date}/agent-performance.md
+      summary:
+        total_sessions: 0
+        avg_session_duration: ""
+        failure_rate: ""
+        slowest_agent: ""
+        most_used_tool: ""
+
+  # ── Quota trend analysis via claude-pace ──
+  - id: quota-trend
+    skill: claude-pace
+    action: weekly-quota-trend
+    description: >
+      Analyse quota utilisation patterns over the past week. Identify peak
+      usage periods, quota constraint frequency, and capacity planning
+      recommendations.
+    timeout: 120
+    parallel_with: token-budget-audit
+    inputs:
+      source: logs/workflows/ # Extract quota data from backlog executor logs
+      time_range: 7d
+      metrics:
+        - daily_peak_usage
+        - red_zone_incidents
+        - deferred_items_count
+    outputs:
+      file: outputs/engineering/weekly/{date}/quota-trend.md
+
+  # ── Synthesise engineering health report ──
+  - id: synthesise-health-report
+    agent: engineering-oversight
+    action: produce-engineering-health-report
+    description: >
+      Synthesise token audit, architecture scan, agent performance, and quota
+      trends into a unified engineering health dashboard update and narrative.
+    timeout: 300
+    depends_on:
+      [token-budget-audit, architecture-scan, agent-performance-review, quota-trend]
+    inputs:
+      components:
+        - outputs/engineering/weekly/{date}/token-audit.md
+        - outputs/engineering/weekly/{date}/architecture-scan.md
+        - outputs/engineering/weekly/{date}/agent-performance.md
+        - outputs/engineering/weekly/{date}/quota-trend.md
+      dashboard: state/dashboards/engineering-health.yaml
+    outputs:
+      file: outputs/engineering/weekly/{date}/engineering-health-report.md
+      dashboard_update: state/dashboards/engineering-health.yaml
+
+  # ── Notify ──
+  - id: notify-ready
+    action: notify
+    description: Signal engineering health report is ready for the execution review
+    depends_on: [synthesise-health-report]
+    inputs:
+      channel: slack
+      target: "#engineering"
+      message: "Weekly engineering health report ready — feeding into execution review."
+
+on_failure:
+  action: log-and-notify
+  message: "Engineering health check failed at step {failed_step}"
+  notify: sophie-chief-of-staff
+  severity: medium
+
+final_output: outputs/engineering/weekly/{date}/engineering-health-report.md