canyonlabz/subagent-orchestrator

Subagent Orchestrator

When to Use This Skill

• User wants to extract BlazeMeter results and Datadog metrics via subagents
• User mentions "subagent workflow", "subagent orchestrator", or "run the extractors"
• User wants to offload BlazeMeter and Datadog MCP work to subagents to save context

What This Skill Does

1. Collects inputs from the user
2. Invokes the blazemeter-extractor subagent to populate artifacts/{test_run_id}/blazemeter/
3. Extracts timestamps via subagent return (primary) or test_config.json (fallback)
4. Invokes the datadog-extractor subagent to populate artifacts/{test_run_id}/datadog/
5. Writes an orchestrator_manifest.json with execution results
6. STOPS — does NOT proceed to PerfAnalysis, PerfReport, or Confluence

After this skill completes, the user can continue with the performance-testing-workflow skill starting from Step 4 (PerfAnalysis).

Architecture

User Prompt (test_run_id, env_name, ...)
  │
  ▼
Orchestrator (this skill)
  │
  ├── blazemeter-extractor subagent
  │     └── artifacts/{test_run_id}/blazemeter/
  │           ├── test-results.csv
  │           ├── aggregate_performance_report.csv
  │           ├── test_config.json
  │           ├── jmeter.log (or jmeter-*.log)
  │           ├── public_report.json
  │           ├── sessions/session_manifest.json
  │           └── subagent_manifest.json
  │
  ├── [extract start_time / end_time]
  │
  ├── datadog-extractor subagent
  │     └── artifacts/{test_run_id}/datadog/
  │           ├── host_metrics_*.csv or k8s_metrics_*.csv
  │           ├── logs_*.csv
  │           ├── apm_traces_*.csv (if traces exist)
  │           ├── kpi_metrics_*.csv (if requested)
  │           └── subagent_manifest.json
  │
  └── orchestrator_manifest.json
        └── artifacts/{test_run_id}/orchestrator_manifest.json

Platform Notes

mcpServers YAML field: Confirmed that Cursor does NOT enforce the mcpServers field in subagent frontmatter. Both subagents see all configured MCP servers. Tool isolation is enforced via prompt-level instructions in each subagent's system prompt. The mcpServers field is retained in the YAML for forward compatibility and for Claude Code users where it IS enforced.

---

Execution

Follow these steps exactly, in order.

---

Step 1 — Collect Inputs

Ask the user for the following values. Do not proceed until all required values are collected.

REQUIRED:
  test_run_id = [BlazeMeter test run ID — e.g., "12345678"]
  env_name    = [Datadog environment name — e.g., "QA", "UAT"]

OPTIONAL:
  test_name       = [informational label for the test run]
  log_query_type  = [Datadog log query type — default: "all_errors"]
  apm_query_type  = [Datadog APM query type — default: "all_errors"]
  kpi_query_names = [list of KPI query group keys — default: none]

---

Step 2 — Initialize Task Tracking

Create task items to monitor progress:

• BlazeMeter subagent invocation
• Timestamp handoff (primary + fallback)
• Datadog subagent invocation
• Orchestrator manifest generation

---

Step 3 — Invoke BlazeMeter Subagent

Action: Invoke the blazemeter-extractor subagent with the following prompt:

Extract BlazeMeter test results for test_run_id: {test_run_id}.
{Include test_name if provided: "Test name: {test_name}"}

Follow all instructions in your system prompt including writing the
subagent_manifest.json file.

After the subagent returns:

1. Parse the JSON block from the subagent's response
2. Record the full JSON response for the orchestrator manifest
3. Extract status, start_time, end_time, and notes
4. Record whether JSON parsing succeeded or failed

Save:

• bz_status = parsed status value
• bz_start_time = parsed start_time value (may be null)
• bz_end_time = parsed end_time value (may be null)
• bz_return_json = the full parsed JSON object

If bz_status is "failed", warn the user but continue to Step 4 to attempt the fallback timestamp mechanism.

---

Step 4 — Timestamp Handoff (Primary + Fallback)

This step uses two approaches for getting timestamps. Record results for both.

4a. Primary Approach — From Subagent Return JSON

Check if bz_start_time and bz_end_time from Step 3 are non-null and valid ISO 8601.

Record:

• primary_handoff_success = true/false
• primary_start_time = value or null
• primary_end_time = value or null

4b. Fallback Approach — From test_config.json File

Attempt to read artifacts/{test_run_id}/blazemeter/test_config.json.

If the file exists, extract start_time and end_time from it.

Note: The test_config.json format may differ from ISO 8601 (e.g., "2026-02-26 07:42:33 UTC" instead of "2026-02-26T07:42:33Z"). Normalize to ISO 8601 before passing to Datadog if using the fallback.

Record:

• fallback_file_exists = true/false
• fallback_start_time = value or null
• fallback_end_time = value or null

4c. Determine Effective Timestamps

Use the primary approach values if available. Fall back to the file-based values if the primary approach returned null. If both are null, record the failure.

Record:

• effective_start_time = the value that will be passed to Datadog
• effective_end_time = the value that will be passed to Datadog
• timestamp_source = "subagent_return" or "test_config_file" or "none"

If timestamp_source is "none", warn the user that Datadog extraction cannot proceed without timestamps. Stop and report the failure.

---

Step 5 — Invoke Datadog Subagent

Action: Invoke the datadog-extractor subagent with the following prompt:

Extract Datadog metrics for the following test run:

  test_run_id: {test_run_id}
  env_name:    {env_name}
  start_time:  {effective_start_time}
  end_time:    {effective_end_time}
  {Include if provided: "log_query_type: {log_query_type}"}
  {Include if provided: "apm_query_type: {apm_query_type}"}
  {Include if provided: "kpi_query_names: {kpi_query_names}"}

Follow all instructions in your system prompt including writing the
subagent_manifest.json file.

After the subagent returns:

1. Parse the JSON block from the subagent's response
2. Record the full JSON response for the orchestrator manifest
3. Extract status, env_type, and notes
4. Record whether JSON parsing succeeded or failed

Save:

• dd_status = parsed status value
• dd_return_json = the full parsed JSON object

---

Step 6 — Write Orchestrator Manifest

Write artifacts/{test_run_id}/orchestrator_manifest.json with the following structure:

{
  "orchestrator": "subagent-orchestrator",
  "orchestrator_version": "1.0.0",
  "test_run_id": "<test_run_id>",
  "env_name": "<env_name>",
  "execution_timestamp": "<ISO 8601 UTC>",
  "subagents": {
    "blazemeter": {
      "invocation_success": "<true | false>",
      "return_json_parsed": "<true | false>",
      "return_json": "<full bz_return_json or null>",
      "subagent_manifest_exists": "<true | false — check artifacts/{test_run_id}/blazemeter/subagent_manifest.json>"
    },
    "timestamp_handoff": {
      "primary_approach": {
        "source": "subagent_return",
        "success": "<true | false>",
        "start_time": "<value or null>",
        "end_time": "<value or null>"
      },
      "fallback_approach": {
        "source": "test_config_file",
        "file_exists": "<true | false>",
        "success": "<true | false>",
        "start_time": "<value or null>",
        "end_time": "<value or null>"
      },
      "effective_source": "<subagent_return | test_config_file | none>",
      "effective_start_time": "<value or null>",
      "effective_end_time": "<value or null>"
    },
    "datadog": {
      "invocation_success": "<true | false>",
      "return_json_parsed": "<true | false>",
      "return_json": "<full dd_return_json or null>",
      "subagent_manifest_exists": "<true | false — check artifacts/{test_run_id}/datadog/subagent_manifest.json>"
    }
  },
  "artifact_validation": {
    "blazemeter_folder_exists": "<true | false>",
    "blazemeter_files": {
      "test_results_csv": "<true | false>",
      "aggregate_performance_report_csv": "<true | false>",
      "test_config_json": "<true | false>",
      "jmeter_log": "<true | false>",
      "session_manifest_json": "<true | false>",
      "public_report_json": "<true | false>"
    },
    "datadog_folder_exists": "<true | false>",
    "datadog_files": {
      "infrastructure_metrics_csv": "<true | false>",
      "logs_csv": "<true | false>",
      "apm_traces_csv": "<true | false>",
      "kpi_metrics_csv": "<true | false | not_applicable>"
    }
  },
  "overall_assessment": {
    "blazemeter_extraction": "success | partial | failed | not_attempted",
    "datadog_extraction": "success | partial | failed | not_attempted",
    "ready_for_perfanalysis": "<true | false>"
  }
}

---

Step 7 — Report Results to User

Present a clear summary to the user:

1. BlazeMeter Subagent Results

   • Status (success/partial/failed)
   • Files written to artifacts/{test_run_id}/blazemeter/
   • Any errors or warnings

2. Timestamp Handoff Results

   • Which approach worked (primary, fallback, both, neither)
   • Effective timestamps used

3. Datadog Subagent Results

   • Status (success/partial/failed)
   • Files written to artifacts/{test_run_id}/datadog/
   • Any errors or warnings

4. Overall Assessment

   • Are artifacts ready for PerfAnalysis?

5. Manifest Locations

   • artifacts/{test_run_id}/orchestrator_manifest.json
   • artifacts/{test_run_id}/blazemeter/subagent_manifest.json
   • artifacts/{test_run_id}/datadog/subagent_manifest.json

6. Next Steps

   • If artifacts are ready, the user can continue with the performance-testing-workflow skill starting from Step 4 (PerfAnalysis) to complete the pipeline.

---

Error Handling

• If a subagent fails to invoke entirely, record it in the orchestrator manifest and continue to the next step.
• If JSON parsing of a subagent return fails, record the raw text response in the manifest under a raw_response field.
• Do NOT retry subagent invocations. Each subagent handles its own retries internally.
• Do NOT modify any existing Rules, Skills, or MCP source code.
• If the orchestrator itself encounters an error writing the manifest, report the error directly to the user with the full error message.

---

Related Files

• Production E2E orchestration skill: .cursor/skills/performance-testing-workflow/SKILL.md
• BlazeMeter subagent: .cursor/agents/blazemeter-extractor.md
• Datadog subagent: .cursor/agents/datadog-extractor.md
• MCP error handling rules: .cursor/rules/mcp-error-handling.mdc
• Skill execution rules: .cursor/rules/skill-execution-rules.mdc
• Prerequisites: .cursor/rules/prerequisites.mdc